How fuzzware-fuzzer/hoedur-experiments works
Project Type and Purpose
• This is neither a typical web app nor a library; it is a research experiment orchestration framework.
• Purpose: reproduce, distribute, and evaluate embedded‐firmware fuzzing experiments using Hoedur and Fuzzware on multiple hosts, collect results (coverage, bug discovery timings), and post‐process them into tables and plots.
Key Architectural Components
a. Local Orchestration Layer
• generate_host_run_config.py
• run_experiment.py
• reproduce_targets_and_configs.py
• install.py, install scripts under scripts/
• experiment-config directory (profiles.yml, host‐run‐configs, available_hosts.txt)
b. Execution Layer (Remote Hosts)
• SSH endpoints as defined in experiment-config/available_hosts.txt
• Docker Engine on each host
• Docker containers for:
• Hoedur fuzzing (hoedur-convert-fuzzware-config, fuzz-local.py, fuzz-coverage-list.py)
• Fuzzware fuzzing (fuzzware genconfig, custom Dockerfiles)
• AFL/AFL++ or libfuzzer backends invoked by fuzzers
c. Data Storage Layer
• NFS or shared fs (results directories: 01-bug-finding-ability…04-prev-unknown-vulns) on controller or central storage
• Targets directory (pre-built firmware and unpatched set)
• experiment-config/host-run-configs (YAML dispatch files)
d. Results Processing Layer
• compute_metrics.py
• scripts/eval_data_processing (Docker env, parsing.py, plotters, Makefile)
• scripts/summarize_bug_discovery_timings.py, check_data.py, check_install.py, clean_data.py
• sync_experiment_data.py, rsync
Relationships and Data Flow
1. Developer invokes install.py → sets up local environment (Python dependencies, Docker images).
2. User configures hosts in experiment-config/available_hosts.txt.
3. generate_host_run_config.py reads profiles.yml + available_hosts.txt → produces per‐host run‐configs (YAML).
4. (Optionally) --upload pushes run‐configs via SSH to remote hosts.
5. On each host: run_experiment.py <host-config>.yml
→ spawns Docker containers running Hoedur and Fuzzware fuzzers
→ fuzzers read target binaries from targets/arm/..., use hook scripts, corpus seeds
→ generate per-target results in results/fuzzing-runs, coverage, bug-reproducers.
6. After fuzzing completes, sync results back: sync_experiment_data.py or rsync
→ centralizes results under project’s results directories.
7. compute_metrics.py reads raw results → computes summary statistics (execs/sec, discovery times).
8. scripts/eval_data_processing Docker environment → runs parsing, plotting, PDF/table generation.
9. Final artifacts: .tex tables, .pdf plots, coverage charts, result summaries in each experiment directory.
Architectural Patterns and Principles
• Pipeline pattern: clearly defined stages (configuration → distribution → execution → collection → analysis).
• Distributed execution: work split across hosts, using SSH + Docker.
• Containerization: reproducible environments for fuzzers and analysis (Dockerfiles under scripts/fuzzware/env/).
• Separation of concerns:
• Orchestration vs. Execution vs. Analysis vs. Data Storage
• Auto-generation of configs (fuzzware ↔ hoedur conversion)
• Data immutability: targets and results directories are append‐only; patches and binary versions are versioned.