TTP - 透明 Tor 代理

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

功能特性 • 系统要求 • 安装 • 使用方法 • 工作原理 • 验证 • 参与贡献

无需针对每个应用程序进行配置——只需 sudo ttp start，所有连接都会通过 Tor。

[!CAUTION] TTP 是一款旨在通过 Tor 路由流量来帮助保护隐私的工具。然而，没有任何工具能够保证 100% 的匿名性。您的安全还取决于您的行为（例如，使用普通浏览器而非 Tor 浏览器、登录账户等）。请始终将 TTP 作为多层安全策略的一部分使用。

[!WARNING] 如果您是举报人或正在从事高风险活动，请勿使用 TTP。 请改用经过官方审计且可靠的工具，例如直接使用 TailsOS 或 Tor 浏览器。TTP 的作者和贡献者对您的安全或使用本软件所产生的后果不承担任何责任。

为什么选择 TTP？

传统的透明代理脚本（TorGhost、Anonsurf）会覆盖配置文件并构建 iptables 规则集，而这些规则集在失效时是开放的：当它们崩溃时，流量会以明文形式泄露。TTP 的构建方式恰恰相反——它以失效关闭（fail closed）为原则，并且不在磁盘上保留任何内容。

功能特性

• 持续完整性保护——由形式化 FSM（transitions）管理的看门狗通过双重 inotify 监视来监控 Tor、nftables 链和 DNS 覆盖层，能够捕获符号链接目标替换。它会修复一次，然后应用紧急终止开关。
• 分流隧道——通过原生 nftables UID/GID 匹配来豁免用户或组（--bypass-user、--bypass-group），或通过 cgroups v2 slice 使用 ttp bypass <cmd> 在 Tor 之外运行单条命令。
• 保留局域网——RFC 1918 和链路本地子网保持可达，因此您的打印机和 NAS 可以继续工作。
• 双栈，或无栈——当回环路由可用时，IPv6 通过 Tor 路由；当不可用时，直接丢弃。不存在第三种会泄露的选项。
• 阻止 DoT 和 DoH——拒绝端口 853，在 443 端口（TCP 和 QUIC）上拒绝已知的公共 DoH 解析器，并在 torrc 中污染浏览器金丝雀域名。
• 与系统 Tor 共存——在非标准端口上运行自己的易失性 ttp-tor.service，不影响现有的 Tor 实例。
• 网桥——支持 obfs4 和 snowflake，以及 BYOD（自带守护进程）模式。

系统要求

• 带 systemd 的 Linux
• Python 3.10+
• nftables（大多数现代发行版已预装）
• Root 权限（防火墙和 DNS 修改所需）

安装

选择最适合您需求的方法。强烈推荐使用原生软件包，以确保系统稳定性、安全性和干净卸载。

1. 原生软件包（推荐）

通过原生软件包安装可确保所有系统依赖项（tor、nftables）和内核级优化（SELinux）由您的操作系统包管理器管理。

从最新发布下载您所需版本的 .deb 或 .rpm——这些软件包是发布资产，未检入仓库——然后安装：

• Debian / Ubuntu：sudo apt install ./transparent-tor-proxy_0.4.9_all.deb
• Fedora / RHEL：sudo dnf install ./transparent-tor-proxy-0.4.9-1.noarch.rpm
• Arch Linux：从仓库构建，使用 cd packaging && makepkg -si

有关如何验证发布资产完整性和真实性的说明，请参阅发布验证指南。

2. 手动源码安装（开发者/通用）

如果您是开发者或希望从仓库安装：

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

[!TIP] 为什么要使用 ./install.sh？
与标准的 Python 安装程序不同，此脚本是**"智能"**的。在基于 Red Hat 的系统上，它会检测 SELinux 是否处于强制模式，并动态编译自定义策略模块（来自 ttp_tor_policy.te），以允许 Tor 绑定到 TTP 所需的非标准端口（9041、9054）。这种内核级优化无法由 pip 执行。

3. 替代安装方法（后备）

有关通过 Python 专用包管理器（pipx 或带虚拟环境的 pip）安装 TTP 的信息，请参阅替代安装方法参考。

使用方法

TTP 的设计简单轻量。有关 CLI 命令、选项、退出代码和技术规范的完整列表，请参阅外部接口参考。

快速开始

大多数修改网络的命令需要 root 权限（sudo）：

• 启动代理：

  root@kitploit:~

  sudo ttp start
  

• 停止代理：

  root@kitploit:~

  sudo ttp stop
  

• 检查当前会话状态：

  root@kitploit:~

  ttp status
  

• 验证 Tor 路由和延迟：

  root@kitploit:~

  ttp check
  

• 请求新的出口 IP（轮换电路）：

  root@kitploit:~

  sudo ttp refresh
  

有关更高级的设置和规避配置文件，请参阅高级安全与使用配置文件参考或查阅外部接口参考。

检查您的会话

完全卸载

要从系统中完全移除 TTP：

sudo ./scripts/uninstall.sh

工作原理

TTP 通过编排标准 Linux 内核子系统、系统工具和 Tor 的控制接口，透明地路由所有网络流量：

flowchart LR
    App["Application"] --> Local["Local Network"]
    Local --> DNS["systemd-resolved (Intercepted)"]
    DNS --> NFT["nftables (inet ttp table)"]
    NFT --> Tor["Tor Daemon"]
    Tor --> Internet["Internet"]

