{"id":2120,"library":"mitmproxy-wireguard","title":"Mitmproxy WireGuard","description":"mitmproxy-wireguard provides a user-space WireGuard VPN server implementation, allowing mitmproxy to transparently intercept traffic from WireGuard clients. While the standalone project is no longer actively maintained, its core functionality has been subsumed and is actively integrated within the mitmproxy project (version 11.x and newer). This integration offers a modern alternative to traditional transparent proxying, simplifying the setup for intercepting traffic from various devices. The current version available on PyPI is 0.1.23.","status":"maintenance","version":"0.1.23","language":"en","source_language":"en","source_url":"https://github.com/mitmproxy/mitmproxy_wireguard","tags":["network","proxy","vpn","wireguard","mitmproxy","security","traffic interception","rust"],"install":[{"cmd":"pip install mitmproxy-wireguard","lang":"bash","label":"Install directly (as a dependency of mitmproxy)"}],"dependencies":[{"reason":"This library's functionality is primarily exposed and used as a mode within mitmproxy.","package":"mitmproxy","optional":false},{"reason":"Requires Python >=3.7. Note that mitmproxy itself requires Python >=3.9.","package":"python","optional":false},{"reason":"Required for building from source (Rust 1.58.0+).","package":"rust","optional":true},{"reason":"Required for building from source (maturin 0.13.x).","package":"maturin","optional":true}],"imports":[{"note":"Direct programmatic interaction with mitmproxy_wireguard is less common; users typically engage via the mitmproxy CLI (`mitmproxy --mode wireguard`). The Server class represents a running WireGuard server instance.","symbol":"Server","correct":"from mitmproxy_wireguard import Server"},{"note":"Provides APIs identical to Python's `asyncio.StreamReader` and `asyncio.StreamWriter` for established TCP connections. Generally used internally by mitmproxy.","symbol":"TcpStream","correct":"from mitmproxy_wireguard import TcpStream"},{"note":"A coroutine to initialize, start, and return a Server instance. Most users will use `mitmproxy --mode wireguard` instead of directly calling this.","symbol":"start_server","correct":"from mitmproxy_wireguard import start_server"}],"quickstart":{"code":"# To run mitmproxy in WireGuard mode, install mitmproxy first.\n# pip install mitmproxy\n\nimport subprocess\nimport time\nimport os\n\nprint(\"Starting mitmweb in WireGuard mode. This will open a browser window.\")\nprint(\"Connect your WireGuard client to the displayed configuration (QR code or file in ~/.mitmproxy/wireguard.conf).\")\nprint(\"Then, from the connected device, navigate to http://mitm.it to install the CA certificate.\")\n\n# Ensure mitmproxy is in the PATH or provide full path\nmitmproxy_cmd = [\"mitmweb\", \"--mode\", \"wireguard\", \"--web-host\", \"127.0.0.1\", \"--web-port\", os.environ.get('MITMWEB_PORT', '8081')]\n\n# You might need to adjust this if mitmweb doesn't start in a way that allows direct subprocess control\n# For typical usage, users would run this command directly in a terminal.\n# This example is illustrative of the command, not a robust programmatic launch.\n\ntry:\n    # Start mitmweb in a non-blocking way if possible, or instruct user to run it.\n    # For simplicity in a quickstart, we'll just print the command.\n    print(f\"\\nRun this command in your terminal: {' '.join(mitmproxy_cmd)}\\n\")\n    # In a real scenario, you'd use subprocess.Popen for background execution\n    # p = subprocess.Popen(mitmproxy_cmd)\n    # p.wait() # Or handle it asynchronously\nexcept FileNotFoundError:\n    print(\"Error: 'mitmweb' command not found. Please ensure mitmproxy is installed and in your PATH.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n# Example of what a user would do after starting mitmweb:\n# 1. Configure WireGuard client using the QR code or ~/.mitmproxy/wireguard.conf\n# 2. On the client, browse to http://mitm.it to install the CA certificate.\n# 3. All traffic from the WireGuard client will now be intercepted by mitmproxy.\n","lang":"python","description":"The primary way to use mitmproxy-wireguard's functionality is through the `mitmproxy` CLI tools (mitmproxy, mitmweb, or mitmdump) using the `--mode wireguard` option. This starts a WireGuard VPN server. Clients then connect using a standard WireGuard application, importing the configuration (often via a QR code or a file at `~/.mitmproxy/wireguard.conf`) provided by mitmproxy. After connecting, the mitmproxy CA certificate must be installed on the client device by navigating to `http://mitm.it`."},"warnings":[{"fix":"Ensure you are using a recent version of the `mitmproxy` project (mitmproxy 9+), which includes and maintains this WireGuard mode functionality. Refer to the mitmproxy documentation for the latest usage.","message":"The standalone `mitmproxy-wireguard` project is no longer maintained as a separate entity; its functionality has been subsumed into `mitmproxy_rs` and is now an integrated part of the main `mitmproxy` project. While the functionality persists, direct development on this specific PyPI package has ceased.","severity":"breaking","affected_versions":"All versions of mitmproxy-wireguard as a standalone project."},{"fix":"To enable incomplete IPv6 support, manually add `::/0` or other desired IPv6 ranges to the `AllowedIPs` setting in the WireGuard client configuration.","message":"IPv6 traffic support in WireGuard mode is limited. Generated client configurations may not list IPv6 addresses by default. While the server supports receiving IPv6 packets, proxying them is incomplete.","severity":"gotcha","affected_versions":"All current versions (0.1.x) and integrated mitmproxy versions (9+)."},{"fix":"Use WireGuard mode for external devices or specific applications on the same device where the application does not route its own traffic through the VPN. For local host traffic, consider other mitmproxy modes like 'local' or 'transparent' (though transparent mode setup is more complex).","message":"It is not possible to proxy all traffic of the host machine where `mitmproxy` itself is running in WireGuard mode. This limitation prevents an infinite loop where outgoing WireGuard packets are sent over the WireGuard tunnel they originate from.","severity":"gotcha","affected_versions":"All current versions (0.1.x) and integrated mitmproxy versions (9+)."},{"fix":"If experiencing issues, try removing `--allow-hosts` or `--ignore-hosts` arguments. If host filtering is critical, carefully test specific IP/hostname patterns and monitor `mitmproxy`'s event log for DNS-related errors. Consider implementing filtering logic within a mitmproxy addon if CLI options prove problematic.","message":"Using `--allow-hosts` or `--ignore-hosts` options with `mitmproxy` in WireGuard mode can sometimes lead to issues where all traffic breaks, often related to DNS resolution.","severity":"gotcha","affected_versions":"mitmproxy versions 9+ (where WireGuard mode is integrated)."},{"fix":"To enable HTTP/3 interception in Chrome, you can either provide a publicly trusted certificate to mitmproxy, start Chrome with a specific command-line switch (`--ignore-certificate-errors` or similar, which is not recommended for general browsing), or accept that Chrome will fall back to HTTP/2. Firefox does not have this limitation.","message":"Chrome browsers do not trust user-added Certificate Authorities for QUIC (HTTP/3) by default, even after installing the mitmproxy CA certificate. This causes Chrome to fall back to HTTP/2.","severity":"gotcha","affected_versions":"mitmproxy versions 11+ (with HTTP/3 support)."},{"fix":"This can be a persistent issue on iOS. Double-check all steps: ensuring the WireGuard VPN is active, the CA certificate is installed, and 'Full Trust' is enabled. If the problem persists, it may indicate a deeper iOS-specific trust store interaction that can be challenging to debug or resolve consistently. Consider alternative proxy modes or devices if this remains a blocker.","message":"iOS clients may fail to trust the mitmproxy CA certificate in WireGuard mode, even after installing it as a profile and explicitly enabling 'Full Trust for Root Certificates' in iOS settings. This results in certificate errors for HTTPS sites.","severity":"gotcha","affected_versions":"mitmproxy versions 9+ when used with iOS clients."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}