DEV Community: onyks

Building a Stateless, RAM-Only Transparent Tor Proxy for Linux (TTP v0.3.0)

onyks — Fri, 15 May 2026 10:51:30 +0000

Transparent Tor Proxy (TTP) is a Linux CLI tool designed to intercept all outgoing network traffic and force it through the Tor network using nftables. Version 0.3.0 introduces a major architectural shift focused on system integrity and forensic invisibility, transitioning the application to a fully volatile runtime.

The Challenge

Classic transparent proxy implementations often suffer from severe state management issues. System configurations, such as /etc/resolv.conf, are typically overwritten directly. Furthermore, the default system Tor daemon (tor.service) is usually hijacked, leading to permission conflicts and disrupting any pre-existing background Tor relays.

The v0.3.0 Solution: Amnesia Core

The application core has been redesigned to operate almost entirely in volatile memory.

Volatile Standard Core: All runtime metadata, lock files, and logs are now stored in /run/ttp, which utilizes a tmpfs mount. This ensures zero physical traces are left on the host's physical disk after a power cycle.
Native Service Management: Tor is executed as a dedicated ttp-tor.service systemd unit. The volatile unit file is dynamically generated in /run/systemd/system/, avoiding interference with the system's own tor.service and bypassing its sandboxing restrictions.
Conflict Resolution: Daemon management is handled via a private Unix ControlSocket located at /run/tor/ttp/control.sock. SocksPort is set to 0 by default, allowing TTP to coexist alongside other Tor instances without triggering "Address already in use" errors.
Stateless DNS Overlay: Physical overwrites of /etc/resolv.conf have been replaced with a kernel-level mount --bind strategy. This achieves non-destructive redirection of DNS queries. Stale DNS mount overlays are automatically cleared to ensure absolute idempotency, and a lazy unmount fallback (umount -l) ensures successful removal during teardown even if the resource is busy.

Network Safety and Memory Trade-offs

Operating exclusively in RAM introduces specific constraints that require careful resource and state management.

Graceful Teardown: A cryptographic SHUTDOWN signal is sent to the Tor daemon before nftables firewall rules are removed. This guarantees all circuits close cleanly and strictly prevents cleartext RST packet leaks on the physical interface.
Persistent Entry Guards: Bootstrapping Tor entirely from scratch on every execution introduces severe latency. To mitigate this, DataDirectory /var/lib/tor/ttp/ is utilized to preserve Entry Guards across runs, maintaining a fast bootstrap time of approximately 3 seconds.
Resource Management: Logs have been moved to /run/ttp/ttp.log and are capped at a 1MB limit to prevent memory exhaustion in the RAM disk. Additionally, a pre-flight safety check is performed to verify sufficient tmpfs space is available before execution, preventing out-of-memory crashes mid-setup.

The networking logic utilizes a dedicated inet ttp table for nftables, ensuring all firewall modifications are isolated and cleanup is executed atomically via an nft destroy command.

Disclaimer: Entry guards are maintained in a persistent cache to facilitate rapid initialization. Although a setting to modify this behavior is currently absent, its introduction is expected in a subsequent version. It must be noted that standard OS-level logging, including systemd journals, remains active, meaning the tool is not forensically invisible or reliable for high-stakes anonymity. For scenarios necessitating absolute forensic protection, the use of TailsOS and the TOR Browser is advised.

Repository: TransparentTorProxy on GitHub

How I fixed network state corruption in my Linux Tor proxy

onyks — Mon, 11 May 2026 13:00:00 +0000

Most transparent proxy scripts share a fatal flaw: if they crash, they take your system's network down with them. Firewall rules are left lingering, DNS is routed to a dead port, and you're forced to manually flush routing tables just to get back online.

When building TTP (Transparent Tor Proxy), I wanted to engineer a resilient system that survives crashes and prevents leaks, especially on modern distros dealing with systemd-resolved and firewalld conflicts.

Here is the engineering approach I used to handle the three biggest network failure points.

1. Atomic Cleanup with Stateless nftables

Modifying the system's default firewall rules requires complex backup and restore logic. It's fragile and prone to race conditions.

Instead of touching existing rules, TTP creates a strictly isolated inet ttp table. I set the output hook to priority -150 to ensure TTP's redirection executes before any standard NAT or firewalld rules.

Because the ruleset is completely isolated, network restoration is a single, atomic operation:

nft destroy table inet ttp

If the proxy stops, the table is nuked. No system state backups are required, meaning zero risk of permanent corruption.

2. Auto-Recovering Orphaned Sessions

If the main process is killed abruptly (e.g., SIGKILL or power loss), the network remains trapped in Tor-routing mode.

To solve this, TTP uses a persistent JSON lock file (/var/lib/ttp/ttp.lock) to track the session state. On startup, the CLI checks for this file. If it exists, it verifies if the recorded PID is actually alive:

def is_orphan() -> bool:
    # ...
    pid = data.get("pid")
    try:
        os.kill(pid, 0) # Sends no signal, just checks for existence
    except OSError:
        return True # Process is dead, session is orphaned
    return False

If an orphaned session is detected, TTP automatically triggers the rollback logic (destroying the nftables table and restoring DNS) before starting a new, clean circuit.

3. The DNS Hard-Reset Strategy

Routing DNS through Tor (127.0.0.1:9053) is straightforward. Restoring it reliably is hard because systemd-resolved aggressively caches states.

A simple revert command often leaves the system unable to resolve domains. To guarantee cleartext connectivity upon exit, the restoration uses a "Hard-Reset" sequence:

Revert interface-specific overrides (resolvectl revert <interface>).
Force-restart the daemon to purge lingering memory states (systemctl restart systemd-resolved).
Wipe the cache entirely (resolvectl flush-caches).

The Result

The result is a proxy that guarantees a safe return to cleartext routing, even after a fatal crash. I've also added an emergency --restore-only flag and active leak audits (ttp check-leak) to verify exit IPs and DNS routes dynamically.

If you're interested in low-level Linux networking, nftables routing, or want to audit the code, you can check the repository here.

I am currently an undergraduate CS student, so any feedback is profoundly appreciated.