mitmproxy

mitmproxy is a free and open-source interactive console tool, web interface, and Python library designed for intercepting, inspecting, modifying, and replaying HTTP/S traffic. It serves as a powerful man-in-the-middle proxy for developers, security researchers, and QA engineers working with web applications, APIs, and mobile traffic.

Overview of mitmproxy

mitmproxy operates as a proxy server, positioned between a client and a target server. All HTTP and HTTPS traffic flowing through the proxy can be viewed, filtered, and manipulated in real-time. Its core functionality enables deep inspection of request and response headers, bodies, and other attributes. The tool suite includes:

• mitmproxy: An interactive terminal interface for real-time traffic analysis.
• mitmweb: A browser-based graphical user interface offering similar functionality to mitmproxy but accessible via a web browser.
• mitmdump: A command-line tool for programmatic modification and logging of traffic, suitable for scripting and automation.

Key Features

SSL/TLS Interception

mitmproxy generates its own SSL/TLS certificates on the fly, allowing it to decrypt and inspect encrypted HTTPS traffic. This requires the client to trust the mitmproxy CA certificate.

Interactive Interface

Both mitmproxy and mitmweb provide interactive environments to view and manage traffic flows. Users can filter flows, search content, edit requests/responses, and mark specific flows for later analysis.

Traffic Modification

Requests and responses can be modified on the fly using the interactive interface or through Python scripts. This enables testing edge cases, injecting headers, altering data, or simulating different server responses.

Replay Functionality

mitmproxy supports replaying recorded client requests to a server or replaying server responses to a client. This is useful for testing specific scenarios without re-executing client actions or for simulating server behavior.

Scripting and Automation

mitmdump provides a Python API for developing custom scripts. These scripts can programmatically inspect, modify, redirect, or drop traffic based on defined logic, facilitating automated testing and complex traffic manipulation.

Transparent Proxy Mode

mitmproxy can operate in a transparent proxy mode, where clients do not need explicit proxy configuration. Network traffic is redirected to mitmproxy at the network layer, often via router rules or firewall configurations.

Installation

mitmproxy can be installed using pip:

pip install mitmproxy

For specific operating systems, pre-compiled binaries are available from the official mitmproxy website, or it can be installed via package managers like Homebrew on macOS.

Basic Usage

Starting mitmproxy

To start the interactive console interface:

mitmproxy

To start the web interface:

mitmweb

By default, mitmproxy listens on localhost:8080.

Client Configuration

Clients must be configured to use mitmproxy as their HTTP/S proxy.

Browser Example (Firefox):
1. Open Firefox settings.
2. Navigate to Network Settings or Proxy Settings.
3. Select "Manual proxy configuration".
4. Set HTTP Proxy to 127.0.0.1 and Port to 8080.
5. Set SSL Proxy to 127.0.0.1 and Port to 8080.
6. Ensure "Use this proxy server for all protocols" is checked or configure other protocols similarly.

Operating System (macOS):
1. Go to System Settings > Network > Wi-Fi > Details.
2. Select "Proxies".
3. Enable "Web Proxy (HTTP)" and "Secure Web Proxy (HTTPS)".
4. Set Server to 127.0.0.1 and Port to 8080 for both.

SSL/TLS Certificate Installation

To decrypt HTTPS traffic, clients must trust the mitmproxy CA certificate.
1. With mitmproxy running, navigate a configured client's browser to http://mitm.it.
2. Download and install the appropriate CA certificate for the client's operating system or browser.
3. For systems like Android or iOS, specific installation steps are required, often involving downloading the certificate and manually trusting it in security settings.

Advanced Usage

Modifying Requests and Responses

From the mitmproxy or mitmweb interface:
1. Select a flow.
2. Press e (edit) to modify the request or response.
3. Select the component to edit (e.g., headers, body, URL).
4. Make changes and press q to save and continue the flow.

Scripting with mitmdump

Python scripts can be passed to mitmdump to automate traffic manipulation.

Example: Modifying a request header

modify_header.py:

from mitmproxy import http

def request(flow: http.HTTPFlow):
    if "example.com" in flow.request.pretty_host:
        flow.request.headers["X-Modified-By"] = "mitmproxy-script"
        print(f"Modified header for {flow.request.url}")

Run with mitmdump:

mitmdump -s modify_header.py

This script adds a custom header X-Modified-By to requests targeting example.com.

Example: Modifying a response body

modify_response.py:

from mitmproxy import http

def response(flow: http.HTTPFlow):
    if "api.example.com/data" in flow.request.url and flow.response.content:
        # Assuming the response is JSON
        data = flow.response.json()
        data["status"] = "modified_by_mitmproxy"
        flow.response.set_json(data)
        print(f"Modified response body for {flow.request.url}")

Run with mitmdump:

mitmdump -s modify_response.py

This script intercepts responses from api.example.com/data, parses them as JSON, modifies a field, and sends the modified JSON back to the client.

Replaying Flows

mitmproxy allows replaying captured HTTP flows.

Replay Client Request:
1. In mitmproxy or mitmweb, select a flow.
2. Press r to replay the client request to the server. This re-sends the exact request without client interaction.

Replay Server Response:
1. Select a flow.
2. Press R (shift+r) to replay the server response to the client. This sends the recorded server response back to the client, bypassing the actual server interaction. Useful for testing client-side behavior with specific server responses.

Use Cases

• API Development and Debugging: Inspecting requests and responses to understand API behavior, validate data formats, and debug integration issues.
• Security Testing: Identifying vulnerabilities by manipulating requests (e.g., injecting SQL, XSS payloads), testing authentication mechanisms, and analyzing encrypted traffic.
• Mobile Application Analysis: Intercepting and analyzing traffic from mobile applications to understand their backend communication, data handling, and potential security flaws.
• Reverse Engineering: Deconstructing proprietary protocols or understanding how applications interact with remote servers by observing their network communications.
• Automated Testing: Using mitmdump scripts to simulate specific network conditions, mock API responses, or perform automated checks on application behavior.

mitmproxy vs. Other Proxy Tools

While several tools offer HTTP/S interception, mitmproxy differentiates itself with its open-source nature, powerful scriptability, and flexible interfaces.

Feature	mitmproxy	Burp Suite Community Edition	Fiddler (Windows)
License	Open Source (MIT)	Proprietary (Free/Paid Tiers)	Proprietary (Free/Paid Tiers)
Scriptability	Python API (mitmdump)	Limited (Extensions via Java/Python/Ruby)	FiddlerScript (JScript.NET), .NET Extensions
Interface	Console (mitmproxy), Web UI (mitmweb)	Desktop GUI	Desktop GUI
SSL/TLS	Full interception	Full interception	Full interception
Traffic Mod.	Yes	Yes	Yes
Replay	Yes (client/server)	Yes (Repeater)	Yes (Composer)
Transparent P.	Yes	Yes	Yes
Target Audience	Developers, security researchers, automation	Penetration testers, web app security	Developers, testers, web app security
Platform	Cross-platform (Linux, macOS, Windows)	Cross-platform (Java-based)	Windows, macOS (via Fiddler Everywhere)

This comparison highlights mitmproxy's strengths in automation and open-source flexibility, making it a robust choice for technical users requiring deep control over their traffic analysis workflows.