Mitmproxy
@magistr/mitmproxyv2026.10.25.10
01README
Install, run and inspect a local mitmproxy (HTTP/HTTPS intercepting proxy) from swamp.
Model @magistr/mitmproxy:
install—uv tool install --no-build mitmproxy(wheels only)status— version, process, listener and CA certificate statestart— run mitmdump or mitmweb in the background (idempotent)stop— stop the background proxy (idempotent)flows— summarise captured flows, filtered by a mitmproxy filter expressionclear_flows— empty the capture filetrust_ca— trust the mitmproxy CA in the macOS login keychain
Flows stream to <stateDir>/flows.mitm and are read back through
mitmdump's built-in HAR export, so no Python addon is required.
02Release Notes
2026.10.25.10
- Repo-wide republish; no functional change.
03Behaviors
@magistr/mitmproxyv2026.10.25.10extensions/models/mitmproxy.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| binDir? | string | Directory holding mitmdump/mitmweb. Default: ~/.local/bin if present, |
| confdir? | string | mitmproxy confdir (CA certificates). Default: ~/.mitmproxy |
| stateDir? | string | Where the pid file, log and flow capture live. Default: |
| listenHost? | string | Proxy listen address |
| listenPort? | number | Proxy listen port |
| mode? | string | mitmproxy --mode: regular, socks5, upstream:URL, reverse:URL, |
| ui? | enum | dump runs headless mitmdump; web runs mitmweb with its browser UI |
| webHost? | string | mitmweb UI address |
| webPort? | number | mitmweb UI port |
| options? | preprocess | Extra mitmproxy options passed as --set key=value |
fn install(python?: string, version?: string, upgrade?: boolean)
Install mitmproxy with `uv tool install --no-build`
| Argument | Type | Description |
|---|---|---|
| python? | string | Python version uv uses for the tool venv (must have mitmproxy wheels) |
| version? | string | Pin a mitmproxy version; default is the latest |
| upgrade? | boolean | Reinstall even when mitmproxy is already present |
fn status()
Read installed version, process, listener and CA state.
fn start(timeoutSeconds?: number)
Start mitmdump (ui=dump) or mitmweb (ui=web) in the
| Argument | Type | Description |
|---|---|---|
| timeoutSeconds? | number | How long to wait for the proxy port to accept connections |
fn stop(timeoutSeconds?: number)
Stop the background proxy started by `start`. No-op when
| Argument | Type | Description |
|---|---|---|
| timeoutSeconds? | number | Grace period after SIGTERM before SIGKILL |
fn flows(filter?: string, limit?: number, includeHeaders?: boolean)
Summarise captured flows (method, URL, status, size,
| Argument | Type | Description |
|---|---|---|
| filter? | string | mitmproxy filter expression, e.g. '~d example.com & ~m POST' |
| limit? | number | Keep only the newest N matching flows |
| includeHeaders? | boolean | Include request/response headers in each flow |
fn clear_flows()
Delete the flow capture file. Refuses while the proxy
fn trust_ca()
Trust the mitmproxy CA certificate in the macOS login
Resources
installation(infinite)— Installed mitmproxy version
status(infinite)— Proxy process, listener and CA certificate state
flows(infinite)— Summary of captured flows
04Previous Versions
2026.10.21.2MIT
2026.10.21.2
Fixed
- Option keys must start with a letter.
__proto__was accepted, then silently dropped. Keys containing digits, such ashttp2, are now accepted.
05Stats
A
100 / 100
Downloads
5
Archive size
13.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace06Platforms
07Labels