transparent-tor-proxy 0.4.5

Transparent Tor Proxy - route all system traffic through Tor

TTP - Transparent Tor Proxy

A Linux CLI tool that transparently routes all system traffic through the Tor network using nftables.

Features • Requirements • Installation • Usage • How It Works • Contribute

---

---

No per-application setup needed - just sudo ttp start and every connection goes through Tor.

[!CAUTION] TTP is a tool designed to aid privacy by routing traffic through Tor. However, no tool can guarantee 100% anonymity. Your safety also depends on your behavior (e.g., using a regular browser vs. Tor Browser, signing into accounts, etc.). Always use TTP as part of a multi-layered security strategy.

[!WARNING] If you are a whistleblower or are engaging in high-risk activities, DO NOT use TTP. Instead, use officially audited and reliable tools like TailsOS or the Tor Browser directly. The authors and contributors of TTP assume no responsibility for your safety or the consequences of using this software.

Features

• Volatile Core Architecture: Entire session state, lockfiles, and logs are stored exclusively in tmpfs (/run/ttp/ and /run/tor/ttp/), ensuring no forensic traces are written to physical disk and automatically vanishing on reboot.
• Stateless DNS Overlay: Transparently redirects DNS requests using a kernel-level mount --bind overlay on /etc/resolv.conf without modifying the original configuration file on disk, with automatic stale mount cleanup for absolute idempotency.
• Proactive Watchdog & Killswitch: Active background session integrity daemon monitoring Tor status, nftables table/chain presence, and DNS overlay mount. Triggers a single-strike auto-healing repair or a hard network lockout (emergency drop-all killswitch) under persistent failure.
• LAN Bypass & Split Tunneling: Excludes local subnets (RFC 1918 & Link-Local) dynamically from Tor routing to maintain access to local resources (printers, NAS). Supports user- or group-specific exceptions (--bypass-user / --bypass-group) via nftables uid/gid checks.
• Native Dual-Stack IPv6 Redirection: Dynamically detects IPv6 loopback availability, building dual-stack nftables redirect chains or dropping all outgoing IPv6 traffic (IPv6 leak prevention) if unsupported.
• DoH/DoT Leak Mitigation: Actively blocks outbound DoT (port 853) and well-known DoH resolver IPs (port 443) to force system fallback to Tor DNS, utilizing canary domains in torrc to disable browser-level DoH where supported.
• Native Tor Service Management: Tor is managed via a dedicated volatile ttp-tor.service systemd unit running on non-standard ports, coexisting seamlessly with any standard system tor.service without address conflicts.

Requirements

• Linux with systemd (optional if using --external-daemon in BYOD mode)
• Python 3.10+
• nftables (pre-installed on most modern distros)
• Root privileges (required for firewall and DNS modifications)

Installation

Choose the method that best fits your needs. Native packages are strongly recommended for system stability, security, and clean uninstallation.

1. Native Packages (Recommended)

Installing via native packages ensures that all system dependencies (tor, nftables) and kernel-level optimizations (SELinux) are managed by your OS package manager.

• Debian / Ubuntu: sudo apt install ./packaging/transparent-tor-proxy_0.4.5_all.deb
• Fedora / RHEL: sudo dnf install ./packaging/transparent-tor-proxy-0.4.5-1.fc43.noarch.rpm
• Arch Linux: cd packaging && makepkg -si

For instructions on how to verify the integrity and authenticity of the release assets, see the Release Verification Guide.

---

2. Manual Source Install (Developer/Universal)

If you are a developer or want to install from the repository:

git clone https://github.com/onyks-os/TransparentTorProxy.git
cd TransparentTorProxy
sudo ./scripts/install.sh

[!TIP] Why use ./install.sh?
Unlike standard Python installers, this script is "intelligent". On Red Hat-based systems, it detects if SELinux is in Enforcing mode and dynamically compiles a custom policy module (from ttp_tor_policy.te) to allow Tor to bind to the non-standard ports required by TTP (9041, 9054). This kernel-level optimization cannot be performed by pip.

3. Alternative Installation Methods (Fallback)

For installing TTP via Python-specific package managers (pipx or pip with virtual environments), see the Alternative Installation Methods Reference.

Usage

TTP is designed to be simple and lightweight. For the complete list of CLI commands, options, exit codes, and technical specifications, refer to the External Interfaces Reference.

Quick Start

Most network-modifying commands require root privileges (sudo):

• Start the proxy:

  sudo ttp start
  

• Stop the proxy:

  sudo ttp stop
  

