Skip to main content

WireGuard interface for mitmproxy

Project description


PyPI PyPI - License PyPI - Status PyPI - Python Version PyPI - Wheel ci

Transparently proxy any device that can be configured as a WireGuard client!


  • multithreaded / asynchronous WireGuard server using tokio:
    • one worker thread for the user-space WireGuard server
    • one worker thread for the user-space network stack
    • one worker thread for communicating with the Python runtime
  • full support for IPv4 packets (TCP and UDP)
  • basic support for IPv6 packets (TCP and UDP)
  • partial support for IPv6 packets
  • Python interface similar to the Python asyncio module
  • integration tests in mitmproxy


  • more complete IPv6 support
  • various other small TODO and FIXME items

Architecture support

mitmproxy_wireguard should work on most architectures / targets - including, but not limited to Windows, macOS, and Linux, running on x86_64 (x64) and aarch64 (arm64) CPUs.

Binary wheels for the following targets are available from PyPI:

  • Windows / x64 (x86_64-windows-msvc)
  • macOS / Intel (x86_64-apple-darwin)
  • macos / Apple Silicon (aarch64-apple-darwin) via "Universal 2" binaries
  • Linux / x86_64 (x86_64-unknown-linux-gnu)
  • Linux / aarch64 (aarch64-unknown-linux-gnu), i.e. for Raspberry Pi 2+ and similar devices


mitmproxy_wireguard currently requires Python 3.7 or newer at runtime, since that is the oldest version of Python that is still supported by PyO3 v0.16. mitmproxy already requires Python 3.9 or newer, so this should not be a problem.

Additionally, mitmproxy_wireguard currently has the following requirements at build-time:

  • Python 3.7+ (range of Python versions that is supported by PyO3 v0.16)
  • Rust 1.58.0+ (the oldest supported version of Rust / MSRV is 1.58.0)
  • maturin 0.13.x


library architecture


The API interface of the PyO3 module is documented in mitmproxy_wireguard.pyi:

  • Server class: a running WireGuard server instance, with methods for
    • graceful shutdown (close / wait_closed)
    • sending UDP packets
  • TcpStream class: an established TCP connection (provides APIs identical to Python's) asyncio.StreamReader and asyncio.StreamWriter)
  • start_server coroutine: initialize, start, and return a Server instance


Setting up the development environment is relatively straightforward, as only a Rust toolchain and Python 3 are required:

# set up a new venv
python3 -m venv venv

# enter venv (use the activation script for your shell)
source ./venv/bin/activate

# install maturin and pdoc
pip install maturin pdoc

Compiling the native Rust module then becomes easy:

# compile native Rust module and install it in venv
maturin develop

# compile native Rust module with optimizations
maturin develop --release

Once that's done (phew! Rust sure does take a while to compile!), the test echo server should work correctly. It will print instructions for connecting to it over a WireGuard VPN:

python3 ./

The included mitm-wg-test-client binary can be used to test this echo test server, which can be built by running cargo build inside the test-client directory, and launched from target/debug/mitm-wg-test-client.


Documentation for the Python module can be built with pdoc.

The documentation is built from the mitmproxy_wireguard.pyi type stubs and the rustdoc documentation strings themselves. So to generate the documentation, the native module needs to be rebuilt, as well:

maturin develop
pdoc mitmproxy_wireguard

By default, this will build the documentation in HTML format and serve it on http://localhost:8080.

Note: This requires version >=11.2.0 of pdoc. It is the first version that supports generating documentation for "native-only" Python modules (like our mitmproxy_wireguard PyO3 module).

Introspecting the tokio runtime

The asynchronous runtime can be introspected using tokio-console if the crate was built with the tracing feature:

tokio-console http://localhost:6669

There should be no task that is busy when the program is idle, i.e. there should be no busy waiting.

Note: This requires maturin>=0.12.15, as earlier versions accidentally clobbered the RUSTFLAGS that were passed to the Rust compiler, breaking use of the console_subscriber for tokio-console, which requires using the --cfg tokio_unstable flag.

Code style

The format for Rust code is enforced by rustfmt. To apply the formatting rules, use:

cargo fmt

The format for Python code (i.e. the test echo server and the type stubs in mitmproxy_wireguard.pyi) is enforced with black and can be applied with:

black mitmproxy_wireguard.pyi benches/*.py

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mitmproxy_wireguard-0.1.16.tar.gz (27.8 kB view hashes)

Uploaded Source

Built Distributions

mitmproxy_wireguard-0.1.16-cp37-abi3-win_amd64.whl (685.1 kB view hashes)

Uploaded CPython 3.7+ Windows x86-64

mitmproxy_wireguard-0.1.16-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view hashes)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ x86-64

mitmproxy_wireguard-0.1.16-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.2 MB view hashes)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ ARM64

mitmproxy_wireguard-0.1.16-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (1.6 MB view hashes)

Uploaded CPython 3.7+ macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

mitmproxy_wireguard-0.1.16-cp37-abi3-macosx_10_7_x86_64.whl (850.4 kB view hashes)

Uploaded CPython 3.7+ macOS 10.7+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page