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 (
TcpStream
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.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74444259da35c3578f11e95f7c3889134a7dbf97bd7f3dc2294f2c2abdede4fc |
|
MD5 | 4635f6a8330af42a031435aab51cd0ce |
|
BLAKE2b-256 | 1b43298d1404f16db513472215cdc1dca8a841cd7ec342d2f943d81b0214ec7d |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 84487209e0f147a0ffc3a943f3f97ab939609298b4014bdd2e4b44e98d4ff89c |
|
MD5 | 8c98b4ec1a926a1f1a54273095237e83 |
|
BLAKE2b-256 | 7d5972aedefff82e70e7096e521cba468dcdda05341be58a9d4dadf05ed28d2a |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4c110f749fbbbd53754d63706f1da3ade882053cd8035b11dd0d47e59f77754 |
|
MD5 | f0a7deefc52d3a34d8c5a32c2a080129 |
|
BLAKE2b-256 | 362edc3b72b924b86807f1173a5f50116bbfb8a0c13f61f4701acfb3e20f5934 |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4f26a7fb90976f15a278f1b9d271ed068eeb05922c2194525f38333e216f1472 |
|
MD5 | b70e610f5347762a02cb45dd95d3a0ed |
|
BLAKE2b-256 | c66d77839e5d8ca4eeb29784ecf7d817c8b5bae9ba3ccca0d805348486e34f2d |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd90af66d050b1f5b730a14f0dbafa92fcb8efcf3674c32cc0bed4f3d4b542b5 |
|
MD5 | f4180403ef7a9278935ced06f448ceb7 |
|
BLAKE2b-256 | fa4097921a638e4677b6511752682b70afd6c9e625919dcb3da026b18126ee6b |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74bc687db04302b64c0a5e740ba5f85a227df74beec03d91976e6d6795b09e58 |
|
MD5 | 649feb1d0cab14854d3538f2780cd3a6 |
|
BLAKE2b-256 | cb1c3fa04d6d05906a6a345a082adfcc7fd51c84f61c7dad0bd812a3e5548dbf |
Hashes for mitmproxy_wireguard-0.1.0-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1bf12b25fa1bdd7917e5b1dc2762538280983f88378e74f93e8410321a645b9a |
|
MD5 | ab4338618bd2c4563a9d7bc11716b66c |
|
BLAKE2b-256 | 3e1c61c00d6384f9f7027bbab8920ff2480b4d9c31504d9b312e802bc2c6338b |