{"id":28392776,"url":"https://github.com/zetxtech/pywssocks","last_synced_at":"2025-06-26T07:31:19.863Z","repository":{"id":275832823,"uuid":"924331662","full_name":"zetxtech/pywssocks","owner":"zetxtech","description":"A SOCKS proxy implementation over WebSocket protocol.","archived":false,"fork":false,"pushed_at":"2025-04-13T22:11:10.000Z","size":227,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T02:08:19.451Z","etag":null,"topics":["networking","proxy","reverse-proxy","socks5","waf","websocket"],"latest_commit_sha":null,"homepage":"https://pywssocks.zetx.tech","language":"Python","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/zetxtech.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}},"created_at":"2025-01-29T20:11:42.000Z","updated_at":"2025-04-21T03:57:31.000Z","dependencies_parsed_at":"2025-02-04T20:33:19.298Z","dependency_job_id":"cebb1665-8f3e-430c-a879-11aed12fe49e","html_url":"https://github.com/zetxtech/pywssocks","commit_stats":null,"previous_names":["zetxtech/pywssocks"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/zetxtech/pywssocks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zetxtech%2Fpywssocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zetxtech%2Fpywssocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zetxtech%2Fpywssocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zetxtech%2Fpywssocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zetxtech","download_url":"https://codeload.github.com/zetxtech/pywssocks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zetxtech%2Fpywssocks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262022121,"owners_count":23246264,"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":["networking","proxy","reverse-proxy","socks5","waf","websocket"],"created_at":"2025-05-31T15:08:14.144Z","updated_at":"2025-06-26T07:31:19.847Z","avatar_url":"https://github.com/zetxtech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/zetxtech/pywssocks/ci.yml?logo=github\u0026label=Tests)](https://github.com/zetxtech/pywssocks/actions) [![Codecov](https://img.shields.io/codecov/c/github/zetxtech/pywssocks?logo=codecov\u0026logoColor=white)](https://app.codecov.io/gh/zetxtech/pywssocks/tree/main) ![Python Version](https://img.shields.io/badge/python_version-%3E%203.8-blue?logo=python\u0026logoColor=white) [![PyPI - Version](https://img.shields.io/pypi/v/pywssocks?logo=pypi\u0026logoColor=white)](https://pypi.org/project/pywssocks/) ![PyPI - Downloads](https://img.shields.io/pypi/dm/pywssocks?logo=pypi\u0026logoColor=white) [![Docker Pulls](https://img.shields.io/docker/pulls/jackzzs/pywssocks?logo=docker\u0026logoColor=white)](https://hub.docker.com/r/jackzzs/pywssocks)\n\n# Pywssocks\n\nPywssocks is a SOCKS proxy implementation over WebSocket protocol.\n\n## Overview\n\nThis tool allows you to securely expose SOCKS proxy services under Web Application Firewall (WAF) protection (forward socks), or enable clients to connect and serve as SOCKS proxy servers when they don't have public network access (reverse socks).\n\n![Main Diagram](https://github.com/zetxtech/pywssocks/raw/main/images/abstract.svg)\n\nFor golang version, please check [zetxtech/wssocks](https://github.com/zetxtech/wssocks).\n\n## Features\n\n1. Both client and server modes, supporting command-line usage or library integration.\n2. Forward and reverse proxy capabilities.\n3. Round-robin load balancing for reverse proxy.\n4. SOCKS proxy authentication support.\n5. IPv6 over SOCKS5 support.\n6. UDP over SOCKS5 support.\n\n## Potential Applications\n\n1. Distributed HTTP backend.\n2. Bypassing CAPTCHA using client-side proxies.\n3. Secure intranet penetration, using CDN network.\n\n## Usage\n\n### As a tool\n\nForward Proxy:\n\n```bash\n# Server (WebSockets at port 8765, as network connector)\npywssocks server -t example_token\n\n# Client (SOCKS5 at port 1080)\npywssocks client -t example_token -u ws://localhost:8765 -p 1080\n```\n\nReverse Proxy:\n\n```bash\n# Server (WebSockets at port 8765, SOCKS at port 1080)\npywssocks server -t example_token -p 1080 -r\n\n# Client (as network connector)\npywssocks client -t example_token -u ws://localhost:8765 -r\n```\n\n### As a library\n\nForward Proxy:\n\n```python\nimport asyncio\nfrom pywssocks import WSSocksServer, WSSocksClient\n\n# Server\nserver = WSSocksServer(\n    ws_host=\"0.0.0.0\",\n    ws_port=8765,\n)\ntoken = server.add_forward_token()\nprint(f\"Token: {token}\")\nasyncio.run(server.start())\n\n# Client\nclient = WSSocksClient(\n    token=\"\u003ctoken\u003e\",\n    ws_url=\"ws://localhost:8765\",\n    socks_host=\"127.0.0.1\",\n    socks_port=1080,\n)\nasyncio.run(client.start())\n```\n\nReverse Proxy:\n\n```python\nimport asyncio\nfrom pywssocks import WSSocksServer, WSSocksClient\n\n# Server\nserver = WSSocksServer(\n    ws_host=\"0.0.0.0\",\n    ws_port=8765,\n    socks_host=\"127.0.0.1\",\n    socks_port_pool=range(1024, 10240),\n)\ntoken, port = server.add_reverse_token()\nprint(f\"Token: {token}\\nPort: {port}\")\nasyncio.run(server.start())\n\n# Client\nclient = WSSocksClient(\n    token=\"\u003ctoken\u003e\",\n    ws_url=\"ws://localhost:8765\",\n    reverse=True,\n)\nasyncio.run(client.start())\n```\n\n## Installation\n\nPywssocks requires `python \u003e= 3.8`, and can be installed by:\n\n```bash\npip install pywssocks\n```\n\nPywssocks is also available via docker:\n\n```bash\ndocker run --rm -it jackzzs/pywssocks --help\n```\n\n## Documentation\n\nVisit the documentation: [https://pywssocks.zetx.tech](https://pywssocks.zetx.tech)\n\n## License\n\nPywssocks is open source under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzetxtech%2Fpywssocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzetxtech%2Fpywssocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzetxtech%2Fpywssocks/lists"}