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

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]

**Passe credenciais sem expô-las em `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 -

**Avaliação passiva de autenticação + sonda de escrita ativa:**```bash
python3 sparkplug-fuzzer.py -H 10.0.1.30 --probe-anon-write -v

**Descoberta estendida com ritmo lento (minimizar carga do broker):**```bash
python3 sparkplug-fuzzer.py -H 192.168.1.100 --discovery-time 60 --delay 0.5

**Monitore o tráfego do broker em um terminal separado:**```bash
mosquitto_sub -h <broker_host> -p 1883 -t 'spBv1.0/#' -F '%I %t %x'

**Layout de saída por execução:**```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

O fuzzer imprime `[+] Extra string payloads: loaded N from <path>` na inicialização, e cada payload é emitida através de todos os lugares que iteram `STRING_FUZZ_VALUES` — principalmente a categoria `string`, mas também os casos de tipos de string do gerador de incompatibilidade de tipos.

Limites fixos: 10 MB de tamanho de arquivo, 10.000 payloads. Ajuste `MAX_EXTRA_PAYLOADS_FILE_SIZE` / `MAX_EXTRA_PAYLOADS_COUNT` no topo do script se precisar de mais (e tiver orçamento de tempo de execução compatível).

## v0.2 release notes

- Sinalizador `--output-dir` mais padrão `./sparkplug-runs/<UTC-ts>_<host>/` criado automaticamente — cada execução cai em seu próprio diretório para que artefatos não colidam entre execuções.
- Sinalizador `--tahu-path` para `--setup` — aponta para um clone local de `eclipse/tahu` para ambientes de teste isolados onde `git clone` de saída é bloqueado. A fonte local nunca é excluída na limpeza.
- Carimbos de data/hora do console + JSONL forçados para UTC com sufixo `Z` explícito para que a correlação cruzada com logs do broker seja livre de aritmética de fuso horário.
- Logger `paho.mqtt` limitado a WARNING por padrão; visível em INFO com `-v`, DEBUG com `-vv`. A telemetria do cliente por pacote não afoga mais o sinal de fuzz.
- Test harness pytest em `tests/` — 23 testes cobrindo FuzzLogger, auxiliar de tópico, resolução de caminho de saída e validação de `--tahu-path`. Veja [Running the tests](#running-the-tests).

## Running the tests

O test harness cobre a superfície independente de rede (correção do logger, construtor de tópicos, resolução de caminho de saída, análise de `--tahu-path`) e é executado sem um broker, paho-mqtt ou protobuf instalados.```bash
pip install -r requirements-dev.txt
pytest tests/

### Descoberta de Rede

Durante a fase de descoberta, o fuzzer assina `spBv1.0/#` e escuta todo o tráfego Sparkplug. O componente `DeviceTracker` analisa as mensagens observadas para construir um mapa de rede ativo:

- Mensagens **NBIRTH** revelam nós de borda e suas definições de métricas (nome, alias, tipo de dado)
- Mensagens **DBIRTH** revelam dispositivos e seus esquemas de métricas
- Mensagens **NDEATH/DDEATH** rastreiam o estado do ciclo de vida do nó/dispositivo
- Mensagens **STATE** revelam aplicações host e seu status online/offline

Este mapa é usado na fase de fuzzing direcionado para enviar ataques contextualmente relevantes contra dispositivos reais com seus esquemas de métricas reais.

### Avaliação de Autenticação

Quando o fuzzer se conecta sem `-u/-P` (e `MQTT_USERNAME`/`MQTT_PASSWORD` não estão definidos), ele deriva uma postura de autenticação do broker apenas a partir da descoberta passiva. Isso produz um único evento `AUTH_ASSESSMENT` no log e um resumo impresso:

| Sinal | O que significa | Como é derivado |
|---|---|---|
| `anon_connect_accepted` | Broker aceitou CONNECT sem credenciais | O próprio CONNECT do fuzzer foi bem-sucedido |
| `anon_subscribe_accepted` | Broker encaminha `spBv1.0/#` / `STATE/#` para clientes anônimos | Pelo menos uma mensagem RX chegou durante a janela de escuta |
| `anon_publish_accepted` | Broker aceita PUBLISH de clientes anônimos | Definido apenas se `--probe-anon-write` for passado; sonda QoS=1 + espera por PUBACK |
| `unauth_endpoints` | Nós / dispositivos / aplicações host observáveis sem autenticação | Cada entidade no mapa de rede descoberto (autenticação nunca foi produzida) |

A sonda QoS=1 é opt-in porque ela passa de passiva para ativa. Com QoS=0 o broker descarta silenciosamente mensagens que negaria, então confirmar aceitação de escrita requer a leitura de um PUBACK.

MQTT/Sparkplug não possuem autenticação por endpoint — a autenticação é uma preocupação no nível do broker. Portanto, "endpoints observáveis sem autenticação" é relatado como uma lista de *alvos alcançáveis a custo zero*, em vez de uma propriedade dos próprios endpoints.

### Fuzzing Direcionado

Após o fuzzing sistemático, a ferramenta direciona cada dispositivo descoberto com:

1. **Avisos de falecimento falsificados** — publica NDEATH/DDEATH para enganar assinantes fazendo-os pensar que os dispositivos ficaram offline
2. **Certidões de nascimento falsificadas** — publica NBIRTH/DBIRTH para se passar por nós/dispositivos descobertos
3. **Injeção de comandos** — envia mensagens NCMD/DCMD com valores limite para cada métrica conhecida, testando se o alvo valida comandos de entrada
4. **Comandos de renascimento** — envia comando `Node Control/Rebirth` NCMD para forçar os dispositivos a republicarem seus nascimentos

## Saída e Análise de Log

### Formato do Log

O arquivo de log usa o formato JSON-lines (`.jsonl`) — um objeto JSON por linha, adequado para análise com `jq`, Python ou qualquer ferramenta compatível com JSON.

Payloads maiores que 64 KiB não são hex-inline; em vez disso, `payload_hex` carrega `sha256:<digest>+len=<n>` para que o log permaneça limitado para casos de fuzz muito grandes. `payload_len` está sempre presente.

**Registro TX** (mensagem de fuzz de saída):```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 evento** (evento do 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}
}

**Extraia todos os casos de injeção de string:**```bash
jq 'select(.category == "string")' sparkplug_fuzz.jsonl

**Encontre casos que acionaram desconexões do broker:**```bash
jq 'select(.event == "UNEXPECTED_DISCONNECT" or .event == "RECONNECT_FAIL")' sparkplug_fuzz.jsonl

**Liste endpoints acessíveis sem autenticação:**```bash
jq -r 'select(.event == "AUTH_ASSESSMENT") | .details.unauth_endpoints[] | [.kind, .group, .node, .device, .host_id, .status] | @tsv' sparkplug_fuzz.jsonl

**Exportar todos os tópicos que foram publicados para:**```bash
jq -r 'select(.dir == "TX") | .topic' sparkplug_fuzz.jsonl | sort -u

## Cobertura de Protocolo

### Tipos de Mensagem

Todos os 9 tipos de mensagem Sparkplug B são testados:

| Tipo de Mensagem | Padrão de Tópico | Descrição | Uso do Fuzzer |
|---|---|---|---|
| NBIRTH | `spBv1.0/{group}/NBIRTH/{node}` | Certificado de nascimento do nó | Estabelece presença do fuzzer; falsificado para nós descobertos; testes de ordenação |
| NDEATH | `spBv1.0/{group}/NDEATH/{node}` | Notificação de morte do nó | Última vontade MQTT; falsificado para nós descobertos; testes de ordenação |
| DBIRTH | `spBv1.0/{group}/DBIRTH/{node}/{device}` | Certificado de nascimento do dispositivo | Estabelece dispositivo do fuzzer; falsificado para dispositivos descobertos; testes de ordenação |
| DDEATH | `spBv1.0/{group}/DDEATH/{node}/{device}` | Notificação de morte do dispositivo | Falsificado para dispositivos descobertos; testes de ordenação; testes de órfãos |
| NDATA | `spBv1.0/{group}/NDATA/{node}` | Atualização de dados do nó | Valores limite; números de sequência; testes de ordenação |
| DDATA | `spBv1.0/{group}/DDATA/{node}/{device}` | Atualização de dados do dispositivo | Meio principal para a maioria das categorias de fuzzing |
| NCMD | `spBv1.0/{group}/NCMD/{node}` | Comando do nó | Fuzzing direcionado (comandos de renascimento); testes de órfãos |
| DCMD | `spBv1.0/{group}/DCMD/{node}/{device}` | Comando do dispositivo | Fuzzing direcionado contra métricas de dispositivos descobertos; testes de órfãos |
| STATE | `STATE/{host_id}` | Estado da aplicação hospedeira (JSON) | Injeção de JSON malformado |

### Tipos de Dados

Todos os 19 tipos de dados métricos Sparkplug B são testados com valores limite específicos para cada tipo:

| Código | Tipo | Campo Protobuf | Valores Limite Testados |
|------|------|---------------|----------------------|
| 1 | Int8 | int_value | 0, -128, 127, 128 (estouro), -129 (subfluxo) |
| 2 | Int16 | int_value | 0, -32768, 32767, estouro/subfluxo |
| 3 | Int32 | int_value | 0, -2^31, 2^31-1, estouro/subfluxo |
| 4 | Int64 | long_value | 0, -2^63, 2^63-1, estouro |
| 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 | Booleano | boolean_value | True, False; também testado com valores inteiros brutos (0, 1, 2, 255) |
| 12 | String | string_value | Vazio, longo (até 64KB), cargas de injeção |
| 13 | DateTime | long_value | Epoch, max, futuro/passado distante |
| 14 | Texto | string_value | Mesmas cargas de injeção que String |
| 15 | UUID | string_value | Vazio, válido, formato inválido, injeções |
| 16 | DataSet | dataset_value | Violações estruturais via categoria de dataset |
| 17 | Bytes | bytes_value | Vazio, bytes nulos, aleatório, grande |
| 18 | Arquivo | bytes_value | Vazio, bytes mágicos, grande |
| 19 | Template | template_value | Referências indefinidas, templates órfãos |

### Cobertura de Campos

O fuzzer cobre mais de 87 caminhos de campos protobuf únicos, incluindo:

- **Campos raiz do payload**: timestamp, seq, uuid, body, metrics
- **Campos de métrica**: name, alias, timestamp, datatype, is_historical, is_transient, is_null, metadata, properties, e todas as variantes oneof de value
- **Campos de MetaData**: is_multi_part, content_type, size, seq, file_name, file_type, md5, description
- **PropertySet/PropertyValue**: keys, values, type, is_null, propertyset_value recursivo, propertysets_value
- **DataSet**: num_of_columns, columns, types, rows, elements, todas as variantes de DataSetValue
- **Template**: version, template_ref, is_definition, métricas aninhadas, parameters

## Arquitetura

O fuzzer é um único arquivo Python organizado nestes componentes:```
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