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

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.