Mitmproxy WireGuard

0.1.23 · maintenance · verified Thu Apr 09

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.

Common errors

```
ModuleNotFoundError: No module named 'mitmproxy_wireguard'
```
cause The standalone `mitmproxy_wireguard` Python package is not installed, or the Python environment where it's being imported lacks access to it. While `mitmproxy` (version 11.x and newer) integrates WireGuard functionality, this specific error occurs if a user or script attempts to directly import the separate `mitmproxy-wireguard` library.

fix If you intend to use `mitmproxy`'s integrated WireGuard mode, you typically do not need to `import mitmproxy_wireguard` in your Python code; you simply run `mitmproxy --mode wireguard`. If you have a specific reason to use the standalone library directly in a script, install it via `pip install mitmproxy-wireguard`.
```
Address already in use (when starting mitmproxy in WireGuard mode)
```
cause The default UDP port for the WireGuard server (usually 51820) or a custom port specified for `mitmproxy` is already occupied by another application or process on your system.

fix Change the listening port for `mitmproxy`'s WireGuard server by specifying it in the command, for example: `mitmproxy --mode wireguard@51821`. Alternatively, identify and stop the process currently using the conflicting port.
```
mitmproxy wireguard traffic not intercepted
```
cause Although the WireGuard client may show as connected, traffic is not correctly being routed through `mitmproxy` or is not being processed by it. Common reasons include incorrect `AllowedIPs` or `Endpoint` settings in the client's WireGuard configuration, local firewall rules blocking traffic, or a missing/untrusted `mitmproxy` CA certificate on the client device preventing HTTPS interception.

fix Verify that the WireGuard client configuration has `AllowedIPs = 0.0.0.0/0` (for IPv4 traffic) and that the `Endpoint` points to the correct IP address and UDP port of your `mitmproxy` server. Check `mitmproxy`'s event log for `clientconnect` messages. Ensure the `mitmproxy` CA certificate is installed and trusted on the client device by navigating to `http://mitm.it` in a browser *after* establishing the WireGuard VPN connection.
```
mitmproxy wireguard dns not working
```
cause Clients connected via `mitmproxy`'s WireGuard mode are unable to resolve domain names, leading to websites not loading or network applications failing. This indicates an issue with DNS resolution within the WireGuard tunnel.

fix Confirm that the `DNS` setting in your WireGuard client configuration is correctly pointing to the IP address of `mitmproxy`'s internal DNS server (typically `10.0.0.53` or similar, as provided in the generated WireGuard configuration). If you've configured custom DNS settings in `mitmproxy`, double-check their correctness.

Warnings

breaking 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.
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.
gotcha 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.
Fix: To enable incomplete IPv6 support, manually add `::/0` or other desired IPv6 ranges to the `AllowedIPs` setting in the WireGuard client configuration.
gotcha 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.
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).
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install mitmproxy-wireguard Install directly (as a dependency of mitmproxy)

Imports

Server
```
from mitmproxy_wireguard import Server
```
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.
TcpStream
```
from mitmproxy_wireguard import TcpStream
```
Provides APIs identical to Python's `asyncio.StreamReader` and `asyncio.StreamWriter` for established TCP connections. Generally used internally by mitmproxy.
start_server
```
from mitmproxy_wireguard import start_server
```
A coroutine to initialize, start, and return a Server instance. Most users will use `mitmproxy --mode wireguard` instead of directly calling this.

Quickstart

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`.

# To run mitmproxy in WireGuard mode, install mitmproxy first.
# pip install mitmproxy

import subprocess
import time
import os

print("Starting mitmweb in WireGuard mode. This will open a browser window.")
print("Connect your WireGuard client to the displayed configuration (QR code or file in ~/.mitmproxy/wireguard.conf).")
print("Then, from the connected device, navigate to http://mitm.it to install the CA certificate.")

# Ensure mitmproxy is in the PATH or provide full path
mitmproxy_cmd = ["mitmweb", "--mode", "wireguard", "--web-host", "127.0.0.1", "--web-port", os.environ.get('MITMWEB_PORT', '8081')]

# You might need to adjust this if mitmweb doesn't start in a way that allows direct subprocess control
# For typical usage, users would run this command directly in a terminal.
# This example is illustrative of the command, not a robust programmatic launch.

try:
    # Start mitmweb in a non-blocking way if possible, or instruct user to run it.
    # For simplicity in a quickstart, we'll just print the command.
    print(f"\nRun this command in your terminal: {' '.join(mitmproxy_cmd)}\n")
    # In a real scenario, you'd use subprocess.Popen for background execution
    # p = subprocess.Popen(mitmproxy_cmd)
    # p.wait() # Or handle it asynchronously
except FileNotFoundError:
    print("Error: 'mitmweb' command not found. Please ensure mitmproxy is installed and in your PATH.")
except Exception as e:
    print(f"An error occurred: {e}")

# Example of what a user would do after starting mitmweb:
# 1. Configure WireGuard client using the QR code or ~/.mitmproxy/wireguard.conf
# 2. On the client, browse to http://mitm.it to install the CA certificate.
# 3. All traffic from the WireGuard client will now be intercepted by mitmproxy.

view raw JSON →