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, 100 % local — Gemma 4-12B dirige un arsenal de 42 herramientas a través de reconocimiento, ataque y generación de informes, expuesto como un servidor estándar de Model Context Protocol (MCP). Sin nube, sin claves API.

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

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

Una sola palabra inicia una operación: 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 automática de flags 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 de la shell comprometida; ni un simple banner uid=0 ni un tarpit pueden falsificarlo, así que una brecha confirmada es real (evidencia derivada de la ejecución, consumo único en la puerta)

• 🎯 Biblioteca de PoCs curada — exploits deterministas y autoevidentes (vsftpd 2.3.4, ingreslock, UnrealIRCd) lanzados a través de una primitiva de entrega con sandbox que devuelve una shell real, no una suposición

• 🧠 Caché persistente de experiencias negativas — aprende lo que falla en todas las sesiones y deja de perder 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 la marca al salir

• 🔒 100 % local — Gemma 4-12B en LM Studio; nada sale de tu máquina

Related MCP server: Debugg AI MCP

Arsenal de herramientas

42 herramientas se sitúan 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 sola vez en el registro de esquemas TOOLS de halo_tools.py y se sirven a través de ambos transportes (MCP y HTTP).

Reconocimiento y OSINT

Escaneo

Web y fuzzing

Explotación

Credenciales

Enumeración y sistema

Arquitectura

Un único motor de herramientas (halo_tools.py) posee el arsenal y sus esquemas; dos transportes ligeros se sitúan sobre él, 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 a él para usar el arsenal de HALO como herramientas estándar.

• tool_server.py — el servidor local de herramientas HTTP Flask (puerto 8000) que controla 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

Las operaciones son coordinadas por un conjunto de agentes especialistas que pasan un esquema de mensaje compartido (agent_schema.py):

Capa de agente soberano

La caché de experiencias negativas toma la huella de cada llamada a herramienta. Una llamada que falla recibe un reintento; si falla dos veces, se la incluye en la lista negra, por lo que el agente pasa a una herramienta más práctica para el trabajo. A lo largo de una operación, el agente estructura su propio aprendizaje por ensayo y error — creando 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 corazonadas

El problema difícil con un atacante autónomo es saber si realmente entró o solo repitió un banner esperanzador. HALO responde 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 incluye una línea estructurada HALO-EVIDENCE nonce=… level=… que repite ese nonce — algo que la primitiva de entrega (pocs/_delivery.py) solo puede producir ejecutando código dentro de la shell que afirma tener.

• El nonce es de un solo uso: la puerta (exploitation_core.py:breach_confirmed) rechaza un nonce reutilizado o nunca generado, por lo que un tarpit, una cadena reflejada o un banner estático uid=0 no pueden falsificar una confirmación.

Los PoCs curados en pocs/ son bugs deterministas y autoevidentes (vsftpd 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1) que superan esta puerta con honestidad: o consiguen una 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ó especialista a especialista, verificando cada uno contra un objetivo real antes de seguir:

• Lenguaje compartido: un esquema de mensaje común (agent_schema.py) para que los agentes puedan hablarse entre sí

• Planificador: convierte un objetivo en un plan ordenado, verificado contra LM Studio en vivo

• Orquestador: enruta cada tarea al especialista adecuado

• Detección de Vulnerabilidades: saca a la luz 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 con evidencia real antes de que cuenten, y luego se compilan en un informe legible para el cliente

A partir de ahí, el arsenal creció hasta 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 con regularidad; consulta el registro de cambios para ver los hitos publicados.

Stack

• Modelo: Gemma 4-12B Instruct Abliterated (GGUF a través de LM Studio) — funciona con cualquier modelo local que elijas

• 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 en UTM en Apple Silicon M1)

• Referencia de hardware: MacBook Pro M1, 16 GB de 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 las rutas usan por defecto una configuración local estándar (LM Studio en localhost:1234, servidor de herramientas HTTP en localhost:8000). Puedes anular cualquiera de ellos con las variables de entorno HAL_* (consulta la tabla de anulaciones de entorno). Algunas rutas de caché/registro 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 arrancará sin engagement.yaml — es la autorización y el alcance por el que pasa cada llamada a herramienta, no es opcional. Ver el paso 5 de la guía de inicio rápido.

Ejecutando las 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. Si te resulta útil, marca el repositorio con una estrella, o abre un PR para construir algo juntos.

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

Aviso legal y exención

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

⚠️ Aviso de contenido: El modelo referenciado está fuertemente ablacionado y responderá a solicitudes sensibles sin los controles habituales. Úsalo con responsabilidad, solo en entornos adecuados.

🔒 Aviso legal: Esta herramienta está pensada estrictamente para pruebas de penetración autorizadas e investigación de seguridad en sistemas que poseas o para los que tengas autorización explícita por escrito. El uso no autorizado es ilegal.

Licencia

Publicado bajo la Licencia MIT.