Command-line tools and other trust stores

HTTPGlass sees a program’s traffic when two things are true:

1. The program uses a proxy — normally the macOS system proxy that HTTPGlass sets while capturing.
2. The program trusts the HTTPGlass root — normally through the macOS trust settings that Install & Trust changes.

Safari, Chrome, and most apps built on Apple’s networking meet both. Many command-line tools and language runtimes miss one or the other, and the fix is usually one environment variable.

If the tool’s requests don’t appear at all

It isn’t using the system proxy. Point it at HTTPGlass yourself. Use the address from Settings → Proxy → Listening on — 127.0.0.1:9191 unless that port was taken.

curl doesn’t read the macOS proxy settings. Pass the proxy on the command line:

curl -x http://127.0.0.1:9191 https://api.example.com/

The proxy environment variables are read by curl, Python, Go, and many other tools. Set them for one terminal session:

export http_proxy=http://127.0.0.1:9191
export https_proxy=http://127.0.0.1:9191

Java takes proxy settings as system properties:

java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9191 \
     -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9191 -jar app.jar

or -Djava.net.useSystemProxies=true to follow the macOS setting.

Node.js’s built-in HTTP clients don’t use a proxy unless you configure one; set it in the HTTP library your code uses.

Remember to unset these when you stop capturing — with nothing listening on the port, the tool’s requests will fail.

If the requests appear but are refused

The row reads Pinned, and the inspector says the app refused the certificate even though your Mac trusts the root. For tools HTTPGlass recognises, the inspector says it has its own certificate store, not pinning, and shows what to do, with a Save Certificate File button that writes the root certificate as a PEM file to ~/Library/Application Support/HTTPGlass/HTTPGlass Root Certificate.pem and shows it in Finder.

You can also export the certificate from your keychain in Terminal:

security find-certificate -c "HTTPGlass CA" -p > ~/httpglass-ca.pem

Then, with path/to/cert.pem being that file:

Client	What to do
Node.js	Start it with NODE_EXTRA_CA_CERTS="path/to/cert.pem". This adds to Node’s trusted certificates rather than replacing them
Python	Set REQUESTS_CA_BUNDLE (for requests) and SSL_CERT_FILE to the file
curl (a build with its own CA bundle, such as Homebrew’s)	Pass --cacert path/to/cert.pem
Ruby	Set SSL_CERT_FILE to the file
Java	Import it into the JDK’s trust store: keytool -importcert -cacerts -alias httpglass -file path/to/cert.pem. The default store password is changeit; depending on where the JDK is installed, you may need sudo
Firefox	In about:config, set security.enterprise_roots.enabled to true, then restart Firefox. It then trusts roots from the macOS keychain

--cacert, REQUESTS_CA_BUNDLE, and SSL_CERT_FILE replace the tool’s list of trusted certificates rather than adding to it. With them set, a host HTTPGlass passes through without decrypting presents its real certificate, which the tool will now reject. Set them only for the session you’re debugging, or have HTTPGlass decrypt the tool — pick it as the app you’re debugging, which works for command-line tools too.

Firefox and the system proxy

Firefox follows the system proxy by default (Settings → Network Settings → Use system proxy settings). If you’ve set a manual proxy there, point it at 127.0.0.1:9191 for both HTTP and HTTPS, or switch it back to the system setting.

When it really is pinning

If the client isn’t one of the above and still refuses a trusted root, it pins its certificate. No proxy can read that traffic — see What HTTPGlass can’t see.