How hgarrereyn/graphfuzz works
Project Type & Purpose
• This is an open-source developer tool whose goal is to generate, execute, and minimize library-API fuzzing harnesses.
• It comprises a Python-based CLI (gfuzz), a C++ core runtime library (libgraphfuzz), documentation/experiments, and integrations with external tools (libFuzzer, Protobuf, Doxygen, Docker).
Top-Level Structure
• cli/gfuzz: A Python package implementing the gfuzz command-line tool with subcommands (gen, min, doxygen, schema, extractor, etc.).
• core: A C++ library and runtime graph‐mutation engine, defined by graph.hpp, schema.hpp, and graph.proto (Protobuf).
• docs: Static site content (Jekyll), markdown guides, assets.
• experiments: Dockerized example workloads that invoke gfuzz gen, fuzz_exec, and fuzz_write on target libraries.
Key Architectural Patterns
• CLI follows a command pattern: each subdirectory under commands implements one gfuzz subcommand.
• Core runtime uses a dataflow‐graph representation (vertices = API calls, edges = object dependencies), generated by protobuf definitions, and executed via a custom libFuzzer mutation engine.
• Separation of concerns: harness generation vs. harness execution/minimization vs. documentation vs. experiments.
Main Components & Relationships
A. gfuzz CLI (Python)
• Reads user schema (YAML) and optional Doxygen output.
• Subcommands:
• gen cpp: converts YAML → JSON schema → C++ harness templates (fuzz_exec.cpp, fuzz_write.cpp).
• doxygen: runs a Docker container with Doxygen to extract API definitions into schema.
• min: runs graph-aware minimization on a crash corpus via gfuzz min.
• Outputs: JSON schema, harness source files.
B. Build System
• CMakeLists.txt and pyproject.toml coordinate building:
• Python package for CLI.
• C++ library (libgraphfuzz + protobuf → libgraphfuzz.a or .so).
• Generated harnesses compiled with clang++ + libFuzzer + ASAN/UBSAN + -lgraphfuzz -lprotobuf → binaries fuzz_exec & fuzz_write.
C. Runtime Engine (fuzz_exec)
• Loads schema.json via Protobuf runtime.
• Uses libFuzzer as driver for coverage-guided mutations.
• Applies custom graph‐based mutation strategies (shuffle nodes, change arguments, cross-over).
• Dynamically traverses the in-memory dataflow graph, invoking API calls on the target library under test.
• On crash, serializes the failed graph to disk.
D. Post-Processing (fuzz_write)
• Reads serialized graph artifact.
• Reconstructs an equivalent C++ test harness source file with explicit new/delete calls for debugging.
E. Experiments & Docker
• Each subfolder under experiments contains:
• Dockerfile to build the target library.
• In/ directory with build/test scripts and schemas.
• Shell wrappers that invoke gfuzz gen, compile harnesses, then run fuzz_exec/fuzz_write.
F. Documentation
• Hosted as a static site, explaining architecture, quick start, schema format, research paper.