TTP - Transparent Tor Proxy

nftables를 사용하여 모든 시스템 트래픽을 Tor 네트워크를 통해 투명하게 라우팅하는 Linux CLI 도구입니다.

기능 • 요구 사항 • 설치 • 사용법 • 작동 방식 • 검증 • 기여

애플리케이션별 설정이 필요하지 않습니다 - sudo ttp start만 실행하면 모든 연결이 Tor를 통해 이루어집니다.

[!CAUTION] TTP는 트래픽을 Tor를 통해 라우팅하여 프라이버시를 지원하도록 설계된 도구입니다. 그러나 어떤 도구도 100% 익명성을 보장할 수는 없습니다. 사용자의 안전은 사용자의 행동(예: 일반 브라우저 사용 vs. Tor Browser 사용, 계정 로그인 등)에도 달려 있습니다. 항상 TTP를 다층 보안 전략의 일부로 사용하십시오.

[!WARNING] 내부고발자이거나 고위험 활동에 종사하는 경우 TTP를 사용하지 마십시오. 대신 TailsOS나 Tor Browser와 같이 공식적으로 감사되고 신뢰할 수 있는 도구를 직접 사용하십시오. TTP의 저자와 기여자는 사용자의 안전이나 이 소프트웨어 사용의 결과에 대해 어떠한 책임도 지지 않습니다.

TTP를 사용하는 이유?

기존의 투명 프록시 스크립트(TorGhost, Anonsurf)는 설정 파일을 덮어쓰고 개방형으로 실패하는 iptables 규칙 세트를 구축합니다. 즉, 이들이 깨지면 트래픽이 평문으로 유출됩니다. TTP는 반대 방향으로 설계되었습니다 - 폐쇄형으로 실패하며, 디스크에 아무것도 남기지 않습니다.

기능

• 지속적인 무결성 보호 - 형식적 FSM(transitions)에 의해 관리되는 워치독이 심볼릭 링크 대상 교체를 감지하는 이중 inotify 감시를 통해 Tor, nftables 체인 및 DNS 오버레이를 모니터링합니다. 한 번 복구한 후 비상 킬스위치를 적용합니다.
• 분할 터널링 - 네이티브 nftables UID/GID 매칭으로 사용자 또는 그룹(--bypass-user, --bypass-group)을 예외 처리하거나, cgroups v2 슬라이스를 통해 ttp bypass <cmd>로 단일 명령을 Tor 외부에서 실행합니다.
• LAN 보존 - RFC 1918 및 링크-로컬 서브넷이 계속 접근 가능하므로 프린터와 NAS가 계속 작동합니다.
• 듀얼 스택 또는 스택 없음 - 루프백 라우팅이 가능한 경우 IPv6가 Tor를 통해 라우팅되며, 그렇지 않은 경우 완전히 드롭됩니다. 유출되는 세 번째 옵션은 없습니다.
• DoT 및 DoH 차단 - 포트 853 거부, 알려진 공용 DoH 리졸버의 443(TCP 및 QUIC) 거부, 브라우저 카나리 도메인을 torrc에서 포이즈닝합니다.
• 시스템 Tor와 공존 - 비표준 포트에서 자체 휘발성 ttp-tor.service를 실행하여 기존 Tor 인스턴스를 건드리지 않습니다.
• 브리지 - obfs4 및 snowflake, BYOD(자체 데몬 사용) 모드 지원.

요구 사항

• systemd를 사용하는 Linux
• Python 3.10+
• nftables (대부분의 최신 배포판에 사전 설치됨)
• 루트 권한 (방화벽 및 DNS 수정에 필요)

설치

필요에 가장 적합한 방법을 선택하십시오. 시스템 안정성, 보안 및 깔끔한 제거를 위해 네이티브 패키지를 강력히 권장합니다.

1. 네이티브 패키지 (권장)

네이티브 패키지를 통해 설치하면 모든 시스템 종속성(tor, nftables)과 커널 수준 최적화(SELinux)가 OS 패키지 관리자에 의해 관리됩니다.

최신 릴리스에서 원하는 버전의 .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가 Enforcing 모드인지 감지하고, Tor가 TTP에 필요한 비표준 포트(9041, 9054)에 바인딩할 수 있도록 사용자 정의 정책 모듈(ttp_tor_policy.te에서)을 동적으로 컴파일합니다. 이 커널 수준 최적화는 pip로 수행할 수 없습니다.

3. 대체 설치 방법 (폴백)

Python 전용 패키지 관리자(pipx 또는 가상 환경과 함께 pip)를 통해 TTP를 설치하려면 대체 설치 방법 참조를 참조하십시오.

사용법

TTP는 간단하고 가볍게 설계되었습니다. CLI 명령, 옵션, 종료 코드 및 기술 사양의 전체 목록은 외부 인터페이스 참조를 참조하십시오.

빠른 시작

