TransparentTorProxy

Un'utilità CLI per Linux che instrada in modo trasparente tutto il traffico di sistema attraverso la rete Tor utilizzando nftables. Consente una rapida rotazione dell'IP e un facile attivazione/disattivazione delle impostazioni proxy globali per attività legate alla privacy.

Funzionalità • Requisiti • Installazione • Utilizzo • Come funziona • Verifica • Contribuisci

Nessuna configurazione per singola applicazione necessaria - basta sudo ttp start e ogni connessione passa attraverso Tor.

[!CAUTION] TTP è uno strumento progettato per favorire la privacy instradando il traffico attraverso Tor. Tuttavia, nessuno strumento può garantire l'anonimato al 100%. La tua sicurezza dipende anche dal tuo comportamento (ad esempio, usare un browser normale invece del Tor Browser, accedere agli account, ecc.). Usa sempre TTP come parte di una strategia di sicurezza a più livelli.

[!WARNING] Se sei un whistleblower o stai svolgendo attività ad alto rischio, NON usare TTP. Usa invece strumenti ufficialmente verificati e affidabili come TailsOS o direttamente il Tor Browser. Gli autori e i contributori di TTP non si assumono alcuna responsabilità per la tua sicurezza o per le conseguenze dell'uso di questo software.

Perché TTP?

Gli script proxy trasparenti legacy (TorGhost, Anonsurf) sovrascrivono i file di configurazione e costruiscono set di regole iptables che falliscono aperti: quando si rompono, il traffico esce in chiaro. TTP è costruito al contrario - fallisce in modo chiuso e non conserva nulla su disco.

Funzionalità

• Protezione continua dell'integrità - un watchdog governato da una FSM formale (transitions) monitora Tor, le catene nftables e l'overlay DNS tramite un doppio watch inotify che rileva lo scambio del target dei symlink. Ripara una volta, poi applica un killswitch di emergenza.
• Split tunnelling - esenta utenti o gruppi (--bypass-user, --bypass-group) con il matching nativo UID/GID di nftables, oppure esegui un singolo comando fuori da Tor con ttp bypass <cmd> tramite una slice cgroups v2.
• LAN preservata - le sottoreti RFC 1918 e link-local rimangono raggiungibili, così la tua stampante e il NAS continuano a funzionare.
• Dual-stack, o nessuno stack - IPv6 viene instradato attraverso Tor quando il routing loopback è disponibile, e scartato del tutto quando non lo è. Non esiste una terza opzione in cui perde.
• DoT e DoH bloccati - porta 853 rifiutata, resolver DoH pubblici noti rifiutati sulla 443 (TCP e QUIC), e domini canary dei browser avvelenati in torrc.
• Coesiste con il tuo Tor di sistema - esegue il proprio ttp-tor.service volatile su porte non standard, lasciando intatta un'istanza Tor esistente.
• Bridge - obfs4 e snowflake, con modalità BYOD (bring your own daemon).

Requisiti

• Linux con systemd
• Python 3.10+
• nftables (preinstallato sulla maggior parte delle distro moderne)
• Privilegi di root (richiesti per le modifiche al firewall e al DNS)

Installazione

Scegli il metodo più adatto alle tue esigenze. I pacchetti nativi sono fortemente consigliati per stabilità del sistema, sicurezza e disinstallazione pulita.

1. Pacchetti nativi (consigliato)

L'installazione tramite pacchetti nativi garantisce che tutte le dipendenze di sistema (tor, nftables) e le ottimizzazioni a livello kernel (SELinux) siano gestite dal gestore di pacchetti del tuo OS.

Scarica il .deb o .rpm per la versione che desideri dalla ultima release - i pacchetti sono asset di release e non sono versionati nel repository - poi installalo:

• 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: compila dal repository con cd packaging && makepkg -si

Per istruzioni su come verificare l'integrità e l'autenticità degli asset di release, vedi la Guida alla verifica delle release.

2. Installazione manuale dai sorgenti (sviluppatore/universale)

Se sei uno sviluppatore o vuoi installare dal repository:

[!TIP] Perché usare ./install.sh?
A differenza degli installer Python standard, questo script è "intelligente". Sui sistemi basati su Red Hat, rileva se SELinux è in modalità Enforcing e compila dinamicamente un modulo di policy personalizzato (da ttp_tor_policy.te) per consentire a Tor di associarsi alle porte non standard richieste da TTP (9041, 9054). Questa ottimizzazione a livello kernel non può essere eseguita da pip.

3. Metodi di installazione alternativi (fallback)

Per installare TTP tramite gestori di pacchetti specifici per Python (pipx o pip con ambienti virtuali), vedi il Riferimento ai metodi di installazione alternativi.

Utilizzo

TTP è progettato per essere semplice e leggero. Per l'elenco completo dei comandi CLI, delle opzioni, dei codici di uscita e delle specifiche tecniche, consulta il Riferimento alle interfacce esterne.

Avvio rapido

La maggior parte dei comandi che modificano la rete richiede privilegi di root (sudo):

• Avvia il proxy:

  root@kitploit:~

  sudo ttp start
  

• Ferma il proxy:

  root@kitploit:~

  sudo ttp stop
  

• Controlla lo stato della sessione corrente:

  root@kitploit:~

  ttp status
  

• Verifica il routing Tor e la latenza:

  root@kitploit:~

  ttp check
  

• Richiedi un nuovo IP di uscita (ruota i circuiti):

  root@kitploit:~

  sudo ttp refresh
  

Per configurazioni più avanzate e profili di aggiramento, vedi il Riferimento ai profili di sicurezza e utilizzo avanzati o consulta il Riferimento alle interfacce esterne.

Verifica della sessione

Disinstallazione completa

Per rimuovere completamente TTP dal sistema:

