v1.6.0 — Alpine 3.24, Governance Expansion & Tuesday Dependabot Schedule

Release Highlights

This release introduces an upgraded Alpine Linux 3.24 base image, configures Dependabot weekly update schedules to Tuesdays, expands project governance in CODEOWNERS, and hardens GitHub Actions workflow token permissions.

🛡️ Governance & Security

• Expanded CODEOWNERS: Added @kuenstlichedummheit-sys (Felix) and @majorungustl (Gustav) to repository governance and security oversight alongside @hapheus and @MustermenschAlex (#49).
• Workflow Hardening: Restricted top-level workflow token permissions to contents: read across all GitHub Actions workflows (#44).

📦 Base Image & Dependencies

• Alpine Linux 3.24: Upgraded Docker base container to Alpine 3.24 with pinned SHA256 digest (#47).
• Dependabot Schedule: Configured weekly maintenance runs to Tuesday across all package ecosystems (github-actions, uv, docker) (#46).

🔄 Compatibility Contract

• 100% backward compatible drop-in replacement.
• Unchanged port listeners (8118, 9050, 8080), environment variables (TORPROXY_*), and REST control API endpoints.

v1.5.0 — CLI Version & Help Flags, macOS Chrome Incognito Example

Release Highlights

This release introduces native command-line interface flags (-v/--version and -h/--help) to the torproxy executable entrypoint, exports package-level version metadata, and provides a new automated macOS Chrome incognito example.

✨ Features & CLI Runtime

• CLI Flags: Running torproxy --version or torproxy -v cleanly reports the application version without attempting to bind service ports. Full --help usage instructions added via argparse.
• Package Version: Exported __version__ in torproxy top-level namespace.
• TDD Coverage: Added dedicated hermetic unit tests in tests/unit/test_cli.py verifying exit codes, output streams, and server lifecycle invocation.

🌐 Examples & Documentation

• macOS Chrome Incognito: Added examples/macos-chrome-via-tor demonstrating ephemeral, isolated Chrome sessions routed entirely through torproxy.
• OpenSSF Best Practices: Integrated OpenSSF Best Practices badge in README.md.
• Tooling Alignment: Standardized testing and linting guides around uv.

🔄 Compatibility Contract

• 100% backward compatible drop-in replacement.
• Unchanged port listeners (8118, 9050, 8080), environment variables (TORPROXY_*), and REST control API endpoints.

v1.4.1 — Minimal Alpine Linux Base Image & 48% Size Reduction

Release Highlights

This release migrates the container runtime from debian:bookworm-slim to alpine:3.21, reducing image footprint by nearly 50% while preserving 100% backward compatibility and zero CVE vulnerabilities.

⚡ Performance & Size Optimization

• Minimal Base Image: Migrated to alpine:3.21 pinned cryptographically by SHA256 digest.
• Uncompressed Size: Reduced from 184.0 MB down to 94.3 MB (-48.8%).
• Compressed Download: Reduced from ~52 MB down to ~29 MB (-46.1%).
• Direct GeoIP Bundling: Uses Alpine's integrated Tor GeoIP databases without requiring heavyweight external packaging.

🛡️ Security & Hardening

• Vulnerabilities: Trivy container scan reports 0 Vulnerabilities (0 High, 0 Critical).
• Supply Chain Security: Maintained multi-architecture builds (linux/amd64, linux/arm64, linux/arm/v7) with SLSA provenance and SBOM attestations.
• Least Privilege: Non-root system user (torproxy), fail-closed Privoxy proxy routing, and dropped Linux capabilities remain fully enforced.

🔄 Compatibility Contract

• 100% backward compatible drop-in replacement.
• Unchanged port listeners (8118, 9050, 8080), environment variables (TORPROXY_*), and REST control API endpoints.

v1.4.0 — SOLID Hexagonal Architecture & Security Tooling Alignment

Release Highlights

This release refactors torproxy into a decoupled, SOLID Python package following Hexagonal Architecture principles, and elevates repository security, supply chain hardening, and governance to match cf-docker-tunnel-sync.

🏗️ Architecture & SOLID Refactoring

• Package Architecture: Extracted internal scripts into a modular Python package under src/torproxy (domain, ports, adapters, service, web, runtime).
• Ports & Adapters: Decoupled abstract protocols (ControlPort, EgressProbe, SocksProbe, Clock) from concrete network and OS implementations.
• Architectural Tests: Added automated AST checks (tests/unit/test_architecture.py) ensuring zero adapter or IO leakage into core domain logic.
• Backward Compatibility: Container entrypoints (docker/start.sh, docker/api.py, docker/tor_control.py) preserved as thin wrappers with 100% contract fidelity.

🛡️ Security & Supply Chain Workflows

• Dependabot: Automated weekly updates for GitHub Actions, Python dependencies, and Docker base images.
• CodeQL: Integrated continuous GitHub Advanced Security static analysis (codeql.yml).
• OSV-Scanner: Scheduled and PR-level dependency vulnerability audits (osv-scanner.yml).
• OpenSSF Scorecard: Automated supply-chain security evaluation (scorecard.yml).
• Strict Quality Gate: PR gate enforces ruff check, ruff format, mypy, ShellCheck, and hermetic pytest execution.

👥 Governance & Community

• Added .github/CODEOWNERS for @hapheus and @MustermenschAlex.
• Aligned README.md status badges with production standard.
• Shipped hardened production deployment examples (examples/hardened-production/).
• Strictly enforced zero AI files policy across all repositories.

🧪 Verification

• 204 passed unit & contract tests (100% green).
• Multi-architecture container build, smoke tests, and Trivy scans passing.

v1.3.0 — Country-Specific Exit Routing & Dynamic Reconnect

Release Highlights

• Country-Specific Exit Nodes (Static & Dynamic):
  • Configure exit country routing at container launch using TORPROXY_COUNTRY (e.g. DE, AT, DE,AT) and TORPROXY_STRICT_NODES (0 / 1).
  • Dynamically switch or clear exit country on the fly via POST /reconnect?country=DE or POST /connect without restarting the container.
  • Supports query parameters as well as JSON request bodies (e.g. {"country": "AT", "strict_nodes": true}).
  • Bundled tor-geoipdb Debian package with configured IPv4 and IPv6 GeoIP databases.
• Observability:
  • Active exit country and strict nodes policy are surfaced in /health, /diagnostics, and /metrics (torproxy_exit_country_info and torproxy_strict_nodes).
• Automated Docker Hub Sync:
  • Automated synchronization of DOCKERHUB.md description on Docker Hub for both default branch pushes and v* release tags.
• Documentation & Badges:
  • Added Docker Pulls tracking badge to README.md.
  • Unified configuration, API, and compatibility documentation.
• Absolute Compatibility Guarantee:
  • 100% backward compatible with existing docker compose up -d configurations and API clients.

v1.2.0 — Production-Grade Tor HTTP & SOCKS5 Proxy with Observability, Hardening & Provenance

Highlights in v1.2.0

v1.2.0 is a major feature and reliability release completing Milestones 0 through 7 of the production quality roadmap. It brings hardened security, authenticated Tor control, zero-leak fail-closed protection, comprehensive health probes, Prometheus metrics, and verifiable container provenance—all while preserving 100% backward compatibility with zero breaking changes.

🛡️ Security & Correctness (Milestones 1 & 7)

• Local ControlPort Authentication: Secured internal ControlPort with ephemeral 32-byte filesystem cookie authentication (CookieAuthentication 1).
• RFC-Compliant Control Protocol: Implemented robust TCP response parser handling multiline replies, fragmented reads, and accurate status codes without false positives.
• Tor Egress Verification: Explicitly verifies IsTor: true against Tor Project verification APIs instead of parsing arbitrary IP strings.
• Fail-Closed Protection: Privoxy strictly routes to Tor SOCKS5 (forward-socks5t); requests immediately fail (500/503) if Tor is disconnected rather than leaking to clearnet.
• Container Runtime Hardening: Documented and verified container execution with dropped Linux capabilities (cap_drop: [ALL]) and privilege escalation prevention (security_opt: [no-new-privileges:true]).
• Automated Vulnerability Scanning: Integrated automated Trivy vulnerability scanning into CI gates.

⚡ Reliability & Health Checks (Milestones 2 & 3)

• Multi-Subsystem Health Endpoint: Added additive GET /health and GET /v1/health endpoints reporting granular status across Tor daemon, proxy listeners, and external egress.
• SOCKS5 Socket Readiness Probes: Pre-flight socket handshake probe verifies Tor listener readiness without external network dependence.
• Thread-Safe Synchronized Cache: Concurrency-safe caching of external IP address with automatic invalidation during circuit rotation (/reconnect).
• Graceful Process Supervision: Proper SIGTERM and SIGINT process reaping ensures sub-second graceful container shutdown without dangling zombie processes.

📊 Observability (Milestone 6)

• Operational Diagnostics: Added GET /diagnostics and GET /v1/diagnostics exposing container uptime, reconnect counters, bootstrap progress, and cache state.
• Prometheus Metrics: Added GET /metrics and GET /v1/metrics exporting standard exposition-format metrics without external third-party dependencies.
• Privacy-Preserving Logs: Masked query strings and URL parameters in operational logs to protect sensitive user and scraping data.

📦 Supply Chain & Examples (Milestones 4 & 7)

• Multi-Arch Builds & Provenance: Releases generate automated SBOM (SPDX) and SLSA provenance attestations (mode=max) via Docker Buildx for linux/amd64, linux/arm64, and linux/arm/v7.
• Shipped Examples: Added examples/hardened-production/ alongside Browserless Chromium, CRW Web Scraper, and SearXNG examples—all strictly bound to 127.0.0.1 and verified with automated tests.
• Docker Hub Synchronization: Added master overview documentation in DOCKERHUB.md.

🔄 Compatibility Statement

• Zero Breaking Changes: All original ports (8118, 9050, 8080), environment variables, response fields, and legacy GET mutation routes (/connect, /disconnect, /reconnect) remain fully operational. Upgrades from prior releases are instantaneous drop-in replacements.

v1.1.1 — Canary Verification Resilience & Exit Node Hardening

What's Changed

• fix(canary): harden live image verification against exit node flapping (#8) by @hapheus in #8

Highlights & Resilience Improvements

• Transient Network Flapping Defense: Added retry loop (curl --retry 2 --retry-all-errors) across 3 attempts for both Privoxy (HTTP) and SOCKS5 egress checks, mitigating transient exit-node TLS drops (curl exit code 35).
• Circuit Stabilization: Introduced a 5-second sleep following Tor bootstrap confirmation to allow circuit stabilization before proxy requests.
• Fallback Egress Verification: Queries api.ipify.org if check.torproject.org drops TLS/connectivity, while rigorously asserting IP leak prevention (!= runner IP).
• Observability: Automatic container log dumping (docker logs torproxy-canary) on step failure.
• Automated Alert Resolution: Automatically resolves open canary alert issues upon subsequent successful canary runs.

Full Changelog: v1.1.0...v1.1.1

v1.1.0 — Configurable SOCKS Port, Cold-Start Reliability & Integration Examples

v1.1.0 is a feature and reliability release of torproxy, introducing configurable Privoxy SOCKS routing, enhanced cold-start resilience, turn-key integration examples, and comprehensive automated test suites.

Highlights

• Configurable SOCKS Port in Privoxy: Privoxy now dynamically routes to custom TORPROXY_SOCKS_PORT configurations instead of hardcoded 9050 (#5).
• Cold-Start Resilience: Extended healthcheck start grace period to 180 seconds to reliably accommodate slower Tor circuit bootstrapping (#4).
• Turn-Key Integration Examples: Complete docker-compose reference stacks and documentation:
• Browserless Chromium via Tor (Headless Scraping)
• CRW (Crawl4AI) Web Scraper via Tor
• SearXNG Privacy Metasearch Engine via Tor (#3)
• Automated Quality & CI: Added unit test suite for API and configuration, multi-arch build gates, and automated daily live canary verification (#5, #6).

Full Changelog: v1.0.0...v1.1.0

v1.0.0 — Minimal Tor HTTP & SOCKS5 Proxy for Docker

v1.0.0 is the first stable release of torproxy: a lightweight Docker image that routes HTTP and SOCKS5 traffic through the Tor network.

Highlights

• HTTP proxy provided by Privoxy on port 8118
• Native Tor SOCKS5 proxy on port 9050, including hostname resolution through Tor
• Small JSON REST API on port 8080 for status, IP lookup, connect, disconnect, and circuit renewal
• Readiness-aware Docker health check: the container becomes healthy only when Tor is connected and the proxy is usable
• Secure-by-default Compose example that publishes proxy and API ports only on 127.0.0.1
• Unprivileged container runtime, signal handling through tini, and no persistent state
• Configurable proxy, SOCKS5, and API ports through environment variables