Mitmproxy

12.2.1 · active · verified Thu Apr 09

Mitmproxy is an interactive, SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2, and WebSockets. It allows developers and security researchers to inspect, modify, and replay network traffic. Currently at version 12.2.1, it receives frequent patch and minor updates, with major versions introducing significant breaking changes less often.

Warnings

breaking Mitmproxy v12.0.0 and later require Python 3.12+. Earlier versions required Python 3.11+ (v9.0.0+) or Python 3.8+ (prior to v9.0.0).
Fix: Ensure your Python environment meets the minimum requirement for your mitmproxy version. Upgrade to Python 3.12 or higher for mitmproxy 12+.
breaking The `flow.request.url` and `flow.response.url` attributes were removed in v9.0.0. Use `flow.request.pretty_url` for display or reconstruct the URL. Similarly, direct access to `flow.request.host` and `flow.request.port` was deprecated.
Fix: Replace `flow.request.url` with `flow.request.pretty_url` (for a user-friendly string) or reconstruct from `flow.request.scheme`, `flow.request.host`, `flow.request.port`, and `flow.request.path`. Use `flow.request.pretty_host` for the host name.
breaking Content attributes (`request.content`, `response.content`) now always return `bytes` or `None` since v6.0.0. Direct assignment of `str` or non-bytes objects will raise an error.
Fix: Ensure you are working with `bytes` for `content`. If you need string representation, explicitly decode (e.g., `flow.response.content.decode('utf-8')`) and encode back before setting (e.g., `b'new content'`).
gotcha Addon methods (like `request`, `response`) must be synchronous. Directly using `async def` will not work. If you need asynchronous operations, use `asyncio.run()` or similar within a synchronous method.
Fix: Rewrite asynchronous logic to be called synchronously, typically by wrapping `await` calls with `asyncio.run()` or using `loop.run_until_complete()` within your synchronous addon method, or run `asyncio.run()` in the main thread outside the addon.
gotcha Clients must explicitly trust the mitmproxy CA certificate to avoid SSL/TLS errors. This is a common setup oversight, leading to `SSL_ERROR_HANDSHAKE_FAILURE` or similar.
Fix: After starting mitmproxy, configure your client to proxy through it, then navigate to `http://mitm.it` through that client to download and install the CA certificate. Refer to the mitmproxy documentation for detailed installation instructions for your specific client/OS.

Install

pip install mitmproxy Install mitmproxy

Imports

HTTPFlow
```
from mitmproxy import http
```
HTTPFlow is now typically accessed via `mitmproxy.http` namespace and often type-hinted directly from there.
Options
```
from mitmproxy import options
```
Global options are directly under the `mitmproxy` namespace via `mitmproxy.options`.
ctx
```
from mitmproxy import ctx
```
The context object (`mitmproxy.ctx`) provides access to global state, logging, and master instance.
Addon
```
from mitmproxy.addonmanager import Addon
```
Base class for type hinting or extending mitmproxy addons, though often not explicitly inherited for simple callback-based addons.

Quickstart

This quickstart demonstrates a basic mitmproxy addon that intercepts and modifies HTTP requests and responses. It adds custom headers for traffic to 'example.com'. To run, save this code as a `.py` file (e.g., `myaddon.py`) and execute `mitmproxy -s myaddon.py` in your terminal, then configure your client to use mitmproxy as a proxy.

import os
from mitmproxy import http

class SimpleModifier:
    def request(self, flow: http.HTTPFlow):
        # Modify all requests to example.com
        if "example.com" in flow.request.pretty_url:
            flow.request.headers["X-Modified-By"] = "Mitmproxy-Addon"
            # To redirect, uncomment and adjust:
            # flow.request.host = "www.google.com"
            # flow.request.port = 443
            # flow.request.scheme = "https"
            
        # Access options via flow.options or mitmproxy.ctx.options
        # print(f"Verbosity: {flow.options.verbosity}")

    def response(self, flow: http.HTTPFlow):
        # Modify all responses from example.com
        if flow.response and "example.com" in flow.request.pretty_url:
            flow.response.headers["X-Response-Modified-By"] = "Mitmproxy-Addon"
            # Modify response content (ensure it's bytes)
            # if flow.response.content:
            #     flow.response.content = flow.response.content.replace(b"example", b"modified")

# To run this addon:
# 1. Save it as e.g., `myaddon.py`
# 2. Run mitmproxy from your terminal: `mitmproxy -s myaddon.py`
# 3. Configure your client (browser, app) to proxy through mitmproxy (default: http://127.0.0.1:8080).
#    For HTTPS, install the mitmproxy CA certificate (navigate to mitm.it from the proxied client).

view raw JSON →