HALO (GEMMA-by-GOOGLE)

Agente autônomo de pentest de IA totalmente local — um modelo local Gemma aciona um servidor MCP de 29 ferramentas durante reconhecimento, ataque e relatórios. Sem nuvem, sem chaves de API.

GitHub

Experimente este MCPPatrocinado

Documentação

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

🔐 GEMMA-by-GOOGLE — HALO

Um agente autônomo de teste de penetração com IA, totalmente local — Gemma 4-12B dirigindo um arsenal de 42 ferramentas através de reconhecimento, ataque e relatórios, exposto como um servidor padrão Model Context Protocol (MCP). Sem nuvem, sem chaves de API.

O que faz · Ferramentas · Arquitetura · Stack · Início rápido · Changelog · Contribuindo

O HALO é um agente de segurança autônomo que roda dentro de um ambiente Linux dirigido por um LLM local — Gemma 4-12B (sem censura / abliterado) servido através do LM Studio. Ele planeja, executa reconhecimento, encadeia ataques com base no que encontra e escreve um relatório profissional de pentest por conta própria. Tudo roda localmente: sem nuvem, sem chaves de API, nada sai da sua máquina.

Uma palavra inicia um engajamento: engage.

O que faz

🔍 Reconhecimento autônomo — masscan + nmap para descobrir portas e serviços abertos
⚔️ Loop de ataque autônomo — seleciona e encadeia ferramentas com base no que encontra
🌐 Pipeline de reconhecimento web → ataque — enumeração de apex para URL (subdomínios, hosts, URLs históricas), descoberta de conteúdo, varredura de templates e XSS, com captura de flag automática em alvos web estilo CTF
✅ Brechas verificadas, não banners — cada tentativa carrega um desafio/nonce de uso único que o exploit deve ecoar de dentro do shell invadido; um banner uid=0 simples ou um tarpit não pode forjá-lo, então uma brecha confirmada é uma brecha real (evidência derivada de execução, consumo único no portão)
🎯 Biblioteca de PoCs curada — exploits determinísticos e auto-evidentes (vsftpd 2.3.4, ingreslock, UnrealIRCd) disparados através de uma primitiva de entrega em sandbox que retorna um shell real, não um palpite
🧠 Cache persistente de experiências negativas — aprende o que falha em todas as sessões e para de desperdiçar ciclos em becos sem saída comprovados
🧩 Injeção adaptativa de habilidades — carrega playbooks de ataque relevantes no prompt com base no objetivo atual
📝 Relatórios HTML automáticos — compila descobertas em um relatório com marca na saída
🔒 100% local — Gemma 4-12B no LM Studio; nada sai da sua máquina

Arsenal de Ferramentas

42 ferramentas ficam atrás do loop de decisão do agente, todas roteadas pela mesma camada de cache de falhas. Elas são definidas uma vez no registro de esquema TOOLS em halo_tools.py e servidas por ambos os transportes (MCP e HTTP).

Reconhecimento e OSINT

Ferramenta	Propósito
`run_subfinder`	Enumeração de subdomínios
`run_theharvester`	OSINT passivo — e-mails, subdomínios, hosts
`run_httpx`	Sondagem e fingerprinting HTTP
`run_katana`	Crawling web
`run_sherlock`	OSINT de nomes de usuário em 90+ plataformas
`run_shodan`	Consultas de inteligência de exposição na internet
`run_phoneinfoga`	OSINT de números de telefone
`run_phonextract`	OSINT / extração de números de telefone
`run_ghosttrack`	OSINT para nome de usuário / IP / telefone
`run_cloudfox`	Enumeração de infraestrutura em nuvem
`run_wafw00f`	Fingerprinting de WAF / soluções de segurança
`run_amass`	Enumeração de subdomínios (passiva por padrão)
`run_dnsx`	Resolução e sondagem de DNS
`run_gau`	URLs conhecidas do OTX / Wayback / Common Crawl
`run_waybackurls`	URLs históricas do Wayback Machine
`run_gowitness`	Captura de tela web para reconhecimento visual
`run_spiderfoot`	Varredura OSINT headless multi-módulo
`run_recon_ng`	Framework OSINT recon-ng (não interativo)