대부분의 네트워크 수정 명령은 루트 권한(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. 원자적 방화벽 리디렉션: TCP 및 DNS 트래픽을 가로채기 위해 격리된 inet ttp nftables 규칙 세트를 원자적으로 생성하고 로드하여, IPv6 및 DoT/DoH 유출을 방지하면서 이들을 Tor로 리디렉션합니다.
2. DNS 바인드 마운트 오버레이: 커널 수준 바인드 마운트를 통해 /etc/resolv.conf를 휘발성 RAM 기반 구성으로 오버레이하여 DNS 호출이 Tor에 의해 해석되도록 합니다.
3. Tor 데몬 통합: 포트 충돌을 방지하기 위해 비표준 포트에서 휘발성 systemd 서비스를 통해 격리된 Tor 인스턴스를 구성, 실행 및 모니터링합니다.
4. 세션 워치독: 구성 무결성을 검증하고 보안 침해 또는 시스템 수정 시 폐쇄형 비상 킬스위치를 실행하는 활성 백그라운드 모니터를 실행합니다.

실행 흐름, 시스템 후크, 보안 경계 및 모듈식 구성 요소에 대한 자세한 설명은 다음을 참조하십시오:

기술 아키텍처 및 설계 가이드

충돌 복구

TTP는 예외적인 경우에도 항상 네트워크를 복원하도록 설계되었습니다:

알려진 동작 및 제한 사항

[!WARNING]

• Tor Browser: 명시적 SOCKS5 프록시를 사용하는 애플리케이션은 이중 Tor 홉을 생성합니다. TTP가 활성화된 동안에는 일반 브라우저를 대신 사용하십시오.
• DNS-over-HTTPS (DoH): 일반 브라우저(Firefox, Chrome, Brave, Edge)는 DoH를 사용하여 시스템 DNS를 우회할 수 있습니다. TTP는 3계층 방어를 통해 DoH를 완화합니다: (1) 모든 아웃바운드 TCP 트래픽(DoH 포함)이 Tor TransPort로 리디렉션됨; (2) 일반적인 DoH 카나리 도메인이 torrc에서 0.0.0.0으로 매핑됨; (3) 공용 DoH IP 리졸버가 TCP/UDP 포트 443에서 차단됨(HTTP/3 QUIC DoH 차단). 최대 보안을 위해 브라우저 설정에서 **DoH / "Secure DNS"**를 비활성화하십시오.
• IPv6: 사용 가능한 경우 완전히 지원됩니다. TTP는 IPv6 루프백을 동적으로 감지하고 IPv6 트래픽을 Tor를 통해 라우팅합니다. 호스트에 IPv6 루프백 지원이 없거나 --no-ipv6 옵션이 전달되면 TTP는 유출을 방지하기 위해 모든 아웃바운드 IPv6 트래픽을 드롭합니다.
• 출구 IP 변동: Tor 스트림 격리로 인해 서로 다른 연결이 서로 다른 출구 IP를 표시할 수 있습니다.

잔여 위험, 아키텍처 신뢰 경계 및 STRIDE 위협 모델에 대한 전체 분석은 다음을 참조하십시오:

docs/security-assessment.md

개발 및 테스트

TTP는 Makefile을 사용하여 테스트 파이프라인을 자동화하고 표준화합니다. 이를 통해 모든 변경 사항이 커밋되기 전에 단위 및 통합 테스트에 대해 검증됩니다.

"Pre-Push" 규칙

[!IMPORTANT] 코드를 푸시하기 전에 항상 make verify를 실행하십시오. 이 명령이 실패하면 코드는 프로덕션에 사용할 준비가 되지 않은 것입니다.

필수 명령

검증

TTP의 제로 유출 주장은 주장이 아닌 측정된 것입니다. Network Sandbox Engine은 격리된 네트워크 네임스페이스를 구축하고, TTP의 실제 생성된 규칙 세트를 로드하고, 유출이 구성될 트래픽을 생성하고, Scapy 스니퍼로 경계 veth 인터페이스를 감시합니다.

모든 격리 테스트는 두 번 실행됩니다. assert no leaks는 스니퍼가 시작되지 않았을 때, 인터페이스 이름이 잘못되었을 때, 또는 트래픽이 프로세스를 떠나지 않았을 때도 참입니다. 따라서 각 테스트는 먼저 규칙 세트가 플러시된 상태에서 동일한 자극을 실행하고 패킷이 보이는 것을 요구합니다. 그런 다음에야 TTP의 규칙 세트가 이를 중지한다고 주장합니다. 유출을 관찰할 수 없는 하네스는 테스트를 통과하는 대신 실패합니다.

포함 범위: 일반 DNS(UDP 및 TCP), 일반 TCP, 853의 DoT, UDP/443의 QUIC DoH, ICMP, 임의 UDP, IPv6 — 그리고 반대 방향으로, 우회된 UID가 여전히 LAN에 도달할 수 있는지도 포함합니다. 모든 것을 차단하는 방화벽은 처음 일곱 개를 통과하고 여덟 번째에서 실패할 것입니다.

# 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(Zero-leak ruleset verification 작업)에서 실행되며, 릴리스 전 scripts/verify.sh의 단계로도 실행됩니다.

고급: 실제 VM 테스트

Docker 통합 테스트는 빠르고 원자적이지만 커널/systemd의 모든 뉘앙스를 100% 포착하지는 못합니다. 중요한 변경의 경우 실제 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부터 시작하십시오: 버그를 잡았을 검사를 추가하지 않고는 버그를 절대 수정하지 말 것, 그리고 부재를 주장하는 테스트는 먼저 존재를 감지할 수 있음을 증명해야 한다는 것입니다.

이 프로젝트는 여가 시간에 유지 관리됩니다. 스타는 다른 사람들이 찾는 데 도움이 되며, 후원은 프로젝트가 계속 진행되도록 돕습니다.

라이선스

MIT. 자세한 내용은 LICENSE를 참조하십시오.