# google/oss-fuzz-gen architecture

> Architecture diagram of the GitHub repository google/oss-fuzz-gen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/oss-fuzz-gen
- Repository: https://github.com/google/oss-fuzz-gen

## Overview

##### Main components to include as nodes
- Fuzz Target Generation Module:
- Agents (located under the “agent” directory) which include various analyzers (e.g., analyzer.py, crash_analyzer.py, semantic_analyzer.py) and prototyper components.
- Prompts and Templates (under “prompts” & “prompts/template_xml”) that define LLM input for fuzz target generation.
- LLm Toolkit Module (under “llm_toolkit”) which manages interactions with different language models, constructs prompts, parses outputs, and handles code fixing or enhancements.

- Experiment and Evaluation Framework:
- Experimental modules (directories “experiment” and “experimental”) orchestrate benchmark experiments, evaluation of fuzz targets (e.g., evaluating coverage, compiling, runtime crashes).
- Fuzzer Build Scripts (found under “fuzzer_build_script”) handling target-specific build logic.

- Data Preparation and Analysis:
- Data preparation tools (in “data_prep”) prepare training data, parse training inputs, and manage project contexts.
- Report generation modules (in “report”) that aggregate and compare benchmark results and generate HTML/JSON reports.

- Continuous Integration and Deployment:
- CI configuration and Kubernetes deployment files (in “ci”) to build, test, and deploy experiments in a containerized environment (Dockerfiles and cloudbuild files indicate container orchestration).

- Auxiliary Tools and Helper Scripts:
- Helper scripts (in “helper” and “tool” directories) that handle various utility tasks like diff targeting, container execution, and logging.
- The “pipeline.py”, “scripts” directory, and “stage” directory represent the orchestration of different processing stages (analysis, execution, writing).

##### Relationships and interactions
- Data flow from prompt/template modules → LLm Toolkit → Agent components:
- Prompts serve as the input for the LLM toolkit, which in turn produces modifications or generates new fuzz targets. The agent then uses these outputs for further analysis or refinements.

- Integration of external services:

- CI/CD pipelines:
- The “ci” directory and Dockerfiles indicate containerized build pipelines that trigger analysis, building, and eventually reporting using gathered experimental data.

- Reporting and result aggregation:
- Results flow from experimental evaluations (coverage metrics, crash reports, etc.) into the reporting component, which aggregates data and produces visual dashboards.

##### Important architectural patterns or design principles
- Modular Design: The use of several directories (agent, experiment, data_prep, experimental, reports) each suggests a separation of concerns.
- Pipeline/Stage Architecture: The “stage” directory (with analysis, execution, writing stages) shows a multi-step processing pipeline.
- Extensibility and configurability: The existence of various benchmarks (“benchmark-sets”) and multiple experiment drivers indicates that the framework is designed to easily integrate new projects and models.
- Containerization and CI automation: Dockerfiles and CI descriptors showcase a strategy for standardized builds and deployments.

##### Relevant technologies/frameworks/libraries
- LLM APIs (Vertex AI, OpenAI) for model integration.
- Docker/Kubernetes for containerized builds and deployments.
- Python as the main programming language (evidenced by configuration files and Python scripts).
- OSS-Fuzz platform integration for fuzz evaluation.
- Various static analysis and linting tools (configuration files like .pylintrc, .pyrightconfig.json) to ensure code quality.

- Clearly delineate the separation between components that generate text/code (LLM Toolkit, Prompts, Agent) and those that execute tests (Experiment, Fuzzer Build Scripts, CI pipeline).
- Orchestration pipeline from data preparation, through fuzz target generation, to evaluation and reporting.

##### Final advice
- Integration points – for instance, where LLM responses go through analysis (agent) and then are evaluated (experiment), and finally summarized (report).

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Fuzz Target Generation"
    A1["Prompts & Templates"]:::prompts
    A2["LLM Integration Toolkit"]:::llm
    A3["Fuzz Target Generation Agent"]:::agent
    A1 --> A2
    A2 --> A3
  end

  subgraph "Experiment and Evaluation"
    B0["Fuzzer Build Scripts"]:::build
    B1["Experiment Modules (experiment)"]:::experiment
    B2["Experiment Modules (experimental)"]:::experiment
    B0 --> B1
    B1 --> B2
    B2 -->|"benchmarks"| C["OSS-Fuzz Platform"]:::external
  end

  subgraph "Data Preparation & Reporting"
    D1["Data Preparation Tools"]:::dataprep
    D2["Reporting Modules"]:::report
    D1 --> D2
    B2 --> D2
  end

  subgraph "CI/CD & Container Orchestration"
    E["CI/CD & Container Orchestration"]:::ci
  end

  subgraph "Pipeline & Utilities"
    F1["Helper Scripts"]:::pipeline
    F2["Pipeline Orchestration"]:::pipeline
    F3["Execution Scripts"]:::pipeline
    F4["Stage Modules"]:::pipeline
    F5["Utility Tools"]:::pipeline
    F1 --> F2
    F2 --> F3
    F3 --> F4
    F4 --> F5
  end

  E -->|"triggers"| B0
  E -->|"deploys_to"| D2
  E -->|"orchestrates"| F2
  A3 --> B0

  click A1 "https://github.com/google/oss-fuzz-gen/tree/main/prompts"
  click A2 "https://github.com/google/oss-fuzz-gen/tree/main/llm_toolkit"
  click A3 "https://github.com/google/oss-fuzz-gen/tree/main/agent"
  click B0 "https://github.com/google/oss-fuzz-gen/tree/main/fuzzer_build_script"
  click B1 "https://github.com/google/oss-fuzz-gen/tree/main/experiment"
  click B2 "https://github.com/google/oss-fuzz-gen/tree/main/experimental"
  click D1 "https://github.com/google/oss-fuzz-gen/tree/main/data_prep"
  click D2 "https://github.com/google/oss-fuzz-gen/tree/main/report"
  click E "https://github.com/google/oss-fuzz-gen/tree/main/ci"
  click F1 "https://github.com/google/oss-fuzz-gen/tree/main/helper"
  click F2 "https://github.com/google/oss-fuzz-gen/blob/main/pipeline.py"
  click F3 "https://github.com/google/oss-fuzz-gen/tree/main/scripts"
  click F4 "https://github.com/google/oss-fuzz-gen/tree/main/stage"
  click F5 "https://github.com/google/oss-fuzz-gen/tree/main/tool"

  classDef prompts fill:#ADD8E6,stroke:#000,stroke-width:2px;
  classDef llm fill:#B0E0E6,stroke:#000,stroke-width:2px;
  classDef agent fill:#FFC0CB,stroke:#000,stroke-width:2px;
  classDef build fill:#FFEFD5,stroke:#000,stroke-width:2px;
  classDef experiment fill:#FFFACD,stroke:#000,stroke-width:2px;
  classDef external fill:#FFA500,stroke:#000,stroke-width:2px;
  classDef dataprep fill:#DDA0DD,stroke:#000,stroke-width:2px;
  classDef report fill:#D8BFD8,stroke:#000,stroke-width:2px;
  classDef ci fill:#90EE90,stroke:#000,stroke-width:2px;
  classDef pipeline fill:#E6E6FA,stroke:#000,stroke-width:2px;

  class A1 prompts;
  class A2 llm;
  class A3 agent;
  class B0 build;
  class B1 experiment;
  class B2 experiment;
  class C external;
  class D1 dataprep;
  class D2 report;
  class E ci;
  class F1 pipeline;
  class F2 pipeline;
  class F3 pipeline;
  class F4 pipeline;
  class F5 pipeline;
```
