mitmproxy

mitmproxy is the industry-standard interactive HTTPS proxy for security testing and debugging. With over 42,300 GitHub stars, it has become essential infrastructure for mobile app security researchers, API testers, and privacy advocates who need visibility into encrypted web traffic. The tool functions as a swiss-army knife for intercepting, inspecting, and modifying network communications.

Released as free and open source under the MIT license, mitmproxy offers three interfaces: an interactive console (mitmproxy), a web-based UI (mitmweb) that resembles Chrome DevTools, and a command-line tool (mitmdump) for scripting and automation. This flexibility makes it suitable for both manual security testing and automated analysis pipelines.

What is mitmproxy?

mitmproxy is an SSL/TLS-capable intercepting proxy that sits between clients and servers, decrypting and re-encrypting traffic to provide full visibility. The basic idea is to pretend to be the server to the client, and pretend to be the client to the server, while sitting in the middle decoding traffic from both sides.

To achieve HTTPS interception, mitmproxy generates a Certificate Authority (CA) certificate which you install on your device. This CA certificate is used to sign other certificates on-the-fly, making the intercepted traffic appear trusted to your browser or application. Once configured, all HTTP and HTTPS requests and responses flow through mitmproxy where you can inspect headers, bodies, and timing information.

The tool supports modern protocols including HTTP/2, HTTP/3 (QUIC), and WebSockets, ensuring compatibility with contemporary mobile apps and web services. It handles TLS 1.2 and 1.3, certificate pinning scenarios (when combined with bypass tools), and various authentication schemes.

Key features

Mobile App Traffic Analysis

mitmproxy is essential for mobile app security testing. Configure your Android or iOS device to use mitmproxy as its HTTP proxy, and all app traffic becomes visible. This reveals API endpoints, authentication tokens, data formats, and encryption usage.

For modern mobile platforms, there’s an important caveat: Since Android 7.0 (API 24) and recent iOS versions, apps only trust system-level CA certificates by default. User-installed certificates like the one mitmproxy generates are ignored. To work around this, you can:

• Make apps debuggable and patch network security config (Android)
• Use Objection or Frida to disable certificate validation
• Install mitmproxy’s certificate as a system certificate (requires root/jailbreak)

Once configured, you can inspect API calls to find hardcoded credentials, identify insecure endpoints, test for injection vulnerabilities, and understand data flow.

Three Interface Options

mitmproxy (console): A terminal-based interface with keyboard-driven navigation. Fast and efficient for experienced users who prefer command-line workflows. Ideal for remote servers or resource-constrained environments.

mitmweb: A web interface that looks and feels like Chrome DevTools. Point your browser at mitmproxy’s web UI port to get a graphical view of all traffic. Best for beginners and when you need to share findings with non-technical stakeholders.

mitmdump: A command-line tool that prints traffic to stdout or logs it to files. Perfect for automated testing, CI/CD integration, or processing large traffic captures with custom scripts.

Scripting and Automation

mitmproxy’s Python API enables powerful automation. Write scripts (called addons) that react to events like request received, response received, or error occurred. Use these hooks to:

• Automatically modify requests (inject headers, change parameters)
• Log specific traffic patterns to databases
• Trigger alerts when sensitive data appears in traffic
• Implement custom authentication or session handling
• Generate reports from captured traffic

Scripts can be loaded via --scripts parameter, making it easy to build reusable testing tools tailored to your organization’s needs.

Integration with Mobile Testing Tools

mitmproxy integrates seamlessly with other mobile security tools. A typical workflow:

1. Decompile the app with Jadx to understand structure
2. Use Objection or Frida to bypass SSL pinning
3. Route traffic through mitmproxy to inspect API calls
4. Identify interesting endpoints and parameters
5. Replay and modify requests to test for vulnerabilities

This combination provides comprehensive coverage from static analysis through dynamic testing to runtime manipulation.

Transparent Proxy Mode

For scenarios where configuring explicit proxy settings isn’t feasible, mitmproxy supports transparent mode. Using iptables or pf rules, you can redirect traffic to mitmproxy without application awareness. This is useful for analyzing apps that don’t respect system proxy settings or for capturing all device traffic simultaneously.

When to use mitmproxy

Strengths:

• Industry-standard tool with extensive documentation and community
• Completely free and open source with permissive MIT license
• Excellent protocol support including modern HTTP/2, HTTP/3, WebSockets
• Flexible interfaces (console, web, command-line) for different use cases
• Powerful Python scripting for automation and customization
• Active development with regular updates
• Cross-platform (Windows, macOS, Linux)
• Low resource usage compared to heavyweight proxy alternatives

Limitations:

• Requires CA certificate installation on target devices
• Modern mobile OSes require additional steps for user certificate trust
• Cannot bypass SSL pinning alone (needs Frida/Objection integration)
• Learning curve for advanced features and scripting
• Terminal-based interface may be unfamiliar to GUI-preferring users

Getting started

Install mitmproxy via package managers:

# macOS
brew install mitmproxy

# Linux
apt install mitmproxy  # or pip install mitmproxy

# Windows
pip install mitmproxy

Start the web interface:

mitmweb

Configure your mobile device:

1. Set device Wi-Fi proxy to your computer’s IP on port 8080
2. Browse to mitm.it on the device to download the CA certificate
3. Install the certificate (iOS: Settings > General > VPN & Device Management; Android: Settings > Security > Encryption & Credentials)
4. For Android 7+, make target app debuggable or use Objection to bypass certificate validation

Launch the app and observe traffic in mitmweb’s interface. Click any request to view headers, body, and timing. Use the filter bar to focus on specific domains or endpoints.

For advanced usage, combine with Frida scripts for SSL unpinning, Objection for automated app patching, and Burp Suite for comprehensive web application testing that extends beyond simple interception.

Extensive tutorials are available on the official mitmproxy documentation, including guides for Android app traffic inspection, transparent proxy setup, and Python scripting examples.

Frequently Asked Questions