How 0vercl0k/wtf works
Project Type and Purpose
• Type: A command-line, distributed master-worker (server/client) application written in C++.
• Purpose: “what the fuzz” (wtf) is a cross-platform, snapshot-based, coverage-guided fuzzer. It drives targets (user-mode or kernel-mode on Windows, experimental Linux mode) inside emulators or hypervisors, collects coverage and crash data, and orchestrates fuzzing in a distributed fashion.
High-Level Components
a. CLI Layer
• Entry point: wtf.exe managed by CLI11 (src/libs/CLI11).
• Subcommands:
– master (server)
– fuzz (client)
– run, minset, trace
b. Core Engine
• Command dispatcher & option parsing
• Master node logic (corpus management, aggregated coverage, test-case scheduling)
• Client node logic (fetch test-case, execute, report results)
• Common abstractions:
– Target_t (harness modules)
– Mutator_t interface (libfuzzer, honggfuzz, custom)
– Backend_t interface (bochscpu, WHV, KVM)
c. Execution Backends (src/wtf/*_backend.*)
• bochscpu_backend (emulator)
• whv_backend (Windows Hypervisor Platform)
• kvm_backend (Linux KVM)
d. Fuzzer Modules (src/wtf/fuzzer_*.cc)
• Init(), InsertTestcase(), Restore(), Crash detection, End-of-test conditions
• Provide: custom generators or mutators
e. Communication Layer
• Socket abstraction (src/wtf/socket.{cc,h}) for TCP/UDP between master and clients
f. File-System State
• targets/<name>/ – subfolders: inputs/, outputs/, coverage/, crashes/, state/
• Master stores aggregated coverage in coverage.cov
• Clients read/write per-target directories
g. External Libraries & Tools
• BLAKE3 for hashing (src/libs/BLAKE3)
• JSON (nlohmann/json) – coverage file, symbol store
• fmt, robin-map, yas, kdmp-parser, libfuzzer, honggfuzz, CLI11, etc.
• Python scripts in scripts/ for generating coverage breakpoints
h. Build System
• CMakeLists.txt in src/
• Cross-platform build scripts in src/build/
Component Interactions and Data Flow
• Startup: User runs wtf.exe <subcommand> [options].
• Master:
1. Loads target state (snapshot, symbol-store.json).
2. Scans current corpus (inputs, outputs).
3. Opens listening socket.
4. Schedules test-cases to clients.
5. Aggregates coverage updates & new inputs.
• Client:
1. Connects to master over network.
2. Requests and receives a test-case.
3. Invokes InsertTestcase() in the fuzzer module to feed input into the target.
4. Chooses a backend: emulator (bochscpu) or hypervisor (WHV/KVM).
5. Executes the target snapshot until completion/timeout/crash.
6. Captures coverage (.cov file), crash info, optionally trace data.
7. Sends results back to master.
• Mutator: Generates or mutates raw input bytes, invoked by client prior to execution.
• State Storage: All intermediate files (mem.dmp, regs.json, coverage fragments, crashes) live on disk under the target directory.
Architectural Patterns & Principles
• Master-Worker Pattern: Central server delegates work to multiple fuzzing clients.
• Plugin-style Interfaces: Abstract Mutator_t and Backend_t allow easy addition of new fuzzers/backends.
• Layered Architecture:
– CLI layer
– Core engine (orchestration)
– Backend/Mutator modules
– OS/emulator
Relevant Technologies & Frameworks
• C++17, CMake, Ninja / MSVC solution
• CLI parsing: CLI11
• Hashing: BLAKE3
• JSON: nlohmann/json
• Coverage & breakpoint generation: Python scripts (gen_coveragefile_*.py)
• Emulation & virtualization: bochscpu, Windows Hypervisor Platform (WHV), Linux KVM
• Fuzzing primitives: libfuzzer, honggfuzz (via Mutator_t)
Essential Details to Capture
• Master’s role in scheduling and aggregating coverage.
• Client’s plugin points: fuzzer modules, mutators, backends.
• Shared file-system state under targets/.
• Key external dependencies and build system.
• Data flows: test-cases, coverage, crash reports, traces.