Desktop and CLI apps

The MITM proxy captures traffic from any application that respects HTTP_PROXY / HTTPS_PROXY environment variables. It stores captures directly into managed storage using the same bundle format as the Chrome extension.

Basic usage

Start the proxy and point your application at it:

spectral capture proxy -a myapp &
HTTPS_PROXY=http://127.0.0.1:8080 curl https://api.example.com/users

Press Ctrl+C to stop the proxy. It stores the capture in managed storage and prints summary statistics (trace count, WebSocket connections, messages).

Domain filtering

By default the proxy intercepts all HTTPS traffic. To target specific domains, use the -d flag (repeatable):

spectral capture proxy -a myapp -d "api.example.com" -d "auth.example.com"

Glob-style patterns are supported:

spectral capture proxy -a myapp -d "*.example.com"

Traffic to non-matching domains passes through without interception.

Domain discovery

If you don’t know which domains an application talks to, use the discovery mode first:

spectral capture discover

This runs a passthrough proxy that does not perform MITM — all connections pass through untouched. It logs TLS SNI hostnames and plain HTTP host headers. Press Ctrl+C to see a summary table of discovered domains with request counts.

Use the output to build your -d filter list for the actual capture.

Options

Option	Default	Description
-a, --app	(prompted)	App name for managed storage
-p, --port	8080	Proxy listen port
-d, --domain	(all)	Domain filter pattern (repeatable)

Certificate setup

The proxy intercepts HTTPS by generating certificates on the fly, signed by the mitmproxy CA. For this to work, the CA certificate must be trusted by the operating system or application making the requests.

On first run, mitmproxy creates its CA in ~/.mitmproxy/. The file you need to install is mitmproxy-ca-cert.pem.

Generate the CA certificate

Run mitmproxy once to generate its CA:

mitmproxy

Then quit (q, y). The CA files are created in ~/.mitmproxy/.

macOS

Add the certificate to the system keychain and mark it as trusted:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem

Alternatively, open Keychain Access, import the certificate, double-click it, expand “Trust”, and set “When using this certificate” to “Always Trust”.

Linux (Debian/Ubuntu)

Copy the certificate and update the trust store:

sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates

Note

The file must have a .crt extension for update-ca-certificates to pick it up.

Linux (Fedora/RHEL)

sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors/mitmproxy.pem
sudo update-ca-trust

Verification

After installing the certificate, verify that the proxy can intercept HTTPS:

spectral capture proxy &
HTTPS_PROXY=http://127.0.0.1:8080 curl -I https://example.com

If the curl command succeeds without certificate errors, the setup is correct. If you see a certificate verification error, the CA is not properly trusted by the system or application.

Limitations

The MITM proxy does not capture UI context (clicks, page content, etc.) — that information only comes from the Chrome extension. Captures produced by the proxy contain network traces and WebSocket data but no context events.

The analysis pipeline still works on proxy-only captures, but the LLM has less context to infer business semantics. For the best results, use the Chrome extension for web applications and reserve the proxy for non-browser traffic (mobile apps, CLI tools, desktop applications).