mitmproxy: Intercept and Analyze Web Traffic

Intercepting web traffic is a foundational skill in web application security testing. Whether you’re auditing an API, analyzing how a mobile app communicates, or looking for insecure data transmission, mitmproxy is one of the most powerful and flexible tools available. Unlike heavier GUI-based proxies, mitmproxy runs in the terminal, offers a rich Python scripting API, and handles modern HTTPS traffic with ease.

What Is mitmproxy?

mitmproxy is an open-source interactive HTTPS proxy. It positions itself between a client (browser, app, script) and a server, decrypting TLS traffic so you can inspect, modify, and replay requests in real time. The project ships three interfaces:

• mitmproxy — interactive terminal UI
• mitmweb — browser-based GUI
• mitmdump — non-interactive, scriptable, similar to tcpdump

All three share the same core engine and certificate infrastructure.

Installation

mitmproxy is available on all major platforms.

# Linux / macOS via pip
pip install mitmproxy

# Kali Linux (pre-installed, or update with)
sudo apt update && sudo apt install mitmproxy

# macOS via Homebrew
brew install mitmproxy

# Verify
mitmproxy --version

Certificate Setup — The Critical Step

HTTPS interception requires the client to trust mitmproxy’s self-signed CA certificate. On first run, mitmproxy generates a CA at ~/.mitmproxy/mitmproxy-ca-cert.pem.

Browser / OS trust:

# Start mitmproxy on default port 8080
mitmproxy -p 8080

Then navigate to http://mitm.it from the proxied browser — this page serves the correct certificate for your platform automatically.

Android devices:

Install the certificate via Settings → Security → Install from storage. On Android 7+, user-installed CAs are not trusted by apps by default. You need to either root the device or patch the app’s network_security_config.xml to include user CAs.

iOS devices:

After installing the profile via http://mitm.it, go to Settings → General → About → Certificate Trust Settings and enable full trust.

Basic Usage

Configure your browser or system to use 127.0.0.1:8080 as an HTTP/HTTPS proxy, then launch:

mitmproxy -p 8080

Traffic flows appear in the TUI. Use arrow keys to navigate, Enter to inspect a flow, e to edit a request, and r to replay it. Press ? for the full keybinding list.

To filter flows by domain:

~d example.com

To filter by method:

~m POST

Upstream Proxy Mode

If your target network uses a corporate proxy, you can chain mitmproxy behind it using upstream mode:

mitmproxy --mode upstream:http://corporate-proxy:3128 -p 8080

In this configuration, mitmproxy intercepts traffic from your client, decrypts it, then re-encrypts and forwards it to the upstream proxy. This lets you inspect traffic that would otherwise be opaque.

Transparent Proxy Mode

On Linux, you can intercept traffic from devices on the same network without configuring a proxy on those devices — useful for mobile app testing.

# Enable IP forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# Redirect HTTP and HTTPS traffic to mitmproxy
sudo iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080
sudo iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8080

# Start in transparent mode
sudo mitmproxy --mode transparent -p 8080

The target device’s default gateway must point to your machine.

Scripting with mitmdump

The real power of mitmproxy surfaces when you script it. mitmdump accepts Python addon scripts via the -s flag.

Example: Log all POST request bodies to a file

# log_posts.py
import mitmproxy.http

def request(flow: mitmproxy.http.HTTPFlow):
    if flow.request.method == "POST":
        with open("posts.log", "a") as f:
            f.write(f"[{flow.request.host}] {flow.request.url}\n")
            f.write(flow.request.get_text() + "\n---\n")

Run it:

mitmdump -s log_posts.py -p 8080

Example: Modify responses to inject a header

# inject_header.py
def response(flow):
    flow.response.headers["X-Injected"] = "mitmproxy"

Example: Block requests to analytics domains

BLOCKED = ["analytics.google.com", "doubleclick.net"]

def request(flow):
    if any(d in flow.request.pretty_host for d in BLOCKED):
        flow.kill()

Saving and Replaying Flows

mitmdump can record all traffic to a file for later analysis:

mitmdump -w capture.mitm -p 8080

Replay saved flows against a different host:

mitmdump -nC capture.mitm --modify-headers "/~q/Host/staging.example.com"

Practical Tips

Scenario	Command/Approach
Inspect mobile API	Transparent mode + CA install
Fuzz a specific endpoint	Record flow, replay with modifications
CI/CD traffic audit	mitmdump with JSON export addon
Check for secrets in headers	Script scanning flow.request.headers

Ethical and Legal Reminders

mitmproxy should only be used on systems and networks you own or have explicit written permission to test. Intercepting traffic on networks without authorization violates computer fraud laws in most jurisdictions. Always operate within the defined scope of an authorized engagement.

mitmproxy is an exceptional tool precisely because it makes HTTPS traffic readable — use that power responsibly.