transparent-tor-proxy 0.1.1__py3-none-any.whl

transparent_tor_proxy-0.1.1.dist-info/METADATA

@@ -0,0 +1,378 @@
+Metadata-Version: 2.4
+Name: transparent-tor-proxy
+Version: 0.1.1
+Summary: Transparent Tor Proxy — route all system traffic through Tor
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0.0
+Requires-Dist: stem>=1.8.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <br>
+  🛡️ TTP — Transparent Tor Proxy
+  <br>
+</h1>
+
+<h4 align="center">A Linux CLI tool that transparently routes <b>all system traffic</b> through the Tor network using nftables.</h4>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/OS-Linux-blue?style=for-the-badge&logo=linux" alt="Linux">
+  <img src="https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge&logo=python" alt="Python">
+  <img src="https://github.com/onyks-os/TransparentTorProxy/actions/workflows/ci.yml/badge.svg" alt="CI Status">
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
+</p>
+
+<p align="center">
+  <a href="#-features">Features</a> •
+  <a href="#-call-for-contributors">Contribute</a> •
+  <a href="#%EF%B8%8F-requirements">Requirements</a> •
+  <a href="#-installation">Installation</a> •
+  <a href="#-usage">Usage</a> •
+  <a href="#-how-it-works">How It Works</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/onyks-os/TransparentTorProxy/main/assets/gif/demo.gif" alt="TTP Demo">
+</p>
+
+---
+
+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](https://tails.net/) or the [Tor Browser](https://www.torproject.org/) 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](CONTRIBUTING.md) or dive right into the [Issues](https://github.com/onyks-os/TransparentTorProxy/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:
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+# 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
+
+```bash
+sudo ttp start
+```
+
+```text
+[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
+
+```bash
+sudo ttp stop
+```
+
+```text
+[TTP] Removing nftables rules...
+[TTP] Restoring DNS...
+[TTP] 🔴 Session terminated. Traffic in cleartext.
+```
+
+### Change exit IP
+
+```bash
+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
+
+```bash
+sudo ttp status
+```
+
+```text
+[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:**
+
+   ```bash
+   curl -s https://check.torproject.org/api/ip
+   ```
+
+2. **Verify DNS Routing:**
+
+   ```bash
+   # Should return a valid IP via Tor's DNSPort
+   dig +short A check.torproject.org
+   ```
+
+3. **DNS Leak Test (Terminal):**
+
+   ```bash
+   # 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](https://www.dnsleaktest.com) and [ipleak.net](https://ipleak.net).
+
+### Full Uninstallation
+
+To remove TTP completely from the system:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+sudo ttp diagnose
+```
+
+## 🗂️ Project Structure
+
+```text
+├── 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](CONTRIBUTING.md) to get started.
+* Please review our [Security Policy](SECURITY.md) before reporting vulnerabilities.
+
+## 📄 License
+
+MIT. See [LICENSE](LICENSE) for more information.

transparent_tor_proxy-0.1.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+ttp/__init__.py,sha256=tjAamIdSaMa12LGx8I-KB6vWnZ7SyVoHnLb4ObYnwrs,60
+ttp/cli.py,sha256=uElGJ_Ho3vGE02uho2ywbZWhyi4rM4I1CRD6NLbM10I,14544
+ttp/dns.py,sha256=nAMp32jnbiwNeRHCQXI-nhxsW86MdBp_YOxRVQDQWLI,4553
+ttp/exceptions.py,sha256=cQWp28_auJRMJgVxzHnb6iBH3pllWGwOudO073sqz_w,759
+ttp/firewall.py,sha256=UvUjL_L4FwGPfJFC8oPB9spI_NLIRwGsYe_3NfQaa6Q,5865
+ttp/state.py,sha256=7TUiTI541AfwxodmRSrTNVgUh9cW_BTBa0q0-Y9Lx44,3327
+ttp/system_info.py,sha256=NSivCA5EkBEES0PNPZYpx2rJvZGtalKOKhpZoT9Mjxo,4508
+ttp/tor_control.py,sha256=b0qP5rb7ufbetfkwGjOqjY40BUXlV0KqQIdBSUzQ7jI,6377
+ttp/tor_detect.py,sha256=3dLM5tT3jcuSJlRvxWmSBbz2ejZL1ySZhY49JWjBaQI,7662
+ttp/tor_install.py,sha256=7ilfNsZOwmA-ww8ALZKgxG08PQjaKv9suMwsWS9pXY4,9049
+ttp/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ttp/resources/selinux/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ttp/resources/selinux/ttp_tor_policy.te,sha256=Dg2u7EDWelhxLr-fUqDMB3720Bw7QuKUhE_tGHosFC0,264
+transparent_tor_proxy-0.1.1.dist-info/METADATA,sha256=RU1G2OwH0Rty57PbAeeERmNFuwag1X-stDROBgs0n6k,16608
+transparent_tor_proxy-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+transparent_tor_proxy-0.1.1.dist-info/entry_points.txt,sha256=DBAqgNP0PKZMf3UwdRTUy5d9tuM1IG1sq4zk1jY1Xko,36
+transparent_tor_proxy-0.1.1.dist-info/licenses/LICENSE,sha256=wLp0IAIlveZuh8Ys6MCG7nJU0s2DERPGD9pikFkxsEA,1065
+transparent_tor_proxy-0.1.1.dist-info/RECORD,,

transparent_tor_proxy-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

transparent_tor_proxy-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ttp = ttp.cli:app

transparent_tor_proxy-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onyks-os
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ttp/__init__.py

@@ -0,0 +1,3 @@
+"""TTP — Transparent Tor Proxy."""
+
+__version__ = "0.1.1"