resocks is a reverse/back-connect SOCKS5 proxy tunnel that can be used to
route traffic through a system that can't be directly accessed (e.g. due to
NAT). The channel is secured by mutually trusted TLS with auto-generated
certificates based on a connection key. Read our
blog post
for more information.
Start the listener on the system that acts as the entry point of the SOCKS5 tunnel:
# on proxy entry point system with IP 1.2.3.4
$ resocks listenCopy the connection key and pass it to resocks on the relay
system:
# on remote relay system with IP 10.0.0.1
$ resocks 1.2.3.4 --key $CONNECTION_KEYNow configure tools on the proxy entry point system to use the local SOCKS5 server, for example:
$ curl --proxy 'socks5://127.0.0.1:1080' 'http://10.0.0.2'You can also generate a connection key with resocks generate and pass it to
the listen command to avoid generating a new connection key every time. It
can also be specified via an environment variable:
$ export RESOCKS_KEY="$(resocks generate)"
$ resocks listenThe threat model of resocks primarily takes into account attackers that can
inspect, intercept and modify traffic between the listener and the relay.
Specifically, resocks aims to defend against the following scenarios:
- A: Malicious Observer: Attackers with network access between the listener and the proxy should not be able to see the SOCKS5 traffic that is routed through the tunnel.
- B: Malicious Listener: When connecting the proxy to a listener, attackers should not be able to redirect the traffic to a malicious listener, as this would grant them access to the proxy server's network.
- C: Malicious Relay: Attackers should not be able to connect to an existing listener in order to be able to receive the traffic that was meant to be routed through the legitimate proxy.
This threat model suggests using a mutually authenticated encrypted connection between the listener and the relay as described here.
Please note that resocks is not designed to defend against the following
scenarios:
- D: Malicious User on Listener System: Malicious users on the system hosting the listener is generally able to connect to the SOCKS5 proxy or extract the connection key.
- E: Malicious User on the Relay System: A malicious user on the system hosting the relay can generally extract the connection key.
However, as described here, there a some defense-in-depth
measures that can employed to harden resocks against such attacks.
The tunnel between the listener and the relay is secured by a shared connection
key which is used to establish a mutually trusted TLS 1.3 connection. This works
by using the key on both sides to derive the same CA certificate which is then
used to sign the server and client certificates that are generated on the spot.
The library that implements this technique (kbtls) is available
here.
When running either the resocks listener or relay on an untrusted system
(scenarios D/E), attackers can potentially read the connection key which
undermines the defenses against scenarios A, B and C.
By default, the connection key is passed as a command line flag and can be read
out by attackers with the permission to see process listing with arguments.
Alternatively, the connection key can be specified via environment variable
($RESOCKS_KEY) or it could be statically built into the binary as described
below. In this case, the read permissions will need to be revoked
for other users. In certain scenarios, these techniques may prevent certain
low-privileged attackers from gaining access to the connection keys.
resocks can be built with the following command:
go buildIn order to compile a static connection key as the default connection key directly into the binary, use the following command:
go run . generate # generate a connection key
go build -ldflags="-X main.defaultConnectionKey=YOUR_CONNECTION_KEY"Similarly, the default connect back address can also be statically compiled into the binary:
go build -ldflags="-X main.defaultConnectBackAddress=192.0.2.1"