Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Enable HTTPS Traffic

Configure the forward proxy to intercept HTTPS traffic

The following is only required if both:

  • The proxy is configured as a forward proxy

  • Recording HTTPS traffic is desired

To enable recording HTTPS traffic, we first must trust Stoobly agent to be a certificate authority. To do so, you will need to add the CA certificate generated by Stoobly as a trusted certificate authority.

System Wide Configuration

Some applications (e.g. browsers) will require additional specific configuration. Please refer to their documentation.

Automated Setup

In the terminal run the following command:

stoobly-agent ca-cert install

This installs the CA certificate under System in Keychain Access. To find the certificate file path, use:

stoobly-agent ca-cert show --format cer

In the terminal run the following command:

stoobly-agent ca-cert install

This will run Linux distribution specific commands to install the CA cert. We currently support the following distributions:

  • Debian based ones, such as Ubuntu

  • RHEL based ones, such as CentOS

Manual Setup

  1. Get the certificate path:

    stoobly-agent ca-cert show --format cer

    This outputs the path to the certificate file (e.g. ~/.stoobly/ca_certs/mitmproxy-ca-cert.cer).

  2. Open Keychain Access and click the + button in the top left corner

  3. Select the certificate file using the path from step 1

  4. Double-click the newly added row mitmproxy

  5. Click the dropdown next to When using this certificate, and select Always Trust

  1. Get the certificate path:

    stoobly-agent ca-cert show --format pem

    This outputs the path to the certificate file (typically ~/.stoobly/ca_certs/mitmproxy-ca-cert.pem).

  2. Install the certificate for your Linux distribution using the certificate path from step 1:

    For Debian/Ubuntu-based distributions:

    sudo cp $(stoobly-agent ca-cert show --format pem) /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
sudo update-ca-certificates

    For RHEL/CentOS-based distributions:

    sudo cp $(stoobly-agent ca-cert show --format pem) /etc/pki/ca-trust/source/anchors/mitmproxy-ca-cert.crt
sudo update-ca-trust

Browser Configuration

Most browsers use the system certificate store, so after running stoobly-agent ca-cert install, Chrome, Edge, and Safari should automatically trust the CA certificate. Firefox uses its own certificate store and requires manual configuration.

Chrome and Edge use the system certificate store. After installing the CA certificate system-wide with stoobly-agent ca-cert install, these browsers should automatically trust it.

Verification:

  1. Start Stoobly agent: stoobly-agent run

  2. Configure your browser to use the proxy (see Forward Proxy configuration)

  3. Visit an HTTPS site (e.g., https://example.com)

  4. If no certificate warning appears, the CA certificate is properly trusted

If you see certificate warnings:

  • Ensure you ran stoobly-agent ca-cert install with administrator privileges

  • Restart your browser after installing the certificate

  • On macOS, verify the certificate is trusted in Keychain Access

Firefox uses its own certificate store and requires manual import of the CA certificate.

  1. Get the certificate path:

    This outputs the path to the certificate file (typically ~/.stoobly/ca_certs/mitmproxy-ca-cert.pem).

  2. Open Firefox and navigate to certificate settings:

    • Go to Settings (or Preferences)

    • Search for "certificates" in the search bar

    • Click View Certificates under Certificates

  3. Import the certificate:

    • Click the Authorities tab

    • Click Import...

    • Navigate to the certificate path from step 1 (use the full path)

    • Select the certificate file and click Open

  4. Trust the certificate:

    • In the dialog that appears, check Trust this CA to identify websites

    • Click OK

  5. Verify:

    • Start Stoobly agent: stoobly-agent run

    • Configure Firefox to use the proxy

    • Visit https://example.com - you should see no certificate warning

Note: You can also use --format cer if you prefer the .cer format:

Safari uses the macOS system Keychain. After running stoobly-agent ca-cert install, Safari should automatically trust the certificate.

Verification:

  1. Verify the certificate is installed in Keychain Access:

    • Open Keychain Access

    • Search for "mitmproxy" or "stoobly"

    • Ensure it shows Trust as "Always Trust"

  2. If not trusted:

    • Double-click the certificate

    • Expand Trust

    • Set When using this certificate to Always Trust

    • Close the dialog

  3. Restart Safari and test with an HTTPS site through the proxy

PreviousForward Proxy
NextReverse Proxy

Last updated