Come funziona

TTP instrada in modo trasparente tutto il traffico di rete orchestrando i sottosistemi standard del kernel Linux, le utility di sistema e le interfacce di controllo di Tor:

1. Redirezione atomica del firewall: genera e carica atomicamente un set di regole nftables isolato inet ttp per intercettare il traffico TCP e DNS, reindirizzandolo a Tor mentre previene leak IPv6 e DoT/DoH.
2. Overlay bind-mount DNS: sovrappone /etc/resolv.conf con una configurazione volatile supportata da RAM tramite un bind-mount a livello kernel per garantire che le chiamate DNS siano risolte da Tor.
3. Integrazione con il daemon Tor: configura, esegue e monitora un'istanza Tor isolata tramite servizi systemd volatili su porte non standard per prevenire conflitti di porte.
4. Watchdog di sessione: esegue un monitor attivo in background che verifica l'integrità della configurazione ed esegue un killswitch di emergenza fail-closed in caso di violazione della sicurezza o modifica del sistema.

Per una descrizione dettagliata dei flussi di esecuzione, degli hook di sistema, dei confini di sicurezza e dei componenti modulari, fai riferimento alla:

Guida tecnica all'architettura e al design

Recupero da crash

TTP è progettato per ripristinare sempre la tua rete, anche in casi limite:

Comportamento noto e limitazioni

[!WARNING]

• Tor Browser: le applicazioni che usano un proxy SOCKS5 esplicito creeranno un doppio hop Tor. Usa invece un browser normale mentre TTP è attivo.
• DNS-over-HTTPS (DoH): i browser normali (Firefox, Chrome, Brave, Edge) possono usare DoH, aggirando il DNS di sistema. TTP mitiga DoH tramite una difesa a 3 livelli: (1) tutto il traffico TCP in uscita (incluso DoH) viene reindirizzato alla TransPort di Tor; (2) i comuni domini canary DoH sono mappati a 0.0.0.0 in torrc; (3) i resolver IP DoH pubblici sono bloccati sulla porta TCP/UDP 443 (bloccando DoH HTTP/3 QUIC). Per la massima sicurezza, disabilita DoH / "DNS sicuro" nelle impostazioni del tuo browser.
• IPv6: pienamente supportato quando disponibile. TTP rileva dinamicamente il loopback IPv6 e instrada il traffico IPv6 attraverso Tor. Se l'host non dispone del supporto loopback IPv6 OPPURE se viene passata l'opzione --no-ipv6, TTP scarta tutto il traffico IPv6 in uscita per prevenire leak.
• Variazione dell'IP di uscita: connessioni diverse possono mostrare IP di uscita diversi a causa dell'isolamento degli stream di Tor.

Per una disamina completa dei rischi residui, dei confini di fiducia architetturali e del modello di minaccia STRIDE, vedi:

docs/security-assessment.md

Sviluppo e test

TTP usa un Makefile per automatizzare e standardizzare la pipeline di test. Questo garantisce che ogni modifica sia verificata rispetto a test unitari e di integrazione prima di essere committata.

La regola "Pre-Push"

[!IMPORTANT] Esegui sempre make verify prima di pushare il codice. Se questo comando fallisce, il codice NON è pronto per la produzione.

Comandi essenziali

Verifica

L'affermazione di zero leak di TTP è misurata, non asserita. Il Network Sandbox Engine costruisce un network namespace isolato, vi carica il set di regole reale generato da TTP, genera il traffico di cui consisterebbe un leak e osserva l'interfaccia di confine veth con uno sniffer Scapy.

Ogni test di contenimento viene eseguito due volte. assert no leaks è vero anche quando lo sniffer non è mai partito, quando il nome dell'interfaccia è sbagliato o quando il traffico non ha mai lasciato il processo, quindi ogni test esegue prima lo stesso stimolo con il set di regole svuotato e richiede che il pacchetto venga visto. Solo allora asserisce che il set di regole di TTP lo fermi. Un harness che non riesce a osservare un leak fallisce il test invece di superarlo.

Coperti: DNS semplice (UDP e TCP), TCP ordinario, DoT sulla 853, QUIC DoH su UDP/443, ICMP, UDP arbitrario, IPv6 — più la direzione opposta, che un UID bypassato possa comunque raggiungere la LAN. Un firewall che bloccasse tutto supererebbe i primi sette e fallirebbe l'ottavo.

Questo viene eseguito in CI a ogni push (il job Zero-leak ruleset verification) e come passaggio in scripts/verify.sh prima di una release.

Avanzato: test su VM reali

Sebbene i test di integrazione Docker siano veloci e atomici, non catturano il 100% delle sfumature del kernel/systemd. Per modifiche critiche, è altamente consigliato testare in una VM QEMU reale:

Diagnostica

Se qualcosa va storto, esegui il comando di diagnostica:

Struttura del progetto

Contribuire

I contributi sono benvenuti, e le aree in cui l'aiuto conta di più sono ristrette e specifiche:

1. Networking Linux - nftables, tabelle di routing, network namespace, rilevamento dell'interfaccia VPN.
2. Interni di Tor - configurazione del daemon, Stem, bridge, casi limite del bootstrap.
3. CI/CD - mantenere le suite di test privilegiate veloci e affidabili su GitHub Actions.

Inizia da CONTRIBUTING.md, che documenta le due regole su cui è costruito questo codebase: non correggere mai un bug senza aggiungere il controllo che lo avrebbe catturato, e un test che asserisce un'assenza deve prima dimostrare di poter rilevare una presenza.

Questo progetto è mantenuto nel tempo libero. Una star aiuta gli altri a trovarlo; una sponsorizzazione aiuta a farlo continuare.

Licenza

MIT. Vedi LICENSE per maggiori informazioni.