{"id":39818001,"url":"https://github.com/nmaguiar/socksd","last_synced_at":"2026-01-18T12:53:08.529Z","repository":{"id":93251041,"uuid":"526783025","full_name":"nmaguiar/socksd","owner":"nmaguiar","description":"Simple SOCKS proxy container","archived":false,"fork":false,"pushed_at":"2026-01-10T07:06:08.000Z","size":44881,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T02:00:26.480Z","etag":null,"topics":["container","kubernetes","proxy","socks-proxy","socks5-proxy"],"latest_commit_sha":null,"homepage":"","language":"Edge","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmaguiar.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-20T00:02:41.000Z","updated_at":"2026-01-10T07:06:09.000Z","dependencies_parsed_at":"2023-10-12T16:29:36.624Z","dependency_job_id":"3dcf1040-f336-44e3-809b-27198e67cb7a","html_url":"https://github.com/nmaguiar/socksd","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nmaguiar/socksd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmaguiar%2Fsocksd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmaguiar%2Fsocksd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmaguiar%2Fsocksd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmaguiar%2Fsocksd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmaguiar","download_url":"https://codeload.github.com/nmaguiar/socksd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmaguiar%2Fsocksd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28536555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["container","kubernetes","proxy","socks-proxy","socks5-proxy"],"created_at":"2026-01-18T12:53:08.401Z","updated_at":"2026-01-18T12:53:08.495Z","avatar_url":"https://github.com/nmaguiar.png","language":"Edge","funding_links":[],"categories":[],"sub_categories":[],"readme":"# socksd\n\nVery simple SOCKS proxy container. Allows you to proxy directly to a docker network or a Kubernetes cluster connecting a curl command, your Chrome or Firefox browser or even other applications like DBeaver to access a database.\n\nMain features:\n- IPv6 support\n- JSON logs output support\n- SOCKS 4, 5 and 5 with DNS resolution\n- Filter the network addresses allowed (e.g. 192.168.1.0/16,fc00::/7, etc...) \n- Filter the network domains allowed (e.g. default.svc,default.svc.cluster.local, etc...)\n- Filter by ASN (Autonomous System Numbers) for granular network control\n- Reverse filter logic to exclude instead of include specified networks\n- Detailed connection log support\n- Scale capacity by increasing deploy replicas\n- Optional extra HTTP proxy for clients that don't support SOCKS proxy\n- Health check and metrics endpoints for monitoring\n\nSecurity scans to latest and build container images:\u003cbr\u003e\u003cbr\u003e\n[![.github/sec-build.svg](.github/sec-build.svg)](.github/sec-build.md)\u003cbr\u003e\n[![.github/sec-latest.svg](.github/sec-latest.svg)](.github/sec-latest.md)\u003cbr\u003e\u003cbr\u003e\n[![.github/sec-ubi-build.svg](.github/sec-ubi-build.svg)](.github/sec-ubi-build.md)\u003cbr\u003e\n[![.github/sec-ubi-latest.svg](.github/sec-ubi-latest.svg)](.github/sec-ubi-latest.md)\u003cbr\u003e\u003cbr\u003e\n[![.github/sec-edge.svg](.github/sec-edge.svg)](.github/sec-edge.md)\n\n\u003e 'latest' tag images are images you can use that have been tested;\n\u003e 'build' tag images are automated weekly un-tested build;\n\u003e 'edge' is equivalent to 'build' but using the very latest versions of everything\n\n## Run on Docker\n\n````bash\ndocker run -d --rm -p 1080:1080 --network mynet --name socksd nmaguiar/socksd\n````\n\nAnd then configure your SOCKS proxy to localhost:1080\n\n## Run on Kubernetes\n\n````bash\nkubectl create deployment socksd --image=nmaguiar/socksd --port=1080\nkubectl port-forward deploy/socksd 1080:1080\n# OR kubectl create service nodeport socksd --tcp=31080:1080 --node-port=31080\n````\n\nAnd then configure your SOCKS proxy to localhost:1080\n\n\u003e You can avoid the port-forward by deploying a K8S NodePort service (e.g port 31080) to the socksd deployment. Please be aware that Istio will impact the connectinos to the socksd pod so it should be deployed in a non-Istio namespace.\n\n## Building\n\nBuild command: \n\n````bash\ndocker build -t socksd .\n````\n\n## Options\n\nYou can control the behaviour with environment variables:\n\n| Variable | Possible values | Description |\n|----------|-----------------|-------------|\n| ONLY_LOCAL | true/false | Filters all proxied traffic only to private network addresses (DOMAINFILTERS, FILTERS and ASNFILTERS are ignored) |\n| LOGS | true/false | Enables basic connection logging |\n| LOGS_DETAIL | true/false | Enables more verbose logging (requires LOGS=true) |\n| FILTERS | \"192.168.1.0/16,fc00::/7\" | Comma-delimited list of CIDRs to filter all traffic proxied. |\n| DOMAINFILTERS | \"default.svc,default.svc.cluster.local\" | Comma-delimited list of domains to filter all traffi proxied. |\n| ASNFILTERS | \"1234,5678\" | Comma-delimited list of ASNs (Autonomous System Numbers) to filter all traffic proxied. |\n| ASNUPDATES | true/false | Enables periodic ASN index updates (set to false to disable). |\n| ASNURL | \"https://example.com/asn.json.gz\" | Alternative URL for ASN index download. |\n| REVFILTERS | true/false | If \"true\" reverse all filters from inclusion to exclusion. |\n| DNSTIMEOUT | 10 | Sets a different DNS resolution timeout (in seconds) from the default (10 seconds) |\n| INITOJOB | setDNS.yaml | (optional) Runs the indicated OpenAF's oJob to perform an initialization function. |\n| INITOJOBARGS | \"(arg1: xyz, arg2: 123)\" | (optional) The INITOJOB arguments to use in [SLON](https://github.com/nmaguiar/slon) format |\n| INITOJOBFAIL | true/false | If \"true\" the socks server will not start if the INITOJOB fails |\n| OJOB_JSONLOG | true/false | Ensures all output log to stdout is in JSON |\n| HTTPPROXY | true/false | (optional) Starts a http/https proxy to relay requests to the socks proxy on port 8888 (to support applications that don't support connecting to a socks proxy) |\n\n\u003e You can add these variables with the option '-e' on the ````docker run -d --rm -p 1080:1080 -e LOGS=true -e ONLY_LOCAL=true -e OJOB_JSONLOG=true --network mynet --name socksd nmaguiar/socksd```` command or with ````kubectl set env deploy socksd LOGS=true ONLY_LOCAL=true OJOB_JSONLOG=true```` in Kubernetes\n\n### Advanced Filtering\n\nThe proxy supports several types of filtering:\n\n- **IP/CIDR Filtering (`FILTERS`)**: Filter by specific IP addresses or CIDR ranges\n- **Domain Filtering (`DOMAINFILTERS`)**: Filter by domain names  \n- **ASN Filtering (`ASNFILTERS`)**: Filter by Autonomous System Numbers for network-level control\n- **Reverse Filtering (`REVFILTERS`)**: When set to \"true\", reverses the logic of all filters from inclusion to exclusion\n\nExamples:\n```bash\n# Allow only specific IP ranges\n-e FILTERS=\"192.168.1.0/24,10.0.0.0/8\"\n\n# Allow only specific domains\n-e DOMAINFILTERS=\"internal.company.com,*.local\"\n\n# Allow only specific ASNs (e.g., specific cloud providers)\n-e ASNFILTERS=\"16509,13335\"  # AWS and Cloudflare ASNs\n\n# Block instead of allow the specified filters\n-e REVFILTERS=true -e FILTERS=\"192.168.1.0/24\"  # Block 192.168.1.0/24\n```\n\n\u003e Note: When `ONLY_LOCAL=true`, all other filter options (FILTERS, DOMAINFILTERS, ASNFILTERS) are ignored.\n\n## Deployment examples\n\n### Docker example\n\nCreating a docker network, launching the socksd container and a nginx container and then \"curl\"ing directly the nginx container as if doing from another container:\n\n````bash\ndocker network create test\ndocker run -d --rm -p 1080:1080 --network test --name socksd nmaguiar/socksd\ndocker run -d --rm -p 8888:80 --network test --name nginx nginx\n\n# Curling inside the docker network 'test'\ncurl http://nginx --proxy socks5h://127.0.0.1:1080\n````\n\n### Kubernetes example\n\nLaunching a socksd deployment, a nginx deployment and exposing the nginx deployment. Then \"curl\"ing directly the nginx service as if it was running inside the Kubernetes cluster:\n\n````bash\nkubectl create deployment socksd --image nmaguiar/socksd --port=1080\nkubectl create deployment nginx --image nginx\n\nkubectl expose deploy nginx --port=80\nkubectl port-forward deploy/socksd 1080:1080 \u0026\n# OR JUST:  kubectl create service nodeport socksd --tcp=31080:1080 --node-port=31080\n\n# Curling inside the Kubernetes cluster\ncurl http://nginx.default.svc --proxy socks5h://127.0.0.1:1080\n````\n\n\u003e Using the Kubernetes NodePort solution is faster than port-forward but requires that you have access to port 31080 on each node.\n\n### Other examples\n\n* [AWS EKS example with AWS Route 53](docs/AWS-EKS.md)\n\n## Usage examples:\n\n### Using browsers\n\n__Chrome__\n\nYou can run a Chrome browser in your desktop and enter URLs as if the browser was running inside the Kubernetes cluster:\n\n![Chrome](images/chrome.png)\n\nTo launch a separate clean Chrome browser configured to use a SOCKS proxy with proxy DNS you can use the following scripts on each OS:\n\n| OS | Command |\n|----|---------|\n| Windows | curl https://ojob.io/win/newChrome.bat -O newChrome.bat\u003cbr\u003enewChrome.bat default localhost:1080 |\n| Mac OS | ````curl https://ojob.io/mac/newChrome.sh \\| sh -s default localhost:1080```` |\n| Linux | ````curl https://ojob.io/unix/newChrome.sh \\| sh -s default localhost:1080```` |\n\n\u003e Use port 31080 instead of 1080 if you use the faster Kubernetes NodePort alternative\n\n__Firefox__\n\nAlternatively to Chrome based browsers you can configure Firefox by changing the connection settings for SOCKS proxy on a Firefox browser while also proxy DNS:\n\n![Firefox](images/firefox.png)\n\n\u003e Use port 31080 instead of 1080 if you use the faster Kubernetes NodePort alternative\n\n### Using a database client:\n\nLaunching a socksd deployment, a postgresql database deployment and then using DBeaver to access it:\n\n````bash\nkubectl create deployment socksd --image nmaguiar/socksd --port=1080\nkubectl port-forward deploy/socksd 1080:1080 \u0026\n# OR kubectl create service nodeport socksd --tcp=31080:1080 --node-port=31080\n\nhelm install postgresql bitnami/postgresql\necho PASSWORD=$(kubectl get secret --namespace default postgresql -o jsonpath=\"{.data.postgres-password}\" | base64 -d)\n````\n\nThen, using DBeaver, create a PostgreSQL connection like this:\n\n![DBeaver_main](images/dbeaver_main.png)\n\nsetting the proxy SOCKS like this:\n\n![DBeaver_proxy](images/dbeaver_proxy.png)\n\n\u003e Use port 31080 instead of 1080 if you use the faster Kubernetes NodePort alternative\n\nand you will be able to use the database directly as if you were running DBeaver inside the Kubernetes cluster:\n\n![DBeaver](images/dbeaver.png)\n\n#### Oracle\n\nTo make it work with Oracle drivers follow these steps:\n\n1. Choose an Oracle connection and then edit the \"Driver settings\" to update the Oracle Driver to the latest (\u003e= 23.2.0.0)\n2. On the connection, choose \"Driver properties\" and set:\n   \n| Name | Value |\n|------|-------|\n| oracle.net.socksProxyHost | 127.0.0.1 (or the host/ip of the K8S node if using NodePort) |\n| oracle.net.socksProxyPort | 1080 (or 31080 if using NodePort) |\n| oracle.net.socksRemoteDNS | true |\n\nTest the connection and connect to the Oracle database.\n\n\u003e This was also tested with an Oracle's connection string\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmaguiar%2Fsocksd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmaguiar%2Fsocksd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmaguiar%2Fsocksd/lists"}