https://github.com/zetxtech/pywssocks
A SOCKS proxy implementation over WebSocket protocol.
https://github.com/zetxtech/pywssocks
networking proxy reverse-proxy socks5 waf websocket
Last synced: 12 months ago
JSON representation
A SOCKS proxy implementation over WebSocket protocol.
- Host: GitHub
- URL: https://github.com/zetxtech/pywssocks
- Owner: zetxtech
- License: mit
- Created: 2025-01-29T20:11:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-13T22:11:10.000Z (about 1 year ago)
- Last Synced: 2025-06-01T02:08:19.451Z (about 1 year ago)
- Topics: networking, proxy, reverse-proxy, socks5, waf, websocket
- Language: Python
- Homepage: https://pywssocks.zetx.tech
- Size: 222 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/zetxtech/pywssocks/actions) [](https://app.codecov.io/gh/zetxtech/pywssocks/tree/main)  [](https://pypi.org/project/pywssocks/)  [](https://hub.docker.com/r/jackzzs/pywssocks)
# Pywssocks
Pywssocks is a SOCKS proxy implementation over WebSocket protocol.
## Overview
This 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).
For golang version, please check [zetxtech/wssocks](https://github.com/zetxtech/wssocks).
## Features
1. Both client and server modes, supporting command-line usage or library integration.
2. Forward and reverse proxy capabilities.
3. Round-robin load balancing for reverse proxy.
4. SOCKS proxy authentication support.
5. IPv6 over SOCKS5 support.
6. UDP over SOCKS5 support.
## Potential Applications
1. Distributed HTTP backend.
2. Bypassing CAPTCHA using client-side proxies.
3. Secure intranet penetration, using CDN network.
## Usage
### As a tool
Forward Proxy:
```bash
# Server (WebSockets at port 8765, as network connector)
pywssocks server -t example_token
# Client (SOCKS5 at port 1080)
pywssocks client -t example_token -u ws://localhost:8765 -p 1080
```
Reverse Proxy:
```bash
# Server (WebSockets at port 8765, SOCKS at port 1080)
pywssocks server -t example_token -p 1080 -r
# Client (as network connector)
pywssocks client -t example_token -u ws://localhost:8765 -r
```
### As a library
Forward Proxy:
```python
import asyncio
from pywssocks import WSSocksServer, WSSocksClient
# Server
server = WSSocksServer(
ws_host="0.0.0.0",
ws_port=8765,
)
token = server.add_forward_token()
print(f"Token: {token}")
asyncio.run(server.start())
# Client
client = WSSocksClient(
token="",
ws_url="ws://localhost:8765",
socks_host="127.0.0.1",
socks_port=1080,
)
asyncio.run(client.start())
```
Reverse Proxy:
```python
import asyncio
from pywssocks import WSSocksServer, WSSocksClient
# Server
server = WSSocksServer(
ws_host="0.0.0.0",
ws_port=8765,
socks_host="127.0.0.1",
socks_port_pool=range(1024, 10240),
)
token, port = server.add_reverse_token()
print(f"Token: {token}\nPort: {port}")
asyncio.run(server.start())
# Client
client = WSSocksClient(
token="",
ws_url="ws://localhost:8765",
reverse=True,
)
asyncio.run(client.start())
```
## Installation
Pywssocks requires `python >= 3.8`, and can be installed by:
```bash
pip install pywssocks
```
Pywssocks is also available via docker:
```bash
docker run --rm -it jackzzs/pywssocks --help
```
## Documentation
Visit the documentation: [https://pywssocks.zetx.tech](https://pywssocks.zetx.tech)
## License
Pywssocks is open source under the MIT license.