toha3ee

Un framework de evaluación de seguridad local y de red escrito en Go. Es una herramienta de investigación y de pruebas de penetración autorizadas que cubre el pipeline de evaluación de red: descubrimiento de hosts y servicios, enumeración, auditoría de credenciales, identificación de vulnerabilidades y explotación autorizada. Sus diez categorías de módulos abarcan reconocimiento, enumeración, OSINT, MITM (envenenamiento ARP/DHCP/DNS/IPv6 e interceptación HTTP/HTTPS en línea), inalámbrico, capa de conmutación (switch), web, autenticación, espionaje y post-explotación, todo controlado desde un REPL interactivo, un asistente guiado o secuencias de comandos de una sola pasada.

MITM es una capacidad dentro de este dominio más amplio: TOHA3EE no se limita a escenarios de tipo man-in-the-middle.

ADVERTENCIA: toha3ee redirige, envenena, descifra e intercepta activamente el tráfico de red. Úsalo solo en redes que te pertenezcan o sobre las que tengas autorización explícita para realizar pruebas. Ejecutar estos módulos contra terceros es ilegal en la mayoría de las jurisdicciones. Lee primero docs/security.md.

Documentación

• Usuario — Primeros pasos · Guía de usuario · Scripting · Configuración · FAQ
• Referencia — Referencia de módulos (los 73 módulos) · Informes
• Desarrollador — Arquitectura · Contribuciones · Registro de cambios
• Gobernanza — Seguridad · Código de conducta · Licencia

Instalación

Los instaladores de una sola línea descargan el binario precompilado para tu plataforma desde la última versión, verifican su checksum SHA-256 y lo añaden a tu PATH. Si todavía no existe un binario precompilado, compilan desde el código fuente.

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

O desde un clon del repositorio:

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

Opciones de instalación (Unix): --prefix <dir> (por defecto: /usr/local/bin como root; si no, ~/.local/bin), --no-path para omitir la edición del rc de tu shell, --from-source para compilar en lugar de descargar, y TOHA3EE_VERSION=<tag> para fijar una versión. Ejecuta con sudo sh ... para instalar en todo el sistema. El instalador de Windows coloca el binario en %LOCALAPPDATA%\Programs\toha3ee\bin y actualiza el PATH de tu usuario; Windows-on-ARM64 ejecuta la compilación x64.

En Linux, el instalador también registra la aplicación en el entorno de escritorio: instala el logotipo en el tema de iconos hicolor y coloca una entrada .desktop junto al prefijo de instalación (p. ej. /usr/local/share o ~/.local/share), de modo que toha3ee aparece en la búsqueda de GNOME con su icono. En Windows copia el .ico y crea un acceso directo en el menú Inicio. El tarball/zip de la versión incluye el icono para que el instalador pueda registrarlo desde el mismo artefacto verificado.

Desinstalación: elimina el binario y la línea de PATH que el instalador añadió al rc de tu shell (o %LOCALAPPDATA%\Programs\toha3ee en Windows).

Compilación

Requiere Go 1.26+ y libpcap.

# Debian/Ubuntu
sudo apt install libpcap-dev

# then
go build ./cmd/toha3ee

Las compilaciones en Linux necesitan los encabezados de libpcap (el respaldo from-source del instalador los comprueba e imprime el comando apt/dnf adecuado si faltan). macOS incluye libpcap con Xcode Command Line Tools.

Inicio 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

La mayoría de los módulos de ataque requieren root (raw sockets, captura de paquetes y reenvío de IP). Ejecuta como root o con CAP_NET_ADMIN/ CAP_NET_RAW cuando sea posible. Añade --no-color para desactivar la salida en color y -v para un registro detallado (verbose).

La herramienta se ejecuta con privilegios de administrador por defecto: en Linux/macOS se re-ejecuta a sí misma bajo sudo y solicita la contraseña de administrador (root) en cada invocación. Pasa --no-sudo (o establece TOHA3EE_NO_SUDO=1) para ejecutarla sin privilegios, p. ej. para un rápido toha3ee --no-sudo version.

Arquitectura

Todo es un módulo. Los módulos se auto-registran en el init() de su paquete y el registro los expone automáticamente; añadir un ataque significa añadir un paquete bajo internal/attacks/ que implemente el contrato attacks.Module (ver internal/attacks/attacks.go):

• Meta() — ID, categoría, riesgo, objetivos, descripción, limitaciones
• Preflight(ctx) — comprueba las condiciones previas antes de ejecutarse
• Run(ctx, opts) — el bucle de ataque (debe respetar ctx.Done)
• Verify(ctx) — informa de lo sucedido
• Cleanup(ctx) — deshace todo, restaura la red

Un ciclo de vida safety central (internal/safety) hace seguimiento de las limpiezas y heartbeats registrados para que cualquier ataque se desmonte incluso ante un panic o SIGINT, y un store compartido mantiene el inventario de hosts, las credenciales capturadas, las sesiones y el registro de eventos que alimenta el generador de informes.

Capas

Módulos

Ejecuta toha3ee modules para ver el catálogo completo y actual. Destacados:

