toha3ee

Un framework di valutazione della sicurezza locale e di rete scritto in Go. È uno strumento di ricerca e di penetration testing autorizzato che copre l'intera pipeline di valutazione della rete: scoperta di host e servizi, enumerazione, audit delle credenziali, identificazione delle vulnerabilità ed exploitation autorizzata. Le sue dieci categorie di moduli spaziano da ricognizione, enumerazione, OSINT, MITM (ARP/DHCP/DNS/IPv6 poisoning e intercettazione HTTP/HTTPS in-line), wireless, livello switch, web, auth, spionaggio e post-exploitation — il tutto guidato da una REPL interattiva, da una procedura guidata o da sequenze di comandi one-shot.

MITM è una delle capacità di questo dominio più ampio: TOHA3EE non è limitato a scenari man-in-the-middle.

ATTENZIONE: toha3ee reindirizza, avvelena, decifra e intercetta attivamente il traffico di rete. Usalo solo su reti di tua proprietà o su cui sei esplicitamente autorizzato a testare. Eseguire questi moduli contro terze parti è illegale nella maggior parte delle giurisdizioni. Leggi prima docs/security.md.

Documentazione

• Utente — Per iniziare · Guida utente · Scripting · Configurazione · FAQ
• Riferimento — Riferimento moduli (tutti i 73 moduli) · Reportistica
• Sviluppatore — Architettura · Contribuire · Changelog
• Governance — Sicurezza · Codice di condotta · Licenza

Installazione

Gli installer one-liner scaricano il binario precompilato per la tua piattaforma dall'ultima release, ne verificano il checksum SHA-256 e lo aggiungono al tuo PATH. Se non esiste ancora un binario precompilato, lo compilano dai sorgenti.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/qyvora/qyvora-toha3ee/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/qyvora/qyvora-toha3ee/main/scripts/install.ps1 | iex

Oppure da una copia del repository:

make install   # installs ~/.local/bin/toha3ee and adds it to PATH

Opzioni di installazione (Unix): --prefix <dir> (default: /usr/local/bin come root, altrimenti ~/.local/bin), --no-path per saltare la modifica del tuo shell rc, --from-source per compilare invece di scaricare, e TOHA3EE_VERSION=<tag> per fissare una release. Esegui con sudo sh ... per installare a livello di sistema. L'installer Windows colloca il binario in %LOCALAPPDATA%\Programs\toha3ee\bin e aggiorna il PATH utente; Windows-on-ARM64 esegue la build x64.

Su Linux l'installer registra anche l'applicazione con l'ambiente desktop: installa il logo nel tema icone hicolor e inserisce una voce .desktop accanto al prefisso di installazione (es. /usr/local/share o ~/.local/share), così toha3ee compare nella ricerca di GNOME con la sua icona. Su Windows copia il file .ico e crea un collegamento nel menu Start. L'archivio tarball/zip della release include l'icona, così l'installer può registrarla dallo stesso artefatto verificato.

Disinstallazione: elimina il binario e la riga nel PATH che l'installer ha aggiunto al tuo shell rc (o %LOCALAPPDATA%\Programs\toha3ee su Windows).

Build

Richiede Go 1.26+ e libpcap.

# Debian/Ubuntu
sudo apt install libpcap-dev

# then
go build ./cmd/toha3ee

