m5stick-wireless-viewer 3.0.0__tar.gz

m5stick_wireless_viewer-3.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

m5stick_wireless_viewer-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (editable, dev extra)
+        run: pip install -e ".[dev]"
+
+      - name: ruff check
+        run: ruff check src tests
+
+      - name: ruff format --check
+        run: ruff format --check src tests
+
+      - name: mypy --strict
+        run: mypy --strict src/m5wireless
+
+      - name: pytest (coverage)
+        run: pytest --cov=m5wireless --cov-report=term-missing
+        env:
+          CI: "true"

m5stick_wireless_viewer-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Create GitHub Release + artifacts
+        uses: softprops/action-gh-release@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # obligatorio para trusted publishing (OIDC)
+    # Solo se ejecuta cuando el repo tenga definida la variable PUBLISH_TO_PYPI=true.
+    # Antes de activar: crear el proyecto en PyPI y configurar trusted publishing
+    # (PyPI: Settings -> Publishing -> Add new publisher, repo + tag pattern v*).
+    if: vars.PUBLISH_TO_PYPI == 'true'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          pip install build twine
+          python -m build
+
+      - name: Publish to PyPI (trusted publishing, sin token manual)
+        run: twine upload --non-interactive dist/*

m5stick_wireless_viewer-3.0.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+m5wireless.db
+*.db
+*.log
+snapshots/
+logs/
+.coverage
+htmlcov/

m5stick_wireless_viewer-3.0.0/AUTHORS.md

@@ -0,0 +1,13 @@
+# Creditos
+
+Este proyecto nace de la fusion de dos repositorios previos:
+
+- `PoisonXploIT/wifi-marauder-viewer` — dashboard para logs de WiFi Marauder
+  (M5StickC/ESP32). Sus regex y logica de parseo viven en
+  `src/m5wireless/parser/marauder.py`.
+- `PoisonXploIT/Visualizacion_extendida_M5StickPlus2` — dashboard para
+  Evil-M5Project (M5Stick Plus 2) con captura serial. Su logica vive en
+  `src/m5wireless/parser/evil_m5project.py`.
+
+Los repos originales se conservan como referencia historica; este proyecto no
+reescribio su historial git, asi que el blame antiguo sigue disponible alli.

m5stick_wireless_viewer-3.0.0/Dockerfile

@@ -0,0 +1,19 @@
+# m5wireless v3.0.0 — modo file por defecto (Docker = modo secundario; la captura
+# serial en vivo se documenta como host nativo, decision del plan).
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN pip install --no-cache-dir ".[serial,web,splunk]"
+
+# El log lo aporta el volumen; se crea vacio si no existe para que `run` arranque.
+VOLUME ["/data"]
+EXPOSE 8000
+
+ENV M5W_LOG_PATH=/data/scan.log \
+    PYTHONUNBUFFERED=1
+
+CMD ["sh", "-c", "touch /data/scan.log && exec m5wireless run --source file --log-path /data/scan.log --host 0.0.0.0"]

m5stick_wireless_viewer-3.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: m5stick-wireless-viewer
+Version: 3.0.0
+Summary: Dashboard y pipeline de datos para firmwares de hardware hacking WiFi en ESP32 (Marauder, Evil-M5Project, ...)
+Author: PoisonXploIT
+License: MIT
+License-File: AUTHORS.md
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyserial>=3; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyserial; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: serial
+Requires-Dist: pyserial>=3; extra == 'serial'
+Provides-Extra: splunk
+Requires-Dist: httpx>=0.27; extra == 'splunk'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == 'web'
+Requires-Dist: uvicorn>=0.30; extra == 'web'
+Description-Content-Type: text/markdown
+
+# 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.
+
+## Estado
+
+v3.0.0 funcional: modelos, parsers, stores, fuentes, colector, dashboard web en
+vivo (SSE), export CSV/JSON, CLI unificada y Docker. Seguimiento de fases en
+`SEGUIMIENTO.md`.
+
+## Instalacion
+
+```bash
+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
+
+```bash
+# 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:
+
+```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)
+
+```bash
+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
+
+| Firmware | Estado |
+|----------|--------|
+| WiFi Marauder (M5StickC/ESP32) | Implementado |
+| Evil-M5Project (M5Stick Plus 2) | Implementado |
+| WiFi Duck, Hash Monster, PacketMonitor | Stubs documentados, pendiente de fixtures reales |
+
+## Desarrollo
+
+```bash
+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.

m5stick_wireless_viewer-3.0.0/README.md

@@ -0,0 +1,98 @@
+# 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.
+
+## Estado
+
+v3.0.0 funcional: modelos, parsers, stores, fuentes, colector, dashboard web en
+vivo (SSE), export CSV/JSON, CLI unificada y Docker. Seguimiento de fases en
+`SEGUIMIENTO.md`.
+
+## Instalacion
+
+```bash
+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
+
+```bash
+# 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:
+
+```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)
+
+```bash
+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
+
+| Firmware | Estado |
+|----------|--------|
+| WiFi Marauder (M5StickC/ESP32) | Implementado |
+| Evil-M5Project (M5Stick Plus 2) | Implementado |
+| WiFi Duck, Hash Monster, PacketMonitor | Stubs documentados, pendiente de fixtures reales |
+
+## Desarrollo
+
+```bash
+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.