transparent-tor-proxy 0.1.1

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 • Contribute • Requirements • Installation • Usage • How It Works

---

---

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.

🤝 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.

✨ Features

• 🌐 System-wide transparent proxy — all TCP traffic is redirected to Tor's TransPort, all DNS queries go through Tor's DNSPort.
• 🛡️ DNS leak prevention — dual-mode DNS management (resolvectl / resolv.conf fallback) with symlink-aware detection.
• 🚫 IPv6 leak prevention — all outgoing IPv6 is blocked to avoid ISP-level leaks.
• 🔄 Crash-safe — a lock file tracks session state; even after kill -9 or a power outage, the next run detects the orphaned session and restores the network.
• ⚡ Atomic firewall rules — nftables rules are loaded with nft -f (all-or-nothing), avoiding dangerous intermediate states.
• 🎭 IP rotation — ttp refresh requests a new Tor circuit for a fresh exit IP.
• 🛡️ SELinux optimization — Compiles a custom SELinux policy from source (.te) on Fedora/RHEL to allow Tor to bind to necessary ports. No opaque binaries shipped.
• 🐧 Multi-distro — auto-detects apt-get, pacman, dnf, and zypper for Tor installation. Handles Debian multi-instance services (tor@default), Fedora (toranon user), and more.
• 🛠️ Auto-configuration — validates and sanitizes torrc before starting, removing invalid settings and appending missing options.

⚙️ Requirements

• Linux with systemd (tested on Debian 12+, Ubuntu 22.04+, Fedora 40+, Arch Linux)
• 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/ttp_0.1.1_all.deb
• Fedora / RHEL: sudo dnf install ./packaging/ttp-0.1.1-1.fc43.noarch.rpm
• Arch Linux: cd packaging && makepkg -si

---

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 (9040, 9053). This kernel-level optimization cannot be performed by pip.

---

3. Fallback: pipx / pip (PEP 668)

[!WARNING] Note on Linux Distributions (PEP 668)
Recent versions of Ubuntu/Debian prevent global pip install to protect system stability. Using these methods will bypass TTP's kernel-level optimizations (SELinux) and won't handle system dependencies automatically.

Option A: pipx (Recommended Fallback)

pipx installs TTP in an isolated environment but makes the command available globally.

pipx install transparent-tor-proxy

Option B: Standard pip with venv

If you prefer standard pip, use a virtual environment to avoid the externally-managed-environment error.

# 1. Create the environment
python3 -m venv ~/.local/share/ttp-venv

# 2. Install the package
~/.local/share/ttp-venv/bin/pip install transparent-tor-proxy

# 3. Create a symbolic link to use 'ttp' everywhere
sudo ln -s ~/.local/share/ttp-venv/bin/ttp /usr/local/bin/ttp

[!CAUTION] Uninstallation Warning: Running pipx uninstall or deleting the venv only removes the Python code. If TTP is active, your firewall and DNS will remain hijacked. Always use ttp stop before uninstalling via pip, or use ./scripts/uninstall.sh if you installed via the source script. [!NOTE]
After installation, the ttp command is available system-wide.

💻 Usage

[!IMPORTANT] All commands require sudo. Except ttp status and ttp --help.

Start the proxy

sudo ttp start

[TTP] Detecting Tor... found (v0.4.9.6), service active (user: debian-tor).
[TTP] Stateless nftables rules applied (Table: inet ttp).
[TTP] DNS set via resolvectl on interface ens3.
[TTP] Waiting for Tor to bootstrap...
[TTP] Tor is 100% bootstrapped.
[TTP] Verifying Tor routing...
[TTP] ✅ Session active. Exit IP: 109.70.100.11
[TTP] Use 'ttp stop' to terminate. 'ttp refresh' to change IP.

Stop the proxy

sudo ttp stop

[TTP] Removing nftables rules...
[TTP] Restoring DNS...
[TTP] 🔴 Session terminated. Traffic in cleartext.

Change exit IP

sudo ttp refresh

