Sparkplug B MQTT Security Fuzzer

Uma ferramenta abrangente de avaliação de segurança para testar implementações do protocolo MQTT Sparkplug B. O fuzzer testa sistematicamente todos os campos do protocolo em todos os 9 tipos de mensagem, descobre dispositivos ativos na rede e produz registos detalhados para análise.

Uso Responsável

Esta ferramenta envia mensagens MQTT malformadas, de injeção e que violam o protocolo para um broker alvo. Execute-a apenas contra sistemas que lhe pertencem ou para os quais tem autorização explícita por escrito para testar. Brokers Sparkplug B normalmente estão em ambientes OT/ICS onde cargas úteis inesperadas podem interromper processos físicos — assuma que cada alvo está adjacente à produção, salvo prova em contrário.

Se descobrir uma vulnerabilidade numa implementação do Sparkplug B usando esta ferramenta, siga a divulgação coordenada com o fornecedor afetado. Para reportar um problema de segurança nesta própria ferramenta, consulte SECURITY.md.

Índice

Visão Geral
Pré-requisitos
Instalação
Início Rápido
Utilização
Como Funciona
Executar os Testes
Saída e Análise de Registos
- Formato do Registo
- Analisar Resultados
Cobertura do Protocolo
Arquitetura

Visão Geral

A especificação Sparkplug B define um espaço de nomes de tópicos e um formato de carga útil baseado em MQTT e Google Protocol Buffers para ambientes de IIoT (Internet Industrial das Coisas). Este fuzzer avalia a segurança e robustez de implementações do Sparkplug B através de:

Testar todos os 19 tipos de dados métricos com valores limite e condições de overflow
Injetar strings maliciosas (XSS, SQLi, format strings, path traversal, command injection)
Criar incompatibilidades de tipo entre tipos de dados declarados e os campos de valor reais do protobuf
Violar a ordenação da máquina de estados do protocolo (dados antes do birth, births duplicados, dados após death)
Corromper cargas úteis serializadas do protobuf ao nível binário
Falsificar certificados de birth/death para dispositivos descobertos na rede
Fuzzing de espaços de nomes de tópicos MQTT com caracteres especiais, variações de maiúsculas/minúsculas e violações estruturais

Pré-requisitos

Python 3.8+
MQTT Broker — o sistema alvo em teste (ex: Mosquitto, HiveMQ, EMQX, ou qualquer broker compatível com Sparkplug B)
Autorização — esta ferramenta destina-se apenas a testes de segurança autorizados

Instalação

Em sistemas Debian/Ubuntu/Kali modernos (sistemas PEP-668), --setup não pode executar pip install no Python do sistema — use um ambiente virtual ou pipx primeiro. O caminho recomendado:```bash python3 -m venv .venv source .venv/bin/activate python3 sparkplug-fuzzer.py --setup

Ou execute via `pipx run` se preferir não gerenciar o venv manualmente. Em sistemas mais antigos sem a imposição do PEP-668, o comando `python3 sparkplug-fuzzer.py --setup` funciona diretamente.

O `--setup` irá:
1. Instalar dependências pip (`paho-mqtt`, `protobuf`)
2. Clonar uma tag fixada do repositório [Eclipse Tahu](https://github.com/eclipse/tahu) (veja `TAHU_REF` no script)
3. Copiar os módulos auxiliares `sparkplug_b.py` e `array_packer.py`
4. Compilar `sparkplug_b.proto` para bindings Python (usa `protoc` se disponível, caso contrário recorre ao `grpcio-tools`)
5. Limpar o clone do Tahu

Após a configuração, seu diretório deve conter:```
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

Configuração manual (if --setup doesn't work)

```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 ```

Início Rápido```bash

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

Isto irá:
1. Conectar-se ao broker em `localhost:1883`
2. Ouvir por 10 segundos para descobrir dispositivos Sparkplug existentes
3. Estabelecer o fuzzer como um nó/dispositivo Sparkplug
4. Executar todas as 12 categorias de fuzz (~635+ casos de teste)
5. Visar quaisquer dispositivos descobertos com mensagens falsificadas
6. Escrever resultados em `sparkplug_fuzz.jsonl`

## Uso

### Opções da Linha de Comando```
python3 sparkplug-fuzzer.py [OPTIONS]

Opção	Padrão	Descrição
`-H`, `--host`	`localhost`	Nome do host ou IP do broker MQTT
`-p`, `--port`	`1883` (ou `8883` com `--tls`)	Porta do broker MQTT
`-u`, `--username`	None	Nome de usuário MQTT (também lê a variável de ambiente `MQTT_USERNAME`)
`-P`, `--password`	None	Senha MQTT (também lê `MQTT_PASSWORD`; passe `-` para ler do stdin sem eco)
`--tls`	off	Conectar via TLS; a porta padrão se torna `8883` se `-p` não for definido
`--cafile`	None	Pacote CA para verificação do certificado do servidor TLS
`--insecure`	off	Pular verificação de hostname/certificado TLS (apenas para teste)
`-g`, `--group`	`Sparkplug B Devices`	ID do grupo Sparkplug sob o qual o fuzzer se registra
`-n`, `--node`	`FuzzNode`	ID do nó de borda Sparkplug para o fuzzer
`-d`, `--device`	`FuzzDevice`	ID do dispositivo Sparkplug para o fuzzer
`-c`, `--categories`	`all`	Lista separada por espaços das categorias de fuzz a executar
`--discovery-time`	`10`	Segundos para escutar passivamente a descoberta de rede
`--delay`	`0.1`	Atraso em segundos entre mensagens de fuzz
`--probe-anon-write`	off	Durante a descoberta, enviar uma publicação QoS=1 para confirmar se o broker aceita PUBLISH não autenticado
`-l`, `--log`	`sparkplug_fuzz.jsonl`	Nome do arquivo de log de saída (caminhos relativos ficam dentro de `--output-dir`; caminhos absolutos são mantidos como estão)
`--output-dir`	`./sparkplug-runs/<UTC-ts>_<host>/`	Diretório de saída por execução. Criado se ausente.
`-v`, `--verbose`	0	Aumentar a verbosidade do console (`-v` = info, `-vv` = debug). `-vv` também mostra pulos do gerador de fuzz, e o logger `paho.mqtt` com limitação sobe para INFO/DEBUG com verbosidade.
`--setup`	—	Instalar todas as dependências e sair
`--tahu-path`	—	Caminho para um clone local de eclipse/tahu (ou seu diretório `python/core`). Usado por `--setup` em ambientes sem rede em vez de `git clone`.
`--extra-string-payloads`	—	Caminho para um arquivo de payloads adicionais de injeção de string (um por linha, UTF-8). Anexado à `STRING_FUZZ_VALUES` incorporada; não a substitui. Máx. 10 MB / 10.000 payloads. Veja Corpora de string personalizados.

sparkplugFuzzer

Mais Populares