This is a simple MVP wrapper that may help you build a tunnel over any custom transport (even through VK messages!). All you need to do is write two parts: a function send_message (that accepts bytes), and a loop around transport.handle_incoming callback that will process incoming messages.
To use the tunnel, you should run the client locally and access the SOCKS proxy that it has bound.
For example, see a tunnel over VK or over UDP.
There are two transports that are already implemented and working:
Feel free to implement and contribute any others.
There are many ways to tunnel your traffic over SOCKS. As it is not a part of this project, I will only mention them:
- Telegram supports the SOCKS proxies directly in the settings (on all platforms).
- On Linux, you can use the
proxychainsutility before any command to (at least try to) tunnel its traffic over the proxy. - For SSH connections, you can add this to your
~/.ssh/config:ProxyCommand nc -X 5 -x 127.0.0.1:1337 %h %p. - For any Android app, you can use the sockstun app to use it as a VPN. To run the desired client on mobile, Termux may be used.
There are a couple of tests that verify the core functionality (and also the UDP transport implementation). If you want to add a new transport, you should write some basic tests for it.
To run all tests:
pytest
There is currently no authentication for the SOCKS proxy, as it is usually bound to localhost.
Server-side authentication is also missing, but it should be added if the transport is publicly accessible. For example, the UDP transport should have authentication, but it does not yet.
Traffic encryption is intentionally omitted. Since 99.9% of websites and applications already use secure protocols with built-in encryption (such as TLS), additional encryption at this layer is usually unnecessary.
If needed, you can connect via SSH (through the proxy) using the -D <port> option to spawn another local SOCKS proxy that will encrypt all tunneled traffic.