Developer tools and HTTPS inspection
Keep Node.js, Python, curl, git and other developer tools working when PulseHA inspects HTTPS.
When Secure Web inspects HTTPS, PulseHA decrypts the connection and presents a certificate issued by your organisation’s inspection root. The PulseHA agent installs that root in the operating system’s trust store, so browsers and apps that use the store accept it. Many developer tools keep their own certificate list instead, and reject inspected connections. This page explains what the agent does about that, how to check a device, and how to handle the tools it cannot configure.
Why developer tools break#
These tools carry their own certificate store, or replace the system one when a variable is set:
- Node.js and Bun, and everything built on them: npm, VS Code extensions, AI coding CLIs. They fail with
SELF_SIGNED_CERT_IN_CHAIN. - Python
requestsandcertifi, used by pip, the Azure CLI (az) and many SDKs. They fail withCERTIFICATE_VERIFY_FAILED. - curl and git builds from Homebrew, conda and similar, which ship their own bundle.
- Go, when
SSL_CERT_FILEis set: Go then treats that file as its whole trust store. Tools such asgo,gh,terraformandkubectlfail withx509: certificate signed by unknown authority. - Java, which uses its own keystore.
- Containers, whose images have their own certificate store.
The certificate chain is valid. These tools never look at the store where the agent installed your root.
What the agent sets up#
With Developer tools trust on, which is the default, the agent sets up these tools on every device that trusts your inspection root. This requires a current PulseHA agent.
Trust files#
The agent keeps two files in a fixed directory, readable by every user. They contain only public certificates.
| Platform | Directory |
|---|---|
| macOS | /Library/Application Support/PulseHA/trust |
| Windows | %ProgramData%\PulseHA\trust |
| Linux | /etc/pulseha/trust |
| File | Contents |
|---|---|
tenant-roots.pem | Your organisation’s inspection roots, exactly as installed in the operating system’s store. During a root rotation it holds both roots. |
ca-bundle.pem | Every root the operating system trusts, plus your inspection roots. Exported from the system store, so other roots your device management installed keep working. |
The agent rewrites both files whenever your inspection root changes, and removes them when the agent is uninstalled.
Environment variables#
| Variable | Points at |
|---|---|
NODE_EXTRA_CA_CERTS | tenant-roots.pem |
REQUESTS_CA_BUNDLE | ca-bundle.pem |
SSL_CERT_FILE | ca-bundle.pem |
CURL_CA_BUNDLE | ca-bundle.pem |
GIT_SSL_CAINFO | ca-bundle.pem |
NODE_EXTRA_CA_CERTS adds to the certificates Node.js and Bun already trust, so it needs only your roots. The other variables replace the tool’s whole list, so they get the full bundle; pointing them at your roots alone would break every site that is not inspected.
On macOS the agent sets them for each login session. On Windows it sets them in the machine environment. On Linux it adds them to /etc/environment.d for desktop sessions and to /etc/profile.d for login shells.
Firefox#
The agent adds a Firefox policy so Firefox trusts your inspection root: on macOS and Windows by importing the roots the operating system trusts, on Linux by installing tenant-roots.pem. It merges with any existing Firefox policy rather than replacing it.
Values you set are left alone#
If one of these variables is already set to something else, by you, a shell profile or your device management, the agent does not override it. It reports a conflict for that variable instead, with the file it points at and whether that file includes your inspection root. Your administrator sees the conflict in the console, and pulsectl doctor shows it on the device.
Restart apps that were already running#
A running app keeps the environment it started with. After the agent sets the variables, or after your inspection root changes, open a new terminal and restart editors and other apps that were open.
Check a device#
Run:
pulsectl doctor
Under TLS INSPECTION TRUST it checks, without changing anything:
- OS trust store: the operating system trusts your inspection root.
- Trust files: both files exist and contain the current roots.
- Each variable, both as the agent applied it and as the terminal you run it in sees it.
- Firefox policy.
Each check is marked as passed, a warning or a failure, and anything that needs action has a fix: line. The command exits with an error when it finds a problem. A warning that a variable is “set for new sessions, but not in this terminal” means you need to open a new terminal.
Fix a conflict#
The most common conflict on a Mac is SSL_CERT_FILE exported by a shell profile and pointing at Homebrew’s certificate bundle, which does not include your inspection root. pulsectl doctor reports it as a failure and names the file. Fix it in one of two ways:
- Remove the
export SSL_CERT_FILE=...line from your shell profile (~/.zshrc,~/.bash_profileor~/.profile), then open a new terminal. The agent’s value then applies. - Or point it at the agent’s bundle, which includes the system roots as well as yours:
export SSL_CERT_FILE="/Library/Application Support/PulseHA/trust/ca-bundle.pem"
The same applies to REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE and GIT_SSL_CAINFO. For NODE_EXTRA_CA_CERTS, point it at tenant-roots.pem, or at a file of your own that includes its contents. On Windows and Linux use the directory from Trust files. Run pulsectl doctor again in the new terminal to confirm.
Tools the agent does not configure#
Java#
The agent does not set JAVA_TOOL_OPTIONS, because Java prints it on every start and that breaks tools that read Java’s output. Import your inspection root into the Java trust store instead:
sudo keytool -importcert -cacerts -alias pulseha-inspection \
-file "/Library/Application Support/PulseHA/trust/tenant-roots.pem"
keytool imports one certificate per run. During a root rotation the file holds two roots; save each to its own file and import both under different aliases. Repeat after updating Java, since a new Java installation has its own trust store.
On macOS you can instead have Java read the macOS keychain by starting it with -Djavax.net.ssl.trustStoreType=KeychainStore. Whether it sees the System keychain, where the agent installs your root, depends on the Java version. If connections still fail, use keytool.
Docker and other container images#
A container uses the certificate store inside its image, not the host’s. For images you build and run on inspected networks, copy tenant-roots.pem into the build context and add it to the image’s store. On Debian and Ubuntu based images:
COPY tenant-roots.pem /usr/local/share/ca-certificates/pulseha-inspection.crt
RUN update-ca-certificates
On Red Hat based images, copy it to /etc/pki/ca-trust/source/anchors/ and run update-ca-trust. Images that run Node.js also need ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/pulseha-inspection.crt, or the path you copied the file to. Rebuild the image after your inspection root rotates.
Apps that pin certificates#
Some apps accept only one specific certificate for their own servers, so no trust setting helps. Stop inspecting those destinations instead: with HTTPS inspection set to Inspect all HTTPS, add them to the Allow domain list chosen as the Do-not-decrypt list (optional) in Secure Web settings, or use Add to never-decrypt list on the destination in Inspection compatibility. Traffic to those destinations is then not decrypted, so path rules and malware scanning do not apply to it.
For administrators#
Developer tools trust#
The setting is in Security → Secure Web → Settings, under Web inspection, beside the tenant HTTPS trust controls. Developer tools trust is on and marked Recommended by default.
Turn it off if you distribute these certificate settings through your own device management. The console asks Turn off developer tools trust? first. Agents then remove the settings they made and only install the certificate in the operating system’s store. Values that a person or your device management set are never changed either way, and the change is recorded in Audit.
Managed HTTPS trust readiness counts devices whose developer tools trust is Configured, Needs attention, or reported by an Agent too old to support it. The device drawer on Devices shows the device’s Developer Tools state, any Conflicts by variable name, and Recent inspection failures (7 days).
Inspection compatibility#
The Inspection compatibility panel on the same Settings page lists the apps and destinations whose secure connections failed while PulseHA inspected them, over the last 24h or 7d. Each row shows the Destination, the Outcome, the number of Devices, the Count and when it was Last seen.
| Outcome | Meaning |
|---|---|
| App rejected the inspection certificate | The client does not trust your inspection root. Usually a developer tool or a pinned app. |
| App closed the connection after the certificate | The client hung up after receiving the certificate. Often the same cause, but less certain. |
| Secure connection failed during inspection | The handshake failed for another reason. |
| Inspection certificate unavailable | PulseHA could not create an inspection certificate for this site. |
Each row’s menu can open an affected device, Add to never-decrypt list after a confirmation, or open this guide. Viewing the panel needs content_filtering:logs; adding to the list needs content_filtering:update; opening a device needs devices:view.
PulseHA never bypasses inspection on its own#
A rejected certificate never changes what is decrypted. Otherwise any program, malware included, could switch inspection off for itself by refusing the certificate. Fix the device’s developer tools trust where only some devices are affected, and stop inspecting a destination only when you decide to.
Troubleshooting#
- A tool still fails in a terminal that was open before. Open a new terminal. Apps that were running when the agent set the variables need a restart.
pulsectl doctorreports a conflict. Something else set the variable. See Fix a conflict.pulsectl doctorsays the agent does not report runtime trust. The agent is too old, or has not finished starting. Update PulseHA, or try again in a minute.- Go tools fail with
x509: certificate signed by unknown authorityon a Mac.SSL_CERT_FILEpoints at a bundle without your inspection root. See Fix a conflict. - The same destination fails on every device. The app may pin its certificate. Check Inspection compatibility, then consider the never-decrypt list.
Related tasks#
- Secure Web to turn on HTTPS inspection and choose a do-not-decrypt list.
- Devices to see a device’s developer tools trust state.
- Audit to review settings changes.
- Troubleshooting for agent connectivity problems.