Sends NEWNYM to Tor via the control interface — all active circuits are rotated and you get a new exit IP.

Check status

sudo ttp status

[TTP] Status: ACTIVE
[TTP] Exit IP: 185.181.61.201
[TTP] Session started: 2026-04-19T01:07:33.384801+00:00
[TTP] Process PID: 3392

🔍 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

1. Detection — checks if Tor is installed, which systemd service runs the daemon, and dynamically detects the Tor user.
2. Installation — if Tor is missing, detects the system's package manager and installs it automatically.
3. Configuration — sanitizes torrc, validates with tor --verify-config, restarts the correct service.
4. Firewall — generates nftables rules in a dedicated inet ttp table:
   • Stateless approach — no system backups needed; cleanup is an atomic nft destroy table.
   • Multi-Chain Protection:
     • prerouting: Intercepts traffic if TTP is used as a gateway.
     • output (NAT): Redirects local TCP/DNS to Tor's ports.
     • filter_out (Filter): Acts as a Kill-Switch.
   • Execution Sequence:
     1. Exclude Tor user (prevents routing loops).
     2. Exclude root processes (system stability).
     3. Intercept DNS (UDP :53) and redirect to Tor's DNSPort.
     4. Accept loopback and local traffic (required for redirected packets).
     5. Redirect all TCP to Tor's TransPort (:9040).
     6. Drop all IPv6 output to prevent leaks.
     7. Kill-Switch (Reject): Terminate any cleartext traffic that bypassed redirection (e.g., pre-existing connections).
5. DNS — redirects DNS resolution to 127.0.0.1 via resolvectl or /etc/resolv.conf.
6. Bootstrap — waits for Tor to reach 100% bootstrap via the control interface.
7. Verification — confirms traffic is routed through Tor via multiple endpoints (check.torproject.org, ipify, ifconfig.me) for resilience.
8. State — writes a JSON lock file at /var/lib/ttp/ttp.lock for crash recovery.

🚑 Crash Recovery

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

Scenario	What happens
ttp stop	Normal cleanup: firewall restored, DNS restored, lock deleted
Ctrl+C / kill	Signal handler catches SIGINT/SIGTERM and runs cleanup before exit
kill -9 / Power Outage	Next ttp start detects the orphaned lock file and auto-restores the network
Manual emergency	Run sudo ./scripts/restore-network.sh to flush all nftables rules, reset DNS, and delete the lock file

⚠️ Known Behavior

[!WARNING]

• Tor Browser: Applications using an explicit SOCKS5 proxy will create a double Tor hop. Use a regular browser instead while TTP is active.
• Chromium-based Browsers (DoH Leak): Chrome, Brave, and Edge might use DNS-over-HTTPS (DoH), which bypasses system DNS settings. To prevent leaks:
  1. Disable "Secure DNS" in browser settings.
  2. Ideally, avoid Chromium-based browsers entirely while using TTP; use Firefox instead (ensuring its own "DNS over HTTPS" setting is also disabled). This still DOES NOT ensure the absence of leaks.
• IPv6: All IPv6 traffic is blocked to prevent leaks. Future versions may support IPv6 through Tor.
• Exit IP variation: Different connections may show different exit IPs due to Tor stream isolation. After ttp refresh, all connections get new circuits.

🧪 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	The Gold Standard: Runs Unit Tests + All Integration Tests.

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
│   └── vm/                 # QEMU VM management scripts
├── assets/                 # Branding and demo assets
│   └── gif/                # Demo animations
├── packaging/              # Build scripts for .deb, .rpm, and Arch packages
│   ├── build_deb.sh
│   ├── build_rpm.sh
│   ├── 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
│   └── system_info.py      # System diagnostic gathering
├── tests/                  # Unit tests (mocked)
└── docs/
    └── architecture.md     # Technical Architecture & Design

🤝 Contributing & Security

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

• Check out our Contributing Guidelines to get started.
• Please review our Security Policy before reporting vulnerabilities.

📄 License

MIT. See LICENSE for more information.