{"id":13509214,"url":"https://github.com/RedTeamPentesting/resocks","last_synced_at":"2025-03-30T13:31:47.944Z","repository":{"id":163037716,"uuid":"635228371","full_name":"RedTeamPentesting/resocks","owner":"RedTeamPentesting","description":"mTLS-Encrypted Back-Connect SOCKS5 Proxy","archived":false,"fork":false,"pushed_at":"2023-09-19T10:43:29.000Z","size":2616,"stargazers_count":378,"open_issues_count":0,"forks_count":25,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-08-02T02:13:30.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/RedTeamPentesting.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":"2023-05-02T08:42:15.000Z","updated_at":"2024-07-29T12:41:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"7c245054-726e-4760-90b4-113a6918e1fb","html_url":"https://github.com/RedTeamPentesting/resocks","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedTeamPentesting%2Fresocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedTeamPentesting%2Fresocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedTeamPentesting%2Fresocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RedTeamPentesting%2Fresocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RedTeamPentesting","download_url":"https://codeload.github.com/RedTeamPentesting/resocks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222552731,"owners_count":17002144,"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","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":[],"created_at":"2024-08-01T02:01:04.664Z","updated_at":"2024-11-01T09:31:02.010Z","avatar_url":"https://github.com/RedTeamPentesting.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\u003cb\u003eresocks\u003c/b\u003e\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\u003ci\u003e\u003c/i\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/RedTeamPentesting/resocks/releases/latest\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/release/RedTeamPentesting/resocks.svg?style=for-the-badge\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/RedTeamPentesting/resocks/actions?workflow=Check\"\u003e\u003cimg alt=\"GitHub Action: Check\" src=\"https://img.shields.io/github/actions/workflow/status/RedTeamPentesting/resocks/check.yml?branch=main\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n    \u003ca href=\"/LICENSE\"\u003e\u003cimg alt=\"Software License\" src=\"https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/RedTeamPentesting/resocks\"\u003e\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/RedTeamPentesting/resocks?style=for-the-badge\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n`resocks` is a reverse/back-connect SOCKS5 proxy tunnel that can be used to\nroute traffic through a system that can't be directly accessed (e.g. due to\nNAT). The channel is secured by mutually trusted TLS with auto-generated\ncertificates based on a connection key. Read our\n[blog post](https://blog.redteam-pentesting.de/2023/introducing-resocks/)\nfor more information.\n\n![resocks](assets/resocks.png)\n\n## Usage\n\nStart the listener on the system that acts as the entry point of the SOCKS5\ntunnel:\n\n```bash\n# on proxy entry point system with IP 1.2.3.4\n$ resocks listen\n```\n\nCopy the connection key and pass it to `resocks` on the relay\nsystem:\n\n```bash\n# on remote relay system with IP 10.0.0.1\n$ resocks 1.2.3.4 --key $CONNECTION_KEY\n```\n\nNow configure tools on the proxy entry point system to use the local SOCKS5\nserver, for example:\n\n```bash\n$ curl --proxy 'socks5://127.0.0.1:1080' 'http://10.0.0.2'\n```\n\nYou can also generate a connection key with `resocks generate` and pass it to\nthe `listen` command to avoid generating a new connection key every time. It\ncan also be specified via an environment variable:\n\n```bash\n$ export RESOCKS_KEY=\"$(resocks generate)\"\n$ resocks listen\n```\n\n## Security\n\nThe threat model of `resocks` primarily takes into account attackers that can\ninspect, intercept and modify traffic between the listener and the relay.\nSpecifically, `resocks` aims to defend against the following scenarios:\n\n- **A: Malicious Observer:** Attackers with network access between the listener\n  and the proxy should not be able to see the SOCKS5 traffic that is routed\n  through the tunnel.\n- **B: Malicious Listener:** When connecting the proxy to a listener, attackers\n  should not be able to redirect the traffic to a malicious listener, as this\n  would grant them access to the proxy server's network.\n- **C: Malicious Relay:** Attackers should not be able to connect to an existing\n  listener in order to be able to receive the traffic that was meant to be\n  routed through the legitimate proxy.\n\nThis threat model suggests using a mutually authenticated encrypted connection\nbetween the listener and the relay as described [here](#key-based-tls).\n\nPlease note that `resocks` is **not** designed to defend against the following\nscenarios:\n\n- **D: Malicious User on Listener System:** Malicious users on the system\n  hosting the listener is generally able to connect to the SOCKS5 proxy or\n  extract the connection key.\n- **E: Malicious User on the Relay System:** A malicious user on the system\n  hosting the relay can generally extract the connection key.\n\nHowever, as described [here](#defense-in-depth), there a some defense-in-depth\nmeasures that can employed to harden `resocks` against such attacks.\n\n### Key-Based TLS\n\nThe tunnel between the listener and the relay is secured by a shared connection\nkey which is used to establish a mutually trusted TLS 1.3 connection. This works\nby using the key on both sides to derive the same CA certificate which is then\nused to sign the server and client certificates that are generated on the spot.\nThe library that implements this technique (`kbtls`) is available\n[here](https://github.com/RedTeamPentesting/kbtls).\n\n![resocks TLS setup](assets/resocks_tls.png)\n\n### Defense-in-Depth\n\nWhen running either the `resocks` listener or relay on an untrusted system\n(scenarios D/E), attackers can potentially read the connection key which\nundermines the defenses against scenarios A, B and C.\n\nBy default, the connection key is passed as a command line flag and can be read\nout by attackers with the permission to see process listing with arguments.\nAlternatively, the connection key can be specified via environment variable\n(`$RESOCKS_KEY`) or it could be statically built into the binary as described\n[below](#building). In this case, the read permissions will need to be revoked\nfor other users. In certain scenarios, these techniques may prevent certain\nlow-privileged attackers from gaining access to the connection keys.\n\n## Building\n\n`resocks` can be built with the following command:\n\n```bash\ngo build\n```\n\nIn order to compile a static connection key as the default connection key\ndirectly into the binary, use the following command:\n\n```bash\ngo run . generate  # generate a connection key\ngo build -ldflags=\"-X main.defaultConnectionKey=YOUR_CONNECTION_KEY\"\n```\n\nSimilarly, the default connect back address can also be statically compiled into\nthe binary:\n\n```bash\ngo build -ldflags=\"-X main.defaultConnectBackAddress=192.0.2.1\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRedTeamPentesting%2Fresocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRedTeamPentesting%2Fresocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRedTeamPentesting%2Fresocks/lists"}