1. 原子防火墙重定向：原子地生成并加载一个隔离的 inet ttp nftables 规则集，以拦截 TCP 和 DNS 流量，将其重定向到 Tor，同时防止 IPv6 和 DoT/DoH 泄露。
2. DNS 绑定挂载覆盖：通过内核级绑定挂载，用易失性的基于 RAM 的配置覆盖 /etc/resolv.conf，以确保 DNS 调用由 Tor 解析。
3. Tor 守护进程集成：通过非标准端口上的易失性 systemd 服务配置、运行和监控一个隔离的 Tor 实例，以防止端口冲突。
4. 会话看门狗：运行一个活跃的后台监控程序，验证配置完整性，并在安全漏洞或系统修改时执行失效关闭的紧急终止开关。

有关执行流程、系统钩子、安全边界和模块化组件的详细说明，请参阅：

技术架构与设计指南

崩溃恢复

TTP 的设计目标是始终恢复您的网络，即使在边缘情况下也是如此：

已知行为与限制

[!WARNING]

• Tor 浏览器：使用显式 SOCKS5 代理的应用程序将创建双重 Tor 跳。在 TTP 激活时，请改用普通浏览器。
• DNS-over-HTTPS (DoH)：普通浏览器（Firefox、Chrome、Brave、Edge）可能使用 DoH，绕过系统 DNS。TTP 通过三层防御来缓解 DoH：(1) 所有出站 TCP 流量（包括 DoH）都被重定向到 Tor TransPort；(2) 常见的 DoH 金丝雀域名在 torrc 中被映射到 0.0.0.0；(3) 公共 DoH IP 解析器在 TCP/UDP 端口 443 上被阻止（阻止 HTTP/3 QUIC DoH）。为获得最大安全性，请在浏览器设置中禁用 DoH / "安全 DNS"。
• IPv6：在可用时完全支持。TTP 动态检测 IPv6 回环，并通过 Tor 路由 IPv6 流量。如果主机缺少 IPv6 回环支持，或者传入了 --no-ipv6 选项，TTP 会丢弃所有出站 IPv6 流量以防止泄露。
• 出口 IP 变化：由于 Tor 流隔离，不同连接可能显示不同的出口 IP。

有关残余风险、架构信任边界和 STRIDE 威胁模型的完整分析，请参阅：

docs/security-assessment.md

开发与测试

TTP 使用 Makefile 来自动化和标准化测试流水线。这确保每次更改在提交前都经过单元测试和集成测试的验证。

"推送前"规则

[!IMPORTANT] 推送代码前请始终运行 make verify。 如果此命令失败，则代码尚未准备好用于生产环境。

基本命令

验证

TTP 的零泄露声明是可测量的，而非断言。 网络沙箱引擎 构建一个隔离的网络命名空间，将 TTP 真实生成的规则集加载到其中，生成泄露所包含的流量，并使用 Scapy 嗅探器监视边界 veth 接口。

每个遏制测试运行两次。 当嗅探器从未启动、接口名称错误或流量从未离开进程时，assert no leaks 同样为真，因此每个测试首先在规则集被刷新的情况下运行相同的刺激，并要求看到数据包。只有在那之后，它才断言 TTP 的规则集阻止了它。一个无法观察到泄露的测试框架会使测试失败，而不是通过测试。

覆盖范围：普通 DNS（UDP 和 TCP）、普通 TCP、853 端口上的 DoT、UDP/443 上的 QUIC DoH、ICMP、任意 UDP、IPv6——以及另一个方向，即被豁免的 UID 仍能访问局域网。一个阻止一切的防火墙会通过前七项，但会在第八项失败。

# libpcap is required: the sniffer compiles a BPF filter, and Scapy dlopen()s
# the unversioned libpcap.so that only the -devel/-dev package ships.
sudo apt install nftables iproute2 conntrack libpcap0.8 libpcap-dev   # Debian/Ubuntu
sudo dnf install nftables iproute2 conntrack libpcap libpcap-devel    # Fedora/RHEL
pip install -e ".[nse]"
make test-nse            # runs as root; TTP_REQUIRE_NSE=1 so it cannot skip itself

这会在每次推送时于 CI 中运行（零泄露规则集验证作业），并作为发布前 scripts/verify.sh 中的一个步骤运行。

高级：真实世界 VM 测试

虽然 Docker 集成测试快速且原子化，但它们无法捕捉 100% 的内核/systemd 细微差别。对于关键更改，强烈建议在真实的 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

诊断

如果出现问题，请运行诊断命令：

sudo ttp diagnose

项目结构

├── pyproject.toml          # Package metadata and dependencies
├── README.md
├── CONTRIBUTING.md         # Contribution guidelines
├── SECURITY.md             # Security policy
├── scripts/                # Installation, verification, and VM management scripts
├── assets/                 # Branding and demo assets
├── packaging/              # Packaging configurations (.deb, .rpm, Arch PKGBUILD)
├── ttp/                    # Main Python source package
│   └── resources/          # Internal package resources (SELinux policies, etc.)
├── tests/                  # Unit, integration, and leak testing suites
└── docs/                   # Technical documentation, threat models, and ADRs

参与贡献

欢迎贡献，而最需要帮助的领域是狭窄且具体的：

1. Linux 网络——nftables、路由表、网络命名空间、VPN 接口检测。
2. Tor 内部机制——守护进程配置、Stem、网桥、引导边缘情况。
3. CI/CD——在 GitHub Actions 上保持特权测试套件快速可靠。

从 CONTRIBUTING.md 开始，其中记录了这个代码库所基于的两条规则：永远不要在不添加本可以捕获该错误的检查的情况下修复错误，以及一个断言不存在的测试必须首先证明它能够检测到存在。

本项目在业余时间维护。一个 star 能帮助他人发现它；赞助能帮助它持续发展。

许可证

MIT。更多信息请参阅 LICENSE。