CyberDeck

CyberDeck es un panel local que centraliza una interfaz web construida con FastAPI, Jinja2, HTML/CSS/JavaScript y Bash scripting para ejecutar tareas de reconocimiento, gestión de capturas Wi‑Fi, simulación Evil Twin y laboratorios CTF con Docker.

Forma parte de mi Proyecto Intermodular del grado superior de Administración de Sistemas Informáticos en Red, en el cual construimos una estación portátil o CyberDeck compuesta por una Raspberry Pi 5 como nodo principal y Raspberry Pi Zero 2WH como auxiliar (proyecto pwnagotchi).

[!WARNING] Este proyecto está pensado exclusivamente para formación, laboratorios propios y entornos controlados.

Tabla de contenidos

• Características
• Arquitectura
• Requisitos
• Instalación
• Ejecución
• Configuración importante
• Módulos disponibles
• Estructura del repositorio
• Rutas web y API
• Datos generados

Características

• Panel web local con estética tipo terminal/cyberdeck.
• Reconocimiento LAN mediante Nmap para descubrir hosts activos y enumerar puertos/servicios por objetivo.
• Integración con Pwnagotchi para iniciar/detener captura remota, sincronizar capturas y consultar estado.
• Gestión de handshakes Wi‑Fi con listado de redes, ficheros de captura y jobs de cracking por diccionario.
• Pipeline de cracking WPA/WPA2 basado en hcxpcapngtool y hashcat.
• Evil Twin controlado con hostapd, dnsmasq, nftables y portal cautivo local.
• Orquestación de laboratorios CTF con Docker Compose desde la UI.
• Servicios en routers, servicios y scripts para facilitar ampliaciones.

Arquitectura

Navegador
   │
   ▼
FastAPI + Jinja2
   │
   ├── Routers HTTP/API
   │   ├── páginas HTML
   │   ├── LAN Scan
   │   ├── Handshakes / Pwnagotchi
   │   ├── Evil Twin
   │   └── Docker CTF Labs
   │
   ├── Services Python
   │   ├── validación/parsing
   │   ├── ejecución de subprocess
   │   ├── persistencia JSONL
   │   └── gestión de jobs
   │
   └── Scripts Bash / herramientas externas
       ├── nmap
       ├── ssh / rsync
       ├── hcxpcapngtool / hashcat
       ├── hostapd / dnsmasq / nft
       └── docker compose

En el archivo app/main.py se inicializa la aplicación web. Crea la instancia FastAPI, monta /static y registra los routers de los módulos.

Requisitos

Software base

• Python 3.11+ recomendado.
• pip y entorno virtual (venv).
• Nmap.
• Docker y Docker Compose v2.
• Bash.

Para el módulo Wi‑Fi / Pwnagotchi

• Pwnagotchi accesible por red en 10.0.0.2.
• Acceso SSH configurado hacia el dispositivo.
• rsync para sincronizar capturas.
• Capturas en formatos .pcap, .pcapng o .cap.

Para cracking de handshakes

• hcxpcapngtool.
• hashcat.
• Diccionarios en data/wordlists/ (.txt, .lst o .dict).

Para Evil Twin

• Adaptador Wi‑Fi compatible con modo AP.
• Interfaz esperada por defecto: wlan1.
• hostapd.
• dnsmasq.
• nftables.
• Permisos de root/sudo para configurar interfaz, DHCP/DNS y redirecciones.

Instalación

1. Clona el repositorio:

   git clone <URL_DEL_REPOSITORIO> CyberDeck
   cd CyberDeck
   

2. Crea y activa un entorno virtual:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Instala dependencias Python:

   pip install -r requirements.txt
   

4. Revisa permisos de scripts:

   chmod +x scripts/lan_scan/*.sh \
     scripts/evil_twin/*.sh \
     scripts/docker/*.sh \
     scripts/handshake_cracking/*.sh
   

5. Crea directorios de datos si no existen:

   mkdir -p data/{handshakes,wordlists,cracking,pwnagotchi}
   

Ejecución

Arranca el servidor de desarrollo desde la raíz del repositorio:

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

Acceso a la GUI:

http://localhost:8080

También puedes consultar la documentación automática de FastAPI en:

http://localhost:8080/docs

Configuración importante

Algunos módulos están adaptados al entorno objetivo original del proyecto. Antes de desplegarlo en otra máquina, revisa esto:

Elemento	Valor actual	Dónde se usa
Ruta base de scripts Docker/Evil Twin	/home/xro/CyberDeck	Servicios Docker/Evil Twin y script Docker
Interfaz LAN para detección	wlan0	scripts/lan_scan/lan_scan.sh
Interfaz AP Evil Twin	wlan1	scripts/evil_twin/start_evil_twin.sh
IP Pwnagotchi	10.0.0.2	Servicios Pwnagotchi/sync
Usuario Pwnagotchi para control	xro	Servicio de control por SSH
Usuario Pwnagotchi para sync	root	Servicio de sincronización por rsync
Carpeta remota handshakes	/root/handshakes	Sync de capturas

Si tu instalación no está ubicada en /home/xro/CyberDeck, ajusta esas rutas o cambia la ubicación de la misma.

Módulos disponibles

1. Escanear red local

Ubicación web: /wifi/scan

Permite:

• Detectar la red asociada a wlan0.
• Ejecutar descubrimiento de hosts con nmap -sn.
• Mostrar IP, MAC y fabricante NIC.
• Lanzar escaneo detallado por host.
• Enumerar puertos abiertos y servicios/versiones.

Scripts que utiliza:

• scripts/lan_scan/lan_scan.sh
• scripts/lan_scan/host_port_scan.sh
• scripts/lan_scan/host_service_scan.sh

2. Capturar handshakes - con Pwnagotchi

Ubicación web: /wifi/handshakes

Permite:

• Consultar si Pwnagotchi está online.
• Iniciar y detener el servicio remoto pwnagotchi por SSH.
• Sincronizar capturas desde /root/handshakes.
• Listar redes detectadas a partir de eventos.
• Asociar redes con capturas locales.
• Seleccionar diccionarios y lanzar jobs de cracking.
• Consultar logs y estado de los jobs.

Directorios relacionados:

• data/handshakes/
• data/wordlists/
• data/cracking/
• data/pwnagotchi/events.jsonl

3. Evil Twin

Ubicación web: /wifi/evil-twin

Permite iniciar y detener un punto de acceso de laboratorio con portal cautivo local.

Componentes usados:

• Interfaz Wi‑Fi wlan1.
• Red AP 10.66.66.1/24.
• DHCP/DNS con dnsmasq.
• AP con hostapd.
• Redirección DNS/HTTP con nftables.
• Portal local en /evil-twin/portal.

Archivos temporales y logs:

• /tmp/cyberdeck_evil_twin/
• /tmp/cyberdeck_evil_twin_logs/

4. Docker Labs

Ubicación web: /ctf/labs o /docker/labs

Permite:

• Listar laboratorios disponibles.
• Preparar, iniciar, detener y reiniciar labs.
• Consultar estado y logs.
• Detener todos los labs activos.

Labs definidos actualmente en labs/compose-labs.yml:

Lab	Puerto(s) local(es)	Tipo
OWASP Juice Shop	31301	Web vulnerable
WebGoat	31302, 31312	Web vulnerable
WrongSecrets	31303, 31313	Secret management training
DVWA	31305	Web vulnerable
vsftpd 2.3.4	31321, 31620	FTP vulnerable
Linux capabilities lab	31222	Linux/privilege training
vulnerable-nginx	Gestionado por script externo	Nginx vulnerable

Estructura del repositorio

CyberDeck/
├── app/
│   ├── main.py                  # App FastAPI y registro de routers
│   ├── routers/                 # Rutas web/API por módulo
│   ├── services/                # Lógica de negocio y subprocess
│   └── utils/                   # Parsers XML de Nmap
├── data/
│   ├── handshakes/              # Capturas Wi‑Fi sincronizadas
│   ├── wordlists/               # Diccionarios para cracking
│   ├── cracking/                # Jobs, logs y resultados
│   └── pwnagotchi/              # Eventos JSONL
├── labs/
│   ├── compose-labs.yml         # Docker Compose de laboratorios
│   └── external/                # Labs externos/build contexts
├── scripts/
│   ├── docker/                  # Control de labs Docker
│   ├── evil_twin/               # Arranque/parada del AP
│   ├── handshake_cracking/      # Conversión y cracking WPA/WPA2
│   └── lan_scan/                # Escaneos Nmap
├── static/
│   ├── images/
│   ├── js/
│   └── style.css
├── templates/
│   ├── docker/
│   ├── wifi/
│   └── index.html
├── requirements.txt
└── README.md

Rutas web y API

Páginas

Método	Ruta	Descripción
GET	/	Dashboard principal
GET	/wifi/scan	Reconocimiento LAN
GET	/wifi/handshakes	Gestión de handshakes
GET	/wifi/evil-twin	Panel Evil Twin
GET	/evil-twin/portal	Portal cautivo
GET	/ctf/labs	Labs Docker
GET	/docker/labs	Alias de labs Docker

API principal

Método	Ruta	Descripción
GET	/api/lan-scan	Ejecuta descubrimiento LAN
POST	/api/lan-scan/detail	Escanea puertos/servicios de una IP
GET	/api/handshakes/status	Estado general y estadísticas
POST	/api/handshakes/capture/start	Inicia captura remota en Pwnagotchi
POST	/api/handshakes/capture/stop	Detiene captura remota
GET	/api/handshakes/networks	Lista redes/capturas/eventos
GET	/api/handshakes/events	Lista eventos recientes
POST	/api/handshakes/events/ingest	Ingresa eventos desde integraciones externas
POST	/api/handshakes/captures/sync	Sincroniza capturas desde Pwnagotchi
GET	/api/handshakes/captures	Lista capturas locales
GET	/api/handshakes/captures/debug	Información de depuración de capturas
GET	/api/handshakes/cracking/wordlists	Lista diccionarios disponibles
POST	/api/handshakes/cracking/start	Lanza job de cracking
GET	/api/handshakes/cracking/jobs/{job_id}	Consulta estado de job
GET	/api/handshakes/cracking/jobs/{job_id}/log	Consulta log de job
POST	/api/handshakes/cracking/jobs/{job_id}/stop	Detiene job de cracking
POST	/api/evil-twin/start	Inicia AP Evil Twin

Datos generados

• /tmp/lan_scan.xml: resultado del descubrimiento LAN.
• /tmp/host_ports_scan_<ip>.xml: resultado de escaneo de puertos por host.
• /tmp/host_scan_<ip>.xml: resultado de enumeración de servicios.
• data/handshakes/: capturas Wi‑Fi sincronizadas.
• data/cracking/: hash HC22000, potfiles, resultados y logs de jobs.
• data/pwnagotchi/events.jsonl: eventos recibidos/registrados.
• /tmp/cyberdeck_evil_twin/: estado runtime de Evil Twin.
• /tmp/cyberdeck_evil_twin_logs/: logs de hostapd y dnsmasq.