mitmproxy — Intercepting Proxy for Real Traffic Debugging
General Information
mitmproxy is one of those tools engineers keep around when network behavior just doesn’t make sense. It’s an intercepting proxy that sits in the middle of client and server traffic, letting administrators and testers see, change, or replay requests as they happen. Unlike packet captures, which only show raw flows, mitmproxy works higher up the stack, showing exactly what the browser, mobile app, or service is sending and receiving. For troubleshooting encrypted APIs, it’s often the most straightforward option.
How It Works
The proxy runs as a middle layer. Once the client is pointed to mitmproxy and its generated root certificate is installed, it can decrypt TLS traffic. Requests and responses are then displayed in real time through a text interface, a browser dashboard, or a command-line tool. Traffic can be filtered, edited, or saved for replay. It supports multiple modes — forward, reverse, transparent, and even WireGuard-based tunneling — so it can be placed where it’s most convenient in the network path.
Functions
Feature | Description |
Protocols | Supports HTTP/1, HTTP/2, WebSockets, and newer versions like HTTP/3. |
Interfaces | Text console, web dashboard, and CLI replay tool. |
Interception | Inspect, modify, or block traffic in real time. |
Replay | Save flows and resend them against test or staging systems. |
Scripting | Extend behavior using Python add-ons. |
Operation Modes | Forward proxy, reverse proxy, transparent, or WireGuard capture. |
Configuration | Live option changes with YAML-based persistent settings. |
Installation Guide
– Windows: download the installer package and run it, the proxy is added to PATH.
– macOS: most teams prefer `brew install mitmproxy` for a quick setup.
– Linux: use distribution packages or fetch prebuilt binaries; Docker images are also available.
After installation, clients are pointed to mitmproxy as their proxy and the generated certificate is added to the trust store. This enables full HTTPS inspection.
Everyday Use
In practice, mitmproxy is used to debug broken API calls, reproduce errors that only appear in production, or check how applications behave under altered responses. Security teams employ it to understand how mobile apps handle certificates, headers, or payloads. Developers often keep it on hand to replay captured flows into staging while testing new releases.
Limitations
It’s not meant for passive monitoring at high throughput — performance drops if placed inline for too much traffic. Applications that use certificate pinning won’t pass through unless patched or bypassed. Setting up trust stores across many devices can also be a challenge in large environments.
Comparison
Tool | Platforms | Strengths | Typical Use Case |
mitmproxy | Multi-platform | Lightweight, scriptable, handles HTTP/3 | Debugging and controlled testing |
Burp Suite | Multi-platform | Broad security testing toolkit | Penetration testing, manual research |
OWASP ZAP | Multi-platform | Free proxy with automated scanning features | DAST and occasional proxying |