Le build Linux richiedono gli header libpcap (il fallback da sorgente dell'installer li controlla e stampa il comando apt/dnf corretto se mancano). macOS include libpcap con gli Xcode Command Line Tools.

Avvio rapido

# Interactive console (bare command drops straight in)
sudo ./toha3ee --iface eth0

# Interactive console (explicit subcommand)
sudo ./toha3ee interactive --iface eth0

# Guided wizard
sudo ./toha3ee wizard --iface eth0

# One-shot: scan the subnet, then show what was found
sudo ./toha3ee --eval "net.scan; net.show" --iface eth0

# Non-interactive caplet script
sudo ./toha3ee run --iface eth0 caplets/basic.cap

# Dry-run a .toha3ee script (validates it, prints the plan, sends no packets)
./toha3ee --no-sudo build scripts/full-pipeline.toha3ee

# Execute a .toha3ee script non-interactively
sudo ./toha3ee script --iface eth0 scripts/full-pipeline.toha3ee

La maggior parte dei moduli di attacco richiede i privilegi di root (socket raw, cattura pacchetti e IP forwarding). Esegui come root o con CAP_NET_ADMIN/CAP_NET_RAW dove possibile. Aggiungi --no-color per disabilitare l'output colorato, -v per un logging verboso.

Lo strumento viene eseguito con privilegi di amministratore per impostazione predefinita: su Linux/macOS si riesegue sotto sudo e richiede la password di amministratore (root) a ogni invocazione. Passa --no-sudo (o imposta TOHA3EE_NO_SUDO=1) per eseguirlo senza privilegi, ad esempio per un rapido toha3ee --no-sudo version.

Architettura

Tutto è un modulo. I moduli si auto-registrano nel loro package init() e vengono esposti automaticamente dal registro; aggiungere un attacco significa aggiungere un package sotto internal/attacks/ che implementa il contratto attacks.Module (vedi internal/attacks/attacks.go):

• Meta() — ID, categoria, rischio, target, descrizione, limitazioni
• Preflight(ctx) — verifica i prerequisiti prima dell'esecuzione
• Run(ctx, opts) — il ciclo dell'attacco (deve rispettare ctx.Done)
• Verify(ctx) — riporta cosa è accaduto
• Cleanup(ctx) — annulla tutto, ripristina la rete

Un ciclo di vita centrale safety (internal/safety) tiene traccia delle cleanup registrate e degli heartbeat, così ogni attacco viene smantellato anche in caso di panic o SIGINT, e uno store condiviso mantiene l'inventario degli host, le credenziali catturate, le sessioni e il log degli eventi che alimenta il generatore di report.

Livelli

Moduli

Esegui toha3ee modules per il catalogo completo e aggiornato. In evidenza:

Console

Un toha3ee senza argomenti (o toha3ee interactive) apre una console in stile bettercap/metasploit: il banner @@@, un prompt toha3eeλ > con accento rosso e completamento tramite Tab, e una HUD di stato persistente su una riga sopra il prompt che mostra l'interfaccia, i moduli in esecuzione e i conteggi live di host/porte/credenziali/eventi. L'output è raggruppato e allineato in una palette verde/ambra/bianco — il rosso è usato deliberatamente per l'accento del prompt, gli errori gravi ([x]), il bordo dell'HUD e i moduli a rischio critico (il rischio alto è ambra). L'output di ogni comando è suddiviso in sezioni (─── modules ───), le tabelle sono allineate per colonne (i colori vengono ignorati nel calcolo dell'allineamento) e i messaggi dei moduli sono colorizzati centralmente, così ogni modulo riceve glifi di stato coerenti senza lavoro aggiuntivo per modulo. L'output passa automaticamente a testo semplice quando viene reindirizzato, e il prompt rimane visibile e attivo mentre qualsiasi modulo è in esecuzione, come bettercap.

