diff --git a/README.md b/README.md index d5ecbe0..58c0193 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ through configurable chains of SOCKS4, SOCKS5, and HTTP CONNECT proxies. - Supported hop protocols: SOCKS5, SOCKS4/4a, HTTP CONNECT - Per-hop authentication (username/password) - DNS leak prevention (domain names forwarded to proxies, never resolved locally) -- Tor integration (Tor is just another SOCKS5 hop) +- Tor integration (SOCKS5 hop + control port NEWNYM for circuit rotation) - Managed proxy pool: multiple sources (API + file), health-tested, weighted selection - Per-proxy failure backoff (60s cooldown), stale proxy expiry, chain pre-flight - Fast warm start (seconds on restart vs minutes on cold start) @@ -76,6 +76,11 @@ api_listen: 127.0.0.1:1081 # control API (disabled by default) chain: - socks5://127.0.0.1:9050 # Tor +tor: + control_port: 9051 # Tor control port (NEWNYM) + password: "" # or cookie_file for auth + newnym_interval: 0 # periodic circuit rotation (0 = manual) + proxy_pool: sources: - url: http://10.200.1.250:8081/proxies diff --git a/ROADMAP.md b/ROADMAP.md index ac5f329..6ec6df6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -24,7 +24,7 @@ - [x] Built-in control API (runtime metrics, pool state, config reload) - [ ] SOCKS5 server authentication (username/password) -- [ ] Tor control port integration (circuit renewal via NEWNYM) +- [x] Tor control port integration (circuit renewal via NEWNYM) - [ ] Metrics (connections/sec, bytes relayed, hop latency) ## v0.3.0 diff --git a/TASKS.md b/TASKS.md index 3bb79c2..a45ec1f 100644 --- a/TASKS.md +++ b/TASKS.md @@ -44,7 +44,8 @@ - [x] Use k8s-file logging driver with rotation - [x] Built-in control API (`api.py`, `--api`, `api_listen`) +- [x] Tor control port integration (NEWNYM signaling, periodic rotation) + ## Next - [ ] Integration tests with mock proxy server - [ ] SOCKS5 server-side authentication -- [ ] Tor control port integration diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md index bff5a6d..c338fcc 100644 --- a/docs/CHEATSHEET.md +++ b/docs/CHEATSHEET.md @@ -59,6 +59,20 @@ proxy_pool: report_url: "" # POST dead proxies (optional) ``` +## Tor Control Port (config) + +```yaml +tor: + control_port: 9051 + password: "" # or cookie_file: /path/to/cookie + newnym_interval: 60 # auto-rotate every 60s (0 = manual) +``` + +```bash +curl -s http://127.0.0.1:1081/tor | jq . # status +curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq . # new circuit +``` + ## Hot Reload ```bash diff --git a/docs/USAGE.md b/docs/USAGE.md index 3a05155..eea824e 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -281,6 +281,69 @@ curl -s -X POST http://127.0.0.1:1081/pool/refresh | jq . Settings that require a restart: `listen`, `chain`, `pool_size`, `pool_max_idle`, `api_listen`. +## Tor Control Port + +Optional integration with Tor's control protocol for circuit management. +When enabled, s5p connects to Tor's control port and can send NEWNYM signals +to request new circuits (new exit node) on demand or on a timer. + +### Configuration + +```yaml +tor: + control_host: 127.0.0.1 # Tor control address + control_port: 9051 # Tor control port + password: "" # HashedControlPassword (torrc) + cookie_file: "" # CookieAuthentication file path + newnym_interval: 0 # periodic NEWNYM in seconds (0 = manual only) +``` + +Requires Tor's `ControlPort` enabled in `torrc`: + +``` +ControlPort 9051 +HashedControlPassword 16:... # or CookieAuthentication 1 +``` + +### Authentication modes + +| Mode | Config | torrc | +|------|--------|-------| +| Password | `password: "secret"` | `HashedControlPassword 16:...` | +| Cookie | `cookie_file: /var/run/tor/control.authcookie` | `CookieAuthentication 1` | +| None | (leave both empty) | No auth configured | + +### Rate limiting + +Tor enforces a minimum 10-second interval between NEWNYM signals. s5p +applies the same client-side rate limit to avoid unnecessary rejections. + +### API endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/tor` | Controller status (enabled, connected, last NEWNYM) | +| `POST` | `/tor/newnym` | Trigger NEWNYM signal (new circuit) | + +```bash +# Check tor controller status +curl -s http://127.0.0.1:1081/tor | jq . + +# Request new circuit +curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq . +``` + +### Periodic NEWNYM + +Set `newnym_interval` to automatically rotate circuits: + +```yaml +tor: + newnym_interval: 60 # new circuit every 60 seconds +``` + +Values below 10 are clamped to Tor's minimum interval. + ## Connection Retry When a proxy pool is active, s5p retries failed connections with a different