# positron11/fuzzer architecture

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

- Interactive diagram: https://gitdiagram.com/positron11/fuzzer
- Repository: https://github.com/positron11/fuzzer

## Overview

##### Project Type and Purpose
- This is an open‑source grammar fuzzer framework. It provides two approaches to grammar‑based fuzzing:
a. Generic fuzzers written directly in C, which take a JSON grammar at runtime.
b. “Compiled” fuzzers: Python scripts that read a JSON grammar and emit specialized C fuzzer code, then compile it.
- Core use‑case: generate deterministic, depth‑limited random strings from context‑free grammars for testing parsers.

##### File‑Structure Analysis
- Top‑level directories:
- compiled/    → code‑generation pipeline for “compiled fuzzers”
- generic/     → C sources for a reusable, runtime‑configurable fuzzer
- grammars/    → JSON grammar definitions (http.json, JSON.json, tinyc.json)
- utilities/   → shared Python utilities (grammar cost computation, helpers)
- docs/        → LaTeX source and profiling outputs
- Build artifacts:
- Each of compiled/ and generic/ has its own Makefile and build/ folder.
- JSON grammars are inputs to both pipelines.
- Key components:
- Python “compilers” (iterative.py, recursive.py)
- Fuzzer driver in generic/src (fuzz-iter.c, fuzz-recr.c)
- Shared fuzzutils.h/.c for random expansion and depth control
- gramutils.py for grammar processing (cost, selection heuristics)

##### README Insights
- Two fuzzing strategies (iterative vs. recursive).
- Build invocation: `make [iterative|recursive] grammar=[name]`.
- Outputs deterministic strings given a seed & max depth.
- Encourages reusability via generic C fuzzer or generation of specialized C code.

a. Main Components
1. Grammar Definitions
– JSON files in grammars/
2. Code‑Generation Pipeline (Compiled Fuzzers)
– Python scripts (compiled/compilers/iterative.py & recursive.py)
– utilities/gramutils.py & utilities/gramutils.py helpers
– Outputs C source (_*.c) into compiled/build/
– Makefile drives gcc into executables
3. Generic Fuzzer Runtime
– C driver (generic/src/fuzz-*.c)
– Shared utilities (generic/src/fuzzutils.c/.h, gstruct.h)
– Reads JSON grammar at runtime
4. Build System
– Makefiles (compiled/Makefile, generic/Makefile)
– Clean, compile, link steps
5. Executable Interface
– CLI: `gi_fuzz-tinyc <seed> [max_depth]`
6. Profiling & Documentation
– docs/ (LaTeX + CSV profiling data)

b. Component Interactions
- JSON grammar → Python generator → generated C code → gcc compiler → compiled fuzzer binary
- JSON grammar → generic fuzzer binary (linked with fuzzutils) → runtime grammar parser → fuzz generation
- Executable → STDOUT fuzzed strings → optionally piped into target under test → profiling scripts → docs/profiling

c. Architectural Patterns and Principles
- Separation of concerns: code generation vs. runtime fuzzing
- Pluggable grammars: JSON‑based grammar definitions decouple grammar from engine
- Deterministic execution via seeded RNG
- Two execution modes (iterative vs. recursive expansion) illustrating strategy pattern

