Assistente de red team com IA local no seu telefone
# Nightcrawler
Um agente autônomo de teste de penetração que roda inteiramente em um smartphone. Coloque o telefone em uma rede, afaste-se, e ele descobre hosts, mapeia serviços, encontra vulnerabilidades e gera um relatório de pentest — tudo sem conectividade com a nuvem.
```
░█▄░█ █ █▀▀ █░█ ▀█▀ █▀▀ █▀█ ▄▀█ █░█░█ █░░ █▀▀ █▀█
░█░▀█ █ █▄█ █▀█ ░█░ █▄▄ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ██▄ █▀▄ v0.1.0
AUTONOMOUS MOBILE PENTEST AGENT
OnePlus 8 · NetHunter · LFM2.5-1.2B · OpenCL GPU
```
## O que é isso?
**Teste de penetração** (pentest) é a prática de testar a segurança de uma rede de computadores simulando um ataque — com a permissão explícita do proprietário da rede. Pentesters profissionais são contratados para encontrar vulnerabilidades *antes* que atacantes reais o façam.
O Nightcrawler automatiza esse processo em um telefone. Ele usa um pequeno modelo de IA (LFM2.5-1.2B-Instruct-Heretic, 1,2 bilhão de parâmetros) rodando localmente na GPU do telefone para decidir o que fazer em seguida — qual host sondar, qual ferramenta usar, o que procurar. Nenhuma conexão com a internet ou API em nuvem é necessária.
## Demonstração
▶️ **[Assista ao Nightcrawler em ação no Instagram](https://www.instagram.com/p/DYNXFvVN0c_/)**
### Como funciona
1. **Invasão de WiFi** (opcional) — Se implantado sem WiFi, ele pode quebrar redes WPA2 autonomamente usando um adaptador WiFi USB externo
2. **Reconhecimento** — Descobre dispositivos na rede usando varreduras furtivas
3. **Enumeração** — Sonda serviços descobertos (servidores web, compartilhamentos de arquivos, SSH, DNS, etc.)
4. **Exploração** — Testa vulnerabilidades conhecidas e credenciais padrão
5. **Relatório** — Gera um relatório de pentest estruturado com descobertas e recomendações de remediação
O agente opera como um pentester humano paciente — ele rotaciona entre hosts, faz uma pequena ação por turno e constrói conhecimento gradualmente ao longo de horas. Isso o torna muito mais difícil de detectar do que scanners de vulnerabilidade tradicionais que atacam todos os hosts de uma vez.
### Conceitos-chave
| Termo | O que significa |
|------|--------------|
| **Drop box** | Um dispositivo deixado em uma rede alvo para realizar testes autonomamente |
| **Escopo** | O conjunto de redes/hosts que você está autorizado a testar |
| **Regras de Engajamento (ROE)** | Um documento legal especificando o que você tem permissão para fazer |
| **Furtividade** | Técnicas para evitar detecção por monitoramento de rede (IDS/IPS) |
| **MCP** | Model Context Protocol — uma interface padrão para uso de ferramentas por IA |
| **C2** | Command and Control — o painel web para monitorar e direcionar o agente |
## Arquitetura
```
┌──────────────────────────────────────────────────────────┐
│ PHONE (OnePlus 8) │
│ │
│ ┌─────────────┐ ┌──────────────────┐ │
│ │ LFM2.5 │ │ Agent Loop │ │
│ │ 1.2B model │◄───►│ (main.py) │ │
│ │ on GPU │ │ Decides what │ │
│ │ (:8080) │ │ to do next │ │
│ └─────────────┘ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Scope Proxy │ ← Safety layer │
│ │ Validates every │ Blocks out- │
│ │ command before │ of-scope │
│ │ execution │ actions │
│ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Kali MCP Server │ ← Runs the │
│ │ nmap, curl, │ actual │
│ │ smbclient, ... │ commands │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Web Dashboard │ │ SQLite DB │ │
│ │ (:8888) │ │ Hosts, vulns, │ │
│ │ Monitor & steer │ │ creds, commands │ │
│ └──────────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
Para o design completo do sistema, consulte [docs/ARCHITECTURE.md](https://github.com/garagehq/nightcrawler/blob/main/docs/ARCHITECTURE.md).
## Recursos
- **Totalmente autônomo** — sem humano no ciclo durante a operação
- **Inferência 100% local** — a IA roda na GPU do telefone, sem necessidade de nuvem
- **Escopo imposto** — defesa em duas camadas impede ações fora do escopo
- **Furtividade em primeiro lugar** — taxas de varredura lentas, rotação de hosts, tráfego de cobertura, apenas nmap -T2
- **27 playbooks de exploração** — cadeias de ataque em várias etapas que executam automaticamente
- **Banco de dados CVE com 24.956 entradas** — correspondência de vulnerabilidades ciente de versões
- **Painel web** — monitoramento em tempo real, gerenciamento de hosts, controles C2
- **Modo de invasão WiFi** — quebra autônoma de WPA2 com adaptador USB (inspirado no Pwnagotchi)
- **Descoberta passiva** — captura em segundo plano de broadcasts mDNS/NBNS/DHCP/ARP
- **Multi-rede** — dados isolados por rede, sobrevive a mudanças de DHCP via hosts chaveados por MAC
- **Autocura** — detecção de lixo, redefinição de contexto, watchdogs, detecção de travamento
- **Captura de treinamento** — registra interações bem-sucedidas para futuro ajuste fino do modelo
- **Geração de relatórios** — relatório de pentest baixável com vulnerabilidades, cadeias de exploração, remediação
Consulte [docs/FEATURES.md](https://github.com/garagehq/nightcrawler/blob/main/docs/FEATURES.md) para a referência completa de recursos.
## Hardware
### Necessário
- **Telefone Android** com [Kali NetHunter](https://www.kali.org/docs/nethunter/) (testado no OnePlus 8, Snapdragon 865)
- **Acesso root** via [Magisk](https://github.com/topjohnwu/Magisk)
- **12GB+ de RAM** (o modelo usa ~1,3GB, o Android usa ~4GB, o restante para ferramentas)
### Opcional
- **Adaptador WiFi USB** para modo de invasão WiFi offline (Ralink RT3572 recomendado)
- **Kernel personalizado** com MAC80211 para modo monitor ([guia de compilação](https://github.com/garagehq/nightcrawler/blob/main/docs/KERNEL_BUILD_PROMPT.md))
- **NVIDIA AGX** para descarregar para um modelo maior via Tailscale
### Desempenho da GPU
Toda a inferência via OpenCL na GPU Adreno 650:
| Modelo | Quantização | Velocidade de Prompt | Velocidade de Geração |
|-------|-------------|-------------|-----------------|
| **LFM2.5-1.2B-Instruct-Heretic** (produção) | Q8_0 | 115 tok/s | 13 tok/s |
| Qwen3.5-0.8B | Q8_0 | 30,5 tok/s | 6,3 tok/s |
| Qwen3.5-4B | Q4_0 | 10,1 tok/s | 2,0 tok/s |
> **Nota:** O Android limita a GPU quando alimentado por bateria (desaceleração de 6x). O Nightcrawler inclui um daemon de governança de GPU que força o desempenho máximo e limita automaticamente a ≤15% de bateria.
## Início Rápido
```bash
# 1. Instalação (dentro do chroot do Kali NetHunter)
bash INSTALL.sh
# 2. Aguarde o llama-server iniciar (~5 min após o boot)
curl -s http://127.0.0.1:8080/health # Deve retornar {"status":"ok"}
# 3. Inicie todos os serviços
bash scripts/run-36h.sh
# 4. Abra o painel web (de qualquer dispositivo na sua rede Tailscale)
# https://<seu-hostname-tailscale>:8888
```
### Execução de Teste (nenhum comando real é executado)
```bash
NC_DRY_RUN=1 python3 main.py
```
Isso usa um servidor Kali simulado para que você possa testar o loop do agente sem executar comandos reais de rede.
### Início Manual (se não estiver usando o lançador tmux)
```bash
kali-server-mcp --port 5000 &
python3 scope_proxy.py --config config.yaml --port 8800 --upstream http://127.0.0.1:5000 &
bash scripts/webui-daemon.sh start
python3 main.py &
```
## Configuração
Edite `config.yaml` antes da implantação:
```yaml
mission:
id: "CLIENT-YYYY-XXX" # Seu ID de engajamento
scope:
networks: ["auto"] # "auto" = detectar a partir de wlan0 na inicialização
excluded_hosts: ["auto"] # "auto" = gateway + IP próprio
excluded_ports: [502, 503] # Portas SCADA/ICS que nunca devem ser tocadas
authorization: "ROE-YYYY-XXX.pdf"
max_runtime_hours: 0 # 0 = sem limite
model:
local:
ctx_size: 8192
port: 8080
```
**Detecção dinâmica de escopo** significa zero mudanças de configuração ao mover entre redes — o agente lê a sub-rede atual de `wlan0` na inicialização.
## Estrutura do Projeto
```
nightcrawler/
├── main.py # Ponto de entrada
├── config.yaml # Escopo da missão + configuração do modelo
├── scope_proxy.py # Proxy de imposição de escopo
├── INSTALL.sh # Instalador
│
├── agent/ # Lógica central do agente
│ ├── loop.py # Loop de decisão + recuperação de erros
│ ├── planner.py # Máquina de estados de fase (recon → exploit)
│ ├── llm_client.py # Cliente de API LLM (llama.cpp / remoto)
│ ├── db.py # Backend SQLite (hosts, vulns, creds)
│ ├── host_memory.py # Observações por host + auto-tagging
│ ├── cve_db.py # Banco de dados CVE com 24.956 entradas
│ ├── attack_planner.py # Diretrizes estratégicas para a fase de exploração
│ ├── output_parser.py # Extrai dados estruturados da saída das ferramentas
│ ├── offline_manager.py # Máquina de estados do pipeline de invasão WiFi
│ ├── net_detect.py # Auto-detecção de rede a partir de wlan0
│ ├── cover_traffic.py # Mistura furtiva com tráfego web realista
│ ├── passive_capture.py # tcpdump em segundo plano para tráfego de broadcast
│ └── ...
│
├── proxy/ # Componentes de imposição de escopo
│ ├── scope.py # Validação de IP/porta/host
│ ├── rate_limiter.py # Limitação de taxa de comandos + jitter
│ └── command_filter.py # Lista de bloqueio de comandos destrutivos
│
├── webui/ # Painel web (Flask)
│ ├── server.py # API + middleware furtivo
│ └── templates/index.html # UI do painel
│
├── data/ # Arquivos de dados estáticos
│ ├── cve_exploits.json # Mapeamentos CVE→comando de exploração
│ └── playbooks.json # 27 playbooks de ataque em várias etapas
│
├── prompts/ # Modelos de prompt LLM (recarregáveis a quente)
├── scripts/ # Scripts operacionais (iniciar, parar, watchdogs)
├── tests/ # Suítes de teste (API, UI, modo offline)
├── kernels/ # Módulos de driver WiFi + documentação do kernel
├── simulation/ # Servidor simulado para execução de teste
├── docs/ # Arquitetura, configuração de GPU, recursos
├── logs/ # Dados de execução (ignorados pelo git)
└── models/ # Arquivos de modelo (ignorados pelo git)
```
## Como o Agente Pensa
O agente usa um loop simples, mas eficaz:
1. **Escolher um alvo** — seleção aleatória ponderada (70% hosts com portas conhecidas, 30% nova descoberta)
2. **Construir contexto** — injeta memória do host, observações de rede, orientação de fase no prompt
3. **Perguntar ao LLM** — o modelo produz `REASONING: ... COMMAND: ...`
4. **Validar** — o proxy de escopo verifica se o comando está no escopo e não é destrutivo
5. **Executar** — o comando roda via servidor Kali MCP
6. **Aprender** — o analisador de saída extrai descobertas, atualiza a memória do host
7. **Redefinir contexto** — limpa a conversa, mantém a memória persistente, repete
O modelo de 1,2B tem uma taxa de sucesso de comando de ~50% (inerente ao seu tamanho). O agente compensa com:
- **Detecção de lixo** — redefinição após 5 falhas com exemplos few-shot variados
- **Detecção de duplicatas** — força diversificação de ferramenta/alvo
- **Detecção de travamento baseada em tempo** — limite de 5 minutos força redefinição de contexto
- **Execução direta de playbooks** — ataques em várias etapas ignoram o LLM completamente
## Painel Web
O painel em `:8888` fornece monitoramento e controle em tempo real:
- **Feed ao vivo** — cada comando, descoberta e decisão do agente
- **Cartões de host** — cartões clicáveis mostrando portas, serviços, vulnerabilidades
- **Mapa de rede** — grafo interativo dirigido por força (arrastar, zoom, pan)
- **Detalhes de vulnerabilidade** — tags CVE, cadeias de exploração, etapas de remediação
- **Controles C2** — favoritar/lista negra de hosts, forçar fase, pausar/retomar, injetar comandos
- **Modo offline** — UI de ataque WiFi inspirada no Pwnagotchi com rosto animado
O painel é filtrado por furtividade: ele falsifica cabeçalhos nginx e retorna 404s vazios para conexões da rede alvo.
## Resultados Testados
De 72+ horas de operação autônoma em múltiplas redes:
- **30+ hosts** descobertos por rede
- **2.000+ comandos** executados autonomamente
- **10+ vulnerabilidades** encontradas em múltiplos serviços
- **6+ playbooks** executados via execução direta
- Memória do agente estável em 35-50MB durante todo o processo (sem vazamentos)
## Contribuindo
Contribuições são bem-vindas! Consulte [CONTRIBUTING.md](https://github.com/garagehq/nightcrawler/blob/main/CONTRIBUTING.md) para diretrizes.
### Áreas onde ajuda é necessária
- **Ajuste fino do modelo** — melhorar a conformidade com o formato de comando de ~50% para 85%+
- **Novos playbooks** — adicionar cadeias de exploração para mais serviços
- **Banco de dados CVE** — expandir a cobertura além das atuais 24.956 entradas
- **Suporte a adaptadores** — testar com mais chipsets WiFi USB
- **Documentação** — tutoriais, guias de configuração para diferentes telefones
- **Testes** — mais cobertura de testes, especialmente para casos extremos
### Configuração de desenvolvimento
```bash
# Clone o repositório
git clone https://github.com/garagehq/nightcrawler.git
cd nightcrawler
# Modo de execução de teste (sem comandos reais, sem necessidade de hardware)
NC_DRY_RUN=1 python3 main.py
# Execute os testes
python3 -m pytest tests/
```
## Legal
**Esta ferramenta é apenas para testes de penetração autorizados.** Você deve ter permissão por escrito (Regras de Engajamento) do proprietário da rede antes de implantar o Nightcrawler. Uso não autorizado contra redes que você não possui ou não tem permissão para testar é ilegal.
## Licença
MIT — consulte [LICENSE](https://github.com/garagehq/nightcrawler/blob/main/LICENSE) para detalhes.
## Suporte
Se você gosta deste projeto, pode me pagar um café ☕:
<a href="https://buymeacoffee.com/cyrilengmann" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/47403/322a7c99f1dd15a03b3c1b00b0d18ddd87443d80b823d3467a240721ae02357e.webp" alt="Buy Me A Coffee" height="50" width="210"></a>
> **[buymeacoffee.com/cyrilengmann](https://buymeacoffee.com/cyrilengmann)**