Varredura

Ferramenta	Propósito
`run_masscan`	Descoberta rápida de portas
`run_nmap`	Varredura profunda de serviços/versões
`run_nikto`	Varredura de vulnerabilidades web
`run_nuclei`	Varredura de vulnerabilidades baseada em templates
`run_netstat`	Análise de conexões de rede

Web e Fuzzing

Ferramenta	Propósito
`run_gobuster`	Força bruta de diretórios web
`run_ffuf`	Fuzzing web
`run_feroxbuster`	Descoberta recursiva de conteúdo
`run_dalfox`	Varredura de XSS (refletido / armazenado / DOM)
`run_curl`	Teste de requisições HTTP
`run_wget`	Recuperação de arquivos

Exploração

Ferramenta	Propósito
`run_sqlmap`	Teste de injeção de SQL
`run_searchsploit`	Consulta de exploits
`run_metasploit`	Disparar um módulo Metasploit escolhido em um alvo (aprovado por humano)
`run_exploit`	Execução em sandbox de scripts PoC personalizados
`run_setoolkit`	Kit de engenharia social

Credenciais

Ferramenta	Propósito
`run_hydra`	Força bruta de credenciais
`run_ncrack`	Quebra de autenticação de rede
`run_medusa`	Força bruta paralela rápida
`run_john`	Quebra de hashes

Enumeração e Sistema

Ferramenta	Propósito
`run_enum4linux`	Enumeração SMB / Samba
`run_command`	Execução arbitrária de comandos
`read_file`	Leitura de conteúdo de arquivos
`write_file`	Gravação de saída em arquivos

Arquitetura

Um único motor de ferramentas (halo_tools.py) possui o arsenal e seus esquemas; dois transportes finos ficam por cima dele, então as ferramentas são definidas exatamente uma 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 — um servidor Model Context Protocol compatível com a especificação (stdio, JSON-RPC 2.0). Aponte qualquer cliente MCP (Claude Desktop, agentes de IDE, inspetores) ou um registro MCP para ele para usar o arsenal do HALO como ferramentas padrão.
tool_server.py — o servidor local de ferramentas HTTP Flask (porta 8000) que o loop do agente autônomo dirige.

Usar o HALO como servidor MCP

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

Um manifesto de registro pronto para envio está em server.json.

Camada multi-agente

Engajamentos são coordenados por um conjunto de agentes especialistas que passam um esquema de mensagens compartilhado (agent_schema.py):

Agente	Papel
`planner_agent.py`	Transforma um objetivo em um plano ordenado
`orchestrator_agent.py`	Roteia tarefas para o especialista certo
`vuln_discovery_agent.py`	Superfícies de vulnerabilidades candidatas
`attacker_agent.py`	Ramifica em especialistas por classe de vulnerabilidade (SQLi, força bruta, IDOR, SSRF, XSS, auth)
`validator_agent.py`	Confirma descobertas contra evidências reais antes de contarem
`debugger_agent.py`	Diagnostica execuções de ferramentas que falharam e ajusta

Camada de Agente Soberano

O cache de experiências negativas faz fingerprint de cada chamada de ferramenta. Uma chamada que falha recebe uma nova tentativa; falhe duas vezes e ela é colocada na lista negra, então o agente segue para uma ferramenta mais prática para o trabalho. Durante um engajamento, o agente estrutura seu próprio aprendizado por tentativa e erro — construindo contexto, evitando becos sem saída repetidos e escalando de forma inteligente — em vez de reexecutar o que já provou que não funciona.

Brechas verificadas, não vibrações

O problema difícil com um atacante autônomo é saber se ele realmente invadiu ou apenas repetiu um banner esperançoso. O HALO responde a isso com um portão de desafio-resposta:

O orquestrador cria um nonce por tentativa, vinculado àquele alvo e ao hash exato do payload, antes de disparar.
Uma brecha só conta se a saída da ferramenta carregar uma linha estruturada HALO-EVIDENCE nonce=… level=… ecoando aquele nonce — que a primitiva de entrega (pocs/_delivery.py) só pode produzir executando código dentro do shell que ela afirma ter.
O nonce é de consumo único: o portão (exploitation_core.py:breach_confirmed) rejeita um nonce repetido ou nunca criado, então um tarpit, uma string refletida ou um banner estático uid=0 não podem forjar uma confirmação.

