OSS-Fuzz

Contract

Field	Bound contract
Trigger	User needs to enroll an open-source project in OSS-Fuzz, run its helper workflow locally, or reproduce an OSS-Fuzz report.
Authority	Reversible local: writes only named local artifacts (oss-fuzz clone, Docker images, project enrollment files); rollback is docker rmi for images and filesystem deletion for the clone. No remote mutation.
Side effect	OSS-Fuzz project integration files, Docker image builds, and local fuzzing campaign artifacts written to the oss-fuzz working directory.
Done	Task A: the project Docker image builds, fuzzers compile with AddressSanitizer, and the named harness executes. Task B: projects/<project_name>/project.yaml, Dockerfile, and build.sh are present and structurally valid.

Inputs

Input	Required	Description
project_name	Required	OSS-Fuzz project identifier (slug used in infra/helper.py commands and the projects/ subdirectory).
harness_name	Required for local run	Fuzzer executable name inside the project's build output directory.
language	Required for enrollment	Project language (e.g. c++, python, rust, go).
main_repo	Required for enrollment	URL of the project's primary source repository.
sanitizer	Optional	Sanitizer for build_fuzzers: address (default), undefined, coverage.
fuzzer_args	Optional	Extra arguments passed through to the fuzzer binary.
oss_fuzz_dir	Optional	Local path of the cloned oss-fuzz repository; defaults to ./oss-fuzz.
primary_contact	Required for enrollment	Maintainer email for project.yaml.

Procedure

Task A: run an enrolled project locally

1. Verify docker is available and the user has permission to run containers (docker info exits 0). Done when: docker info exits 0.
2. Clone oss-fuzz if oss_fuzz_dir does not exist or is not a git repository:

   oss_fuzz_dir="${oss_fuzz_dir:-./oss-fuzz}"
   git clone https://github.com/google/oss-fuzz "$oss_fuzz_dir"
   

   Done when: the oss-fuzz repository is cloned and present at oss_fuzz_dir.
3. Change to the oss-fuzz directory:

   oss_fuzz_dir="${oss_fuzz_dir:-./oss-fuzz}"
   cd "$oss_fuzz_dir"
   

   Done when: the working directory is the oss-fuzz directory.
4. Build the project Docker image:

   project_name="${project_name:?project_name is required}"
   uv run --no-project python infra/helper.py build_image --pull "$project_name"
   

   If build_image reports the project directory does not exist under projects/, stop and return enrollment-missing. Done when: the project Docker image builds successfully or enrollment-missing is returned.
5. Build the fuzzers with AddressSanitizer:

   project_name="${project_name:?project_name is required}"
   sanitizer="${sanitizer:-address}"
   uv run --no-project python infra/helper.py build_fuzzers --sanitizer="$sanitizer" "$project_name"
   

   Capture stdout/stderr. If the build exits non-zero, return build-failed with the captured output. Done when: fuzzers compile with the configured sanitizer and stdout/stderr are captured.
6. Run the named harness:

   project_name="${project_name:?project_name is required}"
   harness_name="${harness_name:?harness_name is required}"
   fuzzer_args="${fuzzer_args:-}"
   uv run --no-project python infra/helper.py run_fuzzer "$project_name" "$harness_name" ${fuzzer_args:+"$fuzzer_args"}
   

   Observe for at least 10 seconds. If the harness exits with a sanitizer report, return crash-detected with the report path. Otherwise return harness-ran. Done when: the harness runs for at least 10 seconds and returns harness-ran or crash-detected.

Task B: enroll a new project

1. Verify the project has an OSS-Fuzz-compatible harness at $main_repo or an associated harness repository. Done when: a compatible harness is confirmed at $main_repo or the associated repository.
2. Create projects/<project_name>/ under the oss-fuzz directory. Done when: the project directory is created.
3. Write projects/<project_name>/project.yaml:

   homepage: "<main_repo>"
   language: "<language>"
   primary_contact: "<primary_contact>"
   main_repo: "<main_repo>"
   fuzzing_engines:
     - libfuzzer
   sanitizers:
     - address
   

   Extend sanitizers and fuzzing_engines if the task specifies additional values. Done when: project.yaml is written with all required fields and any extensions.
4. Write projects/<project_name>/Dockerfile using gcr.io/oss-fuzz-base/base-builder as the base image; add language-specific and project-specific RUN commands to install build dependencies. Do not copy source code directly; use git clone in the Dockerfile. Done when: Dockerfile is written with the base image and git clone for source.
5. Write projects/<project_name>/build.sh as an executable script:
   • Set #!/bin/bash -eu.
   • Clone or build project dependencies.
   • Compile harnesses using $CXX, $CXXFLAGS, $LIB_FUZZING_ENGINE, $SRC, and $OUT as provided by the OSS-Fuzz environment.
   • Copy corpus and dictionary files to $OUT if present. Done when: build.sh is written as an executable script with all four elements.
6. Return enrollment-artifacts-written listing the three files and their paths. Done when: the three artifact paths are returned.

Failure and recovery

Failure class	Trigger	Result
docker-unavailable	docker info exits non-zero	Return blocked: docker-unavailable. Do not attempt container operations.
enrollment-missing	projects/<project_name> absent and task is local run	Return blocked: enrollment-missing. Enrollment is out of scope for local-run unless explicitly requested.
build-failed	build_fuzzers exits non-zero	Return failed: build-failed with captured stderr. Do not proceed to run step.
crash-detected	Harness exits with ASan/UBSan report	Return crash-detected with the report file path. Do not suppress or dismiss the report.
rollback	Any step fails; Docker images written by this session	Rollback: docker rmi $(docker images --filter=reference="gcr.io/oss-fuzz/$(basename "$project_name")*" -q) 2>/dev/null; delete the oss_fuzz_dir clone if this session created it.

Output

Outcome	Output
Local run, build success, no crash	done: harness-ran: fuzzer is running and producing coverage or execution output.
Local run, crash detected	crash-detected: <report-path>: sanitizer report written to the build output directory.
Enrollment artifacts written	done: enrollment-artifacts-written: project.yaml, Dockerfile, build.sh paths listed.
Build failed	failed: build-failed: full build log for diagnosis.
Prerequisites not met	blocked: <failure-class>: reason stated, no progress claimed.