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.0a9.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 22c9d3ddc4e32302af251d59c154a3ba75c63bbb79102595566028cdc6486636 |
|
MD5 | b664eb6decbb70075d17c616baf8cc5f |
|
BLAKE2b-256 | d11cdc90669c8d2ca6151c47dec3bc1b350f0e0cfa60976b5ac8fd63e0b389ab |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 10e16b86445bc5a5b1c13db1f2db43303e78c09362d50abe5dd1a56bcfcbeb52 |
|
MD5 | 306aa46e6e5c5328eb38b7b0df9de792 |
|
BLAKE2b-256 | bd904e255ac2075acf8b0aff1a6bee39a1e8bae7f77588e99bb1d45c592cd88e |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | baf6dd84ac5269537e97aee91965c3443b8c8ecba5da3432a5fe063f7157ce21 |
|
MD5 | b72291db6ed20f159fab94afe2b254cd |
|
BLAKE2b-256 | 99d65f32b8dbdbb0641e587810531ec58b92e4f5186690b1281a1675cee5dba0 |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ca63edf73862bbcb4ddd28a8b13d027949a96cd8d25692ca7517af5452a238d |
|
MD5 | 8f2bef8e3c2f16574e82aeaad43dfaa2 |
|
BLAKE2b-256 | e38ba77b2d3d80b3ec83f715581e3aababceab72e4b6b678ed6999d6ebb75efa |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e8508a5f883564f2dc2ec25226f9066f4650c5356ddf86505aae664ddaf660e |
|
MD5 | 8a712d6777c75a1704066dc8bb6e77c5 |
|
BLAKE2b-256 | f0b7fb3c9c377014285d230d6edfd43b2aae359ef7c0288cfe685bf7465e5148 |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 57263d05af41eb4c97f1ff80a9fb8e159f7d45f714774667a990ee52126aed89 |
|
MD5 | c65c2d8409667dda59cb1959f5803dc7 |
|
BLAKE2b-256 | c3d819dcec6e1d45fda973e0cdfd1deb19e2f041c3d3db438503e6cd89e11d77 |
Hashes for mitmproxy_wireguard-0.1.0a9-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0d727339e6b5560560ab3797fb969540c88a40158c7110d9209ab8e9bce8754d |
|
MD5 | 1dcf99f6f1ab94560ea55d537fb89ff7 |
|
BLAKE2b-256 | 9c49dde9fcb7731f45b22600a3329b60d3b9f2e8a70dbd45b36f8db0baf934b9 |