Sparkplug B MQTT Security Fuzzer

Uno strumento completo di valutazione della sicurezza per testare le implementazioni del protocollo MQTT Sparkplug B. Il fuzzer verifica sistematicamente tutti i campi del protocollo su tutti i 9 tipi di messaggio, scopre i dispositivi attivi sulla rete e genera log dettagliati per l'analisi.

Uso responsabile

Questo strumento invia messaggi MQTT malformati, di injection e che violano il protocollo a un broker target. Eseguilo solo contro sistemi di tua proprietà o per i quali hai un'autorizzazione scritta esplicita a testarli. I broker Sparkplug B si trovano comunemente in ambienti OT/ICS dove payload imprevisti possono interrompere processi fisici — presupponi che ogni target sia adiacente alla produzione finché non viene dimostrato il contrario.

Se scopri una vulnerabilità in un'implementazione Sparkplug B utilizzando questo strumento, segui la divulgazione coordinata con il vendor interessato. Per segnalare un problema di sicurezza in questo strumento stesso, consulta SECURITY.md.

Indice

Overview
Prerequisites
Installation
Quick Start
Usage
How It Works
Running the tests
Output and Log Analysis
- Log Format
- Analyzing Results
Protocol Coverage
Architecture

Panoramica

La specifica Sparkplug B definisce un namespace di argomenti (topic) e un formato di payload basati su MQTT e Google Protocol Buffers per ambienti Industrial IoT (IIoT). Questo fuzzer valuta la sicurezza e la robustezza delle implementazioni di Sparkplug B:

Verifica di tutti i 19 tipi di dati metrici con valori limite e condizioni di overflow
Iniezione di stringhe dannose (XSS, SQLi, stringhe di formato, path traversal, command injection)
Creazione di mismatch di tipo tra i datatype dichiarati e gli effettivi campi di valore protobuf
Violazione dell'ordinamento della macchina a stati del protocollo (dati prima della birth, birth doppie, dati dopo la death)
Corruzione dei payload protobuf serializzati a livello binario
Spoofing dei certificati birth/death per i dispositivi di rete scoperti
Fuzzing dei namespace dei topic MQTT con caratteri speciali, variazioni di maiuscolo/minuscolo e violazioni strutturali

Prerequisiti

Python 3.8+
Broker MQTT — il sistema target sotto test (ad es. Mosquitto, HiveMQ, EMQX, o qualsiasi broker compatibile con Sparkplug B)
Autorizzazione — questo strumento è destinato esclusivamente a test di sicurezza autorizzati

Installazione

Sui moderni sistemi Debian/Ubuntu/Kali (sistemi PEP-668), --setup non può eseguire pip install nel Python di sistema — usa prima un ambiente virtuale o pipx. Il percorso consigliato:```bash python3 -m venv .venv source .venv/bin/activate python3 sparkplug-fuzzer.py --setup

Oppure eseguilo tramite `pipx run` se preferisci non gestire tu stesso il venv. Su sistemi meno recenti senza l'imposizione di PEP-668, funziona direttamente il semplice `python3 sparkplug-fuzzer.py --setup`.

`--setup` farà quanto segue:
1. Installerà le dipendenze pip (`paho-mqtt`, `protobuf`)
2. Clonerà un tag fissato del repository [Eclipse Tahu](https://github.com/eclipse/tahu) (vedi `TAHU_REF` nello script)
3. Copierà i moduli helper `sparkplug_b.py` e `array_packer.py`
4. Compilerà `sparkplug_b.proto` in binding Python (usa `protoc` se disponibile, altrimenti ripiega su `grpcio-tools`)
5. Pulirà il clone di Tahu

Dopo l'installazione, la tua directory dovrebbe contenere:```
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

Configurazione manuale (se --setup non funziona)

```bash pip install -r requirements.txt git clone https://github.com/eclipse/tahu.git cp tahu/python/core/sparkplug_b.py . cp tahu/python/core/array_packer.py . protoc --python_out=. sparkplug_b.proto rm -rf tahu ```

Avvio rapido```bash

python3 sparkplug-fuzzer.py --setup # first-time setup python3 sparkplug-fuzzer.py -H localhost -p 1883 -v # run fuzzer

This will:
1. Collegati al broker su `localhost:1883`
2. Ascolta per 10 secondi per scoprire i dispositivi Sparkplug esistenti
3. Stabilisci il fuzzer come nodo/dispositivo Sparkplug
4. Esegui tutte le 12 categorie di fuzz (~635+ casi di test)
5. Prendi di mira qualsiasi dispositivo scoperto con messaggi spoofati
6. Scrivi i risultati in `sparkplug_fuzz.jsonl`

## Utilizzo

### Opzioni della riga di comando```
python3 sparkplug-fuzzer.py [OPTIONS]

Option	Predefinito	Descrizione
`-H`, `--host`	`localhost`	Hostname o IP del broker MQTT
`-p`, `--port`	`1883` (o `8883` con `--tls`)	Porta del broker MQTT
`-u`, `--username`	None	Nome utente MQTT (legge anche la variabile d'ambiente `MQTT_USERNAME`)
`-P`, `--password`	None	Password MQTT (legge anche `MQTT_PASSWORD`; passare `-` per leggere da stdin senza echo)
`--tls`	off	Connetti via TLS; la porta predefinita diventa `8883` se `-p` non è impostata
`--cafile`	None	Bundle CA per la verifica del certificato del server TLS
`--insecure`	off	Salta la verifica di hostname/certificato TLS (solo per test)
`-g`, `--group`	`Sparkplug B Devices`	ID del gruppo Sparkplug sotto cui il fuzzer si registra
`-n`, `--node`	`FuzzNode`	ID del nodo edge Sparkplug per il fuzzer
`-d`, `--device`	`FuzzDevice`	ID del dispositivo Sparkplug per il fuzzer
`-c`, `--categories`	`all`	Elenco separato da spazi delle categorie di fuzz da eseguire
`--discovery-time`	`10`	Secondi di ascolto passivo per la scoperta di rete
`--delay`	`0.1`	Ritardo in secondi tra i messaggi di fuzz
`--probe-anon-write`	off	Durante la scoperta, invia una pubblicazione QoS=1 per verificare se il broker accetta PUBLISH non autenticati
`-l`, `--log`	`sparkplug_fuzz.jsonl`	Nome del file di log di output (i percorsi relativi finiscono all'interno di `--output-dir`; i percorsi assoluti sono rispettati così come sono)
`--output-dir`	`./sparkplug-runs/<UTC-ts>_<host>/`	Directory di output per ogni esecuzione. Creata se assente.
`-v`, `--verbose`	0	Aumenta la verbosità della console (`-v` = info, `-vv` = debug). `-vv` mostra anche i salti dei generatori di fuzz e il logger limitato `paho.mqtt` passa a INFO/DEBUG con la verbosità.
`--setup`	—	Installa tutte le dipendenze ed esci
`--tahu-path`	—	Percorso di un clone locale di eclipse/tahu (o della sua directory `python/core`). Usato da `--setup` in ambienti air-gapped invece di `git clone`.
`--extra-string-payloads`	—	Percorso di un file di payload aggiuntivi per l'iniezione di stringhe (uno per riga, UTF-8). Accodati ai valori incorporati `STRING_FUZZ_VALUES`; non li sostituisce. Max 10 MB / 10.000 payload. Vedi Corpora di stringhe personalizzati.

sparkplugFuzzer

Più Popolari