TTP - 透明 Tor 代理

一个 Linux CLI 工具，使用 nftables 透明地将所有系统流量路由通过 Tor 网络。

功能 • 要求 • 安装说明 • 用法 • 工作原理 • 参与贡献

无需针对每个应用进行设置 —— 只需 `sudo ttp start`，**每一个连接**都会通过 Tor。 ## 功能 * **易失性核心架构**：整个会话状态、锁文件和日志都专门存储在 `tmpfs`（`/run/ttp/` 和 `/run/tor/ttp/`）中，确保没有取证痕迹写入物理磁盘，并在重启时自动消失。 * **无状态 DNS 覆盖**：在不修改磁盘上原始配置文件的情况下，在 `/etc/resolv.conf` 上使用内核级别的 `mount --bind` 覆盖透明地重定向 DNS 请求，并自动清理陈旧的挂载以实现绝对的幂等性。 * **主动式看门狗与阻断开关**：活动的后台会话完整性守护进程监控 Tor 状态、nftables 表/链的存在以及 DNS 覆盖挂载。在发生持续故障时，触发一次性自愈修复或硬网络锁定（紧急全丢弃阻断开关）。 * **局域网绕过与分流**：动态将本地子网（RFC 1918 和 Link-Local）从 Tor 路由中排除，以维持对本地资源（打印机、NAS）的访问。通过 `nftables` 的 uid/gid 检查，支持特定用户或组的例外（`--bypass-user` / `--bypass-group`）。 * **原生双栈 IPv6 重定向**：动态检测 IPv6 环回可用性，构建双栈 nftables 重定向链，或者在不受支持时丢弃所有传出 IPv6 流量（防止 IPv6 泄露）。 * **DoH/DoT 泄露缓解**：主动阻止出站 DoT（端口 853）和已知的 DoH 解析器 IP（端口 443），强制系统回退到 Tor DNS，并在 `torrc` 中利用金丝雀域在支持的浏览器级别禁用 DoH。 * **原生 Tor 服务管理**：Tor 通过一个专用的、易失性的 `ttp-tor.service` systemd 单元进行管理，该单元运行在非标准端口上，可与任何标准系统的 `tor.service` 无缝共存且无地址冲突。 ## 要求 * **带有 systemd 的 Linux** *(已在 Debian、Ubuntu、Fedora、Arch 上测试)* * **Python 3.10+** * **nftables** *(大多数现代发行版已预装)* * **Root 权限** *(修改防火墙和 DNS 所需)* ## 安装说明 选择最适合您需求的方法。为了系统的稳定性、安全性和干净的卸载，**强烈推荐使用原生包**。 ### 1. 原生包（推荐） 通过原生包安装可确保所有系统依赖项（`tor`、`nftables`）和内核级优化（SELinux）由您的操作系统包管理器管理。 * **Debian / Ubuntu**：`sudo apt install ./packaging/transparent-tor-proxy_0.4.0_all.deb` * **Fedora / RHEL**：`sudo dnf install ./packaging/transparent-tor-proxy-0.4.0-1.fc43.noarch.rpm` * **Arch Linux**：`cd packaging && makepkg -si` 有关如何验证发布资产的完整性和真实性的说明，请参阅[发布验证指南](docs/verification.md)。 ### 2. 手动源码安装（开发者/通用） 如果您是开发者或想从仓库安装： ``` git clone https://github.com/onyks-os/TransparentTorProxy.git cd TransparentTorProxy sudo ./scripts/install.sh ``` ### 3. 备选方案：pipx / pip (PEP 668) #### **选项 A：pipx（推荐的备选方案）** `pipx` 在隔离的环境中安装 TTP，但使命令全局可用。 ``` pipx install transparent-tor-proxy ``` #### **选项 B：带有 venv 的标准 pip** 如果您偏好标准的 `pip`，请使用虚拟环境以避免 `externally-managed-environment` 错误。 ``` # 1. 创建环境 python3 -m venv ~/.local/share/ttp-venv # 2. 安装软件包 ~/.local/share/ttp-venv/bin/pip install transparent-tor-proxy # 3. 创建 symbolic link 以便在所有地方使用 'ttp' sudo ln -s ~/.local/share/ttp-venv/bin/ttp /usr/local/bin/ttp ``` ## 用法 ### 启动代理 ``` sudo ttp start [--interface ] [--bootstrap-timeout ] [--allow-root] [--no-lan-bypass] [--watchdog] [--bypass-user ] [--bypass-group ] [--use-bridges] [--bridge-file ] [--bridge ] ``` ``` [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... [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. ``` ### 停止代理 ``` sudo ttp stop [--restore-only] ``` ``` [TTP] Removing nftables rules... [TTP] Restoring DNS... [TTP] Network restored. Traffic in cleartext. ``` ### 更改出口 IP ``` sudo ttp refresh ``` *通过控制接口向 Tor 发送 `NEWNYM` - 所有活动的电路都会被轮换，您将获得一个新的出口 IP。* ### 检查状态 ``` 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 ``` ### 重启会话 ``` sudo ttp restart [--interface ] [--bootstrap-timeout ] [--allow-root] [--no-lan-bypass] [--watchdog] [--bypass-user ] [--bypass-group ] [--use-bridges] [--bridge-file ] [--bridge ] ``` *这是 `ttp stop` 后接 `ttp start` 的快捷方式。方便应用新设置或清除网络故障。* ### 网络诊断（快速） ``` ttp check ``` *用于验证 Tor 连接的真实状态的专用命令。显示当前 IP、IsTor 状态、到 torproject.org 的延迟以及本地控制器的稳定性。与显示 TTP 内部状态的 `status` 不同，`check` 用于验证网络。* ### 泄露检测 ``` ttp check-leak [-v] ``` *执行一系列 DNS 和 IP 泄露测试。使用 `-v` 或 `--verbose` 可以查看测试的完整原始输出。* ### 调试日志 ``` sudo ttp logs ``` *从位于 `/run/ttp/ttp.log` 的易失性日志文件中实时流式传输日志。* ### 管理会话看门狗 ``` # 手动启动 background session watchdog sudo ttp watchdog start # 手动停止 background session watchdog sudo ttp watchdog stop # 显示 background session watchdog 状态 ttp watchdog status ``` ### 高级安全配置 根据您的安全模型和任务，我们推荐以下设置： #### 1. 日常隐私配置（标准） * **目标**：以最小的开销匿名化常规浏览、绕过地理限制或隐藏 ISP 窥探。 * **命令**： sudo ttp start * **原因**：无需后台活动进程运行（没有看门狗开销），利用极其高效的 `nftables` 重定向规则和本地绕过，实现流畅的家庭/工作局域网打印机/NAS 共享。 #### 2. 最高安全配置（高风险） * **目标**：吹哨举报、高风险活动、全面防止意外的明文泄露或网络状态改变。 * **命令**： sudo ttp start --watchdog --no-lan-bypass * **原因**：启动持续的后台 **看门狗** 守护进程，每 15 秒监控一次状态完整性。禁用局域网绕过以防止向本地局域网设备的侧信道泄露。如果任何组件（DNS 覆盖、nftables 或 Tor 守护进程）被篡改或出现故障，系统会立即将网络完全隔离（紧急阻断开关）并通知您。 #### 3. 管理 / 维护配置 * **目标**：在 Tor 激活时执行本地更新（例如 `apt update`、`dnf upgrade`）或需要高带宽或直接原生路由的维护，或加速初始引导。 * **命令**： sudo ttp start --allow-root * **原因**：通过 Tor 路由所有默认的用户/系统进程，但豁免系统 root 进程（`uid 0`），允许它们直接以明文通信进行更新或故障排除。（请谨慎使用：如果在 sudo 下运行，会增加工具/脚本泄露的风险）。 #### 4. 分流配置 * **目标**：将除特定系统用户或组之外的所有网络流量通过 Tor 路由（例如，以明文运行本地媒体服务器、备份或游戏）。 * **命令**： sudo ttp start --bypass-user debian-tor,mediauser --bypass-group sysadmin * **原因**：使用 `nftables` 例外允许匹配的本地用户 ID 或组 ID 直接与明文互联网通信，绕过重定向和看门狗阻断开关。 #### 5. 规避审查配置（Tor 网桥） * **目标**：在阻止标准 Tor 入口节点的审查环境中连接到 Tor 网络。 * **命令**： sudo ttp start --use-bridges --bridge-file /path/to/my_bridges.txt # 或者直接指定单个网桥： sudo ttp start --bridge "obfs4 192.0.2.1:1234 ..." --bridge "snowflake 192.0.2.2:4321 ..." * **原因**：配置 Tor 通过网桥连接。如果需要像 `obfs4proxy` 或 `snowflake-client` 这样的可插拔传输，TTP 会自动检查它们的存在并使用系统包管理器进行安装。 ## 手动泄露验证 要确认隧道是否正常工作并且没有泄露： 1. **验证 Tor 出口 IP：** curl -s https://check.torproject.org/api/ip 2. **验证 DNS 路由：** # 应该通过 Tor 的 DNSPort 返回一个有效的 IP dig +short A check.torproject.org 3. **DNS 泄露测试（终端）：** # 这个 TXT 查询应该返回一个空输出 dig +short TXT whoami.ipv4.akahelp.net *注意：在 Tor 下，空输出是**预期**的行为。Tor 的透明解析器不支持 TXT 记录；如果此命令返回您真实的 ISP IP，则说明您发生了 DNS 泄露。* 4. **基于 Web 的验证：** 请务必在 [dnsleaktest.com](https://www.dnsleaktest.com) 和 [ipleak.net](https://ipleak.net) 上进行额外的测试。 ### 完全卸载 要从系统中完全移除 TTP： ``` sudo ./scripts/uninstall.sh ``` ## 工作原理 1. **检测与系统审计** - 检查是否安装了 Tor 并确定运行该进程的合适用户。它会自动检查活动的 `firewalld` 配置，以警告用户可能存在的防火墙规则冲突。 2. **包管理与 SELinux 优化** - 如果缺少 Tor，会检测系统的包管理器（`apt-get`、`pacman`、`dnf`、`zypper`）并自动安装。在 Enforcing 模式下的 Fedora/RHEL 系列系统上，它会自动使用 `checkpolicy` 和 `semodule_package` 从源码（`ttp_tor_policy.te`）编译自定义的 SELinux 策略模块，以便 Tor 可以绑定到非标准端口。 3. **预检安全检查** - 验证主机系统的内存易失性目录（`tmpfs`）上是否有足够的可用空间（最少 5MB），以防止设置过程中途出现内存不足崩溃。 4. **Tor 实例生命周期** - 在 `/run/tor/ttp/torrc` 生成经过净化、动态生成的 `torrc` 配置，并在 `/run/systemd/system/` 中注册易失性的 `ttp-tor.service` systemd 单元。使用 `/var/lib/tor/ttp/` 作为持久化 `DataDirectory` 来保留入口守卫和缓存，从而实现快速引导（约 3 秒）。在拆除期间，TTP 会在移除防火墙之前向 Tor 发送加密的 `SHUTDOWN` 信号，以避免在系统关机时泄露明文 TCP `RST` 数据包。 5. **原子化防火墙重定向** - 使用 `nft -f` 将 `nftables` 规则原子化地生成并加载到专用的 `inet ttp` 表中，以防止出现危险的中间状态。 * **多链保护**： * `prerouting`：如果 TTP 作为网关使用，则拦截流量。 * `output` (NAT)：将本地 TCP/DNS 重定向到 Tor 的端口。 * `filter_out` (Filter)：作为硬性 **阻断开关**。 * **执行顺序**： 1. **排除 Tor 用户**：防止 Tor 守护进程出现路由循环。 2. **排除分流**：豁免特定用户或组的流量（`meta skuid` / `meta skgid`），以便在请求时绕过 Tor。 3. **排除系统维护**：如果设置了 `--allow-root`，则豁免 root 进程（`uid 0`）。 4. **拦截 DNS**：将 UDP/TCP 端口 53 流量重定向到 Tor 的 `DNSPort`。 5. **绕过局域网**：除非激活了 `--no-lan-bypass`，否则接受本地子网流量（RFC 1918 和 Link-Local）。 6. **接受环回**：允许本地 `lo` 流量。 7. **重定向 TCP**：将所有 TCP 流量重定向到 Tor 的 `TransPort`。 8. **DoH/DoT 缓解**：阻止端口 853 (DoT) 和端口 443 上已知的 DoH 解析器 IP。 9. **丢弃未路由的 IPv6**：如果主机缺少 IPv6 环回路由，则阻止出站 IPv6 流量。 10. **强制拒绝（阻断开关）**：拒绝所有绕过 Tor 重定向的剩余（例如，预先存在的连接）。 6. **DNS 绑定挂载覆盖** - 将来自 `/run/ttp/resolv.conf` 的易失性解析器文件绑定挂载到目标 `/etc/resolv.conf` 上，以强制进行本地解析。来自不干净运行的陈旧挂载会在 `/proc/mounts` 中被自动检测并清除，然后再应用新的覆盖。 7. **控制套接字通信** - 使用 `stem` 通过 Tor ControlPort Unix 套接字 `/run/tor/ttp/control.sock` 监控进度，直到达到 100% 引导完成。 8. **出口 IP 验证** - 通过三个冗余端点（`check.torproject.org` API、回退 `api.ipify.org` 和 `ifconfig.me`）验证 Tor 路由是否成功。 9. **易失性状态保留** - 在 `/run/ttp/ttp.lock` 写入会话锁，并将 `/run/ttp/ttp.log` 中的易失性日志限制在严格的 1MB 以内，防止系统内存在 RAM 磁盘上耗尽。 10. **会话看门狗守护进程** - 启动一个易失性后台服务（`ttp-watchdog.service`），每 15 秒运行一次检查。验证 DNS 绑定挂载、防火墙表完整性和 Tor 套接字。在调用 `apply_emergency_killswitch()`（阻止除 `lo` 之外的所有接口）并广播系统警报（`wall` 和 `notify-send`）之前，尝试一次性自愈修复。 ## 崩溃恢复 TTP 旨在始终恢复您的网络，即使在边缘情况下也是如此： | 场景 | 发生了什么 | | :----------------------- | :------------------------------------------------------------------------------------------------------- | | `ttp stop` | **正常清理**：优雅地关闭 Tor，恢复防火墙，恢复 DNS，删除锁 | | Ctrl+C / `kill` | 信号处理程序捕获 `SIGINT`/`SIGTERM` 并在退出前执行正常清理 | | `kill -9` / 断电 | 下一次 `ttp start` 会检测到孤立的锁文件，清除所有陈旧的挂载堆栈，并自动恢复 | | 手动紧急情况 | 运行 `sudo ./scripts/restore-network.sh` 以刷新所有 nftables 规则，重置 DNS，并删除锁文件 | ## 已知行为与限制 有关剩余风险、架构信任边界和 STRIDE 威胁模型的完整细分，请参阅： **[`docs/security-assessment.md`](docs/security-assessment.md)** ## 开发与测试 TTP 使用 **Makefile** 来自动化和标准化测试流水线。这确保了每一项更改在提交之前都经过了单元测试和集成测试的验证。 ### “推送前”规则 ### 核心命令 | 命令 | 目标 | | :------------------------ | :------------------------------------------------------------------------ | | `make test` | 在本地运行快速的**单元测试**（无需 root，完全模拟）。 | | `make integration-debian` | 在特权 **Docker** 容器内运行完整的系统测试。| | `make integration-all` | 对所有支持的发行版运行集成测试。 | | `make verify` | 运行单元测试 + 所有集成测试。 | | `make build` | 生成原生的 `.deb` 和 `.rpm` 包。 | | `make clean` | 删除所有构建产物、缓存和临时文件。 | ### 进阶：真实虚拟机测试 虽然 Docker 集成测试快速且原子化，但它们无法捕获 100% 的内核/systemd 细微差别。对于关键更改，**强烈建议**在真实的 QEMU 虚拟机中进行测试： ``` # 启动特定 VM（例如，arch） ./scripts/vm/start.sh arch # 同步当前代码到 VM ./scripts/vm/send.sh # 用于轻松回滚的 Snapshot 管理 ./scripts/vm/snapshot.sh arch save before-risky-test ``` ### 诊断 如果出现问题，请运行诊断命令： ``` sudo ttp diagnose ``` ## 项目结构 ``` ├── 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 ├── ├── verify.sh # CI/CD verification script ├── └── vm/ # QEMU VM management scripts ├── └── vms/ # .iso and .qcow2 files ├── assets/ # Branding and demo assets ├── ├── favicon/ # Project favicons and webmanifest ├── └── gif/ # Demo animations ├── packaging/ # Build scripts for .deb, .rpm, and Arch packages ├── ├── build_deb.sh ├── ├── build_rpm.sh ├── ├── release.sh # Package release/publish script ├── ├── 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 ├── ├── watchdog.py # Session integrity watchdog and auto-healing ├── └── system_info.py # System diagnostic gathering ├── tests/ # Unit tests (mocked) and test_watchdog.py └── docs/ ├── architecture.md # Technical Architecture & Design ├── interfaces.md # External interfaces reference (CLI, Tor, system) └── security-assessment.md # STRIDE threat model & risk assessment ``` ## 号召贡献者 我们正在积极寻找加入 TTP 项目的开发者！无论您是想要学习的学生，还是经验丰富的专业人士，我们都欢迎您的帮助。 **我们特别寻找在以下领域具有专业知识的资深开发者**： * **Linux 网络**（nftables、路由表、网络命名空间）。 * **Tor 内部机制**（守护进程配置、Stem 库、电路管理）。 * **系统级 Python**（异步 I/O、进程管理、安全最佳实践）。 如果您想为使透明代理更安全、更健壮做出贡献，请查看我们的[贡献指南](CONTRIBUTING.md)，或直接深入探讨[问题](https://github.com/onyks-os/TransparentTorProxy/issues)。 ## 获取、反馈与贡献 - **获取**：TTP 可在 [PyPI](https://pypi.org/project/transparent-tor-proxy/) 上获取，也可以从 [GitHub Releases](https://github.com/onyks-os/TransparentTorProxy/releases) 页面下载。有关安装方法，请参阅[安装说明](#installation)部分。 - **反馈**：通过在 [GitHub Issues](https://github.com/onyks-os/TransparentTorProxy/issues) 跟踪器上提交工单来报告错误、建议改进或请求功能。 - **贡献**：始终欢迎您的贡献！请阅读我们的[贡献指南](CONTRIBUTING.md)，了解如何提交代码、遵循编码规范和运行测试。 - **安全**：在报告任何漏洞或安全疑虑之前，请查阅我们的[安全策略](SECURITY.md)。 ## 支持 有关版本支持状态、EOL 信息和支持渠道，请参阅[支持策略](SUPPORT.md)。 这个项目是在我的空闲时间维护的，非常感谢您的捐赠。

此外，如果您觉得 **TTP** 有用，请考虑给它点个 **Star**！ 这有助于其他人发现这个工具，并激励进一步的开发。 [](https://github.com/onyks-os/TransparentTorProxy)

## 许可证 MIT。有关更多信息，请参见 [LICENSE](LICENSE)。

标签：nftables, Python, Tor, 无后门, 网络隐私, 逆向工具, 透明代理