mitmproxy

mitmproxy is a widely used interactive HTTPS proxy for security testing and debugging.

With over 42,100 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 handles 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:

• Widely used 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

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

Frequently Asked Questions