{"id":1557,"library":"mitmproxy","title":"Mitmproxy","description":"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.","status":"active","version":"12.2.1","language":"en","source_language":"en","source_url":"https://github.com/mitmproxy/mitmproxy","tags":["proxy","security","http","https","tls","websockets","network","addon","interception"],"install":[{"cmd":"pip install mitmproxy","lang":"bash","label":"Install mitmproxy"}],"dependencies":[],"imports":[{"note":"HTTPFlow is now typically accessed via `mitmproxy.http` namespace and often type-hinted directly from there.","wrong":"from mitmproxy.flow import HTTPFlow","symbol":"HTTPFlow","correct":"from mitmproxy import http"},{"note":"Global options are directly under the `mitmproxy` namespace via `mitmproxy.options`.","wrong":"from mitmproxy.proxy import options","symbol":"Options","correct":"from mitmproxy import options"},{"note":"The context object (`mitmproxy.ctx`) provides access to global state, logging, and master instance.","symbol":"ctx","correct":"from mitmproxy import ctx"},{"note":"Base class for type hinting or extending mitmproxy addons, though often not explicitly inherited for simple callback-based addons.","symbol":"Addon","correct":"from mitmproxy.addonmanager import Addon"}],"quickstart":{"code":"import os\nfrom mitmproxy import http\n\nclass SimpleModifier:\n    def request(self, flow: http.HTTPFlow):\n        # Modify all requests to example.com\n        if \"example.com\" in flow.request.pretty_url:\n            flow.request.headers[\"X-Modified-By\"] = \"Mitmproxy-Addon\"\n            # To redirect, uncomment and adjust:\n            # flow.request.host = \"www.google.com\"\n            # flow.request.port = 443\n            # flow.request.scheme = \"https\"\n            \n        # Access options via flow.options or mitmproxy.ctx.options\n        # print(f\"Verbosity: {flow.options.verbosity}\")\n\n    def response(self, flow: http.HTTPFlow):\n        # Modify all responses from example.com\n        if flow.response and \"example.com\" in flow.request.pretty_url:\n            flow.response.headers[\"X-Response-Modified-By\"] = \"Mitmproxy-Addon\"\n            # Modify response content (ensure it's bytes)\n            # if flow.response.content:\n            #     flow.response.content = flow.response.content.replace(b\"example\", b\"modified\")\n\n# To run this addon:\n# 1. Save it as e.g., `myaddon.py`\n# 2. Run mitmproxy from your terminal: `mitmproxy -s myaddon.py`\n# 3. Configure your client (browser, app) to proxy through mitmproxy (default: http://127.0.0.1:8080).\n#    For HTTPS, install the mitmproxy CA certificate (navigate to mitm.it from the proxied client).\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment meets the minimum requirement for your mitmproxy version. Upgrade to Python 3.12 or higher for mitmproxy 12+.","message":"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).","severity":"breaking","affected_versions":">=12.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"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'`).","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}