Contents

SPONSOR VIEW SOURCE
CLI TOOL VOLATILE CORE PYTHON 3.10+ KILL-SWITCH WATCHDOG NATIVE IPv6

Transparent Tor Proxy v0.4.5

TTP is a Linux CLI tool designed to route all system traffic transparently through the Tor network. Using nftables, a network-resilient watchdog service, and a zero-leak active socket termination protocol, it provides a crash-safe, leak-proof environment for secure online privacy. It intercepts all outgoing network traffic without per-application configuration, supports split-tunneling user bypasses, coexists with external Tor instances via Bring-Your-Own-Daemon (BYOD) mode, and loads all firewall rules atomically, always ensuring complete network restoration after any shutdown or outage.

bash
$ git clone https://github.com/onyks-os/TransparentTorProxy.git
$ cd TransparentTorProxy && pipx install .
$ sudo ttp start --watchdog
[TTP] Detecting Tor... found (v0.4.9.6), managed via system service (user: debian-tor).
[TTP] Initializing volatile runtime in /run/ttp...
[TTP] Restarting TTP Tor service...
[TTP] Stateless nftables rules applied (Table: inet ttp).
[TTP] DNS set via overlay on interface ens3.
[TTP] Waiting for Tor to bootstrap... 100%
[TTP] Session active. Exit IP: 109.70.100.11
[TTP] Starting session watchdog daemon...
[TTP] Watchdog daemon started successfully (PID: 3410).
SECURITY NOTICE
TTP routes traffic through Tor but does not guarantee anonymity. Your safety also depends on your behavior (signing into accounts, browser fingerprinting, etc.). For high-risk activities use Tails or Tor Browser directly.
0x02

TTP Installation & Setup Guide

Requirements

Requirement Notes
Linux with systemd Tested on Debian 12+, Ubuntu 22.04+, Fedora 40+, Arch Linux
Python 3.10+ Required for union type hints and modern stdlib features
nftables Pre-installed on Debian 12+, Fedora 33+, Arch. Replaces iptables as firewall backend.
Root privileges Required for firewall and DNS modifications, and all commands must be run with sudo
conntrack Recommended. Used during teardown to invalidate active connection states (conntrack -F) and eliminate cleartext leaks.

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.

