AI locale potenziato per red teaming su un telefono
# Nightcrawler
Un agente autonomo di penetration testing che gira interamente su uno smartphone. Lascia il telefono su una rete, allontanati, e lui scopre host, mappa servizi, trova vulnerabilità e genera un report di pentest — tutto senza connettività cloud.
```
░█▄░█ █ █▀▀ █░█ ▀█▀ █▀▀ █▀█ ▄▀█ █░█░█ █░░ █▀▀ █▀█
░█░▀█ █ █▄█ █▀█ ░█░ █▄▄ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ██▄ █▀▄ v0.1.0
AUTONOMOUS MOBILE PENTEST AGENT
OnePlus 8 · NetHunter · LFM2.5-1.2B · OpenCL GPU
```
## Cos'è?
Il **penetration testing** (pentest) è la pratica di testare la sicurezza di una rete informatica simulando un attacco — con il permesso esplicito del proprietario della rete. I pentester professionisti vengono assunti per trovare vulnerabilità *prima* che lo facciano i veri attaccanti.
Nightcrawler automatizza questo processo su un telefono. Usa un piccolo modello di IA (LFM2.5-1.2B-Instruct-Heretic, 1,2 miliardi di parametri) eseguito localmente sulla GPU del telefono per decidere cosa fare dopo — quale host sondare, quale strumento usare, cosa cercare. Nessuna connessione internet o API cloud richiesta.
## Demo
▶️ **[Guarda Nightcrawler in azione su Instagram](https://www.instagram.com/p/DYNXFvVN0c_/)**
### Come funziona
1. **WiFi Breach** (opzionale) — Se lasciato senza WiFi, può craccare autonomamente reti WPA2 usando un adattatore WiFi USB esterno
2. **Ricognizione** — Scopre i dispositivi sulla rete usando scan stealth
3. **Enumerazione** — Sonda i servizi scoperti (server web, condivisioni file, SSH, DNS, ecc.)
4. **Exploitation** — Testa vulnerabilità note e credenziali di default
5. **Reporting** — Genera un report di pentest strutturato con risultati e consigli di remediation
L'agente opera come un pentester umano paziente — ruota tra gli host, fa una piccola azione per turno e costruisce conoscenza gradualmente nel corso delle ore. Questo lo rende molto più difficile da rilevare rispetto ai tradizionali scanner di vulnerabilità che bombardano tutti gli host contemporaneamente.
### Concetti chiave
| Termine | Cosa significa |
|------|--------------|
| **Drop box** | Un dispositivo lasciato su una rete target per eseguire test in autonomia |
| **Scope** | L'insieme di reti/host che sei autorizzato a testare |
| **Rules of Engagement (ROE)** | Un documento legale che specifica cosa ti è permesso fare |
| **Stealth** | Tecniche per evitare il rilevamento da parte del monitoraggio di rete (IDS/IPS) |
| **MCP** | Model Context Protocol — un'interfaccia standard per l'uso di strumenti IA |
| **C2** | Command and Control — la dashboard web per monitorare e guidare l'agente |
## Architettura
```
┌──────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
Per il design completo del sistema, vedi [docs/ARCHITECTURE.md](https://github.com/garagehq/nightcrawler/blob/main/docs/ARCHITECTURE.md).
## Funzionalità
- **Completamente autonomo** — nessun umano nel loop durante l'operazione
- **Inferenza 100% locale** — l'IA gira sulla GPU del telefono, nessun cloud necessario
- **Scope enforced** — difesa a due livelli che previene azioni fuori scope
- **Stealth-first** — velocità di scan lente, rotazione degli host, cover traffic, solo nmap -T2
- **27 playbook di exploit** — catene di attacco multi-step che si eseguono automaticamente
- **Database CVE con 24.956 voci** — corrispondenza delle vulnerabilità basata sulla versione
- **Dashboard web** — monitoraggio in tempo reale, gestione host, controlli C2
- **Modalità WiFi breach** — cracking WPA2 autonomo con adattatore USB (ispirato a Pwnagotchi)
- **Scoperta passiva** — cattura in background di broadcast mDNS/NBNS/DHCP/ARP
- **Multi-rete** — dati isolati per rete, sopravvive ai cambi DHCP tramite host con chiave MAC
- **Self-healing** — rilevamento garbage, reset del contesto, watchdog, rilevamento blocco
- **Cattura per training** — registra interazioni riuscite per il futuro fine-tuning del modello
- **Generazione report** — report di pentest scaricabile con vulnerabilità, catene di exploit, remediation
Vedi [docs/FEATURES.md](https://github.com/garagehq/nightcrawler/blob/main/docs/FEATURES.md) per il riferimento completo delle funzionalità.
## Hardware
### Richiesto
- **Telefono Android** con [Kali NetHunter](https://www.kali.org/docs/nethunter/) (testato su OnePlus 8, Snapdragon 865)
- **Accesso root** tramite [Magisk](https://github.com/topjohnwu/Magisk)
- **12GB+ di RAM** (il modello usa ~1,3GB, Android ~4GB, il resto per gli strumenti)
### Opzionale
- **Adattatore WiFi USB** per la modalità WiFi breach offline (consigliato Ralink RT3572)
- **Kernel personalizzato** con MAC80211 per la modalità monitor ([guida alla build](https://github.com/garagehq/nightcrawler/blob/main/docs/KERNEL_BUILD_PROMPT.md))
- **NVIDIA AGX** per scaricare su un modello più grande tramite Tailscale
### Prestazioni GPU
Tutta l'inferenza tramite OpenCL su GPU Adreno 650:
| Modello | Quantizzazione | Velocità Prompt | Velocità Generazione |
|-------|-------------|-------------|-----------------|
| **LFM2.5-1.2B-Instruct-Heretic** (produzione) | 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:** Android limita la GPU quando si è a batteria (rallentamento di 6x). Nightcrawler include un demone del governor GPU che forza le massime prestazioni e auto-limita a ≤15% di batteria.
## Avvio Rapido
```bash
# 1. Installazione (dentro il chroot di Kali NetHunter)
bash INSTALL.sh
# 2. Attendi l'avvio di llama-server (~5 min dopo il boot)
curl -s http://127.0.0.1:8080/health # Dovrebbe restituire {"status":"ok"}
# 3. Avvia tutti i servizi
bash scripts/run-36h.sh
# 4. Apri la dashboard web (da qualsiasi dispositivo sulla tua rete Tailscale)
# https://<il-tuo-hostname-tailscale>:8888
```
### Dry Run (nessun comando reale eseguito)
```bash
NC_DRY_RUN=1 python3 main.py
```
Questo usa un server Kali mock così puoi testare il loop dell'agente senza eseguire comandi di rete reali.
### Avvio Manuale (se non usi il launcher 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 &
```
## Configurazione
Modifica `config.yaml` prima del deployment:
```yaml
mission:
id: "CLIENT-YYYY-XXX" # Il tuo ID di engagement
scope:
networks: ["auto"] # "auto" = rileva da wlan0 all'avvio
excluded_hosts: ["auto"] # "auto" = gateway + IP proprio
excluded_ports: [502, 503] # Porte SCADA/ICS da non toccare mai
authorization: "ROE-YYYY-XXX.pdf"
max_runtime_hours: 0 # 0 = nessun limite
model:
local:
ctx_size: 8192
port: 8080
```
**Rilevamento dinamico dello scope** significa zero modifiche di configurazione quando ti sposti tra reti — l'agente legge la subnet corrente da `wlan0` all'avvio.
## Struttura del Progetto
```
nightcrawler/
├── main.py # Punto di ingresso
├── config.yaml # Config missione scope + modello
├── scope_proxy.py # Proxy di enforcement dello scope
├── INSTALL.sh # Installer
│
├── agent/ # Logica core dell'agente
│ ├── loop.py # Loop decisionale + recupero errori
│ ├── planner.py # Macchina a stati di fase (recon → exploit)
│ ├── llm_client.py # Client API LLM (llama.cpp / remoto)
│ ├── db.py # Backend SQLite (host, vuln, creds)
│ ├── host_memory.py # Osservazioni per-host + auto-tagging
│ ├── cve_db.py # Database CVE con 24.956 voci
│ ├── attack_planner.py # Direttive strategiche per la fase exploit
│ ├── output_parser.py # Estrae dati strutturati dall'output degli strumenti
│ ├── offline_manager.py # Macchina a stati del pipeline WiFi breach
│ ├── net_detect.py # Auto-rilevamento rete da wlan0
│ ├── cover_traffic.py # Blending stealth con traffico web realistico
│ ├── passive_capture.py # tcpdump in background per traffico broadcast
│ └── ...
│
├── proxy/ # Componenti di enforcement dello scope
│ ├── scope.py # Validazione IP/porta/host
│ ├── rate_limiter.py # Rate limiting comandi + jitter
│ └── command_filter.py # Blocklist comandi distruttivi
│
├── webui/ # Dashboard web (Flask)
│ ├── server.py # API + middleware stealth
│ └── templates/index.html # UI dashboard
│
├── data/ # File dati statici
│ ├── cve_exploits.json # Mappature CVE→comandi exploit
│ └── playbooks.json # 27 playbook di attacco multi-step
│
├── prompts/ # Template prompt LLM (hot-reloadable)
├── scripts/ # Script operativi (start, stop, watchdog)
├── tests/ # Suite di test (API, UI, modalità offline)
├── kernels/ # Moduli driver WiFi + documentazione kernel
├── simulation/ # Server mock per dry-run
├── docs/ # Architettura, setup GPU, funzionalità
├── logs/ # Dati runtime (gitignored)
└── models/ # File modello (gitignored)
```
## Come Pensa l'Agente
L'agente usa un loop semplice ma efficace:
1. **Scegli un target** — selezione casuale pesata (70% host con porte note, 30% nuova scoperta)
2. **Costruisci il contesto** — inietta memoria host, osservazioni di rete, guida di fase nel prompt
3. **Chiedi all'LLM** — il modello produce `REASONING: ... COMMAND: ...`
4. **Valida** — lo scope proxy verifica che il comando sia in scope e non distruttivo
5. **Esegui** — il comando gira tramite il server Kali MCP
6. **Impara** — il parser di output estrae i risultati, aggiorna la memoria host
7. **Reset del contesto** — pulisci la conversazione, mantieni la memoria persistente, ripeti
Il modello da 1,2B ha un tasso di successo dei comandi di ~50% (intrinseco alla sua dimensione). L'agente compensa con:
- **Rilevamento garbage** — reset a 5 streak con esempi few-shot variati
- **Rilevamento duplicati** — forza la diversificazione di strumenti/target
- **Rilevamento blocco basato sul tempo** — backstop di 5 minuti che forza il reset del contesto
- **Esecuzione diretta dei playbook** — gli attacchi multi-step bypassano completamente l'LLM
## Dashboard Web
La dashboard su `:8888` fornisce monitoraggio e controllo in tempo reale:
- **Feed live** — ogni comando, risultato e decisione dell'agente
- **Card host** — card cliccabili che mostrano porte, servizi, vulnerabilità
- **Mappa di rete** — grafo interattivo force-directed (trascina, zoom, pan)
- **Dettagli vulnerabilità** — tag CVE, catene di exploit, passi di remediation
- **Controlli C2** — star/blacklist host, forza fase, pausa/ripresa, inietta comandi
- **Modalità offline** — UI di attacco WiFi ispirata a Pwnagotchi con faccia animata
La dashboard è filtrata stealth: spoofa gli header nginx e restituisce 404 vuoti alle connessioni dalla rete target.
## Risultati Testati
Da 72+ ore di operazione autonoma su più reti:
- **30+ host** scoperti per rete
- **2.000+ comandi** eseguiti autonomamente
- **10+ vulnerabilità** trovate su più servizi
- **6+ playbook** eseguiti tramite esecuzione diretta
- Memoria dell'agente stabile a 35-50MB per tutto il tempo (nessuna leak)
## Contribuire
I contributi sono benvenuti! Vedi [CONTRIBUTING.md](https://github.com/garagehq/nightcrawler/blob/main/CONTRIBUTING.md) per le linee guida.
### Aree dove serve aiuto
- **Fine-tuning del modello** — migliorare la conformità al formato dei comandi da ~50% a 85%+
- **Nuovi playbook** — aggiungere catene di exploit per più servizi
- **Database CVE** — espandere la copertura oltre le attuali 24.956 voci
- **Supporto adattatori** — test con più chipset WiFi USB
- **Documentazione** — tutorial, guide di setup per diversi telefoni
- **Testing** — più copertura di test, specialmente per i casi limite
### Setup di sviluppo
```bash
# Clona il repo
git clone https://github.com/garagehq/nightcrawler.git
cd nightcrawler
# Modalità dry-run (nessun comando reale, nessun hardware necessario)
NC_DRY_RUN=1 python3 main.py
# Esegui i test
python3 -m pytest tests/
```
## Legale
**Questo strumento è solo per penetration testing autorizzato.** Devi avere il permesso scritto (Rules of Engagement) dal proprietario della rete prima di distribuire Nightcrawler. L'uso non autorizzato contro reti che non possiedi o per cui non hai il permesso di testare è illegale.
## Licenza
MIT — vedi [LICENSE](https://github.com/garagehq/nightcrawler/blob/main/LICENSE) per i dettagli.
## Supporto
Se ti piace questo progetto, puoi offrirmi un caffè ☕:
<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)**