Enable HTTPS MITM
CONNECT-only HTTPS gives you destination-level policy (“the agent may not contact this host”). HTTPS MITM gives you full L7 policy (“the agent may not POST a payload over this size to this path”). MITM is already on for every host, so this guide is about making it work rather than turning it on: bootstrap the CA once, trust it narrowly on the agent host, and name the hosts that must stay uninspected in bypass_hosts.
A host that cannot be intercepted is denied, not tunnelled: every host is strict by default. So the two things that make an agent work under this default are the CA being trusted by the agent and every interception-hostile host being listed in bypass_hosts.
You should already have a Sidecar running (Run the sidecar standalone).
Before you start: read the warnings
Section titled “Before you start: read the warnings”The MITM CA is the single most security-sensitive artifact in an OpenFirma deployment. Two rules:
- Bootstrap the CA once. Never regenerate it. Once a host trusts your CA, it has to keep trusting it. Regenerating means revisiting trust on every agent host.
- Trust the CA on the agent’s process, not the OS-wide trust store. Use
SSL_CERT_FILE,REQUESTS_CA_BUNDLE, or per-language equivalents. Never copy the CA into/etc/ssl/certs/system-wide.
For the conceptual background see Concepts: Interception.
Step 1: Bootstrap the CA
Section titled “Step 1: Bootstrap the CA”Add a [sidecar.ca] section to firma.toml:
[sidecar.ca]dir = "/tmp/firma-standalone/firma-ca"dir is optional. Leave the section out and the Sidecar mints its CA into
generated-firma-ca/ inside the state directory — the path firma config
writes, so a hand-written config and a scaffolded one share one CA instead of
minting two.
Restart the Sidecar. On first start with no existing CA, it generates one:
INFO firma_sidecar::startup::ca: bootstrapping CA at /tmp/firma-standalone/firma-caINFO firma_sidecar::startup::ca: wrote firma-ca.crt and firma-ca.keyINFO firma_sidecar: sidecar readyInspect the directory:
ls /tmp/firma-standalone/firma-ca/# firma-ca.crt firma-ca.keyfirma-ca.crt is the public certificate (this is what agents trust). firma-ca.key is the private key (keep it chmod 600). From this point forward, do not delete or regenerate these files.
dir is the only knob. The file names are fixed, and there is no per-file override — so whoever sets dir also decides where the private key lands. That is what lets firma run pin the directory to a run’s state entry and keep the key behind its sandbox mask. Earlier releases accepted ca_cert_path and ca_key_path under [sidecar.interceptor.https_mitm]; both are gone, and a config that still sets either fails at Sidecar startup with an unknown-field error. Point [sidecar.ca].dir at the directory holding the CA instead, naming the files firma-ca.crt and firma-ca.key.
In production, treat the CA directory as immutable infrastructure: provision it once, back it up encrypted, never check it into version control.
Step 2: Configure MITM hosts
Section titled “Step 2: Configure MITM hosts”Add a [sidecar.interceptor.https_mitm] block to firma.toml:
[sidecar.interceptor.https_mitm]enabled = trueintercept_hosts = [ "api.openai.com", "api.anthropic.com", "api.stripe.com",]bypass_hosts = []strict_hosts = ["api.stripe.com"]What each list does:
intercept_hosts— explicit MITM allowlist. Wildcards like*.anthropic.comwork. Anything in this list gets TLS-terminated; the Sidecar can read method, path, headers, body.bypass_hosts— explicit fallback to CONNECT-only. Use for hosts that pin certificates or otherwise reject MITM. You’ll only see destination-level policy on these.strict_hosts— if MITM fails for any reason on these hosts (handshake mismatch, parse error), DENY rather than fall back. Use for hosts where you’d rather break the call than enforce a weaker policy on it.
With no [sidecar.interceptor.https_mitm] block at all, the Sidecar intercepts every host and treats every host as strict. Writing intercept_hosts replaces that default, so the example above narrows interception to three hosts. firma config writes neither intercept_hosts nor strict_hosts, leaving the intercept-everything default in place.
enabled = true with an explicitly empty intercept_hosts is treated as MITM disabled, not as an error: there is nothing to intercept, so the Sidecar starts and falls back to CONNECT-only tunnels.
Restart the Sidecar. The startup log will list how many MITM hosts are configured.
Step 3: Trust the CA on the agent host
Section titled “Step 3: Trust the CA on the agent host”This is the part that varies by agent runtime. The unifying principle: trust the CA narrowly, on the agent’s process or sandbox, not on the host’s global trust store.
Python (requests, httpx)
Section titled “Python (requests, httpx)”export REQUESTS_CA_BUNDLE=/tmp/firma-standalone/firma-ca/firma-ca.crtexport SSL_CERT_FILE=/tmp/firma-standalone/firma-ca/firma-ca.crtThese environment variables apply only to the process that inherits them. They are by far the simplest narrow-scope trust mechanism.
Export them for the agent only, not in the shell that starts firma sidecar or firma run. The Sidecar verifies an https:// Authority with no [sidecar.authority].ca_cert_paths against the platform’s trusted roots, and SSL_CERT_FILE replaces those roots: with it pointing at the MITM CA, the Sidecar trusts only that CA and cannot connect to the Authority. If the variable must stay set there, pin the Authority’s CA with ca_cert_paths.
Node.js
Section titled “Node.js”export NODE_EXTRA_CA_CERTS=/tmp/firma-standalone/firma-ca/firma-ca.crtcurl --cacert <path> per invocation, or:
export CURL_CA_BUNDLE=/tmp/firma-standalone/firma-ca/firma-ca.crtGo’s crypto/tls does not respect a single env var by default. The simplest path is to bundle the CA into your code’s tls.Config.RootCAs. If you can’t change the code, run the agent under firma run — the wrapper handles this for supported profiles.
Inside firma run
Section titled “Inside firma run”When you launch with firma run, the wrapper installs the CA into the sandbox’s trust path automatically and sets the appropriate env vars for the runtime profile. You don’t need to do anything else for firma run-wrapped agents.
The sandbox sees only the public CA material — firma-ca.crt, plus firma-ca-bundle.crt under ca_trust_mode = "append_system_roots". firma-ca.key stays behind the control-plane mask, in this run’s entry and in generated-firma-ca/ alike, so a wrapped agent can verify intercepted connections but cannot mint certificates that other CA-trusting processes would accept.
This works because firma run owns the CA location for a Sidecar it starts: it pins [sidecar.ca].dir to that run’s state entry, and the CA file names are fixed (firma-ca.crt, firma-ca.key), so the key cannot be configured somewhere the mask does not cover.
An external Sidecar’s CA belongs in generated-firma-ca/ or outside FIRMA_STATE_DIR. When you point firma run at a Sidecar you started yourself (--sidecar tcp://…), it trusts that Sidecar’s CA through FIRMA_SIDECAR_CA_CERT_PATH or FIRMA_SIDECAR_CA_DIR, or — failing both — by probing the state directory’s generated-firma-ca/, the working directory’s firma-ca/, /etc/firma/ca/, and /var/lib/firma/ca/ in that order.
The control-plane mask hides everything under FIRMA_STATE_DIR from the wrapped process. Two paths are restored through it, read-only and certificate-only: this run’s own entry and generated-firma-ca/, which is where a Sidecar with no [sidecar.ca].dir mints. A CA published anywhere else inside the state directory stays unreadable in the sandbox, and firma run refuses to launch rather than letting the agent fall back to the host’s system roots:
backend error (bwrap): trust anchor /run/user/1000/firma/external-ca/firma-ca.crt lies inside themasked control-plane runtime /run/user/1000/firma and is not CA material this run restores from/run/user/1000/firma/run/<sandbox-id>/firma-ca or /run/user/1000/firma/generated-firma-ca; move anexternal Sidecar's CA to one of those directories or outside FIRMA_STATE_DIRStep 4: Verify MITM is in effect
Section titled “Step 4: Verify MITM is in effect”With the env vars set in your agent shell, make a verbose HTTPS call:
curl --proxy http://127.0.0.1:8080 -v https://api.openai.com/v1/models 2>&1 | grep -E "issuer:|subject:"Look for issuer: CN=Firma… (or whatever your CA’s common name is) on the leaf cert. If you see the real OpenAI cert chain instead, MITM is not active for this host — check intercept_hosts.
In the audit log, MITM-intercepted calls show full L7 details:
{ "action": "communication.external.send", "resource": "api.openai.com/v1/models"}CONNECT-only calls show only the host:
{ "action": "", "resource": "api.openai.com:443/"}If you don’t see method, path, and provider on a host you intended to MITM, walk through the configuration step by step.
Picking what to leave uninspected
Section titled “Picking what to leave uninspected”Every host is intercepted, so the only decision left is which hosts to exempt:
| Host class | Intercepted? |
|---|---|
| LLM provider APIs (OpenAI, Anthropic, Mistral) | Yes, by default — that is what gives you L7 policy, HTTPS credential injection, and HTTPS secret-provider interception (Inject credentials). The shipped mappings classify both the CONNECT preface and the decrypted requests, so the posture is the same either way. |
| SaaS APIs you have admin access to (Stripe, Slack, GitHub) | Yes, by default |
| Your own services / internal SaaS | Yes, by default |
| Third-party SaaS where MITM violates terms | No — bypass_hosts |
| Banking, healthcare, certificate-pinning APIs | No — bypass_hosts |
| Self-signed internal services | No — bypass_hosts |
Add the rows marked bypass_hosts to that list; it is checked before interception, and it is the one interception key firma config merges rather than strips, so the entry survives a re-run. Narrowing intercept_hosts instead opts every host you forgot to list out of inspection as well — and a re-run removes it, widening interception back to everything.
To opt out globally, write bypass_hosts = ["*"]: the pattern matches every host, so every tunnel is relayed uninspected. enabled = false and intercept_hosts = [] do the same at runtime but do not survive firma config, which strips both.
Each of these hosts keeps destination-level policy only, so the mapping rules that classify its decrypted requests never fire for it.
What about cert pinning?
Section titled “What about cert pinning?”If an agent uses an SDK that pins certificates (validates the cert chain against a hardcoded fingerprint), MITM will fail with a cert-mismatch error in the agent. Two options:
- Add the host to
bypass_hosts. You’ll get destination-level policy only. - Replace the SDK with one that doesn’t pin. Most LLM and SaaS SDKs do not pin; banking and security SDKs sometimes do.
Don’t try to “fix” a pinning error by changing the pin — pinning is a security feature on the agent’s side, and the right answer is to respect it (and lose L7 visibility for that host).
Common gotchas
Section titled “Common gotchas”x509: certificate signed by unknown authority in the agent. The agent process didn’t pick up the CA. Re-export the env var in the exact shell that launches the agent, or use firma run.
MITM works for some hosts but not others. Wildcards in intercept_hosts are
leading-only (*.anthropic.com) and match one or more preceding labels, so that
pattern covers both api.anthropic.com and api.dev.anthropic.com. Mid-name
wildcards are not supported. Add exact entries when you need a narrower trust
scope.
Sidecar logs mitm_handshake_failed. The agent’s TLS client rejected the cert the Sidecar minted. Usually means the agent doesn’t trust your CA — re-check trust setup. If the host is sensitive, add it to strict_hosts so the failure denies instead of falling back.
Audit log shows decision = 3 and the agent reports a TLS error. The Sidecar terminated TLS to the agent fine, then the upstream rejected the Sidecar’s outbound TLS connection. Look for CONNECTOR_FAILURE in nearby Sidecar logs or ABORT events.
You regenerated the CA and now nothing works. Don’t. The fix is to find your old CA in a backup. If you genuinely have to start over, you must re-trust the new CA on every agent host before they can talk again.
What’s next
Section titled “What’s next”- Inject credentials — now that you can MITM, you can attach upstream credentials at the boundary.
- Read & verify the audit log — see the L7 detail for MITM hosts.
- Concepts: Threat model — the security implications of MITM.