toha3ee

Um framework de avaliação de segurança local e de rede escrito em Go. É uma ferramenta de pesquisa e teste de penetração autorizado que cobre o pipeline de avaliação de rede — descoberta de hosts e serviços, enumeração, auditoria de credenciais, identificação de vulnerabilidades e exploração autorizada. Suas dez categorias de módulos abrangem reconhecimento, enumeração, OSINT, MITM (envenenamento de ARP/DHCP/DNS/IPv6 e interceptação HTTP/HTTPS em linha), redes sem fio, camada de switches, web, autenticação, espionagem e pós-exploração — tudo orientado por um REPL interativo, um assistente guiado ou sequências de comandos de uso único.

MITM é uma capacidade dentro desse domínio mais amplo: o TOHA3EE não se limita a cenários de homem-no-meio.

AVISO: o toha3ee redireciona, envenena, descriptografa e intercepta ativamente o tráfego de rede. Use-o somente em redes suas ou para as quais você tenha autorização explícita para testar. Executar esses módulos contra terceiros é ilegal na maioria das jurisdições. Leia docs/security.md primeiro.

Documentação

• Usuário — Começando · Guia do usuário · Scripts · Configuração · FAQ
• Referência — Referência de módulos (todos os 73 módulos) · Relatórios
• Desenvolvedor — Arquitetura · Contribuindo · Changelog
• Governança — Segurança · Código de Conduta · Licença

Instalação

Os instaladores de uma linha buscam o binário pré-compilado para a sua plataforma na versão mais recente, verificam a soma de verificação SHA-256 e o adicionam ao seu PATH. Se ainda não existir um binário pré-compilado, eles compilam a partir do código-fonte.

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

Ou a partir de um checkout:

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

Opções de instalação (Unix): --prefix <dir> (padrão: /usr/local/bin como root, caso contrário ~/.local/bin), --no-path para pular a edição do seu arquivo de shell rc, --from-source para compilar em vez de baixar, e TOHA3EE_VERSION=<tag> para fixar uma versão. Execute com sudo sh ... para instalar em todo o sistema. O instalador do Windows coloca o binário em %LOCALAPPDATA%\Programs\toha3ee\bin e atualiza o PATH do usuário; Windows em ARM64 executa o build x64.

No Linux, o instalador também registra o aplicativo no ambiente de desktop: instala o logotipo no tema de ícones hicolor e adiciona uma entrada .desktop junto ao prefixo de instalação (por exemplo, /usr/local/share ou ~/.local/share), para que o toha3ee apareça na busca do GNOME com seu ícone. No Windows, ele copia o .ico e cria um atalho no Menu Iniciar. O tarball/zip da versão inclui o ícone para que o instalador possa registrá-lo a partir do mesmo artefato verificado.

Desinstalação: exclua o binário e a linha de PATH que o instalador adicionou ao seu shell rc (ou %LOCALAPPDATA%\Programs\toha3ee no Windows).

Compilação

Requer Go 1.26+ e libpcap.

# Debian/Ubuntu
sudo apt install libpcap-dev

# then
go build ./cmd/toha3ee

Os builds Linux precisam dos cabeçalhos libpcap (o fallback de compilação a partir do código-fonte do instalador verifica se eles estão presentes e exibe o comando apt/dnf correto se estiverem faltando). O macOS inclui libpcap com Xcode Command Line Tools.

Início rápido

# 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

A maioria dos módulos de ataque exige root (soquetes raw, captura de pacotes e encaminhamento de IP). Execute como root ou com CAP_NET_ADMIN/CAP_NET_RAW quando possível. Adicione --no-color para desativar a saída colorida e -v para registro detalhado (verbose).

A ferramenta executa com privilégios de administrador por padrão: no Linux/macOS, ela se reexecuta via sudo e solicita a senha de administrador (root) a cada invocação. Use --no-sudo (ou defina TOHA3EE_NO_SUDO=1) para executar sem privilégios, por exemplo, para um rápido toha3ee --no-sudo version.

Arquitetura

Tudo é um módulo. Os módulos se registram no init() de seu pacote e são exibidos automaticamente pelo registro; adicionar um ataque significa adicionar um pacote em internal/attacks/ que implemente o contrato attacks.Module (veja internal/attacks/attacks.go):

• Meta() — ID, categoria, risco, alvos, descrição, limitações
• Preflight(ctx) — verifica as pré-condições antes de executar
• Run(ctx, opts) — o loop de ataque (deve respeitar ctx.Done)
• Verify(ctx) — relata o que aconteceu
• Cleanup(ctx) — desfaz tudo, restaura a rede

Um ciclo de vida central de safety (internal/safety) rastreia cleanups e heartbeats registrados, de modo que todo ataque é encerrado mesmo em caso de pânico ou SIGINT, e um store compartilhado mantém o inventário de hosts, credenciais capturadas, sessões e o log de eventos que alimenta o gerador de relatórios.

Camadas

Módulos

Execute toha3ee modules para ver o catálogo completo e atual. Destaques:

Console

