# ocyberlab/chipfuzzer architecture

> Architecture diagram of the GitHub repository ocyberlab/chipfuzzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ocyberlab/chipfuzzer
- Repository: https://github.com/ocyberlab/chipfuzzer

## Overview

ChipFuzzer is a Python harness for checking and fuzzing Matter devices through chip-tool. Its principal workflow loads device configuration, optionally checks reachability and device-specific commands, then reports whether the check passed. Separate basic and ZCL fuzzers generate malformed command inputs; their calls are commented out in the current main entry point, so those branches are shown as optional. The README describes a broader Matter lab, but the sampled source only supports the harness flow shown here.

Main entry points: [`chip-fuzzer/main.py`](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/main.py) (Main runner), [`chip-fuzzer/pre_check.py`](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/pre_check.py) (Pre-check), [`chip-fuzzer/chip_utils/chip_tool_exec.py`](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/chip_utils/chip_tool_exec.py) (chip-tool wrapper), [`chip-fuzzer/basic_fuzzer.py`](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/basic_fuzzer.py) (Brightness fuzzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Harness"]
  node_main["Main runner<br/>[main.py]"]
  node_configfile["Device config<br/>[config.yaml]"]
  node_config["Config model<br/>[config.py]"]
end

subgraph group_checks["Pre-checks"]
  node_precheck["Pre-check<br/>[pre_check.py]"]
  node_ping["Ping monitor<br/>[ping_detector.py]"]
  node_parser["Log parser<br/>[log_parser.py]"]
end

subgraph group_fuzzing["Fuzzing"]
  node_basic["Brightness fuzzer<br/>[basic_fuzzer.py]"]
  node_zcl["ZCL fuzzer<br/>[zcl_fuzzer.py]"]
end

subgraph group_execution["Tool execution"]
  node_exec["chip-tool wrapper<br/>[chip_tool_exec.py]"]
end

node_operator(("Lab operator"))
node_chiptool["Matter chip-tool"]
node_devices(("Matter devices"))
node_zcldata["ZCL model files"]

node_operator -->|"starts"| node_main
node_main -->|"loads"| node_configfile
node_main -->|"constructs"| node_config
node_main -.->|"runs optionally"| node_precheck
node_main -.->|"optional call"| node_basic
node_main -.->|"optional call"| node_zcl
node_precheck -->|"monitors"| node_ping
node_precheck -->|"executes checks"| node_exec
node_precheck -->|"checks output"| node_parser
node_basic -->|"executes fuzz cases"| node_exec
node_basic -->|"validates output"| node_parser
node_zcl -->|"edits model"| node_zcldata
node_zcl -->|"executes fuzz cases"| node_exec
node_exec -->|"runs commands"| node_chiptool
node_chiptool -->|"sends Matter commands"| node_devices
node_devices -->|"returns responses"| node_chiptool

click node_main "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/main.py"
click node_configfile "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/config.yaml"
click node_config "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/config.py"
click node_precheck "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/pre_check.py"
click node_ping "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/detector/ping_detector.py"
click node_parser "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/chip_utils/log_parser.py"
click node_basic "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/basic_fuzzer.py"
click node_zcl "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/zcl_fuzzer.py"
click node_exec "https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/chip_utils/chip_tool_exec.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_configfile,node_config toneBlue
class node_precheck,node_ping,node_parser toneAmber
class node_basic,node_zcl toneMint
class node_exec toneRose
class node_operator,node_chiptool,node_devices,node_zcldata toneIndigo
```

## Components

### Harness

- [Main runner](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/main.py): `chip-fuzzer/main.py`
- [Device config](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/config.yaml): `chip-fuzzer/config.yaml`
- [Config model](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/config.py): `chip-fuzzer/config.py`

### Pre-checks

- [Pre-check](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/pre_check.py): `chip-fuzzer/pre_check.py`
- [Ping monitor](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/detector/ping_detector.py): `chip-fuzzer/detector/ping_detector.py`
- [Log parser](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/chip_utils/log_parser.py): `chip-fuzzer/chip_utils/log_parser.py`

### Fuzzing

- [Brightness fuzzer](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/basic_fuzzer.py): `chip-fuzzer/basic_fuzzer.py`
- [ZCL fuzzer](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/zcl_fuzzer.py): `chip-fuzzer/zcl_fuzzer.py`

### Tool execution

- [chip-tool wrapper](https://github.com/ocyberlab/chipfuzzer/blob/main/chip-fuzzer/chip_utils/chip_tool_exec.py): `chip-fuzzer/chip_utils/chip_tool_exec.py`

### Other components

- **Lab operator**
- **Matter chip-tool**
- **Matter devices**
- **ZCL model files**

## Connections

- Lab operator → Main runner: starts
- Main runner → Device config: loads
- Main runner → Config model: constructs
- Main runner → Pre-check: runs optionally
- Main runner → Brightness fuzzer: optional call
- Main runner → ZCL fuzzer: optional call
- Pre-check → Ping monitor: monitors
- Pre-check → chip-tool wrapper: executes checks
- Pre-check → Log parser: checks output
- Brightness fuzzer → chip-tool wrapper: executes fuzz cases
- Brightness fuzzer → Log parser: validates output
- ZCL fuzzer → ZCL model files: edits model
- ZCL fuzzer → chip-tool wrapper: executes fuzz cases
- chip-tool wrapper → Matter chip-tool: runs commands
- Matter chip-tool → Matter devices: sends Matter commands
- Matter devices → Matter chip-tool: returns responses