EVE Sidecar — Deployment Guide

The EVE Sidecar is an Envoy ext_authz authorization service. Envoy asks it before forwarding each outbound request; the sidecar obtains a signed decision from EVE’s hosted control plane, verifies that signature with EVE’s public key, and answers OK only for a verified ALLOW. Everything else — a BLOCK, a bad signature, a timeout, an outage — is denied, and Envoy never sends the request upstream.

1. What the EVE Sidecar Does

Customer app ──▶ Envoy ──ext_authz──▶ EVE Sidecar ──HTTPS──▶ EVE control plane
                    │                     │  ◀── signed eve.decision.v1 ──┘
                    │                     └─ verify signature, issuer, tenant,
                    │                        request digest, expiry, replay
                    ├─ OK (verified ALLOW only) ──▶ upstream model / API
                    └─ 403 / PERMISSION_DENIED  ──▶ request never forwarded

1. Envoy’s ext_authz filter calls the sidecar over gRPC (envoy.service.auth.v3.Authorization/Check, port 9002) or HTTP (port 9001). Both transports share one decision function.
2. The sidecar builds an eve.decision.request.v1 from the request’s metadata and a digest of its body, and posts it to POST /v1/decisions/authorize over verified TLS (optionally mTLS).
3. EVE runs CoreGuard policy evaluation and returns a signed eve.decision.v1. The tenant in that decision is taken from the authenticated caller, never from the request.
4. The sidecar checks, in order: schema, signature and issuer, that the decision answers this request, the payload digest, the tenant, expiry, and a single-use replay nonce (consumed last).
5. Only when every check passes and the verdict is ALLOW does the sidecar answer OK.

2. Decision Table (Fail-Closed)

3. Configuration

All configuration is via environment variables.

Request headers your app sets. Each governed request must carry x-eve-provider and x-eve-model; x-eve-action, x-eve-resource and x-eve-principal are optional. A request without the two required headers is denied.

Health: python -m eve_sidecar.entrypoint healthcheck (used by the image’s HEALTHCHECK and the Helm chart’s exec probes).

4. The Signed Decision

The control plane returns an eve.decision.v1 document. Its content_hash is "sha256-" + sha256(canonical JSON) of the decision without its signature, and the signature is an asymmetric signature over that hash, tagged with its algorithm. EVE’s hosted service signs kms-ecdsa-p384- (ECDSA P-384 in AWS KMS); a self-hosted engine signs ecdsa-p256- or ed25519-. The sidecar accepts only these asymmetric tags, each checked against a key of the matching type: symmetric hmac- signatures, which anyone holding the shared key could forge, are rejected, as are unknown tags.

Because the signature is asymmetric, the sidecar holds no signing key — only EVE’s public key — and cannot mint a decision. The same public key lets you re-verify a stored decision later 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.)

5. What Leaves the Pod

• By default: governance metadata — provider, model, action (default http.<method>), resource (default: the request path) and an optional principal — plus a SHA-256 digest of the body.
• Only when you enable it: the request body, up to EVE_SIDECAR_MAX_BODY_BYTES, when EVE_SIDECAR_ALLOW_CONTENT_INSPECTION is on and the request asks for it.
• Never: credentials from the proxied request (for example the upstream provider’s API key).

6. Kubernetes and Envoy

Run the sidecar as a container in the same pod as your application and Envoy, and point Envoy’s ext_authz filter at it. The reference Envoy config and Helm chart are provided with the image.

# Sidecar container
- name: eve-sidecar
  image: <YOUR-REGISTRY>/eve-sidecar@sha256:<DIGEST>   # issued with your engagement
  ports: [{ containerPort: 9002 }, { containerPort: 9001 }]
  env:
    - { name: EVE_SIDECAR_CONTROL_PLANE_URL, value: "https://api.eveaicore.com" }
    - { name: EVE_SIDECAR_TENANT_ID, value: "org_abc" }
    - { name: EVE_SIDECAR_EXT_AUTHZ_TRANSPORT, value: "grpc" }
    - name: EVE_SIDECAR_AUTH_TOKEN
      valueFrom: { secretKeyRef: { name: eve-sidecar, key: token } }
    - name: EVE_SIDECAR_PUBKEY
      valueFrom: { configMapKeyRef: { name: eve-sidecar, key: pubkey.pem } }

# Envoy HTTP filter
- name: envoy.filters.http.ext_authz
  typed_config:
    transport_api_version: V3
    failure_mode_allow: false       # sidecar down = deny
    grpc_service:
      envoy_grpc: { cluster_name: eve_sidecar_authz }
      timeout: 3s

Making it mandatory. The sidecar governs traffic that reaches Envoy. To stop an application from bypassing it, route all egress through a separate Envoy egress-gateway pod and restrict the application pod’s egress to that gateway — a service-mesh egress gateway does this by default. A NetworkPolicy alone cannot achieve it when Envoy is a sidecar in the same pod: NetworkPolicy selects pods, and all containers in a pod share one network namespace and IP, so any rule permitting Envoy’s egress permits the application container’s egress as well. That network configuration is yours to apply; the sidecar does not install iptables rules.

7. What Is Not Included

• Forward-proxy mode. There is no HTTPS_PROXY listener and no TLS interception; traffic is governed through Envoy.
• Offline decisions. Every decision comes from the control plane; if it is unreachable, requests are denied.
• Metrics and rate limiting. The sidecar has no Prometheus endpoint or per-tenant rate limiter; use Envoy’s own stats and rate-limit filters.
• Public distribution. No public image, Helm repository or self-serve download.

8. Related Documentation

• EVE CoreGuard — decision enforcement engine and policy-evaluation overview
• EVE CoreGuard Integration Guide — call the decision API from code with the SDK
• EVE Sidecar product overview — fail-closed egress gate for regulated deployments