$ sudo ./toha3ee --iface eth0
@@@@@@@@
    @@@@@@@@@@@@@
    @@@@@@@@     @@@@@@@
  @@@@@@@@           @@@@@@@@
  @@@@@@@@                 @@@@@@@@
 @@@@@@@         @               @@@@@@@
 @@@@@@@@        @@@@@@@@@              @@@@@@@
 @@@@@@@@         @@@   @                     @@@@@@@
  @@@@@@@            @@       @@@@@@@@@@              @@@@@@@
  @@@@@@    @@        @     @@@@@@@@@@@@@@@@@@             @@@@@@
  @@@        @@@   @@@@@@@  @@@@@@@@@@@@@@@@@@@@@@            @@@
  @@@         @@@@@   @    @@@@@@@@@@@@@@@@@@@@@@@            @@@
  @@@          @@@@@@  @   @@@@@@@@@@@@@@@@@@ @@@             @@@
  @@@          @@@@@@   @ @@@@@@@@@@@@@@@@@   @@@             @@@
  @@@           @@@@@@    @@@@@@@@@@@@@@@@@@@@@@              @@@
  @@@              @@@@@  @@@@@@@@@@@@@@@    @@@              @@@
  @@@               @@@@@  @@@@@@@@@@@@@@   @@@               @@@
  @@@                 @@@    @@@@@@@@@@@@@ @@@@               @@@
  @@@               @@  @@@@  @@@@@   @@@@@@@@@               @@@
  @@@            @@@@@@@@@@@@@  @@@@@@    @@@                 @@@
  @@@        @@@@@@@@@@@@@@@@@@@  @@@@@@@   @@@               @@@
  @@@       @@@@@@@@@@@@@@@@@@@@@@@     @@@ @@@@@@            @@@
  @@@      @@@@@@@@@@@@@@@@@@@@@@   @@@   @@@@@@@@@@          @@@
  @@@      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@   @@@@@@@@@          @@@
  @@@     @@@@@@@@@@@@@@@@@@   @@@@@@@@@@@@ @@@@@@@@@         @@@
  @@@    @@@@@@@@@@@@@@@    @@@@@@@@@@@@@  @@@@@@@@@@@        @@@
  @@@@@    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  @@@@@@@@@@@    @@@@@
   @@@@@@@    @@@@@@@@@@@@@@@@@@@@@@@@  @@@@  @@@@@@@   @@@@@@@@
     @@@@@@    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@  @@   @@@@@@@
      @@@@@@@   @@@@@@@@@@@@@@@@@@@@@@@@@@@   @@@@@@@
       @@@@@@@    @@@@@@@@@@@@@@@@@@@    @@@@@@@
         @@@@@@@    @@@@@@@@@@@@@    @@@@@@@
           @@@@@@@    @@@@@@@    @@@@@@
               @@@@@@        @@@@@@@
                 @@@@@@@@ @@@@@@@
                     @@@@@@@@
                        @@@

local & network security assessment framework
  [>] iface wlan0 (10.135.199.31, 8c:c8:4b:30:bf:91)
  [>] v 0.1.0
type 'help' for commands, 'modules' for the catalogue, 'quit' to exit

[*] session ready. type 'help' for commands.
toha3eeλ> help

I glifi di stato seguono la convenzione di bettercap:

Il blocco rosso ▮ sul bordo sinistro dell'HUD segna la striscia di stato; l'HUD viene ristampato dopo ogni comando, così i conteggi restano aggiornati senza digitare altro.

Esempio di sessione:

toha3eeλ> modules recon        # module catalogue filtered by category
toha3eeλ> on net.scan          # run a module (preflight checks shown first)
toha3eeλ> net.show             # discovered hosts
toha3eeλ> net.profile          # profile + ranked attack vectors
toha3eeλ> help                 # grouped command reference
toha3eeλ> quit

