mitmproxy

mitmproxy is a suite of tools for intercepting and inspecting HTTP/1, HTTP/2, and WebSockets traffic. It is SSL/TLS-capable and provides three different interfaces depending on your needs:

• mitmproxy: An interactive proxy with a console-based interface.
• mitmdump: A command-line version designed for headless use (similar to tcpdump but for HTTP).
• mitmweb: A web-based user interface for inspecting traffic.

mitmproxy provides an interactive, SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2, and WebSockets. The project consists of three different front-ends that all expose the same underlying core proxy functionality:

• mitmproxy: An interactive console interface for examining and modifying HTTP traffic. It keeps all flows in memory, making it suitable for small-to-medium samples. Use the ? shortcut key for context-sensitive documentation within the UI.
• mitmweb: A web-based user interface for interactive examination and modification of HTTP traffic. Like the console version, it keeps flows in memory. (Note: mitmweb is currently in beta).
• mitmdump: A command-line version designed for high-performance viewing, recording, and programmatic transformation of traffic (similar to tcpdump for HTTP).

mitmproxy supports several modes to capture traffic depending on your network topology and device access:

Recommended Modes:

• Regular Proxy: Default mode. Client is configured to use an HTTP(S) proxy (e.g., localhost:8080).
• Local Capture: Intercepts traffic from processes on the same machine.
• WireGuard: Acts as a VPN server for external devices.
• Reverse Proxy: Places mitmproxy in front of a specific server.

Advanced Modes:

• Transparent Proxy: Uses custom network routes.
• TUN Interface: Creates a virtual network device.
• Upstream Proxy: Chains mitmproxy with another HTTP(S) proxy.
• SOCKS Proxy: Runs a SOCKS5 proxy server.
• DNS Server: Runs a scriptable DNS server.

Mitmproxy provides two mechanisms to maintain session state during replay or scripted interactions:

Sticky Authentication (stickyauth)

When stickyauth is enabled, mitmproxy replays the HTTP Authorization header to the server once it has been seen. This allows access to resources using HTTP Basic authentication. (Note: HTTP Digest authentication is not yet supported).

Sticky Cookies (stickycookie)

When stickycookie is enabled, mitmproxy automatically adds the most recently set server cookie to any subsequent cookie-less requests. This is useful for scripting interactions with authenticated resources (e.g., via curl or wget) after a manual authentication session has been recorded.

On its first run, mitmproxy generates a unique CA in its configuration directory (default: ~/.mitmproxy). This CA is used to generate on-the-fly certificates for intercepted websites. Because the CA is unique to each installation, it cannot be shared between devices.

Key files generated in the config directory:

The server_replay option allows mitmproxy to replay server responses from saved HTTP conversations.

Matching Heuristics

By default, mitmproxy matches incoming requests to saved responses using only the URL and request method. Request headers are excluded from the matching process by default, which allows replaying responses even when headers (like User-Agent) vary. You can customize this matching via options prefixed with server_replay_.

Response Refreshing

To prevent issues like expired cookies or outdated timestamps, mitmproxy refreshes server responses by default. It updates the date, expires, and last-modified headers to maintain the same relative time offset they had during the original recording.

To disable this automatic refreshing, set the server_replay_refresh option to false.

mitmproxy uses filter expressions to select specific flows (requests and responses).

Key rules for constructing expressions:

• Default Matching: A string with no operators is matched against the request URL.
• Regexes: Use Python-style regexes. They can be specified as quoted strings and are case-insensitive by default. To enable case-sensitivity, set the environment variable MITMPROXY_CASE_SENSITIVE_FILTERS=1.
• Binary Operators: The default binary operator is & (AND).
• Header Matching: Use operators like ~h (header), ~hq (header query), or ~hs (header status) to match against strings in the format "name: value".
• Negation: Use ! to negate an expression.

By default, when mitmproxy receives a TLS ClientHello, it connects to the upstream server first to "sniff" its certificate (extracting the Common Name, Organization, and Subject Alternative Names). Mitmproxy then uses this information to generate a forged interception certificate signed by the mitmproxy CA, which is then presented to the client.

To disable this behavior, turn the upstream_cert option off.

Many mitmproxy commands accept flows as arguments. Instead of providing individual flow IDs, you can use mitmproxy's flow specification language (filters) to select flows. The command will intelligently expand these specifications into a list of flows.

Common specifiers include:

• @focus: The currently focused flow.
• @all: All flows in the current session.
• ~d <domain>: Flows matching a specific domain.

Example usage in the mitmproxy console (using the : prompt):

# Replay only the currently focused flow
:replay.client @focus

# Replay all flows
:replay.client @all

# Replay flows for a specific domain
:replay.client "~d google.com"

mitmproxy uses a custom DNS implementation.

Known Limitations:

• Replay: Neither client nor server replay is supported.
• Encrypted DNS: Support for DoT (DNS-over-TLS), DoH (DNS-over-HTTPS), and DoQ (DNS-over-QUIC) is not yet implemented.