{"id":15713682,"url":"https://github.com/jkthorne/sox","last_synced_at":"2025-08-02T10:33:18.625Z","repository":{"id":54538272,"uuid":"156019486","full_name":"jkthorne/sox","owner":"jkthorne","description":"SOCKS client and server for Crystal","archived":false,"fork":false,"pushed_at":"2021-02-12T02:47:23.000Z","size":564,"stargazers_count":26,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-12T21:46:07.824Z","etag":null,"topics":["crystal","crystal-lang","crystal-language","network","networking","socks","socks-proxy","socks4","socks5","socks5-proxy"],"latest_commit_sha":null,"homepage":null,"language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkthorne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-03T20:05:17.000Z","updated_at":"2024-02-09T20:37:16.000Z","dependencies_parsed_at":"2022-08-13T19:01:07.834Z","dependency_job_id":null,"html_url":"https://github.com/jkthorne/sox","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jkthorne/sox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkthorne%2Fsox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkthorne%2Fsox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkthorne%2Fsox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkthorne%2Fsox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkthorne","download_url":"https://codeload.github.com/jkthorne/sox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkthorne%2Fsox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268371356,"owners_count":24239791,"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-02T02:00:12.353Z","response_time":74,"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":["crystal","crystal-lang","crystal-language","network","networking","socks","socks-proxy","socks4","socks5","socks5-proxy"],"created_at":"2024-10-03T21:32:53.518Z","updated_at":"2025-08-02T10:33:18.591Z","avatar_url":"https://github.com/jkthorne.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sox\n\nSox is a library for creating SOCKS5 clients and servers.  Sox is a network proxy and can proxy connections like HTTP requests or ssh connections.  \n\n## Documentation\n\nFor more documentation on the specs, this implementation is based on please read documents at  `./docs/specs.`\n\nFor more documentation on the implementations of SOCKS, please read documents at  `./docs/`.\n\n## FEATURES\n- SOCKS5\n    - addr type\n        - [x] IPv4 connection\n        - [x] IPv6 connection\n        - [x] Domain connection\n    - Authentication\n        - [x] unauthentication\n        - [ ] GSS connection\n        - [ ] username and password\n        - [x] IANA unimplented in ssh\n    - command types\n        - [x] connect\n        - [x] bind\n        - [x] udp associate\n    - reply / response\n        - [x] reply server messages\n        - [x] connection response server messages\n- SOCKS4\n- SOCKS5 server\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  sox:\n    github: wontruefree/sox\n```\n\n## Usage\n\nA SOCKS Client so to make a connection you have to have a corresponding SOCKS server.  The easiest one to use is ssh.\n\nTo start up a local ssh SOCKS server you can connect to yourself.\n\n```bash\n# Setup SOCKS on localhost\nssh -D 1080 -C -N 127.0.0.1\n```\n\nHave a local SOCKS server directing its connection to a remote host.\n\n```bash\n# Setup SOCKS connecting to remote host\nssh -D 1080 -C -N user@remote.com\n```\n\n### Basic Usage\n\n#### Basic Socket\n\nTo open a SOCKS connection and send a basic HTTP request and get a response.\n\n```crystal\nrequire \"sox\"\n\nsocket = Sox.new(addr: \"52.85.89.35\")\nrequest = HTTP::Request.new(\"GET\", \"/\", HTTP::Headers{\"Host\" =\u003e \"crystal-lang.org\"})\n\nrequest.to_io(socket)\nsocket.flush\n\nresponse = HTTP::Client::Response.from_io(socket)\nif response.success?\n  puts \"Got to crystal through SOCKS5!!!\"\nend\n```\n\n#### Basic Client\n\n`Sox::Client` functions almost like the Crystal (HTTP::Client)[https://crystal-lang.org/api/latest/HTTP/Client.html]\n\n```crystal\nclient = Sox::Client.new(\"www.example.com\", host_addr: \"127.0.0.1\", host_port: 1080)\nresponse = client.get(\"/\")\nputs response.status_code      # =\u003e 200\nputs response.body.lines.first # =\u003e \"\u003c!doctype html\u003e\"\nclient.close\n```\n\n#### Basic UDP\n\n`Sox::UDP` functions almost like the Crystal (UDPSocket)[https://crystal-lang.org/api/latest/UDPSocket.html]\n\n```crystal\nserver = UDPSocket.new\nserver.bind \"localhost\", 9999\n\nclient = Sox::UDP.new(host_addr: \"127.0.0.1\", host_port: 1080)\nclient.connect \"localhost\", 9999\n\nclient.send \"message\"\nmessage, client_addr = server.receive\n\nmessage     # =\u003e \"message\"\nclient_addr # =\u003e Socket::IPAddress(127.0.0.1:50516)\n\nclient.close\nserver.close\n```\n\nyou can use `Sox::Client` almost like the Crystal (HTTP::Client)[https://crystal-lang.org/api/latest/HTTP/Client.html]\n\n```crystal\nclient = Sox::Client.new(\"www.example.com\", host_addr: \"127.0.0.1\", host_port: 1080)\nresponse = client.get(\"/\")\nputs response.status_code      # =\u003e 200\nputs response.body.lines.first # =\u003e \"\u003c!doctype html\u003e\"\nclient.close\n```\n\n### Remote server connnection\n\nTo open a connection to a remote SOCKS5 Server.\n\n\n```crystal\nrequire \"sox\"\n\nsocket = Sox.new(host_addr: \"gateway.com\", addr: \"52.85.89.35\")\nrequest = HTTP::Request.new(\"GET\", \"/\", HTTP::Headers{\"Host\" =\u003e \"crystal-lang.org\"})\n\nrequest.to_io(socket)\nsocket.flush\n\nresponse = HTTP::Client::Response.from_io?(socket)\nif response.success?\n  puts \"Got to crystal through SOCKS5!!!\"\nend\n```\n\n### Connection using none default ports\n\nSometimes you connect to web servers or remote SOCKS servers on ports that are not default.  This is built into the top level interface no having to deal with requests or connection requests directly.\n\n```crystal\nrequire \"sox\"\n\nsocket = Sox.new(host_addr: \"gateway.com\" host_port: 8010, addr: \"52.85.89.35\", port: 3000)\nrequest = HTTP::Request.new(\"GET\", \"/\", HTTP::Headers{\"Host\" =\u003e \"crystal-lang.org\"})\n\nrequest.to_io(socket)\nsocket.flush\n\nresponse = HTTP::Client::Response.from_io?(socket)\nif response.success?\n  puts \"Got to crystal through SOCKS5!!!\"\nend\n```\n\n## Specs\n\nBefore running specs you should add your public key to the authorized keys.  Please read below if you have not previously set up a socks server for testing.   Although I like Unit Test Spec SOCKS only use tools in the stdlib so this is written in spec style syntax.\n\n### Runnning specs\n\nTo run the test suite use the spec command built into crystal.\n\n```bash\ncrystal spec\n```\n\n### Setup SOCKS Server\n\nenable key based authentication for testing\n\n```bash\n# enable key based localhost authentication\ncat ~/.ssh/id_rsa.pub \u003e ~/.ssh/authorized_keys\n```\n\n### TOR\nThere are some basic tests for a commonly used SOCKS5 server tor.\n\n#### Debian\nInstall tor via apt.\n\n```bash\nsudo apt install tor\n```\n\nOptional: Start tor at login and keep tor running in the background.\n\n```bash\nsystemctl start tor\n```\n\n#### MAC\n\nUse homebrew to install tor on your mac.\n\n```bash\nbrew install tor\n```\n\nOptional: Use brew services to keep tor running in the background.\n\n```bash\nbrew services start tor\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkthorne%2Fsox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkthorne%2Fsox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkthorne%2Fsox/lists"}