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
.
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 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.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 113ce67f230fd7a318449dfe3d21b20bdd3dfe6fc027ad493ee925118d18c724 |
|
MD5 | 96915dffa135eceb96b152cc6f0e86da |
|
BLAKE2b-256 | eb5f27d0dd8fb162577d3dd7562b57c638682566c4f1f5f27dcdb2b955497b62 |
Hashes for mitmproxy_wireguard-0.1.10-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2a0266a0d35711cf74661065728736a7376471af636e60b5f5a258b96d82f6d6 |
|
MD5 | ce8f60308017b139eb2220e40f19411f |
|
BLAKE2b-256 | 151ffe605d0abc933817af2e3967c11d0d13e8ee4ae5d4ceacb72fe50f3ec9b3 |
Hashes for mitmproxy_wireguard-0.1.10-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0bba0c2f96d9301b6403578fbcaff0d7308d33dc453b7731a5df0528c0189511 |
|
MD5 | d6448016c04791d0ee97f86ab20e51d3 |
|
BLAKE2b-256 | a644fd15191072e25993ee824f76def4c70ad4d3c73fa10531ef2ab641e8f360 |
Hashes for mitmproxy_wireguard-0.1.10-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ba5e0444435e47c42d78035f4ade5e6cbd9329750b6bf8b0e2de54772234569 |
|
MD5 | 60bf56a6b0587631feb1ab8905a09a85 |
|
BLAKE2b-256 | e79084611d5a101f29700bb75474b4304ceb9c73c322cbe7306309823322c179 |
Hashes for mitmproxy_wireguard-0.1.10-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 701cd786322af89b53d94e5a363fd3c0e131ae4bd4f783afb7c3b21e9ba87c80 |
|
MD5 | 3937eed7ac576766570baff5633aba61 |
|
BLAKE2b-256 | c5730ed31c2bd3fdd8fc1f327e4d6fe1a5e13659a828f91a8c5e1b5cd7259e1c |
Hashes for mitmproxy_wireguard-0.1.10-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 470c96399b90fbc84f319423709359d93370b340af894da20f4001ae39bc60fc |
|
MD5 | 9a01d4f1eee268a4b16fff3fd50b8a3c |
|
BLAKE2b-256 | dc7c68f3de9bcf79bb714d135140b421600943146351919fea5caef680dcf9e7 |