HTTPS Interception

How It Works

RoxyProxy performs HTTPS interception via a local Certificate Authority (CA). Here is what happens under the hood:

  1. On first startup, RoxyProxy generates a root CA certificate and private key at ~/.roxyproxy/ca/
  2. When a client sends a CONNECT request (HTTPS), RoxyProxy:
    • Accepts the tunnel
    • Generates a per-domain certificate signed by the CA on the fly
    • Terminates TLS with the client using the generated cert
    • Opens a separate TLS connection to the real server
    • Forwards traffic in both directions, capturing it along the way

Setup

Step 1: Start the proxy

This generates the CA certificate if it does not already exist.

roxyproxy start

Step 2: Trust the CA certificate

roxyproxy trust-ca

This runs the platform-specific trust command. See the table below for details on each platform.

Step 3: Route HTTPS traffic through the proxy

# Via explicit proxy flag
curl -x http://127.0.0.1:8080 https://api.example.com/data

# Or enable system-wide proxy (macOS)
roxyproxy proxy-on

Platform-Specific Trust

Platform What happens
macOS Adds to System Keychain via security add-trusted-cert (requires sudo)
Linux Copies to /usr/local/share/ca-certificates/ and runs update-ca-certificates (requires sudo)
Firefox Must be done manually: Settings > Privacy & Security > Certificates > View Certificates > Import ~/.roxyproxy/ca/ca.crt

Certificate Details

Property Value
CA location ~/.roxyproxy/ca/ca.crt and ca.key
CA validity 10 years
CA subject "RoxyProxy CA"
Per-domain cert validity 1 year
Key size 2048-bit RSA
Signature algorithm SHA-256
Domain cert cache LRU, default 500 entries (configurable)

iOS Device Inspection

RoxyProxy can inspect HTTP/HTTPS traffic from an iOS device. Your computer and iOS device must be on the same Wi-Fi network.

Step 1: Start RoxyProxy on your computer

roxyproxy start

Step 2: Note your computer's network address

The CLI prints a Network line on startup with your hostname, for example:

  ● Network  http://robins-macbook.local:8081

You can also find your IP manually:

ipconfig getifaddr en0    # macOS
hostname -I | awk '{print $1}'  # Linux

Step 3: Configure the iOS device to use the proxy

  1. Open Settings > Wi-Fi
  2. Tap the (i) icon next to your connected network
  3. Scroll down and tap Configure Proxy
  4. Select Manual
  5. Set Server to your computer's hostname or IP (e.g. robins-macbook.local or 192.168.1.42)
  6. Set Port to 8080
  7. Tap Save

HTTP traffic is now being captured. For HTTPS inspection, continue with the steps below.

Step 4: Install the CA certificate on iOS

Open Safari on your iOS device and navigate to the network address shown in the CLI or web UI:

http://robins-macbook.local:8081/api/ca.crt

Or use the IP directly: http://192.168.1.42:8081/api/ca.crt

You can also open the web UI and tap the CA Cert link in the toolbar. Safari will prompt you to download a configuration profile. Tap Allow.

Step 5: Install the profile

  1. Open Settings > General > VPN & Device Management (or Profiles & Device Management on older iOS)
  2. Tap the RoxyProxy CA profile
  3. Tap Install and enter your passcode

Step 6: Enable full trust for the certificate

  1. Open Settings > General > About > Certificate Trust Settings
  2. Toggle Enable Full Trust for RoxyProxy CA
  3. Tap Continue on the warning dialog

HTTPS traffic from the iOS device is now fully inspectable through RoxyProxy.

Viewing traffic

Open the web UI from any browser:

http://<your-computer-ip>:8081

Or use the CLI:

roxyproxy requests --tail

Cleanup

When you are done inspecting, remove the proxy from iOS:

  1. Settings > Wi-Fi > (i) > Configure Proxy > Off
  2. Optionally remove the CA profile: Settings > General > VPN & Device Management > RoxyProxy CA > Remove Profile

On your computer, you can uninstall the CA certificate from your system trust store:

roxyproxy uninstall-ca
← Configuration AI Agent Plugin →