ossfuzz

# OSS-Fuzz

[OSS-Fuzz](https://google.github.io/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 | `uv run --no-project python infra/helper.py build_image --pull <project>` |
| Build fuzzers with ASan | `uv run --no-project python infra/helper.py build_fuzzers --sanitizer=address <project>` |
| Run specific harness | `uv run --no-project python infra/helper.py run_fuzzer <project> <harness>` |
| Generate coverage report | `uv run --no-project python infra/helper.py coverage <project>` |
| Check helper.py options | `uv run --no-project python infra/helper.py --help` |

## OSS-Fuzz Project Components

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

### Bug Tracker

The [bug tracker](https://issues.oss-fuzz.com/issues?q=status:open) allows you to:
- Check bugs from specific projects (initially visible only to maintainers, later [made public](https://google.github.io/oss-fuzz/getting-started/bug-disclosure-guidelines/))
- 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](https://oss-fuzz-build-logs.storage.googleapis.com/index.html) helps track:
- Build statuses of all included projects
- Date of last successful build
- Build failures and their duration

### Fuzz Introspector

[Fuzz Introspector](https://oss-fuzz-introspector.storage.googleapis.com/index.html) displays:
- Coverage data for projects enrolled in OSS-Fuzz
- Hit frequency for covered code
- Performance analysis and blocker identification

Read [this case study](https://github.com/ossf/fuzz-introspector/blob/main/doc/CaseStudies.md) 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

```bash
git clone https://github.com/google/oss-fuzz
cd oss-fuzz
uv run --no-project python infra/helper.py --help
```

### Step 2: Build Project Image

```bash
uv run --no-project python 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

```bash
uv run --no-project python infra/helper.py build_fuzzers --sanitizer=address <project-name>
```

**Sanitizer options:**
- `--sanitizer=address` for [AddressSanitizer](https://appsec.guide/docs/fuzzing/techniques/asan/) with [LeakSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer)
- 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

```bash
uv run --no-project python 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](https://cloud.google.com/storage/docs/gsutil_install) (skip gcloud initialization).

```bash
uv run --no-project python infra/helper.py build_fuzzers --sanitizer=coverage <project-name>
uv run --no-project python 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](https://google.github.io/oss-fuzz/advanced-topics/code-coverage/) for details.

## Common Patterns

### Pattern: Running irssi Example

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

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

# Build and run irssi fuzzer
uv run --no-project python infra/helper.py build_image --pull irssi
uv run --no-project python infra/helper.py build_fuzzers --sanitizer=address irssi
uv run --no-project python infra/helper.py run_fuzzer irssi irssi-fuzz
```

**Expected Output:**
```
INFO:__main__:Running: docker run --rm --privi