External proxy: route HTTPeep traffic upstream

Configure HTTPeep to forward traffic through a corporate proxy or chain it with tools like Burp Suite for security testing workflows.

An external proxy (also called an upstream or downstream proxy) is a second proxy that HTTPeep routes traffic through after it has processed it locally. By default, HTTPeep forwards requests directly to their destination servers. When an external proxy is configured, HTTPeep sends those requests to the upstream proxy instead, which then forwards them onward.

This lets you place HTTPeep in front of another tool in the network path — or behind a corporate gateway that requires all outbound traffic to pass through it.

Common use cases

Corporate proxy environments

Many organizations require all internet traffic to route through a central proxy for security monitoring and access control. Configure HTTPeep's external proxy setting to pass your traffic through the corporate gateway so HTTPeep and the rest of your tooling work correctly on the corporate network.

Security testing with Burp Suite

Chain HTTPeep with Burp Suite (or another security testing proxy) to get HTTPeep's rule engine and traffic visualization while Burp Suite performs vulnerability scanning and manual testing. HTTPeep captures and modifies traffic first, then forwards it to Burp Suite's listener.

How upstream routing works

When an external proxy is configured, the traffic path becomes:

Your app → HTTPeep → External proxy → Destination server

HTTPeep applies all its normal rules, logging, and decryption before passing the request to the external proxy. The external proxy then handles the final leg of the connection. This means you get full visibility and rule control in HTTPeep, plus whatever the upstream proxy provides.

Configuring the external proxy

Go to Settings → Proxy (or the External Proxy section in the settings panel).

Toggle Use external proxy on.

Enter the upstream proxy's host and port, for example http://proxy.corp.example.com:8080 or http://127.0.0.1:8080 for a local tool like Burp Suite.

If your upstream proxy requires a username and password, enter them in the Proxy username and Proxy password fields.

Click Save. HTTPeep applies the setting immediately — no restart required.

Edit ~/.httpeep/rules/external_proxy.yaml directly:

enabled: true
host: proxy.corp.example.com
port: 8080
protocol: http      # http or https
auth:
  username: ""      # Leave empty if authentication is not required
  password: ""

For a local Burp Suite instance listening on port 8080:

enabled: true
host: 127.0.0.1
port: 8080
protocol: http
auth:
  username: ""
  password: ""

HTTPeep watches the file for changes and reloads it automatically.

Chaining with Burp Suite

To use HTTPeep and Burp Suite together for security testing:

Launch Burp Suite and confirm its proxy listener is running. By default it listens on 127.0.0.1:8080.

Set HTTPeep's external proxy to http://127.0.0.1:8080. HTTPeep will forward all traffic to Burp Suite after applying its own rules.

Configure your browser or application to use HTTPeep's proxy address (by default http://localhost:8080). Do not point it directly at Burp Suite.

Traffic flows through HTTPeep first — you can apply mocking, delays, or rewrites — and then reaches Burp Suite for security analysis. Both tools show the same requests.

When chaining with Burp Suite, you need to trust Burp Suite's CA certificate in your browser or application separately. HTTPeep handles the TLS layer on its end; Burp Suite establishes its own TLS connection for the leg it controls.

MCP control

You can read and update the external proxy configuration programmatically using the httpeep.upstream_* MCP tools. This is useful for AI agents or scripts that need to switch proxy configurations dynamically:

httpeep.upstream_get       — Get the current external proxy configuration
httpeep.upstream_set       — Set the external proxy host, port, and credentials
httpeep.upstream_enable    — Enable the external proxy without changing its settings
httpeep.upstream_disable   — Disable the external proxy without removing its settings

For the complete MCP tools reference, see MCP tools reference.

Disabling the external proxy

To stop routing through the upstream proxy, toggle Use external proxy off in the GUI, or set enabled: false in external_proxy.yaml:

enabled: false
host: proxy.corp.example.com
port: 8080
protocol: http
auth:
  username: ""
  password: ""

The proxy address is preserved so you can re-enable it without re-entering the details.

If you work across multiple environments (for example, on a corporate network some days and off it other days), keep the external proxy configured but toggle it on and off as needed. You can also automate this with the MCP tools in a shell alias or startup script.