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.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d58826d4d80423467eda55cb9f8ca032f8f51cb626af1651a6e31fa922db3d0b |
|
MD5 | d34ba4893f1b317a08acc0970c40ca1f |
|
BLAKE2b-256 | 079721a14802323e0bc3da00c28a4ce978c91adb06943574552442eb39d63c02 |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7b8f872cc6c7b60d3ecac3b72720e319567f38e4c6a0ff5e1751f30b3cfb9916 |
|
MD5 | 8db243b216729fad6f868b9c6c262ee6 |
|
BLAKE2b-256 | 94d4da3b14c6b7ce5e96cfba650e119a1512f1cff1909227538db9e17f390070 |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed39fd66a9cdcde2a219ec865b085a2eee75b7cde0b4b5f1f42be9b0fd028f44 |
|
MD5 | 0fc37616ef7ae04a208975fdfb5b6ce4 |
|
BLAKE2b-256 | fa0aecf700c70f45327e9f61801aa9ec2f8352eabcadaa2110f7f999f58c0c57 |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9747ec9b8a647ffa7e4f489b9e38905db775d9af88d25f3eca97fe0e7bb9427 |
|
MD5 | 64a66c238fd44fd0547447c91e52a16f |
|
BLAKE2b-256 | a018cac4aa8c53a5012514661e49c5fb87f9ccc7a28be3de8509444234c19a02 |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f3ba78ce33950a40500b49712bb59730594f7c6fc8d8d1acc802b5dd6a27f784 |
|
MD5 | 95980d598242583eb6856beb354a3b8c |
|
BLAKE2b-256 | ed73df8289dba73d22bbe89d64b5c167ab621fdc967618d93c028d99ce6772af |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 11b7fdceae73f66f4f921b9c760af75431212d1db0c096a93533c80f827800e7 |
|
MD5 | 23d07f5bab6cbd6b8fd24de28b74d632 |
|
BLAKE2b-256 | bc46da3559dcdff55d2565245352f4c8978aa98d0831346558ff116edb26c09f |
Hashes for mitmproxy_wireguard-0.1.2-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c22441374b25b339b49f3b308a8b96819830bf7d5d339f632abacc34e21b9e6 |
|
MD5 | 3781bceb30c29d52b8143d2ae2549509 |
|
BLAKE2b-256 | 05fed4d015c9e803ba6342319c6a3232de28bf063031b1b4c4ead4e29174a3d4 |