# all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge architecture

> Architecture diagram of the GitHub repository all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge
- Repository: https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge

## Overview

##### Project Type and Purpose
- This is a “fuzzing‐challenge orchestration” toolchain: it automates building a target (example-libpng), generating a proof‐of‐vulnerability (PoV) and patch via an LLM agent, and verifying results via OSS-Fuzz infrastructure and test scripts.

##### File Structure
- Top-level “action-*” directories: shell wrappers for three CLI commands—build_cr, run_pov, run_tests.
- create_pov.py & diff/x.bin: the Python LLM agent plus its outputs.
- example-libpng: the sample target code base with an introduced vulnerability.
- oss-fuzz-aixcc: entire OSS-Fuzz integration layer (docs, infra, base-images, build & CI functions, CIFuzz, projects, tools).
- Root configs (README.md, CHANGELOG.md) describe usage and evaluation.

##### Key Components
a. Developer CLI Layer
- action-build-cr (build_cr.sh)
- action-run-pov (run_pov.sh + crash_interpret_config.py)
- action-run-tests (run_tests.sh)
- create_pov.py (LLM agent entrypoint)
b. LLM Services
- External API (OpenAI, Anthropic, Google)
- Local LLM endpoint (ollama at localhost:11434)
c. Containerized Build & Fuzzing Layer
- Docker engine
- OSS-Fuzz base images (infra/base-images/…)
- Builder images → compile harnesses (libfuzzer, AFL, etc.)
- Runner images → execute PoV, coverage, introspection
d. Target Repository
- example-libpng source
- fuzz harnesses (in oss-fuzz-aixcc/projects/libpng & contrib/oss-fuzz)
- patchable code, test scripts
e. Artifacts & Dataflow
- x.bin (PoV binary)
- x.diff (patch)
- Test logs, coverage reports

##### Relationships & Interactions
- User invokes an “action-*” script.
- action-build-cr spins up Docker builder images, mounts example-libpng, produces fuzz harnesses inside OSS-Fuzz tooling.
- create_pov.py calls out to an LLM endpoint, receives PoV & patch, writes x.bin & x.diff.
- action-run-pov runs the PoV inside a runner container, produces crash validation.
- action-build-cr (again) applies x.diff to example-libpng, rebuilds.
- action-run-pov (with –x) verifies the patch prevents the crash.
- action-run-tests spins up a clean container, runs the .aixcc/test.sh to ensure no regressions.

##### Architectural Patterns & Principles
- Pipeline/Orchestration pattern: discrete stages (build → PoV generation → crash test → patch → rebuild → regression test)
- Containerized micro-environments: isolation of build, run, test phases in Docker images
- Separation of concerns: CLI wrappers, LLM logic, OSS-Fuzz infra, and target code are distinct modules
- Reuse & modularity: OSS-Fuzz base images and CI/CD functions serve multiple languages and projects