set <module.key> <value> memorizza le impostazioni per-modulo (gli ID dei moduli sono separati da punti, quindi la suddivisione avviene sull'ultimo punto: set arp.spoof.targets 10.0.0.5); config mostra tutto ciò che è stato impostato finora. Le sessioni conservano i dati catturati tra le esecuzioni dei moduli; report.generate genera una valutazione Markdown dallo store in memoria.

Scripting

I file .toha3ee guidano l'intera pipeline ricognizione → exploit → report con un linguaggio simile a Python che si legge come l'inglese. Eseguine uno con toha3ee script <file>, dalla REPL con script <file>, oppure esegui qualsiasi file .toha3ee con run <file>. toha3ee build <file> (o build <file> nella REPL) valida il file e stampa un piano di dry-run senza toccare la rete. scripts/full-pipeline.toha3ee è un esempio end-to-end funzionante.

# comment (or //)
set net.scan.targets -> "192.168.8.0/24"     # configure a module
on net.scan                                   # start a module (run/start)
wait for net.scan                             # block until it finishes
_hosts -> [$(net.hosts)]                      # capture a list (or =, >>)
echo -> "found $(_hosts.size) hosts"          # print (say/print)

if $(hosts.count) > 1                         # conditions
    on arp.spoof targets "192.168.8.0/24"
    sleep -> 30
    off arp.spoof
end

for each _h in $(_hosts)                      # loops
    repeat 3 times
        exec -> net.show                      # run any REPL command once
        break
    end
end

get net.scan.timeout -> _t                    # read a config value
report -> "assessment.md"                     # write the session report

Note sul linguaggio:

• Istruzioni — set, get, on/start/run, off/stop, wait for <module> [max <secs>], sleep <secs>, echo/say/print, show <module>, report <file>, exec <command>, if/else/end, , , , , , e uno da solo ferma lo script.

Configurazione

La configurazione punta di default a toha3ee.json (--config per sovrascriverla). Le impostazioni per-modulo vengono lette da ciascun modulo nel proprio namespace, es. report.generate.out, switch.portsteal.victim_mac, http.harvest.pcap.

Stealth

La stealth è sempre attiva, in ogni fase, fino al singolo pacchetto. Ogni modulo che invia pacchetti include per impostazione predefinita un profilo randomizzato e con jitter; non c'è nulla da abilitare, e disabilitarla (set <module>.stealth false) è esplicitamente non supportato dall'intento progettuale.

• Ordinamento — i target dei probe vengono mescolati (stealth_shuffle) così le scansioni non attraversano la subnet nel prevedibile ordine crescente in base al quale gli scanner vengono identificati.
• Cadenza — i probe vengono inviati a raffiche con jitter per-probe (stealth_jitter, stealth_burst, stealth_pause), così il traffico non è né un flusso uniforme piatto né una singola inondazione sincronizzata.
• ARP — le richieste who-has usano padding Ethernet randomizzato (stealth_pad) invece dei frame con padding a zero emessi dalla maggior parte degli scanner, e la scansione attiva net.scan viene raccolta da un unico loop di cattura mentre l'ascoltatore passivo continua a ingerire traffico.
• Scansione SYN — ogni probe varia la propria porta sorgente (stealth_ports), TTL e identificazione IP (stealth_ttl, stealth_id), numero di sequenza TCP e window, e occasionalmente azzera il bit DF, così il flusso di probe non si riduce a una singola firma di strumento.
• Fingerprinting — i probe HTTP ruotano user agent di browser realistici e i banner grab sono soggetti a jitter, così l'identificazione dei servizi non rivela il framework.

I parametri regolabili vengono letti per modulo, es. set net.scan.stealth_jitter 5ms, set service.synscan.stealth_burst 128. Il prompt della REPL rimane visibile e attivo mentre qualsiasi modulo è in esecuzione, come bettercap.

Test

go test ./...

La suite copre i costruttori di frame (DHCP, NDP, 802.11, STP/CDP/LLDP), lo store e il renderer dei report, e un test di contratto del registro che fissa l'intero catalogo dei moduli.

La CI (.github/workflows/ci.yml) esegue gofmt, go vet, go build e go test -race su Linux, oltre ai test su Windows e macOS per ogni push/PR; CodeQL esegue l'analisi statica di sicurezza. Gli aggiornamenti delle dipendenze sono gestiti da Dependabot.

Contribuire

Vedi CONTRIBUTING.md, docs/contributing.md e CODE_OF_CONDUCT.md. Segnala i problemi di sicurezza tramite SECURITY.md — non come issue pubbliche.