• Check current session status:

  ttp status
  

• Verify Tor routing and latency:

  ttp check
  

• Request a new exit IP (rotate circuits):

  sudo ttp refresh
  

For more advanced setups and circumvention profiles, see the Advanced Security & Usage Profiles Reference or consult the External Interfaces Reference.

Manual Leak Verification

To confirm that the tunnel is working correctly and no leaks are present:

1. Verify Tor Exit IP:

   curl -s https://check.torproject.org/api/ip
   

2. Verify DNS Routing:

   # Should return a valid IP via Tor's DNSPort
   dig +short A check.torproject.org
   

3. DNS Leak Test (Terminal):

   # This TXT query SHOULD return an EMPTY output
   dig +short TXT whoami.ipv4.akahelp.net
   

   Note: An empty output is the expected behavior under Tor. Tor's transparent resolver does not support TXT records; if this command returns your real ISP's IP, you have a DNS leak.

4. Web-based Verification: Always perform additional tests on dnsleaktest.com and ipleak.net.

Full Uninstallation

To remove TTP completely from the system:

sudo ./scripts/uninstall.sh

How It Works

TTP transparently routes all network traffic by orchestrating standard Linux kernel subsystems, system utilities, and Tor's control interfaces:

1. Atomic Firewall Redirection: Generates and loads an isolated inet ttp nftables ruleset atomically to intercept TCP and DNS traffic, redirecting them to Tor while preventing IPv6 and DoT/DoH leaks.
2. DNS Bind-Mount Overlay: Overlays /etc/resolv.conf with a volatile RAM-backed configuration via a kernel-level bind-mount to ensure DNS calls are resolved by Tor.
3. Tor Daemon Integration: Configures, runs, and monitors an isolated Tor instance via volatile systemd services on non-standard ports to prevent port conflicts.
4. Session Watchdog: Runs an active background monitor that verifies configuration integrity and executes a fail-closed emergency killswitch upon security breach or system modification.

For a detailed walkthrough of the execution flows, system hooks, security boundaries, and modular components, please refer to the:

Technical Architecture & Design Guide

Crash Recovery

TTP is designed to always restore your network, even in edge cases:

Scenario	What happens
ttp stop	Zero-leak cleanup: applies teardown lockdown, gracefully shuts down Tor, executes active socket slaughter, waits 1.5s, flushes connection tracking, restores firewall and DNS (via table flush and delete), and deletes the lock file
Ctrl+C / kill	Signal handler catches SIGINT/SIGTERM and runs normal cleanup before exit
kill -9 / Power Outage	Next ttp start detects the orphaned lock file, clears any stale mount stacks, and auto-restores
Manual emergency	Run sudo ./scripts/restore-network.sh to flush all nftables rules, reset DNS, and delete the lock file

Known Behavior & Limitations

[!WARNING]

• Tor Browser: Applications using an explicit SOCKS5 proxy will create a double Tor hop. Use a regular browser instead while TTP is active.
• DNS-over-HTTPS (DoH): Normal browsers (Firefox, Chrome, Brave, Edge) may use DoH, bypassing system DNS. TTP mitigates this by blocking well-known DoH resolver IPs (forcing fallback to Tor DNS) and routing unlisted DoH traffic through Tor (which can, however, partially compromise anonymity). For maximum security, disable DoH / "Secure DNS" in your browser settings.
• IPv6: Fully supported when available. TTP dynamically detects IPv6 loopback and routes IPv6 traffic through Tor. If the host lacks IPv6 loopback support OR if the --no-ipv6 option is passed, TTP drops all outgoing IPv6 traffic to prevent leaks.
• Exit IP variation: Different connections may show different exit IPs due to Tor stream isolation.

For a full breakdown of residual risks, architectural trust boundaries, and the STRIDE threat model, see:

docs/security-assessment.md

Development & Testing

TTP uses a Makefile to automate and standardize the testing pipeline. This ensures that every change is verified against unit and integration tests before being committed.

The "Pre-Push" Rule

[!IMPORTANT] Always run make verify before pushing code. If this command fails, the code is NOT ready for production.

Essential Commands

Command	Goal
make test	Runs fast Unit Tests locally (no root needed, fully mocked).
make integration-debian	Runs full system tests inside a privileged Docker container (Debian).
make integration-all	Runs integration tests for all supported distros (Debian, Fedora, Arch).
make verify	Runs Unit Tests + All Integration Tests.
make build	Generates native .deb and .rpm packages.
make clean	Removes all build artifacts, caches, and temp files.