##### Technologies & Frameworks
- Bash and Python scripts for orchestration
- Docker and Dockerfiles (infra/base-images and infra/run_fuzzers)
- OSS-Fuzz (base-builder, base-runner, CI functions, clusterfuzzlite configs)
- LLM APIs (OpenAI, Anthropic, local ollama instance)
- Fuzzing engines: libFuzzer, AFL, honggfuzz, etc.
- Git, standard UNIX toolchain (patch, make, cmake)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Developer/CLI" 
        direction TB
        BuildCLI["Build Stage CLI\n(build_cr.sh)"]:::cli
        PovGenCLI["PoV Generation CLI\n(run_pov.sh)"]:::cli
        CrashConfig["Crash Interpret Config\n(crash_interpret_config.py)"]:::cli
        OSSFuzzCfg["OSS-Fuzz Config\n(ossfuzz_config.yaml)"]:::cli
        TestCLI["Regression Test CLI\n(run_tests.sh)"]:::cli
    end

    subgraph "LLM Services"
        direction TB
        ExternalLLM["External LLM APIs\n(OpenAI/Anthropic)"]:::cloud
        LocalLLM["Local LLM Endpoint\n(ollama:11434)"]:::cloud
    end

    subgraph "Build & Fuzzing Platform"
        direction TB
        DockerEngine["Docker Engine"]:::cylinder
        BaseImages["OSS-Fuzz Base Images"]:::cylinder
        RunnerImage["Runner Image\n(run_fuzzers.Dockerfile)"]:::cylinder
        BuilderImage["Builder Image\n(base-builder)"]:::cylinder
    end

    subgraph "Target Project"
        direction TB
        SourceCode["example-libpng\n(source)"]:::code
        FuzzHarnessOSS["OSS-Fuzz Harness\n(oss-fuzz-aixcc/projects/libpng/)"]:::code
        ContribHarness["Sample Harness\n(example-libpng/contrib/oss-fuzz/)"]:::code
    end

    subgraph "Artifacts & Data"
        direction TB
        POVBin["PoV Binary\n(x.bin)"]:::doc
        PatchDiff["Patch Diff\n(x.diff)"]:::doc
        TestLogs["Test Logs\nCoverage Reports"]:::doc
    end

    %% Connections
    BuildCLI -->|"invoke build_cr.sh"| DockerEngine
    DockerEngine -->|"mount source"| SourceCode
    DockerEngine -->|"use base images"| BaseImages
    BaseImages -->|"produce fuzzers"| BuilderImage
    BuilderImage -->|"generate harnesses"| FuzzHarnessOSS
    BuilderImage -->|"generate harnesses"| ContribHarness

    PovGenCLI -->|"invoke run_pov.sh"| CreatePoVAgent
    CreatePoVAgent["LLM Agent\n(create_pov.py)"]:::code -->|"POST /v1/chat.completions"| ExternalLLM
    CreatePoVAgent -->|"POST /v1/chat.completions"| LocalLLM
    ExternalLLM -->|"response PoV & patch"| POVBin
    LocalLLM -->|"response PoV & patch"| POVBin
    POVBin -->|"write x.diff"| PatchDiff

    PovGenCLI --> CrashConfig
    PovGenCLI --> OSSFuzzCfg

    PatchDiff -->|"apply patch"| SourceCode
    BuildCLI -->|"rebuild patched"| DockerEngine

    PovGenCLI -->|"verify crash prevention"| RunnerImage
    RunnerImage -->|"run PoV"| POVBin

    TestCLI -->|"invoke run_tests.sh"| RunnerImage
    RunnerImage -->|"execute tests"| TestLogs

    %% Click Events
    click BuildCLI "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/action-build-cr/build_cr.sh"
    click PovGenCLI "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/action-run-pov/run_pov.sh"
    click CrashConfig "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/action-run-pov/crash_interpret_config.py"
    click OSSFuzzCfg "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/action-run-pov/ossfuzz_config.yaml"
    click TestCLI "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/action-run-tests/run_tests.sh"
    click CreatePoVAgent "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/create_pov.py"
    click BaseImages "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/tree/main/oss-fuzz-aixcc/infra/base-images/"
    click RunnerImage "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/oss-fuzz-aixcc/infra/run_fuzzers.Dockerfile"
    click SourceCode "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/tree/main/example-libpng/"
    click FuzzHarnessOSS "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/tree/main/oss-fuzz-aixcc/projects/libpng/"
    click ContribHarness "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/tree/main/example-libpng/contrib/oss-fuzz/"
    click POVBin "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/x.bin"
    click PatchDiff "https://github.com/all-you-need-is-a-fuzzing-brain/aixcc-sample-challenge/blob/main/x.diff"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef cloud fill:#ccf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef cylinder fill:#cfc,stroke:#333,stroke-width:1px,shape:round
    classDef code fill:#ffc,stroke:#333,stroke-width:1px
    classDef doc fill:#fcf,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
