O ejecútalo mediante `pipx run` si prefieres no gestionar el venv tú mismo. En sistemas antiguos sin la política PEP-668, `python3 sparkplug-fuzzer.py --setup` funciona directamente.

`--setup` hará lo siguiente:
1. Instalar las dependencias pip (`paho-mqtt`, `protobuf`)
2. Clonar una versión fija (tag) del repositorio [Eclipse Tahu](https://github.com/eclipse/tahu) (consulta `TAHU_REF` en el script)
3. Copiar los módulos auxiliares `sparkplug_b.py` y `array_packer.py`
4. Compilar `sparkplug_b.proto` en bindings de Python (usa `protoc` si está disponible; si no, recurre a `grpcio-tools`)
5. Limpiar el clon de Tahu

Después de la configuración, tu directorio debería contener:```
sparkplug-fuzzer.py     # The fuzzer
sparkplug_b.py          # Sparkplug B helper module (from Tahu)
array_packer.py         # Array packing helper (from Tahu)
sparkplug_b_pb2.py      # Generated protobuf bindings
requirements.txt        # Python dependencies

Esto:
1. Se conectará al broker en `localhost:1883`
2. Escuchará durante 10 segundos para descubrir dispositivos Sparkplug existentes
3. Establecerá el fuzzer como un nodo/dispositivo Sparkplug
4. Ejecutará las 12 categorías de fuzzing (~635+ casos de prueba)
5. Apuntará a cualquier dispositivo descubierto con mensajes falsificados
6. Escribirá los resultados en `sparkplug_fuzz.jsonl`

## Uso

### Opciones de línea de comandos```
python3 sparkplug-fuzzer.py [OPTIONS]

**Pasa las credenciales sin exponerlas en `ps`:**```bash
# Via environment
MQTT_USERNAME=admin MQTT_PASSWORD=secret python3 sparkplug-fuzzer.py -H broker.local

# Or read password from stdin (getpass — no echo)
python3 sparkplug-fuzzer.py -H broker.local -u admin -P -

**Evaluación pasiva de autenticación + sonda activa de escritura:**```bash
python3 sparkplug-fuzzer.py -H 10.0.1.30 --probe-anon-write -v

**Descubrimiento extendido con ritmo lento (minimizar la carga del broker):**```bash
python3 sparkplug-fuzzer.py -H 192.168.1.100 --discovery-time 60 --delay 0.5

**Monitoriza el tráfico del broker en una terminal separada:**```bash
mosquitto_sub -h <broker_host> -p 1883 -t 'spBv1.0/#' -F '%I %t %x'

**Diseño de salida por ejecución:**```bash
# Default — directory is auto-named under ./sparkplug-runs/
python3 sparkplug-fuzzer.py -H broker.local
# -> creates ./sparkplug-runs/2026-05-05_1830_broker.local/sparkplug_fuzz.jsonl

# Explicit directory:
python3 sparkplug-fuzzer.py -H broker.local --output-dir ./fuzz-runs/acme-2026Q2

El fuzzer imprime `[+] Extra string payloads: loaded N from <path>` al inicio, y cada payload se emite a través de todos los lugares que iteran `STRING_FUZZ_VALUES` — principalmente la categoría `string`, pero también los casos de tipo cadena del generador de desajuste de tipos.

Límites estrictos: 10 MB de tamaño de archivo, 10,000 payloads. Ajusta `MAX_EXTRA_PAYLOADS_FILE_SIZE` / `MAX_EXTRA_PAYLOADS_COUNT` en la parte superior del script si necesitas más (y dispones del presupuesto de tiempo de ejecución necesario).

## Notas de la versión v0.2

- La opción `--output-dir` y el valor predeterminado `./sparkplug-runs/<UTC-ts>_<host>/` que se crea automáticamente — cada ejecución se ubica en su propio directorio para que los artefactos no colisionen entre ejecuciones.
- La opción `--tahu-path` para `--setup` — apunta a un clon local de `eclipse/tahu` para entornos de prueba aislados de la red donde el `git clone` saliente está bloqueado. El código fuente local nunca se elimina en la limpieza.
- Marcas de tiempo de consola y JSONL forzadas a UTC con sufijo `Z` explícito, de modo que la correlación cruzada con los registros del broker no requiere aritmética de zonas horarias.
- El logger de `paho.mqtt` se limita a WARNING de forma predeterminada; visible en INFO con `-v`, DEBUG con `-vv`. La telemetría del cliente por paquete ya no ahoga la señal de fuzz.
- Banco de pruebas pytest en `tests/` — 23 pruebas que cubren FuzzLogger, el helper de topics, la resolución de rutas de salida y la validación de `--tahu-path`. Consulta [Ejecución de las pruebas](#running-the-tests).

## Ejecución de las pruebas

El banco de pruebas cubre la superficie independiente de la red (corrección del logger, constructor de topics, resolución de la ruta de salida, parseo de `--tahu-path`) y se ejecuta sin tener instalados un broker, paho-mqtt o protobuf.```bash
pip install -r requirements-dev.txt
pytest tests/

### Descubrimiento de red

Durante la fase de descubrimiento, el fuzzer se suscribe a `spBv1.0/#` y escucha todo el tráfico Sparkplug. El componente `DeviceTracker` analiza los mensajes observados para construir un mapa de red en vivo:

- **NBIRTH** revela nodos de borde y sus definiciones de métricas (nombre, alias, tipo de dato)
- **DBIRTH** revela dispositivos y sus esquemas de métricas
- **NDEATH/DDEATH** rastrea el estado del ciclo de vida de nodos/dispositivos
- **STATE** revela aplicaciones host y su estado en línea/fuera de línea

Este mapa se utiliza en la fase de fuzzing dirigido para enviar ataques contextualmente relevantes contra dispositivos reales con sus esquemas de métricas reales.

### Evaluación de autenticación

Cuando el fuzzer se conecta sin `-u/-P` (y `MQTT_USERNAME`/`MQTT_PASSWORD` no están configurados), deduce la postura de autenticación del broker únicamente a partir del descubrimiento pasivo. Esto produce un único evento `AUTH_ASSESSMENT` en el registro y un resumen impreso:

| Señal | Qué significa | Cómo se deduce |
|---|---|---|
| `anon_connect_accepted` | El broker aceptó CONNECT sin credenciales | El propio CONNECT del fuzzer tuvo éxito |
| `anon_subscribe_accepted` | El broker reenvía `spBv1.0/#` / `STATE/#` a clientes anónimos | Al menos un mensaje RX llegó durante la ventana de escucha |
| `anon_publish_accepted` | El broker acepta PUBLISH de clientes anónimos | Solo se establece si se pasa `--probe-anon-write`; sonda QoS=1 + espera de PUBACK |
| `unauth_endpoints` | Nodos / dispositivos / aplicaciones host observables sin autenticación | Cada entidad en el mapa de red descubierto (la autenticación nunca se produjo) |

La sonda QoS=1 es opcional porque cruza de pasiva a activa. Con QoS=0 el broker descarta silenciosamente los mensajes que denegaría, por lo que confirmar la aceptación de escritura requiere leer un PUBACK.

MQTT/Sparkplug no tienen autenticación por endpoint: la autenticación es una preocupación a nivel de broker. Por lo tanto, "endpoints observables sin autenticación" se informa como una lista de *objetivos alcanzables a coste cero* en lugar de una propiedad de los propios endpoints.

### Fuzzing dirigido

Después del fuzzing sistemático, la herramienta apunta a cada dispositivo descubierto con:

1. **Avisos de muerte falsificados** — publica NDEATH/DDEATH para engañar a los suscriptores haciéndoles creer que los dispositivos se desconectaron
2. **Certificados de nacimiento falsificados** — publica NBIRTH/DBIRTH para suplantar nodos/dispositivos descubiertos
3. **Inyección de comandos** — envía mensajes NCMD/DCMD con valores límite para cada métrica conocida, probando si el objetivo valida los comandos entrantes
4. **Comandos de renacimiento** — envía NCMD `Node Control/Rebirth` para provocar que los dispositivos vuelvan a publicar sus nacimientos

## Análisis de salida y registros

### Formato de registro

El archivo de registro utiliza formato JSON-lines (`.jsonl`): un objeto JSON por línea, adecuado para el análisis con `jq`, Python o cualquier herramienta compatible con JSON.

Los payloads de más de 64 KiB no se incluyen como hex; en su lugar, `payload_hex` lleva `sha256:<digest>+len=<n>` para que el registro se mantenga acotado en casos de fuzzing muy grandes. `payload_len` siempre está presente.

**TX record** (mensaje de fuzzing saliente):```json
{
  "ts": "2026-04-10T15:30:00.123456Z",
  "dir": "TX",
  "case_id": "BOUNDARY-0042",
  "category": "boundary",
  "topic": "spBv1.0/Sparkplug B Devices/DDATA/FuzzNode/FuzzDevice",
  "payload_hex": "0800120a0a06...",
  "payload_len": 28,
  "payload_decoded": {"timestamp": 1712345678000, "metrics": [{"name": "fuzz/boundary/Int32", "datatype": 3, "int_value": 2147483647}]},
  "description": "Boundary Int32 = 2147483647 (int_value)"
}

**Registro de eventos** (evento del sistema):```json
{
  "ts": "2026-04-10T15:29:50.000000Z",
  "dir": "EVENT",
  "event": "DISCOVERY_COMPLETE",
  "details": {"groups": ["Production"], "node_count": 3, "device_count": 7, "targets": 10}
}

**Extrae todos los casos de inyección de cadenas:**```bash
jq 'select(.category == "string")' sparkplug_fuzz.jsonl

**Encontrar casos que provocaron desconexiones del broker:**```bash
jq 'select(.event == "UNEXPECTED_DISCONNECT" or .event == "RECONNECT_FAIL")' sparkplug_fuzz.jsonl

**Lista los endpoints accesibles sin autenticación:**```bash
jq -r 'select(.event == "AUTH_ASSESSMENT") | .details.unauth_endpoints[] | [.kind, .group, .node, .device, .host_id, .status] | @tsv' sparkplug_fuzz.jsonl

**Exportar todos los temas publicados en:**```bash
jq -r 'select(.dir == "TX") | .topic' sparkplug_fuzz.jsonl | sort -u

## Protocol Coverage

### Message Types

All 9 Sparkplug B message types are tested:

| Message Type | Topic Pattern | Description | Fuzzer Usage |
|---|---|---|---|
| NBIRTH | `spBv1.0/{group}/NBIRTH/{node}` | Node birth certificate | Establishes fuzzer presence; spoofed for discovered nodes; ordering tests |
| NDEATH | `spBv1.0/{group}/NDEATH/{node}` | Node death notification | MQTT last-will; spoofed for discovered nodes; ordering tests |
| DBIRTH | `spBv1.0/{group}/DBIRTH/{node}/{device}` | Device birth certificate | Establishes fuzzer device; spoofed for discovered devices; ordering tests |
| DDEATH | `spBv1.0/{group}/DDEATH/{node}/{device}` | Device death notification | Spoofed for discovered devices; ordering tests; orphan tests |
| NDATA | `spBv1.0/{group}/NDATA/{node}` | Node data update | Boundary values; sequence numbers; ordering tests |
| DDATA | `spBv1.0/{group}/DDATA/{node}/{device}` | Device data update | Primary vehicle for most fuzz categories |
| NCMD | `spBv1.0/{group}/NCMD/{node}` | Node command | Targeted fuzzing (rebirth commands); orphan tests |
| DCMD | `spBv1.0/{group}/DCMD/{node}/{device}` | Device command | Targeted fuzzing against discovered device metrics; orphan tests |
| STATE | `STATE/{host_id}` | Host application state (JSON) | Malformed JSON injection |

### Data Types

All 19 Sparkplug B metric data types are tested with type-specific boundary values:

| Code | Type | Protobuf Field | Boundary Values Tested |
|------|------|---------------|----------------------|
| 1 | Int8 | int_value | 0, -128, 127, 128 (overflow), -129 (underflow) |
| 2 | Int16 | int_value | 0, -32768, 32767, overflow/underflow |
| 3 | Int32 | int_value | 0, -2^31, 2^31-1, overflow/underflow |
| 4 | Int64 | long_value | 0, -2^63, 2^63-1, overflow |
| 5 | UInt8 | int_value | 0, 255, 256, -1 |
| 6 | UInt16 | int_value | 0, 65535, 65536, -1 |
| 7 | UInt32 | int_value | 0, 4294967295, -1 |
| 8 | UInt64 | long_value | 0, 2^64-1, -1 |
| 9 | Float | float_value | 0.0, -0.0, max, min, inf, -inf, NaN |
| 10 | Double | double_value | 0.0, -0.0, max, min, inf, -inf, NaN |
| 11 | Boolean | boolean_value | True, False; also tested with raw int values (0, 1, 2, 255) |
| 12 | String | string_value | Empty, long (up to 64KB), injection payloads |
| 13 | DateTime | long_value | Epoch, max, far future/past |
| 14 | Text | string_value | Same injection payloads as String |
| 15 | UUID | string_value | Empty, valid, invalid format, injections |
| 16 | DataSet | dataset_value | Structural violations via dataset category |
| 17 | Bytes | bytes_value | Empty, null bytes, random, large |
| 18 | File | bytes_value | Empty, magic bytes, large |
| 19 | Template | template_value | Undefined references, orphan templates |

### Field Coverage

The fuzzer covers 87+ unique protobuf field paths including:

- **Payload root fields**: timestamp, seq, uuid, body, metrics
- **Metric fields**: name, alias, timestamp, datatype, is_historical, is_transient, is_null, metadata, properties, and all value oneof variants
- **MetaData fields**: is_multi_part, content_type, size, seq, file_name, file_type, md5, description
- **PropertySet/PropertyValue**: keys, values, type, is_null, recursive propertyset_value, propertysets_value
- **DataSet**: num_of_columns, columns, types, rows, elements, all DataSetValue variants
- **Template**: version, template_ref, is_definition, nested metrics, parameters

## Architecture

The fuzzer is a single Python file organized into these components:```
sparkplug-fuzzer.py
    |
    +-- Constants / ALL_METRIC_TYPES / STRING_FUZZ_VALUES
    |       Type definitions and fuzz value tables
    |
    +-- FuzzLogger
    |       JSON-lines file logging + console output
    |       Protobuf payload decoding
    |
    +-- DeviceTracker
    |       Passive network discovery
    |       Tracks groups, nodes, devices, metrics
    |
    +-- PayloadBuilder
    |       Valid payload construction (sparkplug_b helpers)
    |       Raw payload construction (sparkplug_b_pb2 direct)
    |       Binary corruption (truncate, flip, append)
    |
    +-- 12 Fuzz Generators
    |       Each is a Python generator yielding (topic, bytes, desc)
    |       Covers boundary, string, type, seq, timestamp, alias,
    |       orphan, ordering, recursive, dataset, malformed, topic
    |
    +-- SparkplugFuzzer
    |       Orchestration: connect, discover, fuzz, target, report
    |       Centralized publish with logging
    |       Auto-reconnect on disconnect
    |
    +-- CLI (argparse) + main()
            Argument parsing and entry point