Red teamer local impulsado por IA en un teléfono
# Nightcrawler
Un agente autónomo de pruebas de penetración que se ejecuta completamente en un smartphone. Deja el teléfono en una red, aléjate, y descubre hosts, mapea servicios, encuentra vulnerabilidades y genera un informe de pentest — todo sin conectividad a la nube.
```
░█▄░█ █ █▀▀ █░█ ▀█▀ █▀▀ █▀█ ▄▀█ █░█░█ █░░ █▀▀ █▀█
░█░▀█ █ █▄█ █▀█ ░█░ █▄▄ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ██▄ █▀▄ v0.1.0
AUTONOMOUS MOBILE PENTEST AGENT
OnePlus 8 · NetHunter · LFM2.5-1.2B · OpenCL GPU
```
## ¿Qué es esto?
**Las pruebas de penetración** (pentesting) son la práctica de probar la seguridad de una red informática simulando un ataque — con el permiso explícito del propietario de la red. Los pentesters profesionales son contratados para encontrar vulnerabilidades *antes* de que lo hagan los atacantes reales.
Nightcrawler automatiza este proceso en un teléfono. Utiliza un pequeño modelo de IA (LFM2.5-1.2B-Instruct-Heretic, 1.2 mil millones de parámetros) que se ejecuta localmente en la GPU del teléfono para decidir qué hacer a continuación — qué host sondear, qué herramienta usar, qué buscar. No requiere conexión a internet ni API en la nube.
## Demo
▶️ **[Mira Nightcrawler en acción en Instagram](https://www.instagram.com/p/DYNXFvVN0c_/)**
### Cómo funciona
1. **Brecha WiFi** (opcional) — Si se deja sin WiFi, puede descifrar redes WPA2 de forma autónoma usando un adaptador WiFi USB externo
2. **Reconocimiento** — Descubre dispositivos en la red mediante escaneos sigilosos
3. **Enumeración** — Sonda servicios descubiertos (servidores web, recursos compartidos de archivos, SSH, DNS, etc.)
4. **Explotación** — Prueba vulnerabilidades conocidas y credenciales por defecto
5. **Informe** — Genera un informe de pentest estructurado con hallazgos y recomendaciones de remediación
El agente opera como un pentester humano paciente — rota entre hosts, realiza una pequeña acción por turno y construye conocimiento gradualmente a lo largo de horas. Esto lo hace mucho más difícil de detectar que los escáneres de vulnerabilidades tradicionales que atacan todos los hosts a la vez.
### Conceptos clave
| Término | Qué significa |
|------|--------------|
| **Drop box** | Un dispositivo dejado en una red objetivo para realizar pruebas de forma autónoma |
| **Alcance** | El conjunto de redes/hosts que estás autorizado a probar |
| **Reglas de Compromiso (ROE)** | Un documento legal que especifica lo que se te permite hacer |
| **Sigilo** | Técnicas para evitar la detección por monitoreo de red (IDS/IPS) |
| **MCP** | Model Context Protocol — una interfaz estándar para el uso de herramientas por IA |
| **C2** | Command and Control — el panel web para monitorear y dirigir al agente |
## Arquitectura
```
┌──────────────────────────────────────────────────────────┐
│ 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 el diseño completo del sistema, consulta [docs/ARCHITECTURE.md](https://github.com/garagehq/nightcrawler/blob/main/docs/ARCHITECTURE.md).
## Características
- **Totalmente autónomo** — sin intervención humana durante la operación
- **Inferencia 100% local** — la IA se ejecuta en la GPU del teléfono, sin necesidad de nube
- **Alcance forzado** — defensa de dos capas que previene acciones fuera de alcance
- **Sigilo primero** — velocidades de escaneo lentas, rotación de hosts, tráfico de cobertura, solo nmap -T2
- **27 playbooks de explotación** — cadenas de ataque de múltiples pasos que se ejecutan automáticamente
- **Base de datos CVE de 24,956 entradas** — coincidencia de vulnerabilidades consciente de versiones
- **Panel web** — monitoreo en tiempo real, gestión de hosts, controles C2
- **Modo de brecha WiFi** — descifrado autónomo de WPA2 con adaptador USB (inspirado en Pwnagotchi)
- **Descubrimiento pasivo** — captura en segundo plano de transmisiones mDNS/NBNS/DHCP/ARP
- **Multi-red** — datos aislados por red, sobrevive a cambios de DHCP mediante hosts con clave MAC
- **Auto-reparación** — detección de basura, reinicio de contexto, watchdogs, detección de bloqueos
- **Captura de entrenamiento** — registra interacciones exitosas para el futuro ajuste del modelo
- **Generación de informes** — informe de pentest descargable con vulnerabilidades, cadenas de explotación y remediación
Consulta [docs/FEATURES.md](https://github.com/garagehq/nightcrawler/blob/main/docs/FEATURES.md) para la referencia completa de características.
## Hardware
### Requerido
- **Teléfono Android** con [Kali NetHunter](https://www.kali.org/docs/nethunter/) (probado en OnePlus 8, Snapdragon 865)
- **Acceso root** mediante [Magisk](https://github.com/topjohnwu/Magisk)
- **12GB+ de RAM** (el modelo usa ~1.3GB, Android usa ~4GB, el resto para herramientas)
### Opcional
- **Adaptador WiFi USB** para el modo de brecha WiFi sin conexión (se recomienda Ralink RT3572)
- **Kernel personalizado** con MAC80211 para modo monitor ([guía de compilación](https://github.com/garagehq/nightcrawler/blob/main/docs/KERNEL_BUILD_PROMPT.md))
- **NVIDIA AGX** para descargar a un modelo más grande a través de Tailscale
### Rendimiento de GPU
Toda la inferencia mediante OpenCL en GPU Adreno 650:
| Modelo | Cuantización | Velocidad de prompt | Velocidad de generación |
|-------|-------------|-------------|-----------------|
| **LFM2.5-1.2B-Instruct-Heretic** (producción) | 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 cuando se usa con batería (desaceleración de 6x). Nightcrawler incluye un daemon de gobernador de GPU que fuerza el rendimiento máximo y se auto-limita al ≤15% de batería.
## Inicio Rápido
```bash
# 1. Instalación (dentro del chroot de Kali NetHunter)
bash INSTALL.sh
# 2. Espera a que se inicie llama-server (~5 min después del arranque)
curl -s http://127.0.0.1:8080/health # Debería devolver {"status":"ok"}
# 3. Inicia todos los servicios
bash scripts/run-36h.sh
# 4. Abre el panel web (desde cualquier dispositivo en tu red Tailscale)
# https://<tu-hostname-tailscale>:8888
```
### Ejecución de prueba (sin comandos reales ejecutados)
```bash
NC_DRY_RUN=1 python3 main.py
```
Esto usa un servidor Kali simulado para que puedas probar el bucle del agente sin ejecutar comandos de red reales.
### Inicio Manual (si no usas el lanzador 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 &
```
## Configuración
Edita `config.yaml` antes del despliegue:
```yaml
mission:
id: "CLIENT-YYYY-XXX" # Tu ID de compromiso
scope:
networks: ["auto"] # "auto" = detectar desde wlan0 al inicio
excluded_hosts: ["auto"] # "auto" = gateway + IP propia
excluded_ports: [502, 503] # Puertos SCADA/ICS que nunca tocar
authorization: "ROE-YYYY-XXX.pdf"
max_runtime_hours: 0 # 0 = sin límite
model:
local:
ctx_size: 8192
port: 8080
```
**Detección dinámica de alcance** significa cero cambios de configuración al moverse entre redes — el agente lee la subred actual desde `wlan0` al inicio.
## Estructura del Proyecto
```
nightcrawler/
├── main.py # Punto de entrada
├── config.yaml # Alcance de misión + configuración del modelo
├── scope_proxy.py # Proxy de cumplimiento de alcance
├── INSTALL.sh # Instalador
│
├── agent/ # Lógica central del agente
│ ├── loop.py # Bucle de decisión + recuperación de errores
│ ├── planner.py # Máquina de estados de fases (recon → exploit)
│ ├── llm_client.py # Cliente API LLM (llama.cpp / remoto)
│ ├── db.py # Backend SQLite (hosts, vulns, creds)
│ ├── host_memory.py # Observaciones por host + auto-etiquetado
│ ├── cve_db.py # Base de datos CVE de 24,956 entradas
│ ├── attack_planner.py # Directivas estratégicas para la fase de explotación
│ ├── output_parser.py # Extrae datos estructurados de la salida de herramientas
│ ├── offline_manager.py # Máquina de estados del pipeline de brecha WiFi
│ ├── net_detect.py # Auto-detección de red desde wlan0
│ ├── cover_traffic.py # Mezcla sigilosa con tráfico web realista
│ ├── passive_capture.py # tcpdump en segundo plano para tráfico de difusión
│ └── ...
│
├── proxy/ # Componentes de cumplimiento de alcance
│ ├── scope.py # Validación de IP/puerto/host
│ ├── rate_limiter.py # Limitación de velocidad de comandos + jitter
│ └── command_filter.py # Lista negra de comandos destructivos
│
├── webui/ # Panel web (Flask)
│ ├── server.py # API + middleware sigiloso
│ └── templates/index.html # Interfaz del panel
│
├── data/ # Archivos de datos estáticos
│ ├── cve_exploits.json # Mapeos CVE→comando de explotación
│ └── playbooks.json # 27 playbooks de ataque de múltiples pasos
│
├── prompts/ # Plantillas de prompt LLM (recargables en caliente)
├── scripts/ # Scripts operativos (inicio, parada, watchdogs)
├── tests/ # Suites de pruebas (API, UI, modo sin conexión)
├── kernels/ # Módulos de driver WiFi + documentación de kernel
├── simulation/ # Servidor simulado para ejecución de prueba
├── docs/ # Arquitectura, configuración de GPU, características
├── logs/ # Datos de ejecución (ignorados por git)
└── models/ # Archivos de modelo (ignorados por git)
```
## Cómo Piensa el Agente
El agente usa un bucle simple pero efectivo:
1. **Elige un objetivo** — selección aleatoria ponderada (70% hosts con puertos conocidos, 30% nuevo descubrimiento)
2. **Construye contexto** — inyecta memoria de host, observaciones de red, guía de fase en el prompt
3. **Pregunta al LLM** — el modelo produce `REASONING: ... COMMAND: ...`
4. **Valida** — el proxy de alcance verifica que el comando esté dentro del alcance y no sea destructivo
5. **Ejecuta** — el comando se ejecuta mediante el servidor Kali MCP
6. **Aprende** — el analizador de salida extrae hallazgos, actualiza la memoria del host
7. **Reinicia contexto** — limpia la conversación, mantiene la memoria persistente, repite
El modelo de 1.2B tiene una tasa de éxito de comandos de ~50% (inherente a su tamaño). El agente lo compensa con:
- **Detección de basura** — reinicio de 5 rachas con ejemplos variados de few-shot
- **Detección de duplicados** — fuerza la diversificación de herramientas/objetivos
- **Detección de bloqueos por tiempo** — respaldo de 5 minutos que fuerza el reinicio de contexto
- **Ejecución directa de playbooks** — los ataques de múltiples pasos omiten el LLM por completo
## Panel Web
El panel en `:8888` proporciona monitoreo y control en tiempo real:
- **Feed en vivo** — cada comando, hallazgo y decisión del agente
- **Tarjetas de host** — tarjetas clicables que muestran puertos, servicios, vulnerabilidades
- **Mapa de red** — gráfico interactivo dirigido por fuerza (arrastrar, zoom, paneo)
- **Detalles de vulnerabilidades** — etiquetas CVE, cadenas de explotación, pasos de remediación
- **Controles C2** — marcar/lista negra de hosts, forzar fase, pausar/reanudar, inyectar comandos
- **Modo sin conexión** — interfaz de ataque WiFi inspirada en Pwnagotchi con cara animada
El panel está filtrado por sigilo: suplanta encabezados nginx y devuelve 404s vacíos a conexiones desde la red objetivo.
## Resultados Probados
De más de 72 horas de operación autónoma en múltiples redes:
- **30+ hosts** descubiertos por red
- **2,000+ comandos** ejecutados de forma autónoma
- **10+ vulnerabilidades** encontradas en múltiples servicios
- **6+ playbooks** ejecutados mediante ejecución directa
- Memoria del agente estable en 35-50MB durante todo el proceso (sin fugas)
## Contribuciones
¡Las contribuciones son bienvenidas! Consulta [CONTRIBUTING.md](https://github.com/garagehq/nightcrawler/blob/main/CONTRIBUTING.md) para las pautas.
### Áreas donde se necesita ayuda
- **Ajuste del modelo** — mejorar el cumplimiento del formato de comandos de ~50% a 85%+
- **Nuevos playbooks** — agregar cadenas de explotación para más servicios
- **Base de datos CVE** — ampliar la cobertura más allá de las 24,956 entradas actuales
- **Soporte de adaptadores** — pruebas con más chipsets WiFi USB
- **Documentación** — tutoriales, guías de configuración para diferentes teléfonos
- **Pruebas** — más cobertura de pruebas, especialmente para casos límite
### Configuración de desarrollo
```bash
# Clona el repositorio
git clone https://github.com/garagehq/nightcrawler.git
cd nightcrawler
# Modo de ejecución de prueba (sin comandos reales, sin necesidad de hardware)
NC_DRY_RUN=1 python3 main.py
# Ejecuta las pruebas
python3 -m pytest tests/
```
## Legal
**Esta herramienta es solo para pruebas de penetración autorizadas.** Debes tener permiso por escrito (Reglas de Compromiso) del propietario de la red antes de desplegar Nightcrawler. El uso no autorizado contra redes que no posees o para las que no tienes permiso de prueba es ilegal.
## Licencia
MIT — consulta [LICENSE](https://github.com/garagehq/nightcrawler/blob/main/LICENSE) para más detalles.
## Soporte
Si disfrutas este proyecto, puedes invitarme a un 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)**