Os PoCs curados em pocs/ são bugs determinísticos e auto-evidentes (vsftpd 2.3.4, ingreslock 1524, UnrealIRCd 3.2.8.1) que passam por este portão honestamente — eles conseguem um shell root real ou não relatam nada.

Como foi construído

O HALO foi construído solo, do zero, em menos de seis meses por um desenvolvedor autodidata e pesquisador de segurança. O núcleo multi-agente foi montado um especialista por vez, cada um verificado contra um alvo real antes de seguir:

Linguagem compartilhada: um esquema de mensagens comum (agent_schema.py) para os agentes conversarem entre si
Planejador: transforma um objetivo em um plano ordenado, verificado contra o LM Studio ao vivo
Orquestrador: roteia cada tarefa para o especialista certo
Descoberta de Vulnerabilidades: superfícies de vulnerabilidades candidatas, testadas contra um alvo Metasploitable ao vivo
Atacante: ramifica em especialistas SQLi / força bruta / IDOR / SSRF / XSS / auth
Depurador: diagnostica execuções de ferramentas que falharam e ajusta
Validador + relatórios: descobertas são confirmadas contra evidências reais antes de contarem, depois compiladas em um relatório legível para o cliente

A partir daí o arsenal cresceu para 42 ferramentas, um pipeline completo de reconhecimento web → ataque com captura de flag e confirmação de brecha por desafio-resposta, enquanto o cache de experiências negativas transformou tentativa e erro em aprendizado persistente entre sessões. O desenvolvimento ativo continua — novas capacidades são enviadas regularmente; veja o changelog para os marcos entregues.

Stack

Modelo: Gemma 4-12B Instruct Abliterated (GGUF via LM Studio) — funciona com qualquer modelo local de sua escolha
Agente: loop autônomo em Python com chamadas de ferramentas MCP
Transportes de ferramentas: um servidor Model Context Protocol (stdio) para clientes MCP, além de um servidor de ferramentas HTTP Flask na porta 8000 para o loop do agente
SO: Kali Linux (testado sob UTM no Apple Silicon M1)
Referência de hardware: MacBook Pro M1, 16 GB de RAM

Início rápido

Veja docs/QUICKSTART.md para a configuração completa. Em resumo:

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: endpoints e caminhos padrão para uma configuração local padrão (LM Studio em localhost:1234, servidor de ferramentas HTTP em localhost:8000). Substitua qualquer um deles com as variáveis de ambiente HALO_* — veja a tabela de substituições de ambiente. Alguns padrões de caminhos de log/cache específicos do autor permanecem em agent_cache.py e tool_server.py; as variáveis de ambiente também cobrem esses.

agent_loop.py não iniciará sem engagement.yaml — é o portão de autorização + escopo pelo qual toda chamada de ferramenta passa, não uma configuração opcional. Veja passo 5 do Início rápido.

Executando testes

Os testes de unidade usam o unittest embutido do Python — sem dependências extras:

python3 -m unittest

Contribuindo

Contribuições das comunidades de segurança, IA e Python são bem-vindas — veja CONTRIBUTING.md. Dê uma estrela no repositório se for útil para você, ou abra um PR e vamos construir algo juntos.

Desenvolvido ativamente por um desenvolvedor autodidata e pesquisador de segurança independente. Novas capacidades são enviadas regularmente.

Aviso legal e jurídico

Este é um projeto comunitário de um desenvolvedor independente. Não é afiliado com, endossado por ou patrocinado pela Google LLC. "Gemma" é uma marca registrada da Google LLC.

⚠️ Aviso de conteúdo: O modelo referenciado é fortemente abliterado e responderá a solicitações sensíveis sem as proteções usuais. Use com responsabilidade, apenas em ambientes apropriados.

🔒 Aviso legal: Esta ferramenta é destinada estritamente a testes de penetração autorizados e pesquisa de segurança em sistemas que você possui ou tem permissão explícita por escrito para testar. Uso não autorizado é ilegal.

Licença

Lançado sob a Licença MIT.