go-socks5

go-socks5 implements the SOCKS5 protocol (RFC 1928) as an embeddable Go package rather than a standalone binary — you construct a socks5.Server with a Config, then call ListenAndServe (or hand it your own net.Listener via Serve) to start proxying TCP connections. Every extension point is an interface: Authenticator for auth (no-auth or user/password out of the box), CredentialStore for validating credentials, NameResolver for custom DNS behavior, RuleSet for permitting or blocking commands per-request, and AddressRewriter for transparently rewriting destinations before rules are applied.

The library supports the CONNECT command fully (BIND and ASSOCIATE are stubbed as not-supported), making it well suited for outbound TCP proxying use cases — bypassing firewalls/NATs, routing traffic through an intermediate hop, or embedding proxy behavior directly inside another Go service. It has shipped largely unchanged since 2014 and is still widely vendored by other Go projects that need a minimal, in-process SOCKS5 server rather than an external proxy process.

What You Get

• A Server type built from a Config struct — start it with ListenAndServe(network, addr) or serve an existing net.Listener via Serve
• Two built-in Authenticator implementations: NoAuthAuthenticator and UserPassAuthenticator backed by a pluggable CredentialStore
• A RuleSet interface with ready-made PermitAll()/PermitNone() and a PermitCommand type for granular per-command (CONNECT/BIND/ASSOCIATE) filtering
• A NameResolver interface with a default DNSResolver for FQDN destinations, swappable for custom or mocked resolution
• An AddressRewriter hook invoked before rule evaluation, for transparently redirecting destinations
• Full CONNECT-command proxying with bidirectional io.Copy streaming and proper connection teardown

Common Use Cases

• Embedding a lightweight SOCKS5 proxy directly inside a Go CLI or service instead of shelling out to an external proxy binary
• Enforcing custom access-control policy (allow/deny by destination or command) on proxied traffic via a custom RuleSet
• Adding username/password-gated proxy access for internal tooling using UserPassAuthenticator and a custom CredentialStore
• Transparently rewriting or redirecting destination addresses (e.g. for testing or traffic steering) via AddressRewriter before a connection is made

Under The Hood

Architecture go-socks5 is a single, monolithic socks5 package built around one central Server type (defined in socks5.go) that owns a Config and a map of registered Authenticators. A connection’s lifecycle flows linearly through ServeConn → authenticate (auth.go) → NewRequest parsing (request.go) → handleRequest, which dispatches on command type to handleConnect/handleBind/handleAssociate. Every extension point — authentication, rule enforcement (ruleset.go), name resolution (resolver.go), and address rewriting — is expressed as a small interface injected via Config, so the core per-connection state machine never changes even though its policy is fully swappable; the only thing that would ripple through the whole codebase is a change to the Request/AddrSpec structs, since nearly every file operates on them directly.

Tech Stack The library depends on nothing beyond the Go standard library (net, bufio, io, log, fmt) plus a single external import, golang.org/x/net/context, reflecting its pre-Go-1.7 origins before context moved into the standard library. There is no go.mod in the repository at all — it predates Go modules and was consumed via GOPATH/vendoring, which downstream users now typically wrap in their own module with a replace or fork. Build tooling is just go build/go test; CI is a now-defunct .travis.yml running the test suite. There is no database, web framework, or ORM involved — it operates purely at the TCP socket layer.

Code Quality Each production file has a matching _test.go counterpart (auth_test.go, credentials_test.go, request_test.go, resolver_test.go, ruleset_test.go, socks5_test.go), and the suite includes a full end-to-end test that spins up a real Server on a localhost listener and drives a handshake through it, alongside more focused unit tests for auth negotiation, FQDN/IPv4/IPv6 address parsing, and rule permit/deny logic. Error handling is consistently fmt.Errorf-wrapped rather than typed/sentinel (aside from two package-level error vars), and a handful of Read calls don’t guard against short reads as rigorously as the io.ReadAtLeast calls elsewhere. There’s no linter configuration, static-analysis step, or go.mod-pinned dependency graph — quality is enforced entirely by the test suite rather than tooling.

API Design The public surface is deliberately small: construct a Config, call socks5.New, then ListenAndServe. Getting a working no-auth proxy running takes three lines, and every optional behavior (auth, rules, resolver, rewriter, custom Dial function, *log.Logger) is an optional struct field with a sane zero-value default rather than a required constructor argument, so there’s very little boilerplate to opt into more advanced behavior. Naming is consistent and idiomatic Go (Authenticate, Resolve, Allow, Rewrite), though documentation is limited to inline comments and a single README example — there’s no dedicated docs site or godoc walkthrough beyond what’s auto-generated from comments.