WireGuard interface for mitmproxy
Project description
mitmproxy_wireguard
Transparently proxy any device that can be configured as a WireGuard client!
Work-In-Progress.
Interface
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
- graceful shutdown (
Configuration
class: minimal configuration support compatible with standard WireGuard configuration filesTcpStream
class: an established TCP connection (provides APIs identical to Python's)asyncio.StreamReader
andasyncio.StreamWriter
)start_server
coroutine: initialize, start, and return aServer
instance
Architecture
DONE
- multi-threaded / 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
- basic TCP/IPv4 functionality, IPv6 only partially supported
- basic UDP functionality
- Python interface similar to the one provided by
asyncio.start_server
- basic support for reading WireGuard configuration files
TODO
- better and more complete IPv6 support
- unit tests
- various other
TODO
andFIXME
items (documented in the code)
Hacking
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 ./echo_test_server.py
Docs
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.toml
. Some used configuration
options are only available on nightly Rust. To apply the formatting rules, use:
cargo +nightly 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 echo_test_server.py mitmproxy_wireguard.pyi benches/*.py
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for mitmproxy_wireguard-0.1.0a10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 459e581563f9f4d6b6baec2ef91906db9770b2683086a4948c2d5337acdefddc |
|
MD5 | 88a69a02c9d57e6ac549d6d32ac58cd8 |
|
BLAKE2b-256 | 9fe8776d9671090fc0eda6eca1fbaa0d74d19a476fae4158c78768d3736cad8c |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dfb9b24eea1f22005f58444017eb843e9558451f17ea112194cbd9c2ad626ec3 |
|
MD5 | 4bcd3f80a2f21ce01804214aaf8f3592 |
|
BLAKE2b-256 | 732d8090aa0fcae1f6d35081f989c02c342c84fe03a836a48e57e0eb70a82bc5 |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cfd8ed9f22952f277476fc1cb2bbf51fcb15985059fc95da760635eacdb49508 |
|
MD5 | deacfa0243c2e75e129e051b0f676f0b |
|
BLAKE2b-256 | 844d7bf27362112b6fbb5dc7af37a0a7779a73af5683c0e10d8945e1fb1fa17a |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0f1f6b6a00eccc30fadded441b46507eda412ad9f1f54a36bf42caaac23d1dc9 |
|
MD5 | 2ba1e7af4f78da526a1b7c622c8267dd |
|
BLAKE2b-256 | 9a6f60782cc56faa8845b0d48d7e8a1c339a7e2a0689a6d3ad3f1ef0467b6fb2 |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba947cd2e06ff71a5f7683588eaa77688829b929996880ab886e0b284aa40723 |
|
MD5 | 7cfdfbc01fac653080fb7ebe5827f23d |
|
BLAKE2b-256 | a3666cec38773e3ede01794943e4b98230be17bf7bd4023170f76dd848799251 |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1f85ffb75780f1695778c9e2bb1cc56f4cd33ffa03257e4751909191dd849399 |
|
MD5 | b7e495c38c8f4c1772d4050ffa3d91c0 |
|
BLAKE2b-256 | 0f8c36fccadfbb36600d47290d97676deb88dbebff2b91a2a8db69398362de2d |
Hashes for mitmproxy_wireguard-0.1.0a10-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6a332710e8f45d1c1d1f9722a8604cea2a1e1b0d47a1c6962ca7728fb1bcd06 |
|
MD5 | 6367e012aa9ced0259eff15c3c6d7129 |
|
BLAKE2b-256 | 8c0859dcb8211d85df3c40f3fbbc11ee3e4ac8ef9f9af2f64c232b13f135ca96 |