ForgeProxy

A self-hosted intercepting proxy + packet-forging workbench for testing software in a controlled test environment. (GUI) + SQLite (flow store). Scope is locked to loopback + declared test domains by default — this is a test-harness, not a live-traffic tool.

Quickstart (Windows)

# 1. Create the venv and install the package (editable) + dev deps
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

# 2. Launch the GUI — either the console command or the script
.\.venv\Scripts\forgeproxy.exe
# or:  .\.venv\Scripts\python.exe run.py

# 3. Run the tests
.\.venv\Scripts\python.exe -m pytest

The ten tabs

Flows (live capture + export/replay a session) · Intercept (pause/edit/forward) · Mocks (fake responses) · Forge (craft requests — variables, signature hooks, codecs, validate/preview/diff, protobuf decode↔encode) · Sequence (chained multi-step requests with capture feed-forward) · Scope / Settings · Timeline (rate/burst pacing + last-byte & single-packet race modes on a Gantt strip) · Fuzzer (sniper/pitchfork/clusterbomb) · WebSocket (frame view) · Scripts (live Python addon console: on_request/on_response/on_websocket).

Using it

1. In Scope / Settings, set the listen port (default 127.0.0.1:8080) and add your test domains to the allowlist. Click Apply settings.
2. Click Start proxy on the Flows tab.
3. Point a throwaway test client at http://127.0.0.1:8080.
4. For HTTPS, install ~/.mitmproxy/mitmproxy-ca-cert.pem into that client's trust store only. This CA can decrypt any TLS that trusts it — keep it off any machine you care about.

Route a browser through ForgeProxy (like Burp)

Same three steps as Burp: start the proxy, point the browser at it, install the CA.

1. Start the proxy. Flows tab → Start proxy (listens on 127.0.0.1:8080). Leave scope on tag (the default) for general browsing — every site loads and off-allowlist hosts are just flagged red; block mode instead drops everything not on the allowlist.

2. Point the browser at the proxy. Firefox is cleanest (it has its own proxy + cert store, so the rest of your system is untouched):

• Firefox → Settings → Network Settings → Manual proxy: HTTP Proxy 127.0.0.1, Port 8080, tick "Also use this proxy for HTTPS".
• Chrome/Edge use the Windows system proxy (Settings → Network & internet → Proxy → Manual → 127.0.0.1:8080), or launch a throwaway profile: chrome.exe --proxy-server="127.0.0.1:8080" --user-data-dir="%TEMP%\fp-chrome"

http:// sites work immediately — load one and confirm it appears in Flows. HTTPS needs the CA (step 3).

3. Install the CA (for HTTPS). The cert already exists at %USERPROFILE%\.mitmproxy\.

• Easiest: with the proxy running and the browser pointed at it, visit http://mitm.it — mitmproxy serves per-platform install buttons.
• Firefox (own store): Settings → Privacy & Security → View Certificates → Authorities → Import → mitmproxy-ca-cert.pem → check "Trust … to identify websites."
• Chrome/Edge/system: double-click mitmproxy-ca-cert.cer → Install → Trusted Root Certification Authorities, then restart the browser.

Use a dedicated/throwaway browser profile on a test machine, and remove the CA when done

Faking a server response (the headline feature)

Add a rule in the Mocks tab, e.g. short-circuit a license check so the real server is never contacted:

{
  "name": "force-license-valid",
  "enabled": true,
  "match": { "method": "POST", "url_regex": "/api/v\\d/license/verify" },
  "action": {
    "mode": "short_circuit",
    "status": 200,
    "headers": { "Content-Type": "application/json" },
    "body": "{\"valid\":true,\"tier\":\"pro\"}"
  }
}

Modes: short_circuit, rewrite_response, match_and_replace, latency_inject, fault_inject.