Certificates: enabling HTTPS interception
Install and trust HTTPeep's built-in root CA so the proxy can decrypt HTTPS traffic for inspection and rule matching on macOS, Windows, and Linux.
HTTPeep decrypts HTTPS traffic using a technique called TLS interception. To do this, it generates a local root Certificate Authority (CA) at first launch and uses it to issue certificates on the fly for every HTTPS host you visit. Your browser or application then sees a valid certificate signed by that CA rather than the original server's certificate.
For this to work transparently, your operating system (or browser) must trust the HTTPeep root CA. Until it does, HTTPS connections will fail with certificate errors, and HTTPeep will only be able to capture unencrypted HTTP traffic.
HTTPeep's root CA is a local debugging CA only. Its private key never leaves your machine. It has no authority over any other device and cannot be used to intercept traffic outside your local proxy session.
How HTTPS interception works
When you make an HTTPS request through HTTPeep:
- HTTPeep intercepts the initial TLS handshake.
- It opens a new TLS connection to the real server, verifying the server's certificate normally.
- It issues a new certificate for that hostname, signed by its local root CA.
- Your application completes the handshake with this locally-signed certificate.
- HTTPeep can now read, log, and apply rules to the decrypted request and response before forwarding them.
This is commonly called a MITM (man-in-the-middle) proxy. In HTTPeep's case, both legs of the connection are controlled by the same process on your own machine — it is a standard technique used by all major HTTP debugging tools.
Checking certificate status
Before installing, you can check whether the root CA already exists and whether it is trusted:
httpeep-cli cert statusExample output:
Root CA: exists
OS Trust: trusted ✓
Expires: 2028-04-13 (in 730 days)
Fingerprint: SHA256:abc123...If OS Trust shows not trusted, follow the installation steps below for your platform.
Installing the root CA
Launch HTTPeep and go to Settings → Certificate.
Click Install Certificate. HTTPeep opens a system dialog asking for your macOS login password. Enter it to add the CA to your System Keychain and mark it as trusted.
Run httpeep-cli cert status in your terminal. OS Trust should show trusted ✓.
You can also install via the CLI: httpeep-cli cert install. macOS will prompt for your password through a system dialog.
Launch HTTPeep and go to Settings → Certificate.
Click Install Certificate. Windows displays a UAC prompt. Click Yes to add the CA to the Windows certificate store (Trusted Root Certification Authorities).
Run httpeep-cli cert status in your terminal. OS Trust should show trusted ✓.
You can also install via the CLI in an elevated PowerShell prompt: httpeep-cli cert install.
Run the install command first — HTTPeep will attempt automatic installation using your distribution's trust store tooling:
httpeep-cli cert installIf your user has sufficient permissions, the CA is added and trusted automatically.
If the automatic attempt fails with a permissions error, run with sudo:
sudo httpeep-cli cert installHTTPeep will print the manual steps if it cannot determine your distribution's trust store location.
httpeep-cli cert statusOS Trust should show trusted ✓.
Some Linux distributions use separate trust stores for different applications (for example, Firefox maintains its own NSS database). If a specific browser still shows certificate errors after installing system-wide, you may need to import the CA into that browser's trust store manually.
GUI path
All platforms support certificate management through the desktop app:
Settings → Certificate
From this screen you can install the certificate, view its expiry date, and see the SHA256 fingerprint to verify authenticity.
Fixing CLI PATH issues
If httpeep-cli is not found in your terminal after installing HTTPeep:
- Open HTTPeep and go to Settings → MCP.
- Click Repair CLI / PATH Installation.
- Restart your terminal.
Troubleshooting
Do not export or distribute HTTPeep's root CA to other devices. It is generated uniquely per installation. Installing it on a different machine would allow that machine to intercept your HTTPS traffic without warning.