ossfuzz

OSS-Fuzz

OSS-Fuzz is an open-source project developed by Google that provides free distributed infrastructure for continuous fuzz testing. It streamlines the fuzzing process and facilitates simpler modifications. While only select projects are accepted into OSS-Fuzz, the project's core is open-source, allowing anyone to host their own instance for private projects.

Overview

OSS-Fuzz provides a simple CLI framework for building and starting harnesses or calculating their coverage. Additionally, OSS-Fuzz can be used as a service that hosts static web pages generated from fuzzing outputs such as coverage information.

Key Concepts

Concept	Description
helper.py	CLI script for building images, building fuzzers, and running harnesses locally
Base Images	Hierarchical Docker images providing build dependencies and compilers
project.yaml	Configuration file defining project metadata for OSS-Fuzz enrollment
Dockerfile	Project-specific image with build dependencies
build.sh	Script that builds fuzzing harnesses for your project
Criticality Score	Metric used by OSS-Fuzz team to evaluate project acceptance

When to Apply

Apply this technique when:

• Setting up continuous fuzzing for an open-source project
• Need distributed fuzzing infrastructure without managing servers
• Want coverage reports and bug tracking integrated with fuzzing
• Testing existing OSS-Fuzz harnesses locally
• Reproducing crashes from OSS-Fuzz bug reports

Skip this technique when:

• Project is closed-source (unless hosting your own OSS-Fuzz instance)
• Project doesn't meet OSS-Fuzz's criticality score threshold
• Need proprietary or specialized fuzzing infrastructure
• Fuzzing simple scripts that don't warrant infrastructure

Quick Reference

Task	Command
Clone OSS-Fuzz	git clone https://github.com/google/oss-fuzz
Build project image	python3 infra/helper.py build_image --pull <project>
Build fuzzers with ASan	python3 infra/helper.py build_fuzzers --sanitizer=address <project>
Run specific harness	python3 infra/helper.py run_fuzzer <project> <harness>
Generate coverage report	python3 infra/helper.py coverage <project>
Check helper.py options	python3 infra/helper.py --help

OSS-Fuzz Project Components

OSS-Fuzz provides several publicly available tools and web interfaces:

Bug Tracker

The bug tracker allows you to:

• Check bugs from specific projects (initially visible only to maintainers, later made public)
• Create new issues and comment on existing ones
• Search for similar bugs across all projects to understand issues

Build Status System

The build status system helps track:

• Build statuses of all included projects
• Date of last successful build
• Build failures and their duration

Fuzz Introspector

Fuzz Introspector displays:

• Coverage data for projects enrolled in OSS-Fuzz
• Hit frequency for covered code
• Performance analysis and blocker identification

Read this case study for examples and explanations.

Step-by-Step: Running a Single Harness

You don't need to host the whole OSS-Fuzz platform to use it. The helper script makes it easy to run individual harnesses locally.

Step 1: Clone OSS-Fuzz

git clone https://github.com/google/oss-fuzz
cd oss-fuzz
python3 infra/helper.py --help

Step 2: Build Project Image

python3 infra/helper.py build_image --pull <project-name>

This downloads and builds the base Docker image for the project.

Step 3: Build Fuzzers with Sanitizers

python3 infra/helper.py build_fuzzers --sanitizer=address <project-name>

Sanitizer options:

• --sanitizer=address for AddressSanitizer with LeakSanitizer
• Other sanitizers available (language support varies)

Note: Fuzzers are built to /build/out/<project-name>/ containing the harness executables, dictionaries, corpus, and crash files.

Step 4: Run the Fuzzer

python3 infra/helper.py run_fuzzer <project-name> <harness-name> [<fuzzer-args>]

The helper script automatically runs any missed steps if you skip them.

Step 5: Coverage Analysis (Optional)

First, install gsutil (skip gcloud initialization).

python3 infra/helper.py build_fuzzers --sanitizer=coverage <project-name>
python3 infra/helper.py coverage <project-name>

Use --no-corpus-download to use only local corpus. The command generates and hosts a coverage report locally.

See official OSS-Fuzz documentation for details.

Common Patterns

Pattern: Running irssi Example

Use Case: Testing OSS-Fuzz setup with a simple enrolled project

# Clone and navigate to OSS-Fuzz
git clone https://github.com/google/oss-fuzz
cd oss-fuzz

