Egress proxy

The egress proxy is a forward proxy that runs as a sidecar beside an untrusted workload. It terminates the workload’s TLS, allows or denies each connection, request, and DNS lookup against an endpoint list, and writes a credential from the Zone into each allowed request that needs one. Run agents in a sandbox shows a deployment.

This page covers the settings that decide what the proxy allows and what it records, while the repository’s configuration reference lists every key, including listeners, the CA, limits, and the admin socket.

The proxy reads one YAML or JSON document at start-up, from --config or EGRESS_PROXY_CONFIG, so restart the proxy after a change. The parser refuses unknown keys, repeated keys, and keys that differ only in case.

version: 1
sandbox:
  id: <sandbox-name>
identity:
  zone_url: <keycard-issuer-url>
  client_id: <workload-identity-credential-id>
  workload_token_file: /var/run/secrets/keycard/token
  impersonate:
    user: <user-id>
policy:
  cluster_cidrs: ["<pod-cidr>", "<service-cidr>"]
endpoints:
  - url: https://api.github.com
    credential:
      placement: {kind: header, name: Authorization, template: "Bearer {credential}"}
  - url: https://pypi.org

endpoints and policy come from the document only, but every other section can also come from an EGRESS_PROXY_* environment variable or a flag, which override the document.

When identity is present, the proxy runs an impersonation token exchange against the Zone for each allowed request to an endpoint with a credential. It does not run an exchange for a request that the endpoint list denies.

Set exactly one of workload_token_file and client_secret_file.

The built-in deny list covers loopback, RFC 1918 ranges, link-local ranges, shared address space, their IPv6 equivalents, cloud metadata host names, and the large public DNS-over-HTTPS resolvers. The proxy refuses a document that names a covered host, and when it dials, it refuses an allowed name that resolves into a covered range.

Each endpoint is one URL: https://host[:port][/path]. The proxy refuses a destination that no endpoint covers, so an empty list refuses everything.

The proxy does not forward cleartext HTTP, even to a listed host.

The placement says where the proxy writes the credential; it replaces any value the workload sent there, and it writes the credential when the workload did not send a value.

The credential does not appear in a log line or an audit record.

The proxy writes one JSON line to stdout for each decision, and you cannot turn off this audit stream. Logs go to stderr and do not include decisions.

{
  "ts": "<timestamp>",
  "sandbox_id": "<sandbox-name>",
  "document": {"digest": "sha256:<hex>"},
  "config": {"digest": "sha256:<hex>"},
  "connection_id": "<connection-id>",
  "request_id": "<request-id>",
  "scope": "request",
  "destination": {"host": "api.github.com", "port": 443, "sni": "api.github.com"},
  "request": {"method": "GET", "path": "/user"},
  "decision": {"verdict": "allow", "reason": "endpoint_allowed", "endpoint": "api.github.com:443/"},
  "outcome": {"status": 200}
}

A refused request gets the reason in the X-Keycard-Deny-Reason response header, and the ID in X-Keycard-Request-Id. A refused TLS handshake does not get an HTTP response, so the client sees a TLS error and only the record has the reason. A blank status below means the client does not get an HTTP response.

The proxy has two frontends: the CONNECT frontend is always on, and the transparent frontend is on when listen.transparent_port is set.

The CONNECT frontend does not need firewall rules in the sandbox, but it works only for clients that honor HTTPS_PROXY. A client that ignores the variable connects directly unless the sandbox blocks every other route out. The reference deployment uses the transparent frontend, with the rules under Containment.

The proxy is not a sandbox by itself, so the pod around it must send all of the workload’s traffic to it. The egress proxy repository ships an init container, egress-netsetup, that installs iptables rules in the pod’s network namespace:

• Outbound TCP goes to the proxy’s transparent listener, and DNS on UDP and TCP port 53 goes to the proxy’s resolver.
• The rules drop every other packet the workload sends, including UDP and QUIC.
• The proxy’s own user ID is exempt, so the workload must run as a different user, without CAP_SETUID, and with allowPrivilegeEscalation: false.

The init container drops NET_ADMIN and writes a receipt of the rules it installed, and the proxy reads the receipt and refuses to start if the rules or capabilities differ from its own settings. The repository’s containers document sets out the pod requirements, and its security model lists each threat, its mitigation, the test that covers it, and the known limits.