mitmproxy — The Interactive HTTPS Proxy for Debugging and Reverse Engineering

Introduction

mitmproxy is the Swiss-army knife of HTTP debugging. Built by Aldo Cortesi and a large contributor base, it sits between your device and the internet, decrypts HTTPS (if you install its CA), and shows every request/response. You can edit them on the fly, replay them, or script reactions in Python.

With over 43,000 GitHub stars, mitmproxy is used by mobile developers (to inspect app traffic), QA teams (to simulate slow/broken networks), security researchers (to reverse-engineer protocols), and anyone who's ever muttered "what is this API actually sending?"

What mitmproxy Does

mitmproxy is an HTTP/HTTPS/HTTP2/WebSocket proxy. Clients connect through it; for HTTPS, it presents a certificate signed by its own CA (which you install on the client), decrypts traffic, re-encrypts to the origin. The TUI/WebUI shows every flow; addons (Python scripts) react to events like request/response/websocket_message.

Architecture Overview

[Client] ----HTTP(S)---> [mitmproxy] ----HTTP(S)----> [Origin]
                             |
                          [Certificate Authority]
                             |
                  +----------+---------+
                  |          |         |
              mitmproxy   mitmweb   mitmdump
                TUI       Web UI    headless CLI
                  |
              [Addon API (Python)]
                def request(flow): ...
                def response(flow): ...
                def websocket_message(flow): ...
                  |
              [Flows + filters]
                modify, replay, replicate, dump

Self-Hosting & Configuration

# myaddon.py — inject a custom header into every outbound request
class AuthInjector:
    def request(self, flow):
        flow.request.headers["X-Debug-User"] = "alice"
        if flow.request.pretty_url.startswith("https://api.example.com/"):
            flow.request.headers["Authorization"] = "Bearer debug-token"

addons = [AuthInjector()]

# Run with custom addon
mitmproxy -s myaddon.py

# Transparent proxy (iptables-based) for mobile testing
mitmproxy --mode transparent --showhost --set block_global=false

# SOCKS5 mode
mitmproxy --mode socks5

# Replay saved flows
mitmdump -n -r traffic.mitm -s myaddon.py

Key Features

• Interactive TUI — keyboard-driven flow inspection and editing
• Web UI — share-friendly browser interface via mitmweb
• HTTPS interception — via installable CA certificate
• HTTP/2 + WebSocket — full modern protocol support
• Flow editing + replay — modify any part of a request/response, replay
• Python addons — hook every event for scripted modifications
• Match filters — BPF-like expressions to focus on relevant traffic
• Modes — regular, transparent, reverse, upstream, SOCKS5, WireGuard

Comparison with Similar Tools

FAQ

Q: How do I intercept HTTPS from an iPhone app? A: 1) Run mitmproxy; 2) On the phone, set the Wi-Fi HTTP proxy to your laptop; 3) Visit mitm.it and install + trust the mitmproxy CA; 4) Enable the cert in Settings -> General -> About -> Certificate Trust. Some apps pin certificates and block the proxy — those need extra work (Frida, patched APK).

Q: Is mitmproxy hard to use in CI? A: Not with mitmdump. Pipe traffic through it headless, use a Python addon to assert requests look right, and dump to a file for artifact inspection.

Q: mitmproxy vs Charles? A: Charles has a polished GUI and is the macOS/Windows dev darling. mitmproxy is open, scriptable (Python addons), and runs in terminals + CI. Pick Charles for interactive visual debugging; mitmproxy for automation and security work.

Q: Can mitmproxy decrypt traffic without installing a CA? A: No — that would defeat the point of TLS. Installing the mitmproxy CA is what allows decryption. Remove it after your debugging session to avoid leaving a trust-store risk.

Sources

• GitHub: https://github.com/mitmproxy/mitmproxy
• Website: https://mitmproxy.org
• License: MIT