# Build and run irssi fuzzer
python3 infra/helper.py build_image --pull irssi
python3 infra/helper.py build_fuzzers --sanitizer=address irssi
python3 infra/helper.py run_fuzzer irssi irssi-fuzz

Expected Output:

INFO:__main__:Running: docker run --rm --privileged --shm-size=2g --platform linux/amd64 -i -e FUZZING_ENGINE=libfuzzer -e SANITIZER=address -e RUN_FUZZER_MODE=interactive -e HELPER=True -v /private/tmp/oss-fuzz/build/out/irssi:/out -t gcr.io/oss-fuzz-base/base-runner run_fuzzer irssi-fuzz.
Using seed corpus: irssi-fuzz_seed_corpus.zip
/out/irssi-fuzz -rss_limit_mb=2560 -timeout=25 /tmp/irssi-fuzz_corpus -max_len=2048 < /dev/null
INFO: Running with entropic power schedule (0xFF, 100).
INFO: Seed: 1531341664
INFO: Loaded 1 modules   (95687 inline 8-bit counters): 95687 [0x1096c80, 0x10ae247),
INFO: Loaded 1 PC tables (95687 PCs): 95687 [0x10ae248,0x1223eb8),
INFO:      719 files found in /tmp/irssi-fuzz_corpus
INFO: seed corpus: files: 719 min: 1b max: 170106b total: 367969b rss: 48Mb
#720        INITED cov: 409 ft: 1738 corp: 640/163Kb exec/s: 0 rss: 62Mb
#762        REDUCE cov: 409 ft: 1738 corp: 640/163Kb lim: 2048 exec/s: 0 rss: 63Mb L: 236/2048 MS: 2 ShuffleBytes-EraseBytes-

Pattern: Enrolling a New Project

Use Case: Adding your project to OSS-Fuzz (or private instance)

Create three files in projects/<your-project>/:

1. project.yaml - Project metadata:

homepage: "https://github.com/yourorg/yourproject"
language: c++
primary_contact: "your-email@example.com"
main_repo: "https://github.com/yourorg/yourproject"
fuzzing_engines:
  - libfuzzer
sanitizers:
  - address
  - undefined

2. Dockerfile - Build dependencies:

FROM gcr.io/oss-fuzz-base/base-builder
RUN apt-get update && apt-get install -y \
    autoconf \
    automake \
    libtool \
    pkg-config
RUN git clone --depth 1 https://github.com/yourorg/yourproject
WORKDIR yourproject
COPY build.sh $SRC/

3. build.sh - Build harnesses:

#!/bin/bash -eu
./autogen.sh
./configure --disable-shared
make -j$(nproc)

# Build harnesses
$CXX $CXXFLAGS -std=c++11 -I. \
    $SRC/yourproject/fuzz/harness.cc -o $OUT/harness \
    $LIB_FUZZING_ENGINE ./libyourproject.a

# Copy corpus and dictionary if available
cp $SRC/yourproject/fuzz/corpus.zip $OUT/harness_seed_corpus.zip
cp $SRC/yourproject/fuzz/dictionary.dict $OUT/harness.dict

Docker Images in OSS-Fuzz

Harnesses are built and executed in Docker containers. All projects share a runner image, but each project has its own build image.

Image Hierarchy

Images build on each other in this sequence:

1. base_image - Specific Ubuntu version
2. base_clang - Clang compiler; based on base_image
3. base_builder - Build dependencies; based on base_clang
   • Language-specific variants: base_builder_go, etc.
   • See /oss-fuzz/infra/base-images/ for full list
4. Your project Docker image - Project-specific dependencies; based on base_builder or language variant

Runner Images (Used Separately)

• base_runner - Executes harnesses; based on base_clang
• base_runner_debug - With debug tools; based on base_runner

Advanced Usage

Tips and Tricks

Tip	Why It Helps
Don't manually copy source code	Project Dockerfile likely already pulls latest version
Check existing projects	Browse oss-fuzz/projects for examples
Keep harnesses in separate repo	Like curl-fuzzer - cleaner organization
Use specific compiler versions	Base images provide consistent build environment
Install dependencies in Dockerfile	May require approval for OSS-Fuzz enrollment

Criticality Score

OSS-Fuzz uses a criticality score to evaluate project acceptance. See [this example](https://github

---

Content truncated.