This is a test setup to apply protocol state fuzzing to Zigbee coordinators and stacks. It is built upon the ProtocolState-Fuzzer framework and can be used to either test a hardware IEEE 802.15.4 adapter over-the-air or to test a Zigbee-on-Host (or ZBOSS) stack in a Linux process.
src/contains code that configures ProtocolState-Fuzzer (PSF) and acts as a bridge between PSF and the mapper. This is done using jep, which allows embedding a CPython interpreter in a Java process.py/contains the mapper.ZigbeeSULuses Scapy to construct and parse IEEE 802.15.4 / Zigbee packets. The radio or stack is selected inpy/config.yaml(driver_type:hardware,zoh, orzboss).experiments/alphabets/contains different alphabets (subsets of Zigbee packet types) that can be used for testing. Useassociation-nwkEntering.xmlfor learning; it matches the symbols the mapper implements.experiments/args/contains test configurations (lists of PSF arguments) for setups that have already been used.experiments/results/contains results after tests have been run.experiments/tests/contains test sequences of interest (e.g., replaying specific sequences to reproduce bugs).scripts/contains miscellaneous scripts for resetting targets and setting up the Python environment.
A Linux environment is required. The Python virtual environment does not install Maven or the JDK.
| Tool | Why |
|---|---|
| Java 21 JDK | Compile and run the shaded jar |
| Maven | Build the project (mvn package) |
| Python 3 | Mapper runtime and Scapy packet parsing |
| libffi & C++ compiler | Compile cffi and jep native extensions |
graphviz (dot) |
Export learned Mealy machine models to PDF |
git clone https://github.com/elisavetpapadopoulou/zigbee-fuzzer.gitsudo apt install -y openjdk-21-jdk maven graphviz python3 python3-venv python3-pip python3-dev libffi-dev g++Ensure toolchains are accessible and Maven points to Java 21:
java -version
mvn -version
python3 --version
dot -Vmvn -version must report runtime Java version: 21.
JEP compiles native C bindings during installation and requires JAVA_HOME pointing to a JDK:
export JAVA_HOME="$(dirname "$(dirname "$(readlink -f "$(which java)")")")"echo "$JAVA_HOME"
# Expected output similar to: /usr/lib/jvm/java-21-openjdk-amd64Run the setup script from the repository root to create the local virtual environment (venv/) and build dependencies (including jep 4.3.2 and pycryptodomex):
source scripts/setup_venv.shBuild the shaded executable jar (the virtual environment can stay active; Maven does not interfere with it):
mvn packageThe compiled artifact is generated at target/zigbee-fuzzer-1.0-SNAPSHOT.jar.
Target selection is controlled through py/config.yaml. driver_type is what selects the SUT, not the Java flags.
| Field | Description |
|---|---|
driver_type |
zoh (default), hardware, or zboss |
zoh_host / zoh_port |
TCP server address bound by the fuzzer (default 127.0.0.1:6000) |
zoh_mac |
Coordinator IEEE address expected by the mapper (0x6c63696c63696c63) |
zoh_timeout |
Seconds to wait for stack responses before timing out |
zoh_restart_cmd |
Command executed to reset/form ZOH between queries (scripts/restartZOHStack.sh) |
hardware_mac |
Coordinator IEEE for over-the-air hardware runs |
hardware_port |
Reference port; the serial device actually opened is passed via Java -adapter |
baud_rate / channel |
Adapter UART baud rate and 802.15.4 radio channel (default 115200, channel 20) |
hardware_restart_cmd |
Command executed to reset the hardware coordinator between queries |
- Always specify
-alphabet experiments/alphabets/association-nwkEntering.xml. Do not omit it, as default fallback symbols are not implemented by the mapper. - Java command-line flags require
-adapterand-connect. Whendriver_typeiszoh, pass dummy strings (e.g.,-adapter unused -connect unused).
Zigbee-on-Host (ZOH) allows software testing without physical RF hardware by having the stack connect to the fuzzer over a local TCP socket (127.0.0.1:6000).
-
Clone ZOH and checkout the verified commit: (See zigbee-on-host github for more information)
git clone https://github.com/Nerivec/zigbee-on-host.git
cd zigbee-on-hostgit checkout fab65af
npm install
npm run build
-
Configure the virtual socket adapter: Edit
dist/dev/conf.json's adapter path field so ZOH connects to the fuzzer's TCP bridge:vi dist/dev/conf.json
... "adapter": { "path": "tcp://127.0.0.1:6000" } ... -
Export the path in your shell: Return to
zigbee-fuzzerand pointZOH_ROOTto your cloned tree:export ZOH_ROOT=/path/to/zigbee-on-host
Replay a short association test sequence from the fuzzer repository root. This checks JEP, Python imports, and that ZOH joins and exchanges frames with the fuzzer:
source scripts/setup_venv.sh
java -jar target/zigbee-fuzzer-1.0-SNAPSHOT.jar @experiments/args/zoh_args \
-test experiments/tests/simple_hw_test.txt \
-times 1-
Short learning trial (capped rounds):
mkdir -p experiments/results/zoh-smoke java -jar target/zigbee-fuzzer-1.0-SNAPSHOT.jar @experiments/args/zoh_args \ -output experiments/results/zoh-smoke \ -roundLimit 4
-
Full learning run:
mkdir -p experiments/results/zoh java -jar target/zigbee-fuzzer-1.0-SNAPSHOT.jar @experiments/args/zoh_args \ -output experiments/results/zoh
Hardware testing requires:
- An IEEE 802.15.4 USB adapter for packet injection (default baud 115200).
- A physical coordinator on channel 20 (matching
py/config.yaml) with its IEEE configured inhardware_mac.
Edit py/config.yaml:
driver_type: "hardware"
hardware_mac: 0x00124b003a053efe # Set to coordinator IEEE
channel: 20 # Set to the coordinator's channelIf using scripts/restartSonoffCoord.sh for coordinator resets:
export HARDWARE_SETUP=/absolute/path/to/hardware_setup
export SONOFF_PORT=/dev/ttyUSB0Locate the injection adapter device:
ls /dev/ttyACM* /dev/serial/by-id/*From the repository root:
source scripts/setup_venv.sh
java -jar target/zigbee-fuzzer-1.0-SNAPSHOT.jar @experiments/args/hw_args \
-adapter /dev/ttyACM0 \
-output experiments/results/hardware_trial \
-roundLimit 4In the -output directory, ProtocolState-Fuzzer writes:
| File | Description |
|---|---|
learnedModel.dot |
Final learned state machine hypothesis |
hyp1.dot, hyp2.dot, … |
Intermediate hypotheses generated per learning round |
statistics.txt |
Query counts, cache performance, and runtime timing |
alphabet.xml |
Snapshot of the alphabet configuration used |
command.args |
Copy of the command-line flags for reproducibility |
error.msg |
Error details if a test run terminates unexpectedly |
Render learned models to PDF using Graphviz:
dot -Tpdf experiments/results/zoh/learnedModel.dot -o learnedModel.pdf- State fuzzer integration follows protocol-fuzzing/ble-fuzzer.
- Hypothesis comparison utilities adapted from protocol-fuzzing/edhoc-fuzzer.