Consola

toha3ee a secas (o toha3ee interactive) abre una consola al estilo bettercap/metasploit: el banner @@@, un prompt toha3eeλ > con acento rojo y autocompletado con tabulador, y un HUD de estado persistente de una línea sobre el prompt que muestra la interfaz, los módulos en ejecución y los recuentos en vivo de hosts/puertos/credenciales/eventos. La salida se agrupa y alinea en una paleta verde/ámbar/blanco — el rojo se usa deliberadamente para el acento del prompt, los errores graves ([x]), la marca del borde del HUD y los módulos de riesgo crítico (el riesgo alto es ámbar). La salida de cada comando está seccionada (─── modules ───), las tablas están alineadas por columnas (los colores se ignoran al calcular la alineación) y los mensajes de los módulos se colorean de forma centralizada, de modo que todos los módulos obtienen glifos de estado coherentes sin trabajo adicional por módulo. La salida cambia automáticamente a texto plano cuando se canaliza (pipe), y el prompt permanece visible y activo mientras se ejecuta cualquier módulo, como 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

Los glifos de estado siguen la convención de bettercap:

El bloque rojo ▮ en el borde izquierdo del HUD marca la franja de estado; el HUD se reimprime después de cada comando para que los recuentos se mantengan actualizados sin teclear más.

Ejemplo de sesión:

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> guarda ajustes por módulo (los IDs de módulo usan puntos, así que la separación se hace en el último punto: set arp.spoof.targets 10.0.0.5); config vuelca todo lo establecido hasta el momento. Las sesiones conservan los datos capturados entre ejecuciones de módulos; report.generate genera un informe de evaluación en Markdown a partir del almacén en memoria.

Scripting

Los archivos .toha3ee impulsan el pipeline completo de reconocimiento → explotación → informe con un lenguaje similar a Python que se lee como inglés. Ejecuta uno con toha3ee script <file>, desde el REPL con script <file>, o ejecuta cualquier archivo .toha3ee con run <file>. toha3ee build <file> (o build <file> en el REPL) valida el archivo e imprime un plan de simulación (dry-run) sin tocar la red. scripts/full-pipeline.toha3ee es un ejemplo funcional de extremo a extremo.

# 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 del lenguaje:

• Sentencias — 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, , , , , , y un a secas detiene el script.

Configuración

La configuración por defecto es toha3ee.json (--config para cambiarla). Cada módulo lee sus ajustes de su propio espacio de nombres, p. ej. report.generate.out, switch.portsteal.victim_mac, http.harvest.pcap.

Sigilo (Stealth)

El modo sigiloso (stealth) está siempre activado, en cada fase, hasta en el paquete individual. Cada módulo que envía paquetes incluye por defecto un perfil aleatorizado y con jitter; no hay nada que activar, y desactivarlo (set <module>.stealth false) no está explícitamente soportado por la intención de diseño.

• Orden — los objetivos de sondeo se barajan (stealth_shuffle) para que los barridos no recorran la subred en el predecible orden ascendente por el que se detecta (fingerprint) a los escáneres.
• Ritmo — los sondeos se envían en ráfagas con jitter por sondeo (stealth_jitter, stealth_burst, stealth_pause) para que el tráfico no sea ni un flujo uniforme y plano ni una única inundación sincronizada.
• ARP — las peticiones who-has usan relleno Ethernet aleatorizado (stealth_pad) en lugar de las tramas con relleno de ceros que emiten la mayoría de los escáneres, y el barrido activo de net.scan se recoge con un único bucle de captura mientras el listener pasivo sigue ingiriendo tráfico.
• Escaneo SYN — cada sondeo varía su puerto de origen (stealth_ports), TTL de IP e identificación (stealth_ttl, stealth_id), número de secuencia TCP y ventana, y ocasionalmente limpia el bit DF, de modo que el flujo de sondeos no se resuelve en una única firma de herramienta.
• Huella (fingerprinting) — el sondeo HTTP rota agentes de usuario realistas de navegador y las capturas de banners tienen jitter, de modo que la identificación de servicios no anuncia el framework.

Los parámetros ajustables se leen por módulo, p. ej. set net.scan.stealth_jitter 5ms, set service.synscan.stealth_burst 128. El prompt del REPL permanece visible y activo mientras se ejecuta cualquier módulo, como bettercap.

Pruebas

go test ./...

El conjunto de pruebas cubre los constructores de tramas (DHCP, NDP, 802.11, STP/CDP/LLDP), el almacén y el renderizador de informes, y una prueba de contrato del registro que fija el catálogo completo de módulos.

La CI (.github/workflows/ci.yml) ejecuta gofmt, go vet, go build y go test -race en Linux, además de pruebas en Windows y macOS en cada push/PR; CodeQL ejecuta análisis estático de seguridad. Las actualizaciones de dependencias las gestiona Dependabot.

Contribuciones

Consulta CONTRIBUTING.md, docs/contributing.md y CODE_OF_CONDUCT.md. Notifica los problemas de seguridad a través de SECURITY.md — no como issues públicos.