EVE Sidecar Forward Proxy — Deployment Guide

The EVE Sidecar is a stdlib-only HTTP/HTTPS forward proxy that sits between a customer application and the internet. Every egress request transits EVE's hosted governance API before reaching upstream. On a governance violation, the TCP connection is severed after a signed Decision Certificate is emitted — there is no silent pass-through. This guide covers the standalone quick start, the full configuration reference, the signed decision certificate format, response codes, the Kubernetes sidecar pattern with non-bypass iptables routing, the fail-closed library wrapper, and audit-trail guidance.

1. What the Sidecar Does

The Sidecar is a stdlib-only HTTP/HTTPS forward proxy that sits between a customer application and the internet. Every egress request transits EVE's hosted governance API before reaching upstream. On a governance violation, the TCP connection is severed after a signed Decision Certificate is emitted. There is no silent pass-through.

┌─────────────────┐    HTTPS_PROXY     ┌────────────────────┐    forwarded    ┌───────────┐
│  Customer App    │ ──────────────────│   EVE Sidecar      │ ───────────────│  Upstream │
│  (libs, agents,  │  :3128             │   forward_proxy.py │                 │   API     │
│   LLM callers)   │                    │                    │                 └───────────┘
└──────────────────┘ ◀───────────────────│  Pillar 128 +      │
                     451 + severed TCP  │  CoreGuard +       │
                     signed cert        │  fail-closed       │
                                        └────────────────────┘

The proxy module is interfaces/gateway/forward_proxy.py and the enforcement guardrail is core/governance/fail_closed.py.

2. Quick Start (Standalone)

Launch the proxy, then point a client at it:

# Launch the proxy
export JWT_SECRET_KEY="<your-hmac-signing-key>"
export EVE_PROXY_PORT=3128
export EVE_PROXY_ORG_ID="bank_tier1_a"
python -m interfaces.gateway.forward_proxy

# In a separate shell — point a client at it
export HTTPS_PROXY=http://localhost:3128
export HTTP_PROXY=http://localhost:3128
curl -v https://api.example.com/v1/completions -d '{"prompt": "hello"}'

Health endpoints:

• GET http://localhost:3128/healthz → 200 ok
• GET http://localhost:3128/readyz → 200 ok

3. Configuration

All configuration is via environment variables. No config file required.

Egress blocklist example:

export EVE_PROXY_BLOCKED_HOSTS="pastebin.com,raw.githubusercontent.com,transfer.sh,0x0.st"

4. Decision Certificate

Every proxy decision — allow, block, or fail-closed — produces a signed certificate delivered via the X-EVE-Decision-Cert response header.

{
  "certificate_id": "cert_9a1b3c5d7e9f0123",
  "verdict": "block",
  "reason": "Pillar 128 Violation: Symbolic Assembly Attack Detected",
  "matched_pillar": "128",
  "matched_vector": "706",
  "caller": "sidecar.forward_proxy.egress",
  "org_id": "bank_tier1_a",
  "latency_ms": 1.412,
  "timestamp": "2026-04-16T14:22:03.847Z",
  "content_hash": "sha256-…",
  "signature": "hmac-…",
  "algorithm": "HMAC-SHA256"
}

Offline verification (no call to EVE required):

from core.governance.fail_closed import verify_certificate
import json

cert = json.loads(response.headers["X-EVE-Decision-Cert"])
assert verify_certificate(cert), "certificate tampered or wrong key"

The auditor holds the same JWT_SECRET_KEY (or a public verification key once asymmetric signing is added) and can verify months later without contacting EVE.

5. Response Codes

6. Kubernetes Sidecar Pattern

Sidecar container (same pod as customer app):

apiVersion: v1
kind: Pod
metadata:
  name: customer-app
spec:
  containers:
    - name: app
      image: customer/app:1.0
      env:
        - name: HTTPS_PROXY
          value: "http://127.0.0.1:3128"
        - name: HTTP_PROXY
          value: "http://127.0.0.1:3128"
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.svc.cluster.local"

    - name: eve-sidecar
      image: eveaicore/sidecar:latest
      ports:
        - containerPort: 3128
      env:
        - name: EVE_PROXY_ORG_ID
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['tenant']
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: eve-signing-key
              key: hmac
        - name: EVE_PROXY_FAIL_CLOSED
          value: "1"
      readinessProbe:
        httpGet:
          path: /readyz
          port: 3128
      livenessProbe:
        httpGet:
          path: /healthz
          port: 3128

Non-bypass enforcement — an init container adds iptables rules so even if the app ignores HTTPS_PROXY, egress is redirected:

  initContainers:
    - name: egress-redirect
      image: eveaicore/iptables-init:latest
      securityContext:
        capabilities:
          add: ["NET_ADMIN"]
      command: ["/bin/sh", "-c"]
      args:
        - |
          iptables -t nat -A OUTPUT -p tcp ! -o lo --dport 80  -j REDIRECT --to-port 3128
          iptables -t nat -A OUTPUT -p tcp ! -o lo --dport 443 -j REDIRECT --to-port 3128

7. Fail-Closed Wrapper (for Library Users)

Customers who don't want the proxy posture can still consume EVE as a library with the same guarantees:

from core.governance.fail_closed import enforce, FailClosedError

@enforce(
    caller="my_service.call_llm",
    org_id="bank_tier1_a",
    timeout_s=2.0,
    run_fmi=True,
    fmi_input=user_prompt,
)
def call_llm(prompt: str) -> dict:
    return llm_client.generate(prompt)

try:
    result = call_llm(user_prompt)
    cert = result["certificate"]            # signed allow cert
except FailClosedError as e:
    cert = e.certificate.to_dict()          # signed block or fail_closed cert
    log.warning("blocked: pillar=%s reason=%s", cert["matched_pillar"], cert["reason"])

Guarantees:

1. Execution is bounded by timeout_s (daemon-thread runner).
2. Any exception → FailClosedError with matched_pillar="114" (Fail-Shut Invariance).
3. Any timeout → FailClosedError with matched_pillar="114".
4. Pillar 128 runs first; its veto takes precedence (matched_pillar="128").
5. Every outcome — allow, block, or fail-closed — returns a signed HMAC-SHA256 certificate.

8. Audit Trail

Tamper-evident append-only JSONL at:

data/governance/fail_closed/fail_closed_events.jsonl

Each line is a complete DecisionCertificate. For WORM posture, ship this file to S3 Object Lock / Azure Immutable Storage / a dedicated PostgreSQL append-only table. The HMAC signature on each line binds the payload — a tampered line fails verify_certificate().

9. Known Open Gaps (Roadmap)

10. Related Documentation

• CoreGuard — decision enforcement engine and policy-evaluation overview
• CoreGuard Integration Guide — connect your LLM pipeline with the SDK
• Sidecar product overview — mandatory-gateway egress proxy for regulated deployments