Inspecting and Modifying Web Traffic with mitmproxy

When debugging complex network interactions or assessing the security of web applications, developers and penetration testers require deep visibility into the data exchanged between clients and servers. mitmproxy is an open-source toolset specifically designed to provide this level of visibility. It functions as an interactive, SSL/TLS-capable intercepting proxy, allowing users to examine and modify HTTP/1, HTTP/2, and WebSockets traffic in real time.

The project offers three different user-facing tools that expose its core proxy functionality. The primary tool, mitmproxy, provides a detailed console interface for interactively analyzing and manipulating traffic flows directly from the terminal. For users who prefer a graphical interface, mitmweb is a web-based interface for mitmproxy that allows interactive examination of HTTP traffic. Finally, mitmdump is the command-line companion to mitmproxy. It provides tcpdump-like functionality to let you view, record, and programmatically transform HTTP traffic without requiring an interactive session.

Capturing Traffic on the Default Port

To begin capturing and inspecting traffic, you must start the proxy service and direct your client application's requests through it. Mitmproxy starts as a regular HTTP proxy by default and listens on http://localhost:8080.

Once the proxy is running, you will need to configure your web browser, mobile device, or command-line HTTP client to route its outbound traffic through this local address. For inspecting HTTPS traffic securely, you must also install the mitmproxy Certificate Authority on the target client device. This certificate enables the proxy to decrypt, inspect, and seamlessly re-encrypt the encrypted traffic before forwarding it to its final destination.

Recording Flows to a File

If you are diagnosing a difficult issue or need to share specific network interactions with other members of your team, you can record the intercepted traffic to a file for later analysis and debugging. Using the mitmdump tool, you can instruct the proxy to write all captured flows to a specified output file.

This straightforward command starts the proxy daemon and saves every HTTP request and corresponding response directly into the specified outfile. You can then review this file at a later time.

Filtering and Extracting Specific Requests

Large network traffic captures often contain significant background noise, such as routine telemetry data, background synchronization, or static asset requests. You can process an existing capture file to extract only the flows that are relevant to your current task. For instance, if you are investigating form submissions or specific API endpoints, you might want to isolate only the POST requests.

This command reads all network flows from the infile without binding to the proxy port, applies the specified filter expression to match only POST requests, and then writes those matching flows into a new, smaller outfile.

Replaying Client Requests

After capturing a sequence of client requests, you may find it useful to test how a server responds to identical inputs or verify if a backend bug has been successfully resolved. The tools allow you to selectively replay previously recorded client requests directly against the destination server.

By executing this command, mitmdump runs without binding to a local proxy port and simply replays all the requests previously stored in outfile.

Scripting Automated Transformations

For repetitive modifications—such as injecting authentication tokens, modifying headers across multiple requests, or automatically substituting response payloads—you can use Python scripts to programmatically transform the data on the fly.

This command runs an example Python script that automatically adds a custom header to all passing HTTP responses. The robust scripting API provides deep customization of the traffic flow based on your specific programmatic logic.