Quickstart

Get up and running with FuzzingBrain in minutes

Installation

Platform Support

Prerequisites

Requirement	Version	Notes
Docker	Latest	Must be installed and running. Install Docker
Go	>= 1.21	Auto-installed if missing. Manual Install
Git	Latest	For cloning repositories
LLM API Key	-	At least one: OpenAI, Anthropic, Google Gemini, or xAI

Option A: Using Docker (Recommended)

The easiest way to get started is using our pre-built Docker image:

# Pull the image
docker pull ghcr.io/o2lab/fuzzingbrain:latest

# Run FuzzingBrain
docker run -it --rm \
  -e OPENAI_API_KEY=your-key-here \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v $(pwd)/output:/app/output \
  ghcr.io/o2lab/fuzzingbrain:latest \
  <repo_url>

Docker Run Options:

• -e: Set API keys as environment variables (at least one required)
• -v: Mount a local directory to save scan results
• Add -b <base_commit> -d <delta_commit> for delta scans

Option B: Install from Source

1 Clone Repository

git clone https://github.com/o2lab/afc-crs-all-you-need-is-a-fuzzing-brain.git
cd afc-crs-all-you-need-is-a-fuzzing-brain

2 Create Configuration File

cd crs
cp .env.example .env

3 Add Your API Keys

Edit crs/.env and add your API keys (at least one is required):

# AI Model API Keys - Add at least one
OPENAI_API_KEY=sk-proj-your-actual-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-actual-anthropic-key-here
GEMINI_API_KEY=your-actual-gemini-key-here
XAI_API_KEY=xai-your-actual-xai-key-here

Optional: Configure Backup Keys

For higher rate limits and failover support:

# Backup keys (optional)
OPENAI_API_KEY_R1=your-openai-backup-key
ANTHROPIC_API_KEY_R1=your-anthropic-backup-key
GEMINI_API_KEY_R1=your-gemini-backup-key

Quick Start

Delta Scan

Analyze changes between two specific commits to find vulnerabilities introduced by the change:

./FuzzingBrain.sh -b bc841a89aea42b2a2de752171588ce94402b3949 -d 2c894c66108f0724331a9e5b4826e351bf2d094b https://github.com/OwenSanzas/libpng.git

• -b: Base commit (the earlier commit)
• -d: Delta commit (the later commit to compare against)

Full Scan

Complete vulnerability analysis on entire repository:

./FuzzingBrain.sh https://github.com/OwenSanzas/libpng.git

You can also specify the OSS-Fuzz project name if auto-detection fails:

./FuzzingBrain.sh --project libpng https://github.com/OwenSanzas/libpng.git

Running with Local Workspace

If you have a local workspace with the following structure:

<workspace>/
├── repo/                    # Source code of your software
├── fuzz-tooling/            # OSS-Fuzz fuzzing suite
└── diff/                    # [Optional]
    └── ref.diff             # Diff file for delta scan

Run the analysis:

./FuzzingBrain.sh /path/to/workspace

Output

After running FuzzingBrain, outputs are organized as follows:

.
├── workspace/
│   └── libpng_20251215_175412/       # Workspace for this run
├── pov/
│   └── libpng_20251215_175412/       # Generated POVs
│       ├── pov_1_claude-sonnet-4_1/
│       │   ├── pov.py
│       │   ├── test_blob.bin
│       │   ├── fuzzer_output.txt
│       │   └── pov_metadata.json
│       └── pov_2_gpt-4_1/
└── patch/
    └── libpng_20251215_175412/       # Generated patches
        └── patch_claude-sonnet-4_1_1/
            ├── patch.diff
            └── patch_metadata.json

Completion Summary

At the end of execution, you'll see a summary like:

╔════════════════════════════════════════════════════════════════╗
║                    TASK COMPLETION SUMMARY                     ║
╠════════════════════════════════════════════════════════════════╣
║ Status: SUCCESS
║ POVs Found: 3
║ Patches Found: 2
╠════════════════════════════════════════════════════════════════╣
║ Paths:
║   Workspace:  /root/.../workspace/libpng_20251215_175412
║   Log:        /root/.../workspace/libpng_20251215_175412/task.log
║   POVs:       /root/.../pov/libpng_20251215_175412
║   Patches:    /root/.../patch/libpng_20251215_175412
╚════════════════════════════════════════════════════════════════╝

Troubleshooting

macOS: Docker Permission Issues

If you see errors like mkdir: cannot create directory '/work/libfuzzer': Permission denied:

1. Enable File Sharing in Docker Desktop:
   • Open Docker Desktop → Settings → Resources → File Sharing
   • Add your workspace directory
   • Click "Apply & Restart"
2. Check Docker Desktop Settings:
   • Ensure "Use gRPC FUSE for file sharing" is disabled in Settings → General
3. Alternative: Use a workspace location in your home directory

Go Installation Issues

If automatic Go installation fails, install manually from go.dev/dl and add to PATH:

export PATH=$PATH:/usr/local/go/bin