Ruleset Verification via Network Sandbox Engine (NSE)

TTP integrates the Network Sandbox Engine (NSE), a development dependency, to run programmatic validation of TTP's nftables rulesets inside isolated network namespaces:

• Zero-Leak PCAP Assertion: Tests apply the actual firewall rules and inject test packets (TCP connections, DNS lookups, bypassed identities). A Scapy sniffer runs on the boundary virtual interface (veth) and asserts that no cleartext packets escape to the WAN.
• To run ruleset tests: Install NSE (pip install network-sandbox-engine>=1.1.0 pyroute2) and run:

  sudo pytest tests/test_nse_rules.py -v
  

Advanced: Real-World VM Testing

While Docker integration tests are fast and atomic, they don't capture 100% of the kernel/systemd nuances. For critical changes, it is highly recommended to test in a real QEMU VM:

# Start a specific VM (e.g., arch)
./scripts/vm/start.sh arch

# Sync current code to the VM
./scripts/vm/send.sh

# Snapshot management for easy rollbacks
./scripts/vm/snapshot.sh arch save before-risky-test

Diagnostics

If something goes wrong, run the diagnostic command:

sudo ttp diagnose

Project Structure

├── pyproject.toml          # Package metadata and dependencies
├── README.md
├── CONTRIBUTING.md         # Contribution guidelines
├── SECURITY.md             # Security policy
├── scripts/                # Installation and VM management scripts
├──   ├── install.sh          # System-wide installer
├──   ├── uninstall.sh        # System-wide uninstaller
├──   ├── restore-network.sh  # Emergency network recovery script
├──   ├── verify.sh           # CI/CD verification script
├──   └── vm/                 # QEMU VM management scripts
├──   └── vms/                # .iso and .qcow2 files
├── assets/                 # Branding and demo assets
├──   ├── favicon/            # Project favicons and webmanifest
├──   └── gif/                # Demo animations
├── packaging/              # Build scripts for .deb, .rpm, and Arch packages
├──   ├── build_deb.sh
├──   ├── build_rpm.sh
├──   ├── release.sh          # Package release/publish script
├──   ├── ttp.spec
├──   ├── PKGBUILD
├──   └── ttp.service
├── ttp/                    # Source code
├──   ├── resources/          # Internal package resources (SELinux policies, etc.)
├──   ├── cli.py              # Typer entry point
├──   ├── exceptions.py       # Custom exception hierarchy
├──   ├── tor_detect.py       # Tor detection logic
├──   ├── tor_install.py      # Auto-install & configuration
├──   ├── firewall.py         # Atomic nftables management
├──   ├── dns.py              # DNS leak prevention
├──   ├── state.py            # Lock file and crash recovery
├──   ├── tor_control.py      # Tor daemon interaction and API
├──   ├── watchdog.py         # Session integrity watchdog and auto-healing
├──   └── system_info.py      # System diagnostic gathering
├── tests/                  # Unit tests (mocked) and test_watchdog.py
└── docs/
    ├── architecture.md     # Technical Architecture & Design
    ├── interfaces.md       # External interfaces reference (CLI, Tor, system)
    ├── security-assessment.md  # STRIDE threat model & risk assessment
    └── decisions/          # Architectural Decision Records (ADRs 0001 - 0008)

Call for Contributors

We are actively looking for developers to join the TTP project! Whether you are a student looking to learn or a seasoned professional, your help is welcome.

We are particularly seeking Senior Developers with expertise in:

• Linux Networking (nftables, routing tables, network namespaces).
• Tor Internals (daemon configuration, Stem library, circuit management).
• System-level Python (asynchronous I/O, process management, security best practices).

If you want to contribute to making transparent proxying safer and more robust, please check out our Contributing Guidelines or dive right into the Issues.

Obtain, Feedback & Contributions

• Obtain: TTP is available on PyPI and can also be downloaded from the GitHub Releases page. For installation methods, see the Installation section.
• Feedback: Report bugs, suggest enhancements, or request features by opening a ticket on the GitHub Issues tracker.
• Contribute: Contributions are always welcome! Review our Contributing Guidelines to learn how to submit code, follow coding standards, and run tests.
• Security: Please review our Security Policy before reporting any vulnerabilities or security concerns.

Support

For version support status, EOL information, and support channels, please refer to the Support Policy.

This project is maintained in my free time, and donations are highly appreciated.

Also, if you find TTP useful, please consider giving it a Star!
It helps others discover the tool and motivates further development.

License

MIT. See LICENSE for more information.