toha3ee puro (ou toha3ee interactive) abre um console no estilo bettercap/metasploit: o banner @@@, um prompt toha3eeλ > com acento vermelho e conclusão por tab, e um HUD de status persistente de uma linha acima do prompt que mostra a interface, os módulos em execução e contagens ao vivo de hosts/portas/credenciais/eventos. A saída é agrupada e alinhada em uma paleta verde/âmbar/branco — o vermelho é usado deliberadamente, para o acento do prompt, erros graves ([x]), a marca de borda do HUD e módulos de risco crítico (risco alto é âmbar). A saída de cada comando é dividida em seções (─── módulos ───), as tabelas são alinhadas por colunas (as cores são ignoradas ao calcular o alinhamento) e as mensagens dos módulos são coloridas centralmente, para que cada módulo receba glifos de status consistentes sem trabalho por módulo. A saída volta automaticamente para texto simples quando é redirecionada (pipe), e o prompt permanece visível e ativo enquanto qualquer módulo estiver em execução, como no 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

Os glifos de status seguem a convenção do bettercap:

O bloco vermelho ▮ na borda esquerda do HUD marca a faixa de status; o HUD é reimpresso após cada comando para que as contagens permaneçam atualizadas sem digitação extra.

Exemplo de sessão:

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> armazena configurações por módulo (os IDs de módulo usam pontos, então a divisão ocorre no último ponto: set arp.spoof.targets 10.0.0.5); config exibe tudo o que foi configurado até o momento. As sessões mantêm os dados capturados entre execuções de módulos; report.generate renderiza um relatório de avaliação em Markdown a partir do armazenamento em memória.

Scripts

Arquivos .toha3ee conduzem todo o pipeline de reconhecimento → exploração → relatório com uma linguagem semelhante a Python que parece inglês. Execute um com toha3ee script <arquivo>, no REPL com script <arquivo>, ou execute qualquer arquivo .toha3ee com run <arquivo>. toha3ee build <arquivo> (ou build <arquivo> no REPL) valida o arquivo e imprime um plano de simulação (dry-run) sem tocar na rede. scripts/full-pipeline.toha3ee é um exemplo funcional de ponta a ponta.

# 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

Notas da linguagem:

• Instruções — set, get, on/start/run, off/stop, wait for <módulo> [max <segundos>], sleep <segundos>, echo/say/print, show <módulo>, report <arquivo>, exec <comando>, , , , , , , e um simples interrompe o script.

Configuração

A configuração usa por padrão o arquivo toha3ee.json (--config para substituir). As configurações por módulo são lidas por cada módulo em seu próprio namespace, por exemplo, report.generate.out, switch.portsteal.victim_mac, http.harvest.pcap.

Furtividade

A furtividade está sempre ativa, em todas as fases, até o nível do pacote individual. Todo módulo que envia pacotes vem com um perfil aleatório e com jitter por padrão; não há nada para ativar, e desativá-la (set <module>.stealth false) é explicitamente não suportado pela intenção do projeto.

• Ordenação — os alvos de sondagem são embaralhados (stealth_shuffle) para que as varreduras não percorram a sub-rede na ordem crescente previsível pela qual os scanners são identificados.
• Ritmo — as sondas são enviadas em rajadas com jitter por sonda (stealth_jitter, stealth_burst, stealth_pause) para que o tráfego não seja nem um fluxo uniforme contínuo nem uma inundação sincronizada única.
• ARP — as solicitações who-has usam preenchimento Ethernet aleatório (stealth_pad) em vez dos quadros preenchidos com zeros que a maioria dos scanners emite, e a varredura ativa do net.scan é coletada por um único loop de captura enquanto o ouvinte passivo continua ingerindo tráfego.
• Varredura SYN — cada sonda varia sua porta de origem (stealth_ports), TTL e identificação de IP (stealth_ttl, stealth_id), número de sequência e janela TCP e, ocasionalmente, limpa o bit DF, para que o fluxo de sondas não seja identificado como uma assinatura de ferramenta única.
• Fingerprinting — a sondagem HTTP alterna user agents realistas de navegadores e as coletas de banner têm jitter, para que a identificação de serviços não revele o framework.

Os parâmetros ajustáveis são lidos por módulo, por exemplo, set net.scan.stealth_jitter 5ms, set service.synscan.stealth_burst 128. O prompt do REPL permanece visível e ativo enquanto qualquer módulo estiver em execução, como no bettercap.

Testes

go test ./...

O conjunto de testes cobre os criadores de quadros (DHCP, NDP, 802.11, STP/CDP/LLDP), o armazenamento e o renderizador de relatórios, além de um teste de contrato do registro que fixa o catálogo completo de módulos.

O CI (.github/workflows/ci.yml) executa gofmt, go vet, go build e go test -race no Linux, além de testes no Windows e macOS para cada push/PR; o CodeQL executa análise estática de segurança. As atualizações de dependências são tratadas pelo Dependabot.

Contribuindo

Consulte CONTRIBUTING.md, docs/contributing.md e CODE_OF_CONDUCT.md. Relate problemas de segurança por meio de SECURITY.md — não como issues públicas.