bash
# Debian / Ubuntu
$ sudo apt install ./packaging/*.deb
# Fedora / RHEL
$ sudo dnf install ./packaging/*.rpm
# Arch Linux
$ cd packaging && makepkg -si

2. Universal Source Script (Developer)

If you want to install from the repository, use the "intelligent" installer. It handles SELinux optimization on Fedora by compiling a custom policy module on the fly.

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

3. Fallback: pipx / venv (PEP 668)

Modern Linux distributions prevent global pip install. Using these methods will bypass kernel-level optimizations (SELinux) and won't handle system dependencies automatically.

bash
# Option A: pipx (Recommended)
$ pipx install transparent-tor-proxy
# Option B: Local source with pip
$ pip install .
NOTE
After installation, the ttp command is registered system-wide via the pyproject.toml entry point ttp = "ttp.cli:app". Tor itself does not need to be pre-installed, as TTP detects its absence and installs it automatically using the system's package manager.

Python dependencies

Package Source Purpose
stem PyPI Official Python library from the Tor Project. Used to connect to Tor's Control Port/Socket, monitor bootstrap progress, and send NEWNYM signals.
typer PyPI Modern CLI framework. Provides argument parsing, --help generation, and clean command routing.
rich PyPI Terminal output formatting: panels, progress bars, colored text.
0x03

TTP System Architecture & Tor Routing Design

TTP is structured as a set of independent Python modules, each with a single responsibility. No module imports from cli.py. UI logic (rich, typer) is confined exclusively to cli.py while all other modules return plain data.

tor_detect.py

Read-only module. Checks if Tor is installed (shutil.which), running (systemctl is-active + pgrep), and correctly configured (TransPort 9041, DNSPort 9054, ControlSocket /run/tor/ttp/control.sock in torrc). Dynamically detects the Tor system user, SELinux enforcement state, and Firewalld presence. Returns a structured dictionary, but never modifies anything.

tor_install.py

Orchestrates Tor detection and auto-installation. Generates a dynamic volatile torrc in /run/tor/ttp/torrc, compiles a custom SELinux policy from source on Fedora/RHEL, writes a dedicated volatile service unit file to /run/systemd/system/ttp-tor.service, and restarts it using native service control.

firewall.py

Implements a multi-chain, "Safe-Release" architecture. Generates a stateless ruleset with three chains: prerouting, output (NAT), and filter_out (Filter). The latter acts as a dedicated Kill-Switch. Supports **Split-Tunneling Bypass** (exempting specific UIDs/GIDs), **IPv6 Force Disable** (dropping all IPv6 traffic), and a multi-stage **Zero-Leak teardown** (injecting TCP resets and flushing connection tracking states). Applied atomically via nft -f.

dns.py

Stateless Kernel-level DNS redirection. Writes the Tor resolver to /run/ttp/resolv.conf and overlays it on /etc/resolv.conf using mount --bind. Implements **DoH/DoT Leak Mitigation** (intercepting browser-level DoH by mapping Mozilla's canary domain use-application-dns.net to 0.0.0.0 in the Tor configuration), resolves symlinks, and uses a lazy umount -l fallback.

state.py

Volatile session locking. Reads and writes a JSON lock file at /run/ttp/ttp.lock (tmpfs) with strict 0o644 permissions. Contains session PID, ports, timestamp, active bypass configurations, and watchdog status keys. Verifies PID validity to auto-recover orphaned sessions, and runs the pre-flight safety check to ensure sufficient tmpfs RAM.

tor_control.py

Handles Tor control Socket interactions. Connects to Tor's dedicated private socket at /run/tor/ttp/control.sock, monitors bootstrap progress via status/bootstrap-phase, rotates circuits with NEWNYM, verifies Tor routing, and performs a graceful cryptographical SHUTDOWN teardown.

watchdog.py

Integrity and auto-healing monitor. Spawns and manages the TTP session background watchdog daemon service (ttp-watchdog.service). Periodically monitors firewall table rules, active bypass rules, the DNS overlay mount, and Tor daemon connectivity. Handles Auto-Healing (First Strike) (re-applying bypassed users/groups rules if missing) and triggers the Emergency Killswitch (Second Strike) if recovery fails.

system_info.py

Pure data-gathering module used by ttp diagnose. Collects OS info, Tor service status, active torrc settings, nftables ruleset, DNS state, and Tor control interface status. Returns a flat dict[str, str]. Every subprocess call is wrapped in a try/except so a single failure never aborts the full diagnostic.

exceptions.py

Defines a custom exception hierarchy for the project. Includes TTPError (base) and specialized classes: FirewallError, DNSError, StateError, and TorError. Used to distinguish between fatal issues and recoverable states.

LOG MANAGEMENT & ROTATION
TTP maintains its own log file in a volatile ramdisk at /run/ttp/ttp.log. Starting with v0.3.0, it employs a RotatingFileHandler with a 1MB limit to prevent memory exhaustion in the RAM disk.
0x04

TTP Session Execution & Core Process Flow

ttp start

1. Pre-flight check, Signal registration & SELinux

Verifies root privileges (os.geteuid() == 0), registers signal handlers, and executes a **Pre-flight safety check** verifying that /run/ttp (tmpfs) has at least 5MB of free space to prevent out-of-memory crashes. On Fedora/RHEL, ensures the custom SELinux policy is compiled. If running in **BYOD mode** (--external-daemon), it scans sockets in /proc/net/tcp / /proc/net/tcp6 to dynamically parse Tor's numeric UID.

2. Orphan detection

Inspects the volatile lock file at /run/ttp/ttp.lock. If the lock exists but its PID is no longer running, it automatically triggers state.attempt_recovery() to safely restore firewall rules and DNS from the orphan session before initiating the new startup.

3. Volatile Tor service setup

If not in BYOD mode, TTP's tor_install.ensure_tor_ready() generates a volatile, sandboxed torrc in /run/tor/ttp/torrc and writes a dedicated service unit file directly to the systemd path at /run/systemd/system/ttp-tor.service. It then reloads systemd and starts this isolated Tor instance. If BYOD mode is active, it runs passive checks on the external daemon ports.

4. Stateless multi-chain firewall application

Applies a stateless ruleset atomically via nft -f. This redirects system TCP and DNS traffic to Tor's dedicated ports while enabling a strict filter-based Kill-Switch to reject all non-Tor cleartext traffic. Also injects dynamic split-tunneling exception rules (meta skuid <uid> accept / meta skgid <gid> accept) at the top of chains for bypassed users/groups, and drops outbound IPv6 if forced via --no-ipv6.

5. Stateless DNS overlay

DNS is redirected at the Kernel level. The module writes nameserver 127.0.0.1 to /run/ttp/resolv.conf and binds it directly over /etc/resolv.conf using mount --bind. This achieves clean redirection without altering physical disk configuration.

6. Volatile lock file write

Writes a JSON session lock file to /run/ttp/ttp.lock with strict 0o644 permissions. It contains the active process PID, timestamps, bypass configurations, DNS parameters, and watchdog status keys. This file resides entirely in `tmpfs` and evaporates automatically if the host loses power.

7. Bootstrap wait & verification

Monitors bootstrap progress up to 100% via the private Unix ControlSocket /run/tor/ttp/control.sock. After a brief settling delay, verifies Tor routing via multiple public lookup APIs to confirm that all network traffic is properly tunneled.

8. Watchdog service daemon activation

If the watchdog monitor is enabled (via --watchdog or -w), the CLI automatically writes the volatile systemd service unit file /run/systemd/system/ttp-watchdog.service and starts it to monitor the session's health proactively.

ttp stop

1. Preventive Watchdog Stop

Stops the background watchdog service daemon immediately to prevent triggering the emergency killswitch during teardown.

2. Lockdown & Active Socket Slaughter

To prevent cleartext leak of in-flight packets, TTP applies temporary firewall lockdown rules (exempting Tor). It then injects TCP Reset rules (meta l4proto tcp counter reject with tcp reset) and standard rejects alongside a 1.5-second micro-delay, actively terminating all pending local sockets.

3. Connection Tracking State Invalidation

If the conntrack utility is installed, TTP invalidates active kernel connection tracking states via conntrack -F. This flushes UDP streams and active NAT links before removing firewall rules.

4. Tor Teardown

Sends a cryptographic SHUTDOWN signal to Tor's Control Socket to close circuits cleanly. If not in BYOD mode, TTP then stops the dedicated ttp-tor.service systemd service, unlinks the transient unit file, and reloads the daemon.

5. Restore Firewall

Atomically flushes and destroys the entire TTP ruleset table by executing nft destroy table inet ttp.

6. Restore DNS & Delete Lock

Dismantles the resolver bind-mount using umount -l (lazy unmount) to ensure instant overlay detachment, cleans up the volatile resolver file, and deletes the lock file at /run/ttp/ttp.lock. Cleartext networking is fully restored.

0x05

Firewall Rules & Nftables Routing Redirection

TTP generates a single nftables table. The ruleset is written to a temporary file and loaded with a single nft -f call, meaning all rules apply atomically, or none do.

nftables
# TTP - Transparent Tor Proxy rules (v0.4.5 Dual-Stack)
# Applied atomically via nft -f
table inet ttp {
chain prerouting {
type nat hook prerouting priority dstnat; policy accept;
udp dport 53 dnat ip to 127.0.0.1:9054
tcp dport 53 dnat ip to 127.0.0.1:9054
udp dport 53 dnat ip6 to [::1]:9054
tcp dport 53 dnat ip6 to [::1]:9054
ip daddr { 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 } accept
ip6 daddr { fc00::/7, fe80::/10 } accept
ip protocol tcp dnat ip to 127.0.0.1:9041
meta l4proto tcp dnat ip6 to [::1]:9041
}
chain output {
type nat hook output priority -150; policy accept;
# 1. Tor user EXEMPTION: Allow Tor daemon output
meta skuid 114 accept
# 1b. Split-tunneling bypass exceptions (UID 1001, GID 1002)
meta skuid 1001 ip daddr != 127.0.0.1 accept
meta skuid 1001 ip6 daddr != ::1 accept
meta skgid 1002 ip daddr != 127.0.0.1 accept
meta skgid 1002 ip6 daddr != ::1 accept
# 2. DNS Redirection: Force queries to Tor's DNSPort (IPv4 & IPv6)
udp dport 53 dnat ip to 127.0.0.1:9054
tcp dport 53 dnat ip to 127.0.0.1:9054
udp dport 53 dnat ip6 to [::1]:9054
tcp dport 53 dnat ip6 to [::1]:9054
# 3. LAN Bypass: Exempt local subnet communication (non-DNS)
ip daddr { 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 } accept
ip6 daddr { fc00::/7, fe80::/10 } accept
# 4. Exempt local loopback traffic (Required for NAT redirect)
ip daddr 127.0.0.0/8 accept
ip6 daddr ::1 accept
# 5. Redirect all other TCP traffic to Tor's TransPort
ip protocol tcp dnat ip to 127.0.0.1:9041
meta l4proto tcp dnat ip6 to [::1]:9041
}
chain filter_out {
type filter hook output priority filter; policy accept;
# Kill-switch: Ensure only Tor and Local traffic leaves
meta skuid 114 accept
# Split-tunneling bypass exceptions (UID 1001, GID 1002)
meta skuid 1001 accept
meta skgid 1002 accept
# Allow root processes if explicitly requested via --allow-root
meta skuid 0 accept
# LAN Bypass: Allow local subnet communication
ip daddr { 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 } accept
ip6 daddr { fc00::/7, fe80::/10 } accept
ip daddr 127.0.0.0/8 accept
ip6 daddr ::1 accept
# DoT (DNS-over-TLS) Leak Prevention
tcp dport 853 reject
# DoH (DNS-over-HTTPS) IP-level Block (Cloudflare, Google, Quad9, OpenDNS)
ip daddr { 1.1.1.1, 1.0.0.1, 8.8.8.8, 8.8.4.4, ... } tcp dport 443 reject
ip6 daddr { 2606:4700:4700::1111, 2001:4860:4860::8888, ... } tcp dport 443 reject
# IPv6 Fallback Leak Prevention (only applied if host lacks IPv6)
meta nfproto ipv6 drop
# Brutal Reject: Kill any cleartext traffic that bypassed NAT
reject
}
}
CRITICAL RULE ORDERING IN TTP v0.4.5
  • DNS before LAN Bypass: The DNS redirect rules must run before the LAN bypass rules. Since browsers might query the LAN gateway (e.g. 192.168.1.1:53) for DNS resolution, executing LAN bypass first would allow these queries to bypass Tor entirely, resulting in a severe DNS leak.
  • DNS before Loopback: The DNS redirect rules must run before the loopback accept rule. If loopback accept matches first, local resolver queries sent to 127.0.0.1 are allowed without being redirected to Tor's DNSPort.
KILL SWITCH
TTP implements a dedicated filter_out chain that acts as a global Kill-Switch. It explicitly allows Tor, root, and local traffic while rejecting everything else. This ensures that no cleartext traffic can bypass the NAT redirection, covering edge cases like pre-existing connections or processes failing to be intercepted.
LAN BYPASS RFC 1918 & IPv6 Local Exempt

Allows local network communication by exempting RFC 1918 subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), Link-Local (169.254.0.0/16), and IPv6 local ranges (fc00::/7, fe80::/10) from Tor redirection. Local services like SSH, NFS, and printing remain fully operational. Disabling is possible via --no-lan-bypass.

ROOT ROUTING UID 0 Interception

Intercepts root process traffic (UID 0) by default to prevent leak vectors during package manager runs (dnf, apt) or background system tasks. For scenarios requiring administrative cleartext communication, the --allow-root flag exempts UID 0 from redirection.

DoT BLOCK Port 853 Reject

Explicitly rejects outbound TCP/UDP port 853 inside the filter_out chain. Blocking DNS-over-TLS (DoT) forces local stub resolvers and modern browsers to fall back to plain UDP/TCP port 53 DNS queries, which are then securely intercepted and routed through Tor's anonymous resolver.

DoH IP BLOCK Port 443 IP Reject

Rejects direct traffic to well-known public DoH resolver IPs on port 443 (Cloudflare, Google, Quad9, OpenDNS) - both IPv4 and IPv6. This provides defense-in-depth protection against non-compliant browsers that bypass the local resolver and ignore canary domain signals.

SPLIT TUNNELING UID & GID Bypass Exceptions

Allows specific local users or groups to communicate directly with the cleartext WAN (bypassing Tor NAT redirection and watchdog lockdown) via meta skuid / meta skgid rules. Configured via --bypass-user and --bypass-group.

ZERO-LEAK SHUTDOWN Active Socket Slaughter

Prevents cleartext traffic leaks during teardown by applying transient lockdown rules, actively injecting TCP resets (RST packets) to terminate pending connections, and flushing Netfilter conntrack states via conntrack -F.

0x06

DNS Handling & Leak Prevention

DNS leak prevention is critical for anonymity. TTP employs a robust, stateless kernel-level overlay to safely redirect all system DNS traffic to Tor's DNSPort at 127.0.0.1:9054. This strategy eliminates the legacy dependency on systemd-resolved / resolvectl, ensuring universal compatibility and absolute reliability without modifying permanent system configuration files.

KERNEL OVERLAY mount --bind

TTP generates a volatile resolv configuration at /run/ttp/resolv.conf containing only nameserver 127.0.0.1, and bind-mounts it directly over the system's resolver configuration. This stateless overlay is instantly visible to all processes and disappears completely on unmount.

SYMLINK RESOLUTION Realpath Target

If /etc/resolv.conf is a symlink (e.g., pointing to systemd-resolved's stub file), TTP resolves its absolute physical path via realpath and applies the bind-mount onto the target file. This preserves symlink integrity and ensures sandboxed apps see the redirected DNS.

PREVENTION Mount Stacking

In case of unclean shutdowns, multiple mount layers could stack on the resolver file. During pre-flight checks, TTP inspects /proc/mounts and iteratively clears stale overlays by running a loop of lazy unmounts (umount -l, up to 10 times) before applying the fresh layer.

DOUBLE PROTECTION
Anonymity is secured via a dual-layer defense: the nftables ruleset intercepts all outbound UDP/TCP port 53 traffic at the network level, forcing it to Tor's DNSPort (127.0.0.1:9054), while the DNS Overlay makes sure local glibc resolver queries are explicitly addressed to 127.0.0.1.
DNS-OVER-HTTPS (DOH) MITIGATION
Modern web browsers often bypass system DNS settings using encrypted DNS-over-HTTPS (DoH). To block this leak vector, TTP injects MapAddress entries into the generated torrc to neutralize DoH canary domains for Cloudflare (use-application-dns.net), Google, Quad9, OpenDNS, and AdGuard. Compliant browsers querying these domains receive null responses, signaling them to disable DoH and fall back to the system resolver, which TTP then safely routes through Tor. Additionally, TTP blocks outbound connections to well-known DoH resolver IPs on port 443 as defense-in-depth.
0x07

TTP CLI Command Reference

All commands require sudo. Global flags --verbose / -v, --quiet / -q, and --log-format text|json are available on all commands.

sudo ttp start [--interface/-i <iface>] [--bootstrap-timeout <sec>] [--allow-root] [--no-lan-bypass] [--watchdog/-w] [--bypass-user <users>] [--bypass-group <groups>] [--no-ipv6] [--external-daemon] [--tor-uid <uid>]

Starts the transparent proxy session. Orchestrates the full startup sequence, establishing the volatile Tor daemon (or linking with an external instance), loading network-level nftables intercepts, and mounting the DNS resolver overlay.

--allow-root Exempt processes running as UID 0 (root) from redirection
--no-lan-bypass Disable automatic exemption of RFC 1918 and local networks
--watchdog, -w Enable background health monitoring and emergency killswitch
--bypass-user <users> Comma-separated list of usernames to exempt from Tor redirection
--bypass-group <groups> Comma-separated list of groupnames to exempt from Tor redirection
--no-ipv6 Force drop all outbound IPv6 traffic to prevent leaks
--external-daemon Enable BYOD mode, coexisting with an external running Tor process
--tor-uid <uid> Specify the numeric UID of the external Tor daemon (BYOD mode)
output
[TTP] Pre-flight: volatile space on /run/ttp is sufficient.
[TTP] Initializing volatile runtime on /run/ttp...
[TTP] Dedicated Tor service 'ttp-tor.service' created and started.
[TTP] Stateless nftables rules applied (Table: inet ttp).
[TTP] DNS set via kernel overlay bind-mount on /etc/resolv.conf.
[TTP] Waiting for Tor to bootstrap... 100%
[TTP] Tor is 100% bootstrapped.
[TTP] Verifying Tor routing...
[TTP] Session active. Exit IP: 109.70.100.11
[TTP] Background watchdog daemon 'ttp-watchdog.service' started.
[TTP] Use 'ttp stop' to terminate. 'ttp refresh' to change IP.
sudo ttp stop [--restore-only]

Stops the session and restores the network to its original state.

output
[TTP] Graceful circuit teardown initiated... done.
[TTP] Removing nftables rules...
[TTP] Removing volatile DNS overlay...
[TTP] Volatile Tor service 'ttp-tor.service' stopped and unloaded.
[TTP] Network restored. Traffic in cleartext.
sudo ttp refresh

Requests a new Tor circuit without stopping the session. Traffic continues to flow through Tor uninterrupted while the circuit rotates.

sudo ttp status

Shows the current session status. Resolves and displays the active external exit IP if the session is active.

output
[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
sudo ttp restart [--interface/-i <iface>] [--bootstrap-timeout <sec>] [--allow-root] [--no-lan-bypass] [--watchdog/-w] [--bypass-user <users>] [--bypass-group <groups>] [--no-ipv6] [--external-daemon] [--tor-uid <uid>]

Quickly restarts the session. Shortcut for stop followed by start, accepting the same startup arguments.

--allow-root Exempt processes running as UID 0 (root) from redirection
--no-lan-bypass Disable automatic exemption of RFC 1918 and local networks
--watchdog, -w Enable background health monitoring and emergency killswitch
--bypass-user <users> Comma-separated list of usernames to exempt from Tor redirection
--bypass-group <groups> Comma-separated list of groupnames to exempt from Tor redirection
--no-ipv6 Force drop all outbound IPv6 traffic to prevent leaks
--external-daemon Enable BYOD mode, coexisting with an external running Tor process
--tor-uid <uid> Specify the numeric UID of the external Tor daemon (BYOD mode)
sudo ttp watchdog [start | stop | status]

Manages the background health monitoring daemon (ttp-watchdog.service). If spawned, the watchdog performs diagnostic checks every 15 seconds to ensure system integrity.

start Spawns and registers the systemd watchdog service
stop Terminates the watchdog service and gracefully unloads it
status Checks service state and prints the last watchdog runtime logs
watchdog status
● ttp-watchdog.service - TTP Volatile Health Watchdog Daemon
Loaded: loaded (/run/systemd/system/ttp-watchdog.service; transient)
Active: active (running) since Fri 2026-05-22 16:05:00 UTC; 10min ago
Main PID: 4512 (python3)
# Diagnostic Logs:
[WATCHDOG] Integrity check: DNS overlay active (OK)
[WATCHDOG] Integrity check: nftables table 'inet ttp' loaded (OK)
[WATCHDOG] Integrity check: Tor socks socket active on port 9041 (OK)
[WATCHDOG] Status: Healthy. Sleeping for 15s...
ttp check

Network diagnostics command. Verifies Tor connectivity, latency to torproject.org, and local controller stability.

ttp check-leak [-v]

Performs a battery of DNS and IP leak tests. Use --verbose to see full test results.

sudo ttp logs

Displays logs from the volatile TTP log file at /run/ttp/ttp.log. Automatically shows startup events, connection states, and Tor daemon feedback.

sudo ttp diagnose

Runs a comprehensive system diagnostic and prints a detailed report. Checks Tor service status, torrc configuration, active nftables rules, and DNS settings.

sudo ttp uninstall

Performs a deep cleanup of the TTP state. Stops any active session, removes the SELinux policy module, and deletes log files.

0x08

Crash Recovery & Systemd Watchdog Protection

TTP is designed around the assumption that any process can die at any time. The lock file at /run/ttp/ttp.lock maintains active session states, enabling immediate recovery and clean slate verification.

NORMAL
ttp stop

Reads lock → destroys isolated nftables table → unmounts DNS overlay → unloads volatile Tor service → deletes lock. Clean exit.

HANDLED
Ctrl+C  /  kill (SIGINT, SIGTERM)

Signal handlers registered at startup intercept the signal and call the same cleanup routine as ttp stop before exiting.

RECOVERED
kill -9  /  power outage

The lock file survives in tmpfs. On the next ttp start, if the process is dead, the lock is orphaned, and TTP runs pre-flight recovery: cleaning stacked mounts, destroying the stale nftables table, and clearing the orphan lock.

Proactive Health Watchdog Daemon

TTP establishes a background monitoring unit (ttp-watchdog.service). Operating continuously during an active session, it runs integrity diagnostics every 15 seconds to ensure that no leakage vectors develop due to system service restarts, third-party interventions, or hardware anomalies. Since v0.4.0, the watchdog has been network-resilient: it dynamically detects physical network carrier drops and route removals, safely suspending integrity checks when offline to prevent false-positive lockouts, and automatically resuming when connectivity stabilizes. The watchdog operates under a strict two-strike escalation protocol:

STRIKE 1: AUTO-HEALING

Non-Destructive Correction

If the watchdog detects a minor anomaly (such as the DNS overlay being unmounted by a system update or a brief failure in resolving Tor status), it triggers an immediate, silent auto-healing attempt. It will clear stacked resolver mounts and re-apply structural configurations to restore the secure pipeline without interrupting your active internet connection or rotating your Tor circuit.

STRIKE 2: EMERGENCY LOCKDOWN

Emergency Killswitch

If the anomaly persists on the second consecutive probe, or if a critical component is compromised, or if the auto-healing command itself fails (such as being unable to re-apply rules), the watchdog instantly engages a system-wide lockdown. It drops all physical network traffic, broadcasts a terminal console warning (wall alert), and triggers a desktop popup via notify-send.

MANUAL RECOVERY
If for any reason automatic recovery does not run, you can restore the network manually:
# Destroy TTP firewall rules
$ sudo nft destroy table inet ttp
# Restore DNS (Unmount the overlay)
$ sudo umount -l /etc/resolv.conf
# Remove stale lock
$ sudo rm /run/ttp/ttp.lock

Or use the nuclear option: sudo ./scripts/restore-network.sh

0x09

Linux Distribution Compatibility & Support

TTP handles the main differences between distributions automatically.

Distribution Service Unit Tor User Package Manager Status
Debian 12+ tor@default debian-tor apt-get Validated
Ubuntu 22.04+ tor@default debian-tor apt-get Validated
Fedora 40+ tor toranon dnf Validated
Arch Linux tor tor pacman Tested (Docker)
DEBIAN SERVICE UNIT
On Debian, tor.service is a multi-instance master that reports active (exited) even when no daemon is actually running. The real daemon lives in tor@default.service. TTP detects this safely.
0x0A

TTP Codebase Development & Custom Compilations

Running unit tests

Unit tests are fully mocked, no root, no network, no system modifications.

bash
$ pip install -e ".[dev]"
$ make test

VM integration tests

Integration tests require root and a real Tor daemon. They run inside a QEMU VM (Debian 13) or Docker containers.

bash
# Docker integration tests
$ make integration-debian
$ make integration-all
# The mandatory pre-commit pipeline
$ make verify
# QEMU VM workflow (scripts/vm/)
$ ./scripts/vm/start.sh arch
$ ./scripts/vm/send.sh
$ ssh -p 2222 debian@localhost
# If network breaks:
$ ./scripts/vm/snapshot.sh load pre-test

Project structure

tree
├── pyproject.toml # Package metadata and dependencies
├── Makefile # Automation entry point
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CHANGELOG.md
├── scripts/ # System-wide scripts
│ ├── install.sh
│ ├── uninstall.sh
│ ├── restore-network.sh
│ ├── verify.sh
│ └── vm/ # QEMU management
├── assets/ # Branding and demo assets
├── packaging/ # Native packaging (.deb, .rpm, Arch)
│ ├── build_deb.sh
│ ├── build_rpm.sh
│ ├── release.sh
│ ├── ttp.spec
│ ├── PKGBUILD
│ └── ttp.service
├── ttp/ # Source code
│ ├── resources/ # Internal resources
│ │ └── selinux/ # Policy source (.te)
│ ├── cli.py
│ ├── firewall.py
│ └── ...
├── tests/ # Unit tests (mocked)
└── docs/
└── architecture.md
0x0B

Known Limitations & Security Considerations

TOR BROWSER / EXPLICIT SOCKS5 PROXY
Applications that configure an explicit SOCKS5 proxy (e.g. Tor Browser, some curl invocations) will create a double Tor hop - their traffic goes through Tor once via TTP's transparent redirect and a second time via their own SOCKS5 connection. This is not a security issue but adds latency. Use a regular browser while TTP is active.
IPv6 DUAL-STACK & FALLBACK DROP
TTP v0.4.5 supports native transparent IPv6 redirection, automatically generating a dual-stack configuration if IPv6 is supported by the host. However, if the host lacks IPv6 support, routing is disabled, or the --no-ipv6 option is supplied, TTP falls back to dropping all outgoing IPv6 traffic to prevent potential cleartext leaks.
UDP (NON-DNS) NOT PROXIED
Only TCP traffic and DNS (UDP port 53) are handled. Other UDP traffic (e.g. VoIP, some games, QUIC/HTTP3) is blocked by the kill switch, not proxied through Tor. Tor's TransPort only supports TCP.
EXIT IP VARIATION ON ttp status
Different connections may show different exit IPs due to Tor's stream isolation. The IP shown by ttp status reflects the circuit used to reach check.torproject.org, which may differ from the circuit used by other applications.
torrc OVERWRITE
When TTP installs and configures Tor, it modifies /etc/tor/torrc to add required directives. The original file is backed up to torrc.bak before any changes. Custom configurations are preserved where possible.
0x0C

Complete System Uninstallation

TTP provides two levels of removal depending on how you installed it.

CLI COMMAND ttp uninstall

Use this to clean up the system state while keeping the TTP binary. It stops any active session, removes the SELinux policy module, and clears log files.

SHELL SCRIPT ./scripts/uninstall.sh

A complete system removal. If you used scripts/install.sh, this script will remove /opt/ttp, the symlink in /usr/local/bin, and perform all the cleanups of the CLI command.