Role in the architecture
The security proxy sits between the sandbox workload and the internet:Per-sandbox CA certificates
Each sandbox gets a unique CA certificate generated at creation time using ECDSA P-256.- Written to
/opt/declaw/run/<sandbox_id>/ca.pem - Injected into the sandbox VM’s trust store at boot (before envd starts)
- Used by the security proxy to sign leaf certificates on-the-fly for each destination hostname
api.openai.com, the proxy presents a certificate signed by the sandbox CA (which the VM trusts), terminates the TLS connection, reads the plaintext body, runs the scanning pipeline, then establishes a new TLS connection to the real api.openai.com and forwards the (possibly modified) request.
Leaf certificate generation
For each new HTTPS destination, the proxy generates a short-lived leaf certificate signed by the sandbox CA:TLS passthrough mode
When only network policies are configured (no PII scanning, no transformations), the proxy operates in passthrough mode:- Peek at the TLS ClientHello to extract the SNI hostname (without decrypting)
- Check the SNI against the domain allowlist/denylist
- If allowed, forward the raw TCP stream directly — no TLS termination, no decryption
Scanning pipeline execution
When TLS interception is active, the proxy:- Terminates TLS from the client
- Reads the HTTP request headers and body
- Runs the pipeline stages in order:
- Transform rules (outbound) → body may be modified
- PII scanner → PII tokens substituted, session map updated
- Injection defense → body checked; blocked if injection detected
- Establishes TLS to the real destination
- Forwards the modified request
- Receives the response
- Runs the response pipeline (inbound transforms, then PII rehydration; the response body is not injection-scanned or blocked — it’s passed through, with untrusted content captured as session context for the optional judge)
- Returns modified response to the workload
Namespace binding
The proxy is a per-sandbox, host-side component that manages the TCP listener for a sandbox’s network namespace. It is created in the host’s root namespace but listens on a socket bound inside the sandbox namespace usingip netns exec.
Domain matching
Domain matching supports three formats:Guardrails Service integration
The proxy sends PII scan requests and injection scan requests to the Guardrails Service HTTP API atGUARDRAILS_URL. Each request is a JSON POST with the text to scan and the scanner types to use.
If the Guardrails Service is unreachable (timeout of 10 seconds), the proxy falls back to the built-in regex scanner transparently. No error is surfaced to the workload.