d. Technologies and Frameworks
- Python 3 for code generation
- C (gcc) for fuzzer engine
- Makefiles for build automation
- JSON for grammar specification
- LaTeX and CSV for documentation and profiling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Grammar Definitions
    subgraph "Grammar Definitions"
        g1["JSON.json"]:::json
        g2["http.json"]:::json
        g3["tinyc.json"]:::json
    end

    %% Shared Python Utilities
    subgraph "Shared Python Utilities"
        gramutils_u["gramutils.py"]:::python
        ggc["ggc.py"]:::python
    end

    %% Compiled Fuzzer Code-Generation Pipeline
    subgraph "Compiled Pipeline"
        py_main["main.py"]:::python
        py_iter["iterative.py"]:::python
        py_rec["recursive.py"]:::python
        make_comp["Makefile"]:::doc
        build_dir["build/"]:::doc
    end

    %% Generic Fuzzer Runtime
    subgraph "Generic Runtime"
        driver["driver.c"]:::cComp
        fuzz_iter["fuzz-iter.c"]:::cComp
        fuzz_recr["fuzz-recr.c"]:::cComp
        fuzzutil_c["fuzzutils.c"]:::cComp
        fuzzutil_h["fuzzutils.h"]:::cComp
        gstruct["gstruct.h"]:::cComp
        fuzzer_h["fuzzer.h"]:::cComp
        make_gen["Makefile"]:::doc
    end

    %% Binaries
    compiled_bin["Compiled Fuzzer Binary"]:::cComp
    generic_bin["Generic Fuzzer Binary"]:::cComp

    %% Execution & Profiling
    exec["Execution<br/>(seed,max_depth)"] 
    subgraph "Profiling Data"
        prof1["cr_http.csv"]:::doc
        prof2["cr_json.csv"]:::doc
        prof3["cr_tinyc.csv"]:::doc
        prof4["cr_tinyc_truncated.csv"]:::doc
        prof5["cumulative.csv"]:::doc
    end

    %% Documentation
    subgraph "Documentation"
        doc_src["main.tex"]:::doc
        doc_bib["main.bib"]:::doc
        doc_pdf["main.pdf"]:::doc
    end

    %% Flows
    g1 -->|input| py_main
    g2 -->|input| py_main
    g3 -->|input| py_main

    g1 -->|input| driver
    g2 -->|input| driver
    g3 -->|input| driver

    py_main -->|uses| py_iter
    py_main -->|uses| py_rec
    py_iter -->|helpers| gramutils_u
    py_rec -->|helpers| gramutils_u
    py_main -->|generate C code| build_dir
    make_comp -->|compile| build_dir
    build_dir -->|produces| compiled_bin

    driver -->|links| fuzz_iter
    driver -->|links| fuzz_recr
    driver -->|links| fuzzutil_c
    driver -->|includes| fuzzutil_h
    driver -->|includes| gstruct
    driver -->|includes| fuzzer_h
    make_gen -->|compile| generic_bin

    compiled_bin -->|execute| exec
    generic_bin -->|execute| exec
    exec -->|produce| prof1
    exec -->|produce| prof2
    exec -->|produce| prof3
    exec -->|produce| prof4
    exec -->|produce| prof5

    prof1 -->|input| doc_src
    prof2 -->|input| doc_src
    prof3 -->|input| doc_src
    prof4 -->|input| doc_src
    prof5 -->|input| doc_src
    doc_src -->|build| doc_pdf
    doc_bib -->|build| doc_pdf

    %% Click Events
    click g1 "https://github.com/positron11/fuzzer/blob/master/grammars/JSON.json"
    click g2 "https://github.com/positron11/fuzzer/blob/master/grammars/http.json"
    click g3 "https://github.com/positron11/fuzzer/blob/master/grammars/tinyc.json"
    click py_main "https://github.com/positron11/fuzzer/blob/master/compiled/main.py"
    click py_iter "https://github.com/positron11/fuzzer/blob/master/compiled/compilers/iterative.py"
    click py_rec "https://github.com/positron11/fuzzer/blob/master/compiled/compilers/recursive.py"
    click gramutils_u "https://github.com/positron11/fuzzer/blob/master/utilities/gramutils.py"
    click make_comp "https://github.com/positron11/fuzzer/tree/master/compiled/Makefile"
    click build_dir "https://github.com/positron11/fuzzer/tree/master/compiled/build/"
    click driver "https://github.com/positron11/fuzzer/blob/master/generic/driver.c"
    click fuzz_iter "https://github.com/positron11/fuzzer/blob/master/generic/src/fuzz-iter.c"
    click fuzz_recr "https://github.com/positron11/fuzzer/blob/master/generic/src/fuzz-recr.c"
    click fuzzutil_c "https://github.com/positron11/fuzzer/blob/master/generic/src/fuzzutils.c"
    click fuzzutil_h "https://github.com/positron11/fuzzer/blob/master/generic/src/fuzzutils.h"
    click gstruct "https://github.com/positron11/fuzzer/blob/master/generic/src/gstruct.h"
    click fuzzer_h "https://github.com/positron11/fuzzer/blob/master/generic/src/fuzzer.h"
    click make_gen "https://github.com/positron11/fuzzer/tree/master/generic/Makefile"
    click ggc "https://github.com/positron11/fuzzer/blob/master/generic/utilities/ggc.py"
    click doc_src "https://github.com/positron11/fuzzer/blob/master/docs/main.tex"
    click doc_bib "https://github.com/positron11/fuzzer/blob/master/docs/main.bib"
    click prof1 "https://github.com/positron11/fuzzer/blob/master/docs/profiling/cr_http.csv"
    click prof2 "https://github.com/positron11/fuzzer/blob/master/docs/profiling/cr_json.csv"
    click prof3 "https://github.com/positron11/fuzzer/blob/master/docs/profiling/cr_tinyc.csv"
    click prof4 "https://github.com/positron11/fuzzer/blob/master/docs/profiling/cr_tinyc_truncated.csv"
    click prof5 "https://github.com/positron11/fuzzer/blob/master/docs/profiling/cumulative.csv"
    click doc_pdf "https://github.com/positron11/fuzzer/blob/master/docs/build/main.pdf"

    %% Styles
    classDef python fill:#aaf,stroke:#333,stroke-width:1px
    classDef cComp fill:#afa,stroke:#333,stroke-width:1px
    classDef json fill:#ff9,stroke:#333,stroke-width:1px
    classDef doc fill:#ddd,stroke:#333,stroke-width:1px
    class py_main,py_iter,py_rec,gramutils_u,ggc python
    class driver,fuzz_iter,fuzz_recr,fuzzutil_c,fuzzutil_h,gstruct,fuzzer_h cComp
    class g1,g2,g3 json
    class make_comp,build_dir,make_gen,doc_src,doc_bib,doc_pdf,prof1,prof2,prof3,prof4,prof5 doc
```
