Features • Requirements • Installation • Usage • How It Works • Verification • 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.

Why TTP?

Legacy transparent proxy scripts (TorGhost, Anonsurf) overwrite configuration files and build iptables rulesets that fail open: when they break, traffic leaves in cleartext. TTP is built the other way round - it fails closed, and keeps nothing on disk.

Features

• Continuous integrity protection - a watchdog governed by a formal FSM (transitions) monitors Tor, the nftables chains and the DNS overlay via a double inotify watch that catches symlink-target swapping. It repairs once, then applies an emergency killswitch.
• Split tunnelling - exempt users or groups (--bypass-user, --bypass-group) with native nftables UID/GID matching, or run a single command outside Tor with ttp bypass <cmd> via a cgroups v2 slice.
• LAN preserved - RFC 1918 and link-local subnets stay reachable, so your printer and NAS keep working.
• Dual-stack, or no stack - IPv6 is routed through Tor when loopback routing is available, and dropped outright when it is not. There is no third option where it leaks.
• DoT and DoH blocked - port 853 rejected, known public DoH resolvers rejected on 443 (TCP and QUIC), and browser canary domains poisoned in torrc.
• Coexists with your system Tor - runs its own volatile ttp-tor.service on non-standard ports, leaving an existing Tor instance untouched.
• Bridges - obfs4 and snowflake, with BYOD (bring your own daemon) mode.

Requirements

• Linux with systemd
• 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.

Download the .deb or .rpm for the version you want from the latest release - the packages are release assets and are not checked into the repository - then install it:

• Debian / Ubuntu: sudo apt install ./transparent-tor-proxy_0.4.9_all.deb
• Fedora / RHEL: sudo dnf install ./transparent-tor-proxy-0.4.9-1.noarch.rpm
• Arch Linux: build from the repository with 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:

[!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:

  root@kitploit:~

  sudo ttp start
  

• Stop the proxy:

  root@kitploit:~

  sudo ttp stop
  

• Check current session status:

  root@kitploit:~

  ttp status
  

• Verify Tor routing and latency:

  root@kitploit:~

  ttp check
  

• Request a new exit IP (rotate circuits):

  root@kitploit:~

  sudo ttp refresh
  

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

Checking Your Session

Full Uninstallation

To remove TTP completely from the system:

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:

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 DoH via a 3-layer defense: (1) all outbound TCP traffic (including DoH) is redirected to Tor TransPort; (2) common DoH canary domains are mapped to 0.0.0.0 in torrc; (3) public DoH IP resolvers are blocked on TCP/UDP port 443 (blocking HTTP/3 QUIC DoH). 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

Verification

TTP's zero-leak claim is measured, not asserted. The Network Sandbox Engine builds an isolated network namespace, loads TTP's real generated ruleset into it, generates the traffic a leak would consist of, and watches the boundary veth interface with a Scapy sniffer.

Every containment test runs twice. assert no leaks is also true when the sniffer never started, when the interface name is wrong, or when the traffic never left the process, so each test first runs the same stimulus with the ruleset flushed and requires the packet to be seen. Only then does it assert that TTP's ruleset stops it. A harness that cannot observe a leak fails the test rather than passing it.

Covered: plain DNS (UDP and TCP), ordinary TCP, DoT on 853, QUIC DoH on UDP/443, ICMP, arbitrary UDP, IPv6 — plus the other direction, that a bypassed UID can still reach the LAN. A firewall that blocked everything would pass the first seven and fail the eighth.

This runs in CI on every push (the Zero-leak ruleset verification job) and as a step in scripts/verify.sh before a release.

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:

Diagnostics

If something goes wrong, run the diagnostic command:

Project Structure

Contributing

Contributions are welcome, and the areas where help matters most are narrow and specific:

1. Linux networking - nftables, routing tables, network namespaces, VPN interface detection.
2. Tor internals - daemon configuration, Stem, bridges, bootstrap edge cases.
3. CI/CD - keeping the privileged test suites fast and reliable on GitHub Actions.

Start with CONTRIBUTING.md, which documents the two rules this codebase is built on: never fix a bug without adding the check that would have caught it, and a test that asserts an absence must first prove it can detect a presence.

This project is maintained in free time. A star helps others find it; sponsorship helps it keep going.

License

MIT. See LICENSE for more information.