asyncio-socks-server

SOCKS5 server with async Python addon hooks.

Docs · Architecture · Addon recipes · Addon model · Public API · 简体中文

Install

pip install asyncio-socks-server

Docker images are versioned:

docker run --rm -p 1080:1080 amaindex/asyncio-socks-server:1.3.2

Run

asyncio_socks_server
asyncio_socks_server --host 127.0.0.1 --port 9050
asyncio_socks_server --auth user:pass

CLI flags:

Use from Python

from asyncio_socks_server import Server

Server(host="::", port=1080).run()

Addons are optional. Add only the behavior you need:

Runtime counters and audit API:

from asyncio_socks_server import FlowAudit, FlowStats, Server, StatsAPI

audit = FlowAudit()
stats = FlowStats()
server = Server(
    addons=[
        audit,
        stats,
        StatsAPI(stats=stats, audit=audit, host="127.0.0.1", port=9900),
    ],
)
server.run()

Addon order is execution order. Built-in addons are opt-in; adding StatsAPI is what starts an HTTP listener.

FlowStats has no network side effects. Use its summary(), snapshot(), and flows() methods directly, or pair it with StatsAPI for a small local HTTP API. Poll GET /stats/summary for aggregate monitoring; it deliberately omits variable-length flow and recent-error details. Fetch GET /flows/active only when an operator explicitly needs current flow details. FlowAudit records closed-flow usage in memory and can be exposed through StatsAPI for Kafra-like usage audit summaries.

Default logs are compact key-value events, for example event=flow_closed flow_id=7 proto=tcp src=127.0.0.1:50000 dst=example.com:443 bytes_up=128 bytes_down=1024. Use --log-format json when a log collector prefers JSON lines.

For task-oriented examples, see Addon recipes.

Model

The core handles SOCKS5 parsing, relay, and hook dispatch. Addons handle policy.

Hook dispatch has three models:

Built-ins:

• ChainRouter for TCP chain proxying
• UdpOverTcpEntry and UdpOverTcpExitServer for UDP chain proxying
• FlowStats for in-memory flow statistics
• FlowAudit for closed-flow usage audit summaries
• StatsAPI as an opt-in HTTP API around FlowStats
• StatsServer as a backward-compatible name for StatsAPI
• TrafficCounter, FileAuth, IPFilter, Logger

Architecture sketch

Client ── SOCKS5 ──▶ Server ──▶ Target
                     │
                     ├─ auth / route hooks
                     ├─ data pipeline hooks
                     └─ flow close hooks

ChainRouter:
Client ──▶ A ──▶ B ──▶ C ──▶ Target

Chain proxying

Each node only knows its next hop:

# A ─▶ B ─▶ C ─▶ target
Server(addons=[ChainRouter("B:1080")])  # A
Server(addons=[ChainRouter("C:1080")])  # B
Server()  # C

UDP chain proxying uses TCP between proxy nodes:

from asyncio_socks_server import Server, UdpOverTcpEntry, UdpOverTcpExitServer

entry = Server(addons=[UdpOverTcpEntry("exit-host:9020")])
exit_server = UdpOverTcpExitServer(host="::", port=9020)

Client

from asyncio_socks_server import Address, connect

conn = await connect(
    proxy_addr=Address("127.0.0.1", 1080),
    target_addr=Address("93.184.216.34", 443),
)
conn.writer.write(b"hello")
await conn.writer.drain()
data = await conn.reader.read(4096)

API surface

Stable imports live at the package root:

from asyncio_socks_server import (
    Addon,
    Address,
    ChainRouter,
    Flow,
    FlowAudit,
    FlowStats,
    Server,
    StatsAPI,
    StatsServer,
    UdpOverTcpEntry,
    UdpOverTcpExitServer,
    connect,
)

Root exports are the 1.x compatibility contract. Submodules remain importable.

Docs

Development

git clone https://github.com/Amaindex/asyncio-socks-server.git
cd asyncio-socks-server
uv sync
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv build

Release

GitHub Actions tests Python 3.12 and 3.13, builds the Python package, and builds Docker images.

Create a GitHub Release from a tag such as v1.3.2. The release workflow publishes the Python package. The Docker workflow publishes semver image tags.

License

MIT