diff --git a/CHANGELOG.md b/CHANGELOG.md index 558b7d8..c80c85e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.7.6] โ€” 2026-11-12 + +### Changed +- **docs**: Restructure README.md and DOCKERHUB.md with developer psychology, progressive disclosure, and 2-step quickstarts (#144, #145) +- **docs**: Add quick-reference endpoint matrix to `docs/api.md` and key variables callout to `docs/configuration.md` (#145) +- **docs**: Relocate MCP quickstart ahead of architecture details in `docs/mcp.md` (#145) +- **chore**: Synchronize version 2.7.6 across pyproject.toml, Dockerfile, server.json, and documentation contracts (#145) + ## [2.7.5] โ€” 2026-11-11 ### Added @@ -240,7 +248,8 @@ Sprint 1 security & contract correctness release. --- -[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.5...HEAD +[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.6...HEAD +[2.7.6]: https://github.com/hapheus/torproxy/compare/v2.7.5...v2.7.6 [2.7.5]: https://github.com/hapheus/torproxy/compare/v2.7.4...v2.7.5 [2.7.4]: https://github.com/hapheus/torproxy/compare/v2.7.3...v2.7.4 [2.7.3]: https://github.com/hapheus/torproxy/compare/v2.7.2...v2.7.3 diff --git a/DOCKERHUB.md b/DOCKERHUB.md index a2a3ec8..ca26aaf 100644 --- a/DOCKERHUB.md +++ b/DOCKERHUB.md @@ -3,43 +3,34 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Docker Pulls](https://img.shields.io/docker/pulls/hapheus/torproxy)](https://hub.docker.com/r/hapheus/torproxy) [![Architectures](https://img.shields.io/badge/arch-amd64%20%7C%20arm64%20%7C%20arm%2Fv7-blue)](https://hub.docker.com/r/hapheus/torproxy) +[![Non-Root: Enforced](https://img.shields.io/badge/Security-Non--Root-brightgreen)](https://github.com/hapheus/torproxy) +[![Fail-Closed](https://img.shields.io/badge/Protection-Fail--Closed-success)](https://github.com/hapheus/torproxy) +[![OpenSSF Best Practices](https://img.shields.io/cii/percentage/15828?logo=linuxfoundation&label=OpenSSF%20Best%20Practices)](https://www.bestpractices.dev/projects/15828) -A lightweight, secure, and production-ready Docker container combining **Tor**, **Privoxy** (HTTP/HTTPS proxy), **SOCKS5**, and a local **REST control API**. +**Production-grade, leak-proof Tor HTTP and SOCKS5 proxy packaged for Docker.** +Route entire container networks with zero application changes, connect AI coding assistants (Claude Desktop, Cursor) via built-in MCP, and rotate circuits dynamically via REST. Source repository: [https://github.com/hapheus/torproxy](https://github.com/hapheus/torproxy) --- -## Key Features +## โšก Core Value & Features -- **Transparent Tor Gateway**: Route any Docker container's entire TCP and DNS traffic automatically through Tor using `network_mode: "service:torproxy"` โ€” zero app proxy configuration, fail-closed netfilter kill switch. -- **HTTP/HTTPS Proxy (Port 8118)**: Powered by Privoxy, automatically resolving DNS lookups through Tor exit relays to prevent DNS leaks. -- **SOCKS5 Proxy (Port 9050)**: Standard Tor SOCKS5 interface supporting remote hostname resolution (`socks5h://`). -- **REST Control API (Port 8080)**: Inspect circuit status, trigger circuit rotation (`/reconnect`), query health diagnostics, and pull Prometheus metrics. -- **Fail-Closed Security**: Privoxy strictly routes to Tor SOCKS5; if Tor circuits drop, proxy requests fail immediately (500/503) rather than leaking to clearnet. -- **Authenticated Tor Control**: Local Tor ControlPort is secured using ephemeral 32-byte filesystem cookie authentication. -- **Non-Root Execution**: Runs under a dedicated, unprivileged system user (`torproxy`), never as root. -- **Multi-Architecture**: Built natively for `linux/amd64`, `linux/arm64`, and `linux/arm/v7`. -- **Country-Specific Exit Nodes**: Route traffic through exit relays in specific countries (e.g. `TORPROXY_COUNTRY=DE` or `DE,AT`) backed by `tor-geoipdb`. -- **Zero Breaking Changes**: Guaranteed backward compatibility across minor releases. +- **๐Ÿ›ก๏ธ Zero Clearnet Leaks:** True fail-closed protection. If Tor disconnects, Privoxy and the netfilter kill-switch immediately drop traffic (HTTP 503) โ€” your real IP is never exposed. +- **๐Ÿš€ Transparent Tor Gateway:** Attach any container via `network_mode: "service:torproxy"` to tunnel all outbound TCP & DNS through Tor automatically โ€” zero app proxy flags or code changes. +- **๐Ÿค– Native AI Agent MCP Server:** Built-in Model Context Protocol server on port `2501` (SSE) and via Stdio (`torproxy mcp`) for seamless Claude Desktop, Cursor, and Antigravity integration. +- **๐Ÿ”„ Dynamic Circuit Rotation:** Rotate Tor identities (`SIGNAL NEWNYM`) or switch exit countries on the fly without container restarts via the REST API (`:8080`). +- **๐Ÿ”’ Hardened Non-Root Security:** Daemons run strictly under an unprivileged user (`torproxy`), with authenticated loopback Tor ControlPort. +- **๐ŸŒ Country-Specific Routing:** Select Tor exit relays by country (e.g. `TORPROXY_COUNTRY=DE` or `DE,AT`) backed by built-in `tor-geoipdb`. +- **๐Ÿ“ฆ Multi-Architecture:** Built natively for `linux/amd64`, `linux/arm64`, and `linux/arm/v7`. --- -## Quick Start +## ๐Ÿš€ Quick Start -### Option 1: Docker Run +### Recommended: Docker Compose -```bash -docker run -d \ - --name torproxy \ - --restart unless-stopped \ - -p 127.0.0.1:8118:8118 \ - -p 127.0.0.1:9050:9050 \ - -p 127.0.0.1:8080:8080 \ - hapheus/torproxy:latest -``` - -### Option 2: Docker Compose +Create a `docker-compose.yml`: ```yaml services: @@ -48,25 +39,74 @@ services: container_name: torproxy restart: unless-stopped ports: - - "127.0.0.1:8118:8118" - - "127.0.0.1:9050:9050" - - "127.0.0.1:8080:8080" + - "127.0.0.1:8118:8118" # HTTP/HTTPS proxy (Privoxy) + - "127.0.0.1:9050:9050" # SOCKS5 proxy (Tor) + - "127.0.0.1:8080:8080" # REST API & Health status ``` -### Option 3: Country-Specific Exit Proxy (e.g. Germany or Austria) +Launch the proxy: +```bash +docker compose up -d +``` + +### Alternative: Docker Run (Single Command) ```bash docker run -d \ --name torproxy \ --restart unless-stopped \ - -e TORPROXY_COUNTRY=DE \ -p 127.0.0.1:8118:8118 \ -p 127.0.0.1:9050:9050 \ -p 127.0.0.1:8080:8080 \ hapheus/torproxy:latest ``` -### Option 4: Transparent Tor Gateway (Zero-Config Routing) +--- + +## ๐Ÿงช Verifying Tor Connectivity + +Wait a few seconds for Tor to finish bootstrapping, then test: + +```bash +# 1. Test HTTP proxy via Privoxy (port 8118) โ€” returns {"IsTor": true, "IP": "..."} +curl --proxy http://127.0.0.1:8118 https://check.torproject.org/api/ip + +# 2. Test SOCKS5 proxy with remote DNS resolution (port 9050) +curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip + +# 3. Check live connection status via REST API (port 8080) +curl -s http://127.0.0.1:8080/status | jq . + +# 4. Request a new Tor identity / circuit on demand +curl -X POST http://127.0.0.1:8080/reconnect + +# 5. Dynamically switch exit country without restarting +curl -X POST "http://127.0.0.1:8080/reconnect?country=DE" +``` + +> [!IMPORTANT] +> **Leak-Proof Guarantee (Fail-Closed):** If Tor fails or disconnects, `torproxy` fails closed immediately. It will **never** fall back to direct clearnet routing. + +--- + +## ๐ŸŽฏ When to Use torproxy + +- โœ… **Ideal For:** + - Automated web scraping, data mining, and distributed crawling without IP rate limits. + - Empowering AI coding assistants (Claude Desktop, Cursor) with native `.onion` and web fetch tools via MCP. + - Zero-code privacy: Tunnel existing containers with `network_mode: "service:torproxy"`. + - Geolocation testing across exit countries (`TORPROXY_COUNTRY=DE,AT,US`). +- โš ๏ธ **Not Designed For:** + - High-bandwidth 4K video streaming or latency-critical online gaming. + - Bypassing strict anti-bot protections (Cloudflare, Akamai) that systematically block public Tor exit relays. + +--- + +## ๐ŸŒŸ Popular Modes & Use Cases + +### 1. Transparent Gateway (Zero-Config Routing for Any Container) + +Route another container's entire network traffic (TCP + DNS) through Tor without setting proxy flags: ```yaml services: @@ -79,7 +119,8 @@ services: TORPROXY_GATEWAY_MODE: "true" restart: unless-stopped - my-app: + # Any container attached to torproxy's network stack is automatically anonymized: + scraper: image: curlimages/curl:latest network_mode: "service:torproxy" depends_on: @@ -88,27 +129,36 @@ services: command: ["-s", "https://check.torproject.org/api/ip"] ``` ---- - -## Verifying Tor Connectivity +### 2. AI Coding Assistants (Model Context Protocol / MCP) -Wait a few seconds for Tor to bootstrap, then test: +Connect **Claude Desktop** directly via Docker Stdio without exposing host ports: -```bash -# 1. Check REST API status -curl -s http://127.0.0.1:8080/status | jq . +```json +{ + "mcpServers": { + "torproxy": { + "command": "docker", + "args": ["exec", "-i", "torproxy", "torproxy", "mcp"] + } + } +} +``` -# 2. Test HTTP proxy via Privoxy -curl --proxy http://127.0.0.1:8118 https://check.torproject.org/api/ip +Or connect **Cursor** / **Antigravity** via HTTP/SSE (`http://127.0.0.1:2501/sse`). -# 3. Test SOCKS5 proxy (using remote DNS to prevent leaks) -curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip +### 3. Country-Specific Exit Proxy -# 4. Request a new Tor identity / circuit -curl -X POST http://127.0.0.1:8080/reconnect +Route traffic exclusively through specific countries: -# 5. Dynamically switch exit country without restart -curl -X POST "http://127.0.0.1:8080/reconnect?country=DE" +```bash +docker run -d \ + --name torproxy \ + --restart unless-stopped \ + -e TORPROXY_COUNTRY=DE,AT \ + -p 127.0.0.1:8118:8118 \ + -p 127.0.0.1:9050:9050 \ + -p 127.0.0.1:8080:8080 \ + hapheus/torproxy:latest ``` --- @@ -137,12 +187,14 @@ The management API listens on port `8080` (HTTP): | Variable | Default | Description | | -------- | ------- | ----------- | -| `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | Bind address for Privoxy and Tor inside the container. | -| `TORPROXY_LISTEN_PORT` | `8118` | Privoxy HTTP proxy port. | -| `TORPROXY_SOCKS_PORT` | `9050` | Tor SOCKS5 proxy port. | -| `TORPROXY_API_PORT` | `8080` | REST API port. | | `TORPROXY_COUNTRY` | *(unset)* | Comma-separated ISO 3166-1 alpha-2 codes (e.g. `DE`, `AT`, `US`, `DE,AT`) to restrict exit nodes. | | `TORPROXY_STRICT_NODES` | `0` | If `1`/`true`, refuse circuits if nodes in the requested country/countries are unavailable. | +| `TORPROXY_GATEWAY_MODE` | `0` | Enable Transparent Tor Gateway mode (`cap_add: [NET_ADMIN]` required). | +| `TORPROXY_API_TOKEN` | *(unset)* | Optional Bearer token / API key securing REST API port 8080. | +| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | Opt-in: periodically download fresh GeoIP database from Tor Project GitLab. | +| `TORPROXY_LISTEN_PORT` | `8118` | Privoxy HTTP proxy port inside container. | +| `TORPROXY_SOCKS_PORT` | `9050` | Tor SOCKS5 proxy port inside container. | +| `TORPROXY_API_PORT` | `8080` | REST API port inside container. | --- diff --git a/README.md b/README.md index 6371c91..1a4cdbc 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,90 @@ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hapheus/torproxy/badge)](https://scorecard.dev/viewer/?uri=github.com/hapheus/torproxy) [![OpenSSF Best Practices](https://img.shields.io/cii/percentage/15828?style=flat-square&logo=linuxfoundation&label=OpenSSF%20Best%20Practices)](https://www.bestpractices.dev/projects/15828) -[Quick Start](#quick-start) ยท [Model Context Protocol (MCP)](#-model-context-protocol-mcp) ยท [Transparent Gateway](#transparent-tor-gateway) ยท [Architecture](#architecture) ยท [REST API](docs/api.md) ยท [Configuration](docs/configuration.md) ยท [Examples](examples/) ยท [Contributing](CONTRIBUTING.md) +[Quick Start](#quick-start) ยท [Transparent Gateway](#transparent-tor-gateway) ยท [Model Context Protocol (MCP)](#-model-context-protocol-mcp) ยท [Use Cases](#-when-to-use-torproxy) ยท [Architecture](#architecture) ยท [REST API](docs/api.md) ยท [Configuration](docs/configuration.md) ยท [Examples](examples/) ยท [Contributing](CONTRIBUTING.md) -A minimal, secure, and reliable Tor HTTP and SOCKS5 proxy packaged for Docker. `torproxy` routes traffic through the Tor network with fail-closed protection, non-root execution, an authenticated Tor control interface, and a lightweight JSON REST API for circuit rotation, health monitoring, and dynamic exit node routing. +**A production-grade, leak-proof Tor HTTP and SOCKS5 proxy packaged for Docker.** +Route entire container stacks without touching application code, equip AI coding assistants (Claude Desktop, Cursor) with native Tor tools via MCP, and rotate circuits dynamically with a single REST call. + +- ๐Ÿ›ก๏ธ **Zero Clearnet Leaks:** Fail-closed netfilter kill-switch & Privoxy fail-safe โ€” never leaks your real IP on connection drops. +- ๐Ÿš€ **Transparent Tor Gateway:** Tunnel any container's TCP & DNS via `network_mode: "service:torproxy"` โ€” zero app config changes. +- ๐Ÿค– **Native AI Agent MCP Server:** Built-in Model Context Protocol server (SSE & Stdio) for Claude Desktop, Cursor, and Antigravity. +- ๐Ÿ”„ **Dynamic Circuit & Country Control:** Switch identities (`SIGNAL NEWNYM`) and select exit node countries on the fly via REST. +- ๐Ÿ”’ **Defense in Depth:** Runs strictly as an unprivileged user (`torproxy`), with ephemeral cookie authentication for Tor control. + +--- + +## Quick Start + +Get up and running with a verified Tor circuit in seconds: + +### 1. Launch torproxy + +Clone and run via Docker Compose: +```sh +docker compose up -d +``` +*Or launch directly via Docker Run without cloning:* +```sh +docker run -d --name torproxy --restart unless-stopped \ + -p 127.0.0.1:8118:8118 -p 127.0.0.1:9050:9050 -p 127.0.0.1:8080:8080 \ + hapheus/torproxy:latest +``` + +### 2. Verify Tor connectivity +```sh +# Verify HTTP proxy (returns {"IsTor": true, "IP": "..."}) +curl -x http://127.0.0.1:8118 https://check.torproject.org/api/ip + +# Verify SOCKS5 proxy with remote DNS resolution +curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip + +# Check live connection status via REST API +curl -s http://127.0.0.1:8080/status | jq . +``` + +> [!IMPORTANT] +> **Leak-Proof Guarantee (Fail-Closed):** If Tor disconnects or crashes, Privoxy immediately returns `503 Service Unavailable` and the Netfilter kill switch drops outgoing packets. Your real IP will **never** silently leak to clearnet under network failures. + +> **Security Note:** In `docker-compose.yml`, all ports bind strictly to `127.0.0.1` by default. Neither the proxy listeners nor the management API require authentication; do not expose them to untrusted networks. + +
+โšก Advanced: Dynamic Identity Rotation & Country Routing (click to expand) + +```sh +# Request a fresh Tor identity without restarting the container: +curl -X POST http://127.0.0.1:8080/reconnect + +# Switch exit country dynamically on reconnect: +curl -X POST "http://127.0.0.1:8080/reconnect?country=DE" + +# Switch with strict exit country enforcement via JSON payload: +curl -X POST http://127.0.0.1:8080/reconnect \ + -H "Content-Type: application/json" \ + -d '{"country": "AT", "strict_nodes": true}' + +# Or launch with a default country at startup: +TORPROXY_COUNTRY=DE docker compose up -d +``` +
+ +--- + +## ๐ŸŽฏ When to Use torproxy + +Understanding where `torproxy` excels helps you pick the right tool for the job: + +- โœ… **Ideal For:** + - **Automated Web Scraping & Data Extraction:** Distribute requests and bypass IP rate limits with dynamic circuit rotation. + - **AI Agent Automation (MCP):** Allow Claude Desktop, Cursor, and agent frameworks to fetch web and `.onion` pages safely. + - **Zero-Friction Container Privacy:** Tunnel third-party containers (crawlers, search engines, microservices) with zero code modifications. + - **Geolocation Verification:** Test localized web experiences and CDN geo-routing across different exit countries (`TORPROXY_COUNTRY=DE,AT,US`). + - **Self-Hosted Privacy Stacks:** Route upstream search queries (e.g. SearXNG) privately. +- โš ๏ธ **Not Designed For:** + - **High-Bandwidth / Latency-Critical Traffic:** Tor is not designed for 4K video streaming, voice calls, or real-time gaming. + - **Bypassing Dedicated Anti-Bot Protection:** Major CDNs (e.g., Cloudflare, Akamai) often challenge or block known public Tor exit nodes. --- @@ -44,38 +123,7 @@ Host Client / Dependent Containers --- -## Quick Start - -```sh -# 1. Start torproxy in the background -docker compose up -d - -# 2. Test HTTP proxy (port 8118) -curl -v -x http://127.0.0.1:8118 https://check.torproject.org/api/ip - -# 3. Test SOCKS5 proxy with remote DNS resolution (port 9050) -curl -v --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/api/ip - -# 4. Check status via the local REST API -curl http://127.0.0.1:8080/status - -# 5. Optional: Route exit traffic through a specific country (e.g. DE or AT) -TORPROXY_COUNTRY=DE docker compose up -d -# or multiple countries: -TORPROXY_COUNTRY=DE,AT docker compose up -d - -# 6. Dynamically switch exit country on reconnect without container restart: -curl -X POST "http://127.0.0.1:8080/reconnect?country=DE" -# or with JSON payload: -curl -X POST http://127.0.0.1:8080/reconnect \ - -H "Content-Type: application/json" \ - -d '{"country": "AT", "strict_nodes": true}' -``` - -> **Security Note:** In `docker-compose.yml`, all ports bind strictly to `127.0.0.1` by default. Neither the proxy listeners nor the management API require authentication; do not expose them to untrusted networks. - ---- - + ## ๐Ÿš€ Transparent Tor Gateway Route **any** existing Docker container's entire outbound TCP and DNS traffic automatically through Tor โ€” **without modifying your applications or adding proxy flags**. @@ -218,35 +266,17 @@ services: ## Configuration -Default settings require no configuration. You can customize listening ports and bindings via environment variables in a `.env` file or Compose `environment` section: - -| Variable | Default | Allowed Values | Description | -| -------- | ------- | -------------- | ----------- | -| `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | Valid IPv4 | Bind address for Privoxy inside the container. | -| `TORPROXY_LISTEN_PORT` | `8118` | `1024`โ€“`65535` | HTTP proxy listening port inside the container. | -| `TORPROXY_HOST_PORT` | `8118` | `1`โ€“`65535` | Host port mapped to HTTP proxy in `docker-compose.yml`. | -| `TORPROXY_API_PORT` | `8080` | `1024`โ€“`65535` | REST API listening port (host and container). | -| `TORPROXY_SOCKS_PORT` | `9050` | `1024`โ€“`65535` | Tor SOCKS5 proxy port (host and container). | -| `TORPROXY_COUNTRY` | *(unset)* | ISO 3166-1 alpha-2 (e.g. `DE`, `AT`, `US`, `DE,AT`) | Route Tor exit circuits through specific countries using `tor-geoipdb`. | -| `TORPROXY_STRICT_NODES` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | When `1`/`true`, reject circuits if configured country exit nodes are unavailable. | -| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | Opt-in: periodically download Tor's GeoIP database (`geoip`/`geoip6`) from Tor Project GitLab and reload Tor. On failure the bundled/previous database keeps working. See [GeoIP auto-update](#geoip-auto-update). | -| `TORPROXY_API_TOKEN` | *(unset)* | String | Optional: Bearer token / API key securing REST API port 8080. Recommended for production. | -| `TORPROXY_API_ALLOW_ANONYMOUS_HEALTH` | `0` | `0`, `1`, `true`, `false` | Optional: Allow unauthenticated `/health` probing when `TORPROXY_API_TOKEN` is set. | -| `TORPROXY_GATEWAY_MODE` | `0` | `0`, `1`, `true`, `false`, `yes`, `no` | Enable Transparent Tor Gateway mode (`TransPort`, `DNSPort`, netfilter kill switch). Requires `cap_add: [NET_ADMIN]`. | -| `TORPROXY_TRANS_PORT` | `9040` | `1024`โ€“`65535` | Listening port for Tor TransPort when gateway mode is enabled. | -| `TORPROXY_DNS_PORT` | `9053` | `1024`โ€“`65535` | Listening port for Tor DNSPort when gateway mode is enabled. | - -All variables are strictly validated at startup. Port conflicts or out-of-range values trigger an immediate diagnostic failure. See [docs/configuration.md](docs/configuration.md) for full details. +Default settings work out-of-the-box with zero configuration. You can customize runtime behavior using environment variables in `.env` or Docker Compose: -### GeoIP Auto-Update - -By default `torproxy` uses the Tor GeoIP database bundled with the Alpine Tor package (`/usr/share/tor/geoip{,6}`), which is only refreshed when the Docker image is rebuilt. To keep country routing (`TORPROXY_COUNTRY=DE`) on a fresh IP-to-country mapping, enable the opt-in auto-update: - -```sh -TORPROXY_GEOIP_AUTO_UPDATE=1 TORPROXY_COUNTRY=DE docker compose up -d -``` +| Variable | Default | Purpose | +| -------- | ------- | ------- | +| `TORPROXY_COUNTRY` | *(unset)* | Restrict exit nodes to specific countries (e.g. `DE`, `AT`, `US`, `DE,AT`). | +| `TORPROXY_STRICT_NODES` | `0` | When `1`/`true`, reject circuits if configured country exit nodes are unavailable. | +| `TORPROXY_GATEWAY_MODE` | `0` | Enable Transparent Tor Gateway mode (`TransPort`, `DNSPort`, netfilter kill switch). Requires `cap_add: [NET_ADMIN]`. | +| `TORPROXY_API_TOKEN` | *(unset)* | Bearer token / API key securing REST API port `8080`. Recommended for production. | +| `TORPROXY_GEOIP_AUTO_UPDATE` | `0` | Opt-in: periodically download and refresh Tor's GeoIP database from Tor Project GitLab. | -With `TORPROXY_GEOIP_AUTO_UPDATE=1` the container downloads `geoip`/`geoip6` from Tor Project GitLab (HTTPS) at startup and then every `TORPROXY_GEOIP_UPDATE_INTERVAL` seconds (default `86400` = 24h), validates the format, installs the files atomically into `TORPROXY_GEOIP_DIR` (default `/var/lib/tor/geoip`), and sends Tor `SIGHUP` to reload them. If the download or validation fails (e.g. offline or upstream unavailable), the previously installed โ€” or bundled โ€” database keeps working, so an old version never breaks country routing. Each attempt is recorded and exposed additively as `geoip` in `/status`, so a silent fallback is visible. The pre-publish Live Image Verification gate checks that the GeoIP URLs are reachable and that a container with auto-update enabled downloads the database; the Daily Live Image Verification workflow repeats this as a drift detector. Additional settings: `TORPROXY_GEOIP_URL`, `TORPROXY_GEOIP6_URL`, `TORPROXY_GEOIP_MAX_BYTES`, `TORPROXY_GEOIP6_MAX_BYTES`. +> ๐Ÿ“– **Full Configuration Reference:** See [docs/configuration.md](docs/configuration.md) for custom listening ports (`TORPROXY_LISTEN_PORT`, `TORPROXY_SOCKS_PORT`, `TORPROXY_API_PORT`), address binding rules, and GeoIP update parameters. --- diff --git a/docker/Dockerfile b/docker/Dockerfile index 93ac9ae..fbd43c1 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -7,7 +7,7 @@ ARG PYTHON_VERSION=3.14 LABEL org.opencontainers.image.title="torproxy" \ org.opencontainers.image.description="A minimal HTTP proxy routed through Tor" \ - org.opencontainers.image.version="2.7.5" \ + org.opencontainers.image.version="2.7.6" \ org.opencontainers.image.licenses="MIT" \ org.opencontainers.image.source="https://github.com/hapheus/torproxy" \ org.opencontainers.image.url="https://github.com/hapheus/torproxy" \ diff --git a/docs/api.md b/docs/api.md index 9a9d283..f244623 100644 --- a/docs/api.md +++ b/docs/api.md @@ -22,6 +22,21 @@ The `torproxy` container includes an internal REST API server written in Python. ## 2. Endpoints +### Quick Reference + +| Endpoint | Methods | Status Codes | Description | +|---|---|---|---| +| [`/status`, `/`](#get--post-status-or-) | `GET`, `POST` | `200`, `500` | Connection status and current verified exit IP. | +| [`/ip`](#get--post-ip) | `GET`, `POST` | `200`, `503` | Current Tor egress IP (returns 503 while bootstrapping). | +| [`/health`](#get--post-health-or-v1health) | `GET`, `POST` | `200`, `503` | Diagnostic health state across Tor, proxies, and egress. | +| [`/reconnect`](#post--get-reconnect) | `POST`, `GET` | `200`, `400` | Request new circuit (`SIGNAL NEWNYM`); optional country change. | +| [`/disconnect`](#post--get-disconnect) | `POST`, `GET` | `200` | Pause Tor network traffic (`DisableNetwork=1`). | +| [`/connect`](#post--get-connect) | `POST`, `GET` | `200`, `400` | Resume Tor network traffic (`DisableNetwork=0`). | +| [`/diagnostics`](#get--post-diagnostics-or-v1diagnostics) | `GET`, `POST` | `200` | Telemetry (uptime, reconnect counts, bootstrap progress). | +| [`/metrics`](#get--post-metrics-or-v1metrics) | `GET`, `POST` | `200` | Prometheus exposition format metrics for scrapers. | + +--- + ### GET | POST `/status` (or `/`) Returns the current connection state and verified egress IP. diff --git a/docs/configuration.md b/docs/configuration.md index 6da43cd..a0e426a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -6,6 +6,16 @@ This guide provides the complete configuration reference for `torproxy`, includi All settings have sensible defaults that allow running `torproxy` with zero configuration. When running via Docker Compose or `docker run`, settings can be customized using environment variables. +> ๐Ÿ’ก **Quick Reference โ€” Frequently Used Variables:** +> - **Route through country:** `TORPROXY_COUNTRY=DE` (or `DE,AT`) +> - **Enforce country strictly:** `TORPROXY_STRICT_NODES=1` +> - **Enable Transparent Gateway:** `TORPROXY_GATEWAY_MODE=1` +> - **Secure API with Bearer token:** `TORPROXY_API_TOKEN=your-token` +> - **Automatic GeoIP database updates:** `TORPROXY_GEOIP_AUTO_UPDATE=1` +> - **Enable AI Agent MCP (SSE):** `TORPROXY_MCP_ENABLED=1` (port `2501`) + +### Complete Settings Reference + | Variable | Default | Type | Description | |---|---|---|---| | `TORPROXY_LISTEN_ADDRESS` | `0.0.0.0` | IP address (IPv4 or IPv6, e.g. `::1`) | Address inside the container that Privoxy binds to. Set to `0.0.0.0` to permit container-to-container connections. | diff --git a/docs/mcp.md b/docs/mcp.md index 6956ab5..c1b31ae 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -4,25 +4,7 @@ --- -## 1. Architecture & Dual-Transport Support - -The MCP server adheres strictly to the `torproxy` zero-dependency standard (using pure Python standard library: `http.server`, `json`, `threading`, `queue`). - -It supports two distinct transport protocols: - -1. **Stdio Transport (`torproxy mcp`):** - - Designed for local processes and container execution: `docker exec -i torproxy torproxy mcp`. - - Communicates using newline-delimited JSON-RPC 2.0 frames over `stdin` and `stdout`. - - All internal diagnostics and operational warnings are directed to `stderr` to maintain clean protocol isolation. - - Recommended for **Claude Desktop**. -2. **HTTP/SSE & Streamable HTTP Transport (Port 2501):** - - Runs as a non-blocking daemon thread on port `2501` (`TORPROXY_MCP_PORT=2501`). - - Supports both **HTTP/SSE** (`GET /sse` or `GET /mcp` for Server-Sent Events stream initialization + `POST /messages?sessionId=...` for JSON-RPC dispatch) and **Streamable HTTP** (direct JSON-RPC `POST` to `/mcp`, `/sse`, or `/`). - - Recommended for **Cursor**, **Antigravity**, and remote container orchestrators. - ---- - -## 2. Quickstart Configuration Examples +## 1. Quickstart Configuration Examples ### Claude Desktop (`claude_desktop_config.json`) @@ -156,6 +138,24 @@ services: --- +## 2. Architecture & Dual-Transport Support + +The MCP server adheres strictly to the `torproxy` zero-dependency standard (using pure Python standard library: `http.server`, `json`, `threading`, `queue`). + +It supports two distinct transport protocols: + +1. **Stdio Transport (`torproxy mcp`):** + - Designed for local processes and container execution: `docker exec -i torproxy torproxy mcp`. + - Communicates using newline-delimited JSON-RPC 2.0 frames over `stdin` and `stdout`. + - All internal diagnostics and operational warnings are directed to `stderr` to maintain clean protocol isolation. + - Recommended for **Claude Desktop**. +2. **HTTP/SSE & Streamable HTTP Transport (Port 2501):** + - Runs as a non-blocking daemon thread on port `2501` (`TORPROXY_MCP_PORT=2501`). + - Supports both **HTTP/SSE** (`GET /sse` or `GET /mcp` for Server-Sent Events stream initialization + `POST /messages?sessionId=...` for JSON-RPC dispatch) and **Streamable HTTP** (direct JSON-RPC `POST` to `/mcp`, `/sse`, or `/`). + - Recommended for **Cursor**, **Antigravity**, and remote container orchestrators. + +--- + ## 3. Available Tools | Tool | Parameters | Description | diff --git a/docs/releases.md b/docs/releases.md index 289683e..679443c 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -91,6 +91,11 @@ If an upgraded image exhibits unexpected behavior in your environment: ## 6. Release Notes +### 2.7.6 (Developer Experience, Behavioral Psychology & Documentation Optimization) + +- **Documentation & DX Optimization (#144, #145):** Restructured `README.md`, `DOCKERHUB.md`, and `/docs` using developer psychology, cognitive load reduction (Hick's Law), and progressive disclosure. Added instant 2-step verification, zero-clone `docker run` quickstarts, honest boundaries ("When to use / when not to use"), explicit fail-closed guarantees, and rapid-navigation matrices across `docs/api.md` and `docs/configuration.md`. +- **Single Source of Truth Synchronization:** Synchronized version 2.7.6 across `pyproject.toml`, `docker/Dockerfile`, `server.json`, `docs/releases.md`, and `CHANGELOG.md`. + ### 2.7.5 (MCP Auto-Discovery Manifests for Cursor and Smithery.ai) - **Cursor & Smithery.ai Manifests (#143):** Added root-level auto-discovery manifest files `.mcp.json` and `smithery.yaml`, enabling zero-config integration in Cursor / cursor.directory and automated live-healthcheck evaluation on Smithery.ai. diff --git a/pyproject.toml b/pyproject.toml index 66004fc..06b4a8b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "torproxy" -version = "2.7.5" +version = "2.7.6" description = "A minimal HTTP and SOCKS5 proxy routed through the Tor network with local REST control API" readme = "README.md" requires-python = ">=3.10" diff --git a/server.json b/server.json index 64de9ff..515d6f7 100644 --- a/server.json +++ b/server.json @@ -3,7 +3,7 @@ "name": "io.github.hapheus/torproxy", "title": "torproxy", "description": "Tor HTTP and SOCKS5 proxy with REST API and built-in MCP server.", - "version": "2.7.5", + "version": "2.7.6", "repository": { "url": "https://github.com/hapheus/torproxy", "source": "github" @@ -11,7 +11,7 @@ "packages": [ { "registryType": "oci", - "identifier": "docker.io/hapheus/torproxy:2.7.5", + "identifier": "docker.io/hapheus/torproxy:2.7.6", "transport": { "type": "stdio" }, diff --git a/uv.lock b/uv.lock index 380bc10..46fc4dc 100644 --- a/uv.lock +++ b/uv.lock @@ -842,7 +842,7 @@ wheels = [ [[package]] name = "torproxy" -version = "2.7.5" +version = "2.7.6" source = { editable = "." } [package.optional-dependencies]