Runtime certificate setup

Patronus observes encrypted AI traffic through a local protection path. Desktop setup trusts the local mitmproxy certificate authority, but Node, Python, curl, pip, and Docker containers may use separate certificate settings.

Patronus configures the host runtime environment where it can. Containers may still need the CA mounted or installed explicitly.

Host runtime environment

On macOS, Patronus writes a combined CA bundle to:

~/.mitmproxy/patronus-ca-bundle.pem

The bundle contains the system CA bundle plus the local mitmproxy CA. This keeps host runtimes usable even when the Patronus proxy is not currently running.

Patronus points these environment variables at the bundle:

Runtime or tool	Environment variable
Node.js	NODE_EXTRA_CA_CERTS
Python/OpenSSL	SSL_CERT_FILE
Python requests	REQUESTS_CA_BUNDLE
curl/libcurl	CURL_CA_BUNDLE
pip	PIP_CERT

On macOS, Patronus writes managed export blocks into these per-user shell profiles:

~/.zshrc
~/.zprofile
~/.bash_profile
~/.bashrc
~/.profile

Patronus also updates the user launch environment with launchctl setenv so newly started GUI-launched processes can inherit the same CA settings where macOS allows it.

On Windows, Patronus writes the same environment variable names to the active user’s environment registry. Windows currently points those values at the generated mitmproxy CA certificate rather than a combined bundle.

The uninstall flow removes the managed environment values and deletes the macOS bundle file.

Container CA file

Patronus stores the generated CA certificate in:

~/.mitmproxy/mitmproxy-ca-cert.pem

Use that PEM certificate when a container or image trust store needs to trust Patronus explicitly. Mount only the public CA certificate, never mitmproxy-ca.pem, which contains the private key.

Mount the CA into a container

The examples below mount the certificate into a Linux container. For tools other than Node, these environment variables can replace the default CA bundle. To preserve trust in other HTTPS services, add the Patronus certificate to the image’s existing trust store using the image setup below, or use a combined bundle.

For an isolated test from a macOS shell:

docker run --rm \
  -v "$HOME/.mitmproxy/mitmproxy-ca-cert.pem:/etc/patronus/ca.pem:ro" \
  -e SSL_CERT_FILE=/etc/patronus/ca.pem \
  -e REQUESTS_CA_BUNDLE=/etc/patronus/ca.pem \
  -e NODE_EXTRA_CA_CERTS=/etc/patronus/ca.pem \
  -e CURL_CA_BUNDLE=/etc/patronus/ca.pem \
  -e PIP_CERT=/etc/patronus/ca.pem \
  your-image

On Windows PowerShell:

docker run --rm `
  -v "$env:USERPROFILE\.mitmproxy\mitmproxy-ca-cert.pem:/etc/patronus/ca.pem:ro" `
  -e SSL_CERT_FILE=/etc/patronus/ca.pem `
  -e REQUESTS_CA_BUNDLE=/etc/patronus/ca.pem `
  -e NODE_EXTRA_CA_CERTS=/etc/patronus/ca.pem `
  -e CURL_CA_BUNDLE=/etc/patronus/ca.pem `
  -e PIP_CERT=/etc/patronus/ca.pem `
  your-image

For Compose:

services:
  app:
    image: your-image
    volumes:
      - ~/.mitmproxy/mitmproxy-ca-cert.pem:/etc/patronus/ca.pem:ro
    environment:
      SSL_CERT_FILE: /etc/patronus/ca.pem
      REQUESTS_CA_BUNDLE: /etc/patronus/ca.pem
      NODE_EXTRA_CA_CERTS: /etc/patronus/ca.pem
      CURL_CA_BUNDLE: /etc/patronus/ca.pem
      PIP_CERT: /etc/patronus/ca.pem

Install into image trust stores

Some images ignore environment variables and require installing the certificate into the image trust store.

For Debian or Ubuntu based images:

COPY patronus-ca.pem /usr/local/share/ca-certificates/patronus-ca.crt
RUN update-ca-certificates

For Alpine:

RUN apk add --no-cache ca-certificates
COPY patronus-ca.pem /usr/local/share/ca-certificates/patronus-ca.crt
RUN update-ca-certificates

Verify

Run a simple HTTPS request from the relevant runtime while Patronus protection is active:

node -e "fetch('https://api.openai.com/').then(r => console.log(r.status))"
python -c "import urllib.request; print(urllib.request.urlopen('https://api.openai.com/').status)"
curl -v https://api.openai.com/

A completed TLS handshake confirms that the runtime trusted the certificate, but the request may still have bypassed Patronus. Verify the inspected request in Traces to confirm coverage. An HTTP error such as 401 or 404 can still indicate a successful TLS handshake.

Common failure modes

• The runtime was started before the environment variables were set.
• A shell profile was not reloaded after Patronus wrote the managed export block.
• A container uses a different CA bundle than the host.
• The mounted CA path is wrong or points to an old mitmproxy CA.
• Corporate base images overwrite trust stores during startup.
• The request bypasses Patronus because the container network path does not use the host protection path.