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.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2f007f59347f5be77bcccf6f87b2f7d8fae6f265e959016e6bc2baa2f2fb094a |
|
MD5 | d7d1d744fc051bbecba112430012ad1e |
|
BLAKE2b-256 | 9e908272804ab7f631a015ed0ba55da86231642bfd84415a55bbb3d3ec37e506 |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5fe8c4bf81e9b68c7cb82d2d3bb557eedae3dbb6f95253df20c7a07f555182dd |
|
MD5 | 7595b4dd0908616c365ac55bd169b477 |
|
BLAKE2b-256 | bc94c31dc923d65c49b4b7f58a49deea187d5fb0b8995ba9e6aa1cfffaa5f4a2 |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6a8d87c5e37f276d3eb698d45c48a9342b81890803e0677378602814bff03e35 |
|
MD5 | 8fc2050f5101c66176dcd1e147eeea0a |
|
BLAKE2b-256 | 7ade4baba2d2f894df2b6d3325e0f567d118805e3f2fa1ae34b54b95c445b44e |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0eb579744e94f4ff9fc765c2d70fbd532573b0975c939557e18b25d8c67c091e |
|
MD5 | 42f222a8561dc129869bdb2bfecf5228 |
|
BLAKE2b-256 | 95c8b4f6d4d88a82bd53ac714d22f15f61d78b579dc78c2fec55a12970137415 |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6b65ff6e020720e6f8caf0a688568ef70646f544222539771d448136e7fa991e |
|
MD5 | a8688242510e1c9f995b6b1f185ce3b0 |
|
BLAKE2b-256 | 7abbdfc7118b8dd1618a5e00a703082f183af7e8a5b8e82e34337dc9c0aad52c |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20da52909de46e8c6a89b53f458be283b2c10dd6467de0a9cb56e828b33d2cd7 |
|
MD5 | d47b756eaa1987eed59036e4bde03cc5 |
|
BLAKE2b-256 | 30338267ebbea2b9a5ae0490fb69ef3ee726507f52c8ce0b1cf337ee0bd78c99 |
Hashes for mitmproxy_wireguard-0.1.1-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 49c6c49aa43dca4a28968e2ad2a5bb036ac9effcaf79c9c1d92f7febb43e2c66 |
|
MD5 | 2ff375c58a92b6333740d13ab76e8368 |
|
BLAKE2b-256 | 0405b52a775c8289af5d3f19dccb87d5352b95e04b187927337aa5f0cfe06a22 |