# hgarrereyn/graphfuzz architecture

> Architecture diagram of the GitHub repository hgarrereyn/graphfuzz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hgarrereyn/graphfuzz
- Repository: https://github.com/hgarrereyn/graphfuzz

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI (Python)" 
        direction TB
        CLI["gfuzz CLI"]:::python
        Commands["Command Framework"]:::python
        Gen["gen Subcommand"]:::python
        Doxygen["doxygen Subcommand"]:::python
        Min["min Subcommand"]:::python
        SchemaUtil["schema Subcommand"]:::python
        DockerUtil["Docker Utilities"]:::python
        Packaging["pyproject.toml"]:::storage
        CLI -->|uses| Commands
        Commands -->|plugins| Gen
        Commands -->|plugins| Doxygen
        Commands -->|plugins| Min
        Commands -->|plugins| SchemaUtil
        Commands -->|invokes| DockerUtil
    end

    %% Build System
    Build["Build System\n(CMakeLists.txt)"]:::cpp
    Packaging -->|defines Python package| CLI
    CLI -->|generates harness sources| Build
    Build -->|compiles| CoreLib

    %% Core Library
    subgraph "Core C++ Library" 
        direction TB
        CoreLib["libgraphfuzz"]:::cpp
        Proto["graph.proto + generated"]:::cpp
    end
    Build -->|builds with Protobuf| Proto
    Proto -->|linked into| CoreLib

    %% Runtime Executable
    subgraph "Runtime Engine" 
        direction TB
        FuzzExec["fuzz_exec"]:::cpp
        LibFuzzer["libFuzzer (driver)"]:::external
        SchemaJSON["schema.json"]:::storage
        CoreLib --> FuzzExec
        LibFuzzer --> FuzzExec
        SchemaJSON --> FuzzExec
        FuzzExec -->|invokes| TargetLib
        FuzzExec -->|on crash writes| CrashFile
    end

    %% Post-Processing
    subgraph "Post-Processing"
        direction TB
        FuzzWrite["fuzz_write"]:::cpp
        CrashFile["serialized graph"]:::storage
        FuzzWrite -->|reads| CrashFile
        FuzzWrite -->|outputs| HumanHarness["C++ test harness"]:::storage
    end

    %% Minimization
    MinRunner["gfuzz min"]:::python
    CrashFile -->|input| MinRunner
    MinRunner -->|outputs| MinCorpus["minimized crash"]:::storage

    %% Doxygen Extraction
    subgraph "Doxygen Extraction Docker"
        direction TB
        DoxyDocker["Docker container"]:::docker
        DoxyExtractor["extractor.py"]:::python
        Doxyfiles["Doxyfile.template"]:::storage
        DoxyRun["run.py"]:::python
        Doxygen -->|launches| DoxyDocker
        DoxyDocker --> DoxyExtractor
        DoxyDocker --> Doxyfiles
        DoxyDocker --> DoxyRun
        DoxyExtractor -->|produces| SchemaJSON
    end

    %% Experiments
    subgraph "Experiments (Docker)" 
        direction TB
        Experiments["experiments/*"]:::docker
        Experiments -->|invoke| CLI
        Experiments -->|compile harness| Build
        Experiments -->|run| FuzzExec
        Experiments -->|run| FuzzWrite
    end

    %% Documentation
    Docs["Documentation Site"]:::storage
    CLI -->|docs commands| Docs

    %% Target Library
    TargetLib["Target Library"]:::external

    %% Storage and Artifacts
    CrashFile
    HumanHarness
    SchemaJSON

    %% Click Events
    click CLI "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/cli.py"
    click Commands "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/commands/__init__.py"
    click Gen "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/commands/gen/gen.py"
    click Doxygen "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/commands/doxygen/extractor.py"
    click Min "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/commands/minimizer.py"
    click SchemaUtil "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/commands/schema.py"
    click DockerUtil "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/gfuzz/docker_util.py"
    click Packaging "https://github.com/hgarrereyn/graphfuzz/blob/master/cli/pyproject.toml"
    click Build "https://github.com/hgarrereyn/graphfuzz/blob/master/CMakeLists.txt"
    click CoreLib "https://github.com/hgarrereyn/graphfuzz/blob/master/core/graph.hpp"
    click Proto "https://github.com/hgarrereyn/graphfuzz/blob/master/core/graph.proto"
    click FuzzExec "https://github.com/hgarrereyn/graphfuzz/blob/master/experiments/eigen/in/f1/fuzz_exec.cpp"
    click FuzzWrite "https://github.com/hgarrereyn/graphfuzz/blob/master/experiments/eigen/in/f1/fuzz_write.cpp"
    click Docs "https://github.com/hgarrereyn/graphfuzz/blob/master/docs/index.html"

    %% Styles
    classDef python fill:#c6f1d6,stroke:#2d662d
    classDef cpp fill:#c6dbff,stroke:#1d3b78
    classDef docker fill:#ffe1b3,stroke:#a65f00
    classDef storage fill:#eeeeee,stroke:#888888
    classDef external fill:#f5f5f5,stroke:#444444,stroke-dasharray: 5 5
```
