m5stick-wireless-viewer

Pipeline de datos y dashboard para firmwares de hardware hacking WiFi en ESP32.

Fusiona wifi-marauder-viewer y Visualizacion_extendida_M5StickPlus2 sobre una arquitectura modular: parsers por firmware, fuentes serial/file, store con historico (SQLite), API web (FastAPI + SSE) y exporter a Splunk HEC.

Conectar tu dispositivo

El firmware (Marauder, Evil-M5Project, ...) corre en la M5Stick; este proyecto lee su salida serial por USB. No hay que instalar nada en el stick mas allá del firmware habitual.

# 1. Conecta la M5Stick por USB y verifica que aparece (pista de placa):
m5wireless ports

# 2. Arranca captura + dashboard (http://localhost:8000).
#    --port es opcional: sin el, autodeteccion (prefiere M5Stick/ESP32).
m5wireless run --source serial --port COM3

Al arrancar se imprime la conexion resuelta: m5wireless: serial COM3 @ 115200 (USB Serial (COM3)) [posible M5Stick (M5Stack)]. Si no hay ningun puerto, el error lista los encontrados y sugiere --port. El dashboard muestra en la barra superior puerto, baudrate, firmware y estado (conectado / reconectando / esperando).

Sin hardware: m5wireless run --demo reproduce un log de ejemplo y deja el dashboard listo para probarse. Si ya tienes un log grabado: m5wireless run --source file --log-path scan.log.

Estado

v3.0.1: claridad de conexion (m5wireless ports, salida explicita al arrancar, widget de estado en el dashboard, modo --demo). v3.0.0: modelos, parsers, stores, fuentes, colector, dashboard web en vivo (SSE), export CSV/JSON, CLI unificada y Docker. Seguimiento de fases en SEGUIMIENTO.md.

Instalacion

pip install .                    # core + CLI (export offline, sin dependencias web)
pip install .[serial,web,splunk] # completo: serial en vivo + dashboard + Splunk HEC

El paquete crea el comando m5wireless (m5wireless --version).

Uso rapido

# Listar puertos serie con pista de placa (M5Stick/ESP32)
m5wireless ports

# Demo sin hardware: log de ejemplo incluido + dashboard
m5wireless run --demo

# Captura serial en vivo + dashboard web (http://localhost:8000)
m5wireless run

# Leer un log existente (modo offline/file), dashboard en :8000
m5wireless run --source file --log-path scan.log

# Export offline de un log a CSV/JSON
m5wireless export csv  --input scan.log --firmware evil_m5project --output out.csv
m5wireless export json --input scan.log --firmware marauder      --output out.json

# Guardar el dashboard HTML periodicamente (legacy auto_save_html)
m5wireless snapshot --url http://localhost:8000 --interval 60 --dir snapshots

Configuracion: CLI > variables de entorno M5W_* > fichero m5wireless.toml (./ o ~/.config/m5wireless/). Ejemplo de toml:

[run]
source = "file"
log_path = "scan.log"
firmware = "auto"
web_port = 8000

[splunk]
url = "https://splunk:8088/services/collector/event"
token = "..."
verify_ssl = true

Bruce (M5Stick)

Bruce no emite un log continuo: se lee su almacenamiento. Dos fuentes:

# Serial: CLI de Bruce + poller de `storage list/read` (requiere el extra [serial]).
m5wireless run --source bruce --port COM7

# WebUI HTTP: sin serial, lista y descarga pcaps por la web del dispositivo.
m5wireless run --source bruce-web --url http://172.0.0.1 --user admin --password bruce

# Si el dispositivo no tiene tarjeta SD, los pcaps viven en LittleFS:
m5wireless run --source bruce-web --url http://172.0.0.1 \
    --user admin --password bruce --fs LittleFS

Control remoto minimo (mismo --url/--user/--password):

m5wireless bruce info                 # version y uso de almacenamiento
m5wireless bruce reboot              # reinicia el dispositivo
m5wireless bruce cmd "power reboot"   # shell serial remota

Aviso: con el sniffer activo la WebUI bloquea la shell; bruce reboot es la unica salida limpia. Los pcaps descargados por HTTP son byte-identicos a los extraidos por serial.

Tarjeta SD montada en el PC (Bruce, Marauder, Flipper, Hound)

El denominador comun de estos firmwares es el fichero de captura en la SD. Con un lector USB, la tarjeta se monta como un directorio del PC y la fuente sdcard escanea las capturas nuevas (.pcap/.cap) hacia el mismo parser, sin depender del dispositivo encendido:

# E:/ es la SD montada; escaneo recursivo con dedup por size+mtime.
m5wireless run --source sdcard --sdcard-dir E:/

# Guardar copia de cada captura procesada:
m5wireless run --source sdcard --sdcard-dir E:/ --artifacts-dir data/artifacts

El directorio tambien se puede fijar con M5W_SDCARD_DIR o m5wireless.toml ([run] sdcard_dir). Los eventos se etiquetan como sdcard en el dashboard y los exportes.

Seguridad antes de usar la WebUI en campo

Los defaults de fabrica del firmware Bruce son publicos:

• AP: SSID BruceNet, password brucenet, IP fija 172.0.0.1/24 sin DHCP (el cliente necesita IP estatica, p. ej. 172.0.0.2).
• WebUI: usuario admin, password bruce.
• El sniffer emite con SSID oculto BruceSniffer.

Un dispositivo en modo sniffer + AP con credenciales publicas es accesible para cualquiera en la red: cambia el user/pwd de la WebUI y la password del AP antes de llevarlo a campo (configuracion desde la shell de Bruce).

Splunk HEC

Se activa automaticamente cuando hay URL y token configurados (M5W_SPLUNK_HEC_URL y M5W_SPLUNK_HEC_TOKEN, o la seccion [splunk] del toml); el colector reenvia cada evento sin accion manual. Robustez: envio por lotes, cola en memoria con spool a disco opcional (max_queue_size/spool_path) y circuit breaker tras fallos consecutivos. verify=True por defecto; desactivar la verificacion TLS es solo vía configuracion explicita (verify_ssl = false).

Docker (modo file por defecto)

docker compose up -d m5wireless          # dashboard en http://localhost:8000
docker compose --profile splunk up -d    # con Splunk para pruebas HEC

La captura serial en vivo se recomienda como host nativo (USB); el log lo aporta el volumen ./data (/data/scan.log).

Firmwares soportados

Desarrollo

python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
# o: source .venv/bin/activate && pip install -e ".[dev]"  # Linux/macOS

.venv/Scripts/python -m pytest
.venv/Scripts/python -m ruff check src tests
.venv/Scripts/python -m mypy src/m5wireless --strict

Licencia

MIT. Ver AUTHORS.md para creditos de los proyectos originales.