HALO (GEMMA-by-GOOGLE)

Agente autónomo de pruebas de penetración de IA completamente local: un modelo local de Gemma impulsa un servidor MCP de 29 herramientas a través de reconocimiento, ataque y generación de informes. Sin nube, sin claves API.

GitHub

Prueba este MCPPatrocinado

Documentación

https://github.com/user-attachments/assets/ba467fae-a4c9-4f63-b2e6-3fc30fb023f3

🔐 GEMMA-by-GOOGLE — HALO

Un agente autónomo de pruebas de penetración con IA totalmente local — Gemma 4-12B impulsando un arsenal de 42 herramientas a través de reconocimiento, ataque e informes, expuesto como un servidor estándar de Model Context Protocol (MCP). Sin nube, sin claves de API.

Qué hace · Herramientas · Arquitectura · Stack · Inicio rápido · Registro de cambios · Contribuciones

HALO es un agente de seguridad autónomo que se ejecuta dentro de un entorno Linux impulsado por un LLM local — Gemma 4-12B (sin censura / abliterado) servido a través de LM Studio. Planifica, ejecuta reconocimiento, encadena ataques según lo que encuentra y redacta un informe de pentest profesional por sí solo. Todo se ejecuta localmente: sin nube, sin claves de API, nada sale de tu máquina.

Una palabra inicia un compromiso: engage.

Qué hace

🔍 Reconocimiento autónomo — masscan + nmap para descubrir puertos y servicios abiertos
⚔️ Bucle de ataque autónomo — selecciona y encadena herramientas según lo que encuentra
🌐 Pipeline de reconocimiento web → ataque — enumeración de apex a URL (subdominios, hosts, URLs históricas), descubrimiento de contenido, escaneo de plantillas y XSS, con captura de flags automática en objetivos web estilo CTF
✅ Brechas verificadas, no banners — cada intento lleva un challenge/nonce de un solo uso que el exploit debe repetir desde dentro del shell comprometido; un banner uid=0 simple o un tarpit no pueden falsificarlo, así que una brecha confirmada es real (evidencia derivada de la ejecución, consumo único en la puerta)
🎯 Biblioteca PoC curada — exploits deterministas y auto-evidentes (vsftpd 2.3.4, ingreslock, UnrealIRCd) lanzados a través de una primitiva de entrega en sandbox que devuelve un shell real, no una suposición
🧠 Caché persistente de experiencias negativas — aprende qué falla en todas las sesiones y deja de desperdiciar ciclos en callejones sin salida comprobados
🧩 Inyección adaptativa de habilidades — carga playbooks de ataque relevantes en el prompt según el objetivo actual
📝 Informes HTML automáticos — compila los hallazgos en un informe con marca al salir
🔒 100% local — Gemma 4-12B en LM Studio; nada sale de tu máquina

Arsenal de herramientas

42 herramientas se encuentran detrás del bucle de decisión del agente, todas enrutadas a través de la misma capa de caché de fallos. Se definen una vez en el registro de esquemas TOOLS en halo_tools.py y se sirven a través de ambos transportes (MCP y HTTP).

Reconocimiento y OSINT

Herramienta	Propósito
`run_subfinder`	Enumeración de subdominios
`run_theharvester`	OSINT pasivo — correos, subdominios, hosts
`run_httpx`	Sondeo HTTP y fingerprinting
`run_katana`	Rastreo web
`run_sherlock`	OSINT de nombres de usuario en más de 90 plataformas
`run_shodan`	Consultas de inteligencia de exposición en internet
`run_phoneinfoga`	OSINT de números de teléfono
`run_phonextract`	OSINT / extracción de números de teléfono
`run_ghosttrack`	OSINT para usuario / IP / teléfono
`run_cloudfox`	Enumeración de infraestructura en la nube
`run_wafw00f`	Fingerprinting de WAF / soluciones de seguridad
`run_amass`	Enumeración de subdominios (pasiva por defecto)
`run_dnsx`	Resolución y sondeo DNS
`run_gau`	URLs conocidas de OTX / Wayback / Common Crawl
`run_waybackurls`	URLs históricas de Wayback Machine
`run_gowitness`	Capturas de pantalla web para reconocimiento visual
`run_spiderfoot`	Escaneo OSINT multimódulo sin interfaz
`run_recon_ng`	Framework OSINT recon-ng (no interactivo)

Escaneo

Herramienta	Propósito
`run_masscan`	Descubrimiento rápido de puertos
`run_nmap`	Escaneo profundo de servicios/versiones
`run_nikto`	Escaneo de vulnerabilidades web
`run_nuclei`	Escaneo de vulnerabilidades basado en plantillas
`run_netstat`	Análisis de conexiones de red

Web y fuzzing

Herramienta	Propósito
`run_gobuster`	Fuerza bruta de directorios web
`run_ffuf`	Fuzzing web
`run_feroxbuster`	Descubrimiento recursivo de contenido
`run_dalfox`	Escaneo XSS (reflejado / almacenado / DOM)
`run_curl`	Pruebas de peticiones HTTP
`run_wget`	Recuperación de archivos

Explotación

Herramienta	Propósito
`run_sqlmap`	Pruebas de inyección SQL
`run_searchsploit`	Búsqueda de exploits
`run_metasploit`	Lanzar un módulo de Metasploit elegido contra un objetivo (aprobado por humano)
`run_exploit`	Ejecución en sandbox de scripts PoC personalizados
`run_setoolkit`	Kit de ingeniería social

Credenciales

Herramienta	Propósito
`run_hydra`	Fuerza bruta de credenciales
`run_ncrack`	Descifrado de autenticación de red
`run_medusa`	Fuerza bruta paralela rápida
`run_john`	Descifrado de hashes

Enumeración y sistema

Herramienta	Propósito
`run_enum4linux`	Enumeración SMB / Samba
`run_command`	Ejecución arbitraria de comandos
`read_file`	Lectura de contenido de archivos
`write_file`	Escritura de salida a archivos

Arquitectura

Un único motor de herramientas (halo_tools.py) posee el arsenal y sus esquemas; dos transportes ligeros se sitúan encima, de modo que las herramientas se definen exactamente una vez:

   agent_loop.py ──HTTP─►  tool_server.py ─┐
                                            ├─►  halo_tools.py  ──►  security tools
   MCP clients  ──stdio►  mcp_server.py  ──┘   (42-tool engine +
                                                 schema registry)
     │
     ├─►  agent_cache.py         (persistent negative-experience cache)
     ├─►  skills.py              (adaptive playbook injection)
     └─►  report_generator.py    (auto HTML pentest report on exit)

mcp_server.py — un servidor Model Context Protocol conforme a la especificación (stdio, JSON-RPC 2.0). Apunta cualquier cliente MCP (Claude Desktop, agentes de IDE, inspectores) o un registro MCP hacia él para usar el arsenal de HALO como herramientas estándar.
tool_server.py — el servidor local de herramientas HTTP Flask (puerto 8000) que impulsa el bucle del agente autónomo.

Usar HALO como servidor MCP

// e.g. an MCP client config
{
  "mcpServers": {
    "halo": { "command": "python3", "args": ["/abs/path/to/mcp_server.py"] }
  }
}

Un manifiesto de registro listo para enviar se encuentra en server.json.

Capa multiagente

Los compromisos son coordinados por un conjunto de agentes especialistas que comparten un esquema de mensajes (agent_schema.py):

Agente	Rol
`planner_agent.py`	Convierte un objetivo en un plan ordenado
`orchestrator_agent.py`	Enruta tareas al especialista adecuado
`vuln_discovery_agent.py`	Expone vulnerabilidades candidatas
`attacker_agent.py`	Se ramifica en especialistas por clase de vulnerabilidad (SQLi, fuerza bruta, IDOR, SSRF, XSS, auth)
`validator_agent.py`	Confirma hallazgos contra evidencia real antes de que cuenten
`debugger_agent.py`	Diagnostica ejecuciones fallidas de herramientas y ajusta

Capa de agente soberano

La caché de experiencias negativas registra la huella de cada llamada a herramienta. Una llamada que falla recibe un reintento; si falla dos veces, se incluye en la lista negra, de modo que el agente pasa a una herramienta más práctica para la tarea. Durante un compromiso, el agente estructura su propio aprendizaje por ensayo y error — construyendo contexto, evitando callejones sin salida repetidos y escalando de forma inteligente — en lugar de volver a ejecutar lo que ya ha demostrado que no funciona.

Brechas verificadas, no vibraciones

El problema difícil con un atacante autónomo es saber si realmente entró o simplemente repitió un banner esperanzador. HALO responde a esto con una puerta de desafío-respuesta:

El orquestador genera un nonce por intento, vinculado a ese objetivo y al hash exacto del payload, antes de disparar.
Una brecha solo cuenta si la salida de la herramienta lleva una línea estructurada HALO-EVIDENCE nonce=… level=… que repita ese nonce — que la primitiva de entrega (pocs/_delivery.py) solo puede producir ejecutando código dentro del shell que afirma tener.
El nonce es de consumo único: la puerta (exploitation_core.py:breach_confirmed) rechaza un nonce repetido o nunca generado, de modo que un tarpit, una cadena reflejada o un banner estático uid=0 no pueden falsificar una confirmación.

Los PoC curados en pocs/ son bugs deterministas y auto-evidentes (vsftpd 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1) que pasan esta puerta honestamente — consiguen un shell root real o no reportan nada.

Cómo se construyó

HALO fue construido en solitario, desde cero, en menos de seis meses por un desarrollador e investigador de seguridad autodidacta. El núcleo multiagente se ensambló un especialista a la vez, cada uno verificado contra un objetivo real antes de continuar:

Lenguaje compartido: un esquema de mensajes común (agent_schema.py) para que los agentes puedan comunicarse entre sí
Planificador: convierte un objetivo en un plan ordenado, verificado contra LM Studio en vivo
Orquestador: enruta cada tarea al especialista adecuado
Descubrimiento de vulnerabilidades: expone vulnerabilidades candidatas, probadas contra un objetivo Metasploitable en vivo
Atacante: se ramifica en especialistas de SQLi / fuerza bruta / IDOR / SSRF / XSS / auth
Depurador: diagnostica ejecuciones fallidas de herramientas y ajusta
Validador + informes: los hallazgos se confirman contra evidencia real antes de contar, y luego se compilan en un informe legible para el cliente

A partir de ahí, el arsenal creció a 42 herramientas, un pipeline completo de reconocimiento web → ataque con captura de flags, y confirmación de brechas por desafío-respuesta, mientras la caché de experiencias negativas convirtió el ensayo y error en aprendizaje persistente entre sesiones. El desarrollo activo continúa — se publican nuevas capacidades regularmente; consulta el registro de cambios para ver los hitos publicados.

Stack

Modelo: Gemma 4-12B Instruct Abliterated (GGUF vía LM Studio) — funciona con cualquier modelo local de tu elección
Agente: bucle autónomo en Python con llamadas a herramientas MCP
Transportes de herramientas: un servidor Model Context Protocol (stdio) para clientes MCP, más un servidor de herramientas HTTP Flask en el puerto 8000 para el bucle del agente
SO: Kali Linux (probado bajo UTM en Apple Silicon M1)
Referencia de hardware: MacBook Pro M1, 16 GB RAM

Inicio rápido

Consulta docs/QUICKSTART.md para la configuración completa. En resumen:

git clone https://github.com/XenoCoreGiger31/GEMMA-by-GOOGLE.git
cd GEMMA-by-GOOGLE
python3 -m pip install -r requirements.txt

cp engagement.example.yaml engagement.yaml   # then fill in authorization + scope_targets

python3 tool_server.py      # terminal 1 — HTTP tool server on port 8000
python3 agent_loop.py       # terminal 2 — the agent

>>> engage 203.0.113.3     # full autonomous recon + attack
>>> run nmap on 10.0.0.1    # single-goal query
>>> exit                    # triggers HTML report generation

Nota: los endpoints y rutas usan por defecto una configuración local estándar (LM Studio en localhost:1234, servidor de herramientas HTTP en localhost:8000). Sobrescribe cualquiera de ellos con las variables de entorno HALO_* — consulta la tabla de sobrescrituras de entorno. Algunas rutas predeterminadas de log/caché específicas del autor permanecen en agent_cache.py y tool_server.py; las variables de entorno también las cubren.

agent_loop.py no se iniciará sin engagement.yaml — es la puerta de autorización + alcance por la que pasa cada llamada a herramienta, no una configuración opcional. Consulta el paso 5 del Inicio rápido.

Ejecutar pruebas

Las pruebas unitarias usan el unittest integrado de Python — sin dependencias adicionales:

python3 -m unittest

Contribuciones

Las contribuciones de las comunidades de seguridad, IA y Python son bienvenidas — consulta CONTRIBUTING.md. Dale una estrella al repositorio si te resulta útil, o abre un PR y construyamos algo juntos.

Desarrollado activamente por un desarrollador e investigador de seguridad independiente y autodidacta. Se publican nuevas capacidades regularmente.

Aviso legal y descargo de responsabilidad

Este es un proyecto comunitario de un desarrollador independiente. No está afiliado, respaldado ni patrocinado por Google LLC. "Gemma" es una marca comercial de Google LLC.

⚠️ Advertencia de contenido: El modelo referenciado está fuertemente abliterado y responderá a solicitudes sensibles sin las salvaguardas habituales. Úsalo de forma responsable, solo en entornos apropiados.

🔒 Advertencia legal: Esta herramienta está destinada estrictamente a pruebas de penetración autorizadas e investigación de seguridad en sistemas que posees o para los que tienes permiso escrito explícito para probar. El uso no autorizado es ilegal.

Licencia

Publicado bajo la Licencia MIT.