A multi-threaded SOCKS5 proxy server built from scratch in Python, following RFC 1928. It handles the full handshake, username/password authentication, the CONNECT command, and bidirectional data relay between client and destination — with IP whitelisting and per-session traffic metrics on top.
- RFC 1928-compliant handshake — negotiates the SOCKS version and auth method before doing anything else.
- Username/password authentication (Sub-negotiation, RFC 1929) — rejects any client that doesn't offer method
0x02, and verifies credentials before allowing a connection through. - IP whitelisting — connections from IPs outside
ALLOWED_IPSare dropped immediately, before any bytes are read off the socket. CONNECTcommand support — resolves the target (IPv4 or domain name) and opens a connection to it on the client's behalf.BINDandUDP ASSOCIATEare not implemented.- Threaded connection handling — built on
ThreadingMixIn, so each client connection is handled on its own thread (the relay itself usesselectors, i.e. epoll on Linux) and multiple sessions can run concurrently. - Non-blocking relay loop — once the tunnel is established,
select()multiplexes reads between the client and the remote socket so data flows in both directions without busy-waiting. - Per-session metrics — logs session duration, bytes uploaded, and bytes downloaded once a connection closes.
- Graceful shutdown —
SIGINT/SIGTERMare caught to shut the server down cleanly instead of dropping connections abruptly.
- Python 3 (standard library only — no external dependencies)
Configuration is via environment variables (defaults shown):
| Variable | Default | Meaning |
|---|---|---|
SOCKS_HOST / SOCKS_PORT |
0.0.0.0 / 9000 |
listen address |
SOCKS_USER / SOCKS_PASS |
user / pass |
the single credential pair - change before real use |
SOCKS_ALLOWED_IPS |
127.0.0.1 |
comma-separated client whitelist; empty = allow all |
SOCKS_LOG |
stderr | log file path |
SOCKS_USER=me SOCKS_PASS=secret python3 proxy.py
curl --socks5-hostname me:secret@127.0.0.1:9000 https://example.compip install pytest
pytest -qCovers the handshake (including byte-at-a-time delivery), auth failure, unsupported commands/address types, IPv4/IPv6/domain targets, half-close, a 2 MB integrity transfer, 150 simultaneous tunnels, the whitelist, and SIGINT/SIGTERM shutdown.
Ctrl+C (or a SIGTERM) triggers a graceful shutdown — the server stops accepting new connections, closes the listening socket, and exits cleanly.
- Credentials come from environment variables — fine for local use; a real deployment wants a secret store.
- Single shared credential pair — there's no per-user account system; every client authenticates with the same username/password.
- No TLS — traffic between the client and this proxy is not encrypted at the proxy layer.
- Only
CONNECTis implemented —BINDandUDP ASSOCIATErequests are rejected.
Each incoming connection is handled by SocksProxy.handle():
- Checks the client IP against
ALLOWED_IPS, dropping unauthorized connections immediately. - Performs the SOCKS5 greeting/method-negotiation handshake, requiring username/password auth.
- Verifies the supplied credentials.
- Parses the client's request (address type + target address/port).
- Opens a
CONNECTto the target and relays data between the client and target sockets usingselect()until either side closes the connection. - Logs session metrics (duration, bytes sent/received) once the exchange loop ends.
Issues and PRs welcome — a config-driven credential/whitelist system and TLS support would be natural next steps.
MIT