How seemoo-lab/virtfuzz works
Project Type and Purpose
• Type: A specialized fuzzing framework for the Linux kernel’s wireless subsystems
• Purpose: Drive VirtIO devices in a QEMU VM, inject fuzzed I/O, collect coverage via KCOV, analyze crashes, and support replay and minimization.
File Structure
Top-level crates and directories:
• src/ – Core library (coverage handling, feedback loops, input gen, observer abstractions, QEMU executor, UI)
• fuzz/ – Fuzzer binary (virtfuzz-fuzz)
• proxy/ – Proxy binary (virtfuzz-proxy) for device I/O forwarding
• replay/ – Replayer/minimizer binary (virtfuzz-replay)
• device-definitions/ – JSON specs for various VirtIO devices
• guestimage/ – Scripts and configs to build the VM image
• kernel-patches/ – Patches to instrument Linux kernel (KCOV, VirtIO drivers)
• kernel-config/ – Kernel config fragments for KASAN, UBSAN, etc.
• resources/ – Sample PCAP init sequences and test logs
• setup-scripts/ – Helpers for building QEMU, guest image, and kernel
README Insights
• Core workflows: build patched QEMU, build guest image, patch & compile kernel, run fuzzer with JSON device definitions
• Dependencies: Rust & Cargo, QEMU, Linux kernel source
• Components: virtfuzz-fuzz, virtfuzz-proxy, virtfuzz-replay
Core Components
a. Fuzzer Engine (Rust, LibAFL)
b. QEMU VM (patched system-emulator binary)
c. Guest VM image (Debian-based, contains virtfuzz agents)
d. Patched Linux Kernel (KCOV-instrumented, VirtIO drivers)
e. VirtIO Device Definitions (JSON files)
f. Proxy Service (network/bluetooth forwarding)
g. Coverage Collector (KCOV via IVSHMEM backchannel)
h. Replay/Minimization Suite (crash reproducers, metadata handlers)
i. External Resources (PCAP init scripts, device definitions)
Relationships & Interactions
• The Fuzzer Engine launches one or more QEMU instances via the QEMU Executor module
• Each VM boots the Guest Image with the patched kernel
• VirtIO devices inside the VM are driven by fuzzed packets generated by the Fuzzer Engine according to JSON specs
• The Proxy (virtfuzz-proxy) sits between the Fuzzer Engine and the VM’s VirtIO ports for I/O forwarding or command fake-complete
• Observers in the fuzzer engine listen on the IVSHMEM channel for KCOV coverage data and on QEMU’s stdio/dmesg outputs
• Feedback loops in the fuzzer use coverage statistics to guide mutation of inputs
• Crashes or hangs trigger the Replay component, which reads saved inputs and metadata to reproduce and minimize
Architectural Patterns & Principles
• Modular Rust crates: separation of core library, binaries, and utilities
• Feedback-driven fuzzing loop (LibAFL)
• Virtualization boundary: host tool vs. guest VM
• Extensibility via JSON device definitions and PCAP initialization sequences
• Coverage collection out-of-band using KCOV→IVSHMEM
Technology Stack Highlights
• Rust + Cargo for all core logic
• LibAFL for mutation and scheduling
• QEMU (patched via qemu-patch.patch) for virtualization
• Linux Kernel (patched and configured) with KCOV instrumentation
• JSON for device definitions
• PCAP files for initialization sequences
• Bash scripts for image/kernel setup