SOCKS5 is everywhere and almost invisible. ssh -D speaks it. Browsers have a settings field for it. curl has a -x socks5h:// option. It is the protocol that lets a program say "open a connection to this host for me" to another machine, without either side caring what travels inside.
For something so widely used, few developers have looked at what happens on the wire. The protocol is defined in two short documents, RFC 1928 and RFC 1929, and a complete server is small. socks5-proxy is my implementation in Rust on Tokio: CONNECT and UDP ASSOCIATE with IPv4, IPv6 and domain-name targets, username/password authentication, first-match allow/deny rules on destinations, handshake, connect and idle timeouts, and per-connection statistics.
The README names two audiences: people learning how a SOCKS proxy works on the wire, since it is short enough to read in one sitting, and anyone who wants a small, auditable proxy for local use. This post covers what I built and what it teaches.
What I built
The byte formats. proto.rs holds every message of the protocol: the greeting, the RFC 1929 sub-negotiation, the request (VER CMD RSV ATYP ADDR PORT), the reply, and the UDP header (RSV FRAG ATYP ADDR PORT DATA).
The connection handler. server.rs runs each connection under a handshake timeout. It reads the client's method list and picks 0x00 (no auth) or 0x02 (username/password, compared in constant time), or answers 0xFF when nothing is acceptable. Then it reads the request. For CONNECT it resolves the target, filters it through the rules, connects under the connect timeout, and replies with the outbound socket's address. After that it relays both directions in one select! loop that counts bytes, forwards half-closes and enforces the idle timeout. I/O errors map to SOCKS reply codes: refused is 5, unreachable is 3 or 4, denied by rules is 2, BIND is 7, an unknown address type is 8.
UDP. udp.rs implements UDP ASSOCIATE. It binds a UDP socket on the interface the client connected to, learns the client's UDP endpoint (announced, or taken from the first datagram from the client's IP), forwards unwrapped payloads to allowed destinations and wraps the replies. It accepts replies only from destinations the client contacted. The association ends with the TCP control connection.
Rules. acl.rs parses and matches the allow/deny rules. Rules are checked in the order given, the first match wins, and --default allow|deny applies otherwise. A pattern is *, an address (10.0.0.1, ::1), a CIDR (10.0.0.0/8, fd00::/8), a domain (example.com, case-insensitive) or a suffix (*.example.com, which also matches example.com), optionally followed by @PORT.
Statistics. stats.rs keeps global counters and the last 1000 connection records: client, user, command, target, bytes each way, duration and outcome.
How to use it
The README lists prebuilt binaries for Linux (x86_64 and aarch64), macOS (x86_64 and arm64) and Windows (x86_64), attached to the GitHub releases, with installer scripts. To build from source:
cargo install --git https://github.com/AbdeldjalilChougui/socks5-proxy --locked
Or run it from a clone of the repository:
cargo run --release -- --listen 127.0.0.1:1080
curl -x socks5h://127.0.0.1:1080 https://example.com/
With authentication and rules:
cargo run --release -- --listen 127.0.0.1:1080 \
--user alice:s3cret --users-file users.txt \
--rule deny:10.0.0.0/8 --rule deny:*.internal.corp --rule allow:*@443 --default deny \
--idle-timeout 120 --stats-every 60
curl -x socks5h://alice:s3cret@127.0.0.1:1080 https://example.com/
This example denies a private range and an internal domain suffix, allows port 443 everywhere else, and denies the rest.
Each finished connection is logged on one line (--quiet turns this off):
#1 127.0.0.1:56298 user=alice CONNECT localhost:18765 up=87B down=187B 0.022s Closed
#2 127.0.0.1:56304 user=alice CONNECT 10.1.2.3:80 up=0B down=0B 0.001s Denied
What it teaches
The whole handshake is a few bytes. The client sends a version and a list of auth methods. The server picks one. The client sends a command, an address type and an address. The server answers with a status. From then on the TCP connection is a plain pipe. Reading proto.rs next to RFC 1928 makes the protocol concrete in a way the RFC alone does not.
Rules must be checked after name resolution. A client can send a domain name as the target, and the name can resolve to anything. In this proxy, domain targets are resolved first and every resolved address is checked with the name attached. So deny:127.0.0.0/8 also blocks localhost, and IPv4-mapped IPv6 addresses are treated as IPv4. A filter that only looks at the text the client sent is easy to walk around.
Relaying is more than copying bytes. One side can finish sending while the other still has data to deliver. Forwarding that half-close correctly, counting bytes in each direction and closing idle connections all live in the same loop, which is why a single select! is a good fit.
Every wait needs a timeout. A client that connects and says nothing would hold a task forever. The handshake, the outbound connect and the relay each have their own limit.
UDP through a proxy needs its own rules. The server has to learn where the client's datagrams come from, and it must not become an open relay for anyone who finds the port. Accepting replies only from destinations the client already contacted is the guard.
Comparing passwords in constant time is a habit worth having, even in a small tool.
Things to know
The README lists these limits:
-
No
BINDcommand. It is answered with "command not supported". - No GSSAPI auth. Username and password travel in clear text, as RFC 1929 specifies. Run it on localhost or behind a tunnel.
-
UDP fragments (
FRAG != 0) are dropped. The UDP socket is bound to one address family, so an IPv4 client cannot relay UDP to IPv6-only targets. - DNS resolution happens before the rule check, so a denied name is still looked up.
- Records stay in memory (the last 1000) and are logged to stderr. There is no metrics endpoint.
-
--max-connectionscaps concurrent clients, and extras wait in the listen backlog. There is no per-client rate limiting.
What was tested. cargo test runs 7 unit tests (the address codec including every truncated prefix, the UDP header, rule parsing and matching) and 15 end-to-end tests in tests/proxy.rs, with a hand-written SOCKS5 client against local echo, HTTP and UDP servers. They cover IPv4, IPv6 and domain CONNECT, auth success and three kinds of failure, deny by IP and port and through a resolved name, default-deny allow lists, refused, unresolvable and BIND requests, handshake and idle timeouts, half-close, 64 concurrent authenticated clients, the connection limit, and UDP ASSOCIATE both ways and against a deny rule. They also run curl through the proxy with socks5h:// and socks5:// over IPv4 and IPv6, plus a wrong password; that part is skipped when curl is not installed. Everything binds to loopback.
Why I built it
I wanted to understand SOCKS5 at the byte level, and a proxy is a good exercise in async Rust because it has all the ingredients in a small space: a binary protocol to parse, timeouts, two-way relaying, UDP next to TCP, and a security boundary to get right.
The second reason is the one the README gives: a proxy small enough to audit. When the job is to route a browser or curl through an SSH host, or to fence a test tool to a set of hosts, a server you can read fully and whose rules you understand is a reasonable thing to want.
Get the code
The source and the tests are on GitHub: https://github.com/AbdeldjalilChougui/socks5-proxy. It's MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)