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 EVE Sidecar Does

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.

┌─────────────────┐    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 in HMAC mode, or just the public key when EVE_CERT_SIGN_ALG=ed25519 or ecdsa-p256 — and can verify months later without contacting EVE. With asymmetric signing, the verifier can authenticate a certificate against the published public key and cannot forge one — cryptographic signature integrity, verifiable without contacting EVE. (This establishes tamper-evidence and origin against that key; it is not a legal-attribution guarantee, which also depends on key custody and authorization controls.) Signatures are algorithm-tagged, so HMAC and asymmetric certificates remain verifiable side-by-side across a key rotation.

5. Response Codes

6. Kubernetes Sidecar Pattern

EVE 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 certificate (HMAC-SHA256 by default, or Ed25519 / ECDSA P-256 for public verification).

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. Advanced Capabilities (Shipped)

The original roadmap gaps are now generally available (June 2026). Each is opt-in via the configuration above and verified end-to-end.

TLS interception & plaintext inspection

When enabled, HTTPS CONNECT tunnels are terminated at the sidecar so the decrypted request body runs through the full Pillar 128 + EVE CoreGuard pipeline, then a fresh certificate-verified TLS connection is re-originated upstream. Each deployment generates its own root CA — one customer's CA can never impersonate another's. Without the CA installed in the application trust store, clients reject the minted leaf, so interception is opt-in and visible, never silent.

Envoy ext_authz integration

For Envoy meshes, the sidecar runs as an external-authorization backend implementing envoy.service.auth.v3.Authorization/Check over gRPC (or the HTTP transport), funnelling into the same fail-closed enforcement core and emitting the same signed Decision Certificates. Set failure_mode_allow: false so an authz outage denies (fail-closed). A reference Envoy config ships with the image.

Observability & rate limiting

GET /metrics exposes Prometheus series including eve_sidecar_requests_total (by verdict and tenant), an enforcement-latency histogram, and rate-limit counters. The per-tenant token-bucket limiter sheds abusive tenants at the edge before any enforcement work is spent, returning 429 with Retry-After.

10. Related Documentation

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