ClusterFuzzLite Documentation

ClusterFuzzLite is a continuous fuzzing solution designed to run within Continuous Integration (CI) workflows. It enables developers to find vulnerabilities by fuzzing pull requests before code is committed.

Key capabilities include:

• Pull Request Fuzzing: Quick fuzzing on code changes to catch bugs early.
• Batch Fuzzing: Continuous, longer-running fuzzing to find deeper bugs and build a corpus for code-change fuzzing.
• Crash Reporting: Automatic downloads of crashing testcases.
• Coverage Reports: Visibility into which parts of the codebase are being exercised by the fuzzer.
• Modular Design: Users can select specific features based on their needs.

The FuzzedDataProvider class (part of the Jazzer API) simplifies fuzzing by translating raw input bytes into useful Java types (e.g., int, long, String).

• Availability: The library is located at $JAZZER_API_PATH in ClusterFuzzLite base images.
• Local Development: You can obtain the library from Maven Central under the group com.code-intelligence and artifact jazzer-api.
• Usage: Pass FuzzedDataProvider as the argument to fuzzerTestOneInput instead of byte[].

ClusterFuzzLite's use of cargo-fuzz automatically enables the fuzzing feature. You can use this to organize code and manage dependencies specifically for fuzzing, similar to how #[cfg(test)] works for unit tests.

Conditional Compilation

You can wrap fuzzing-specific logic in modules using the fuzzing attribute:

#[cfg(fuzzing)]
pub mod fuzz_logic {
    use super::*;
    // ... fuzzing implementation
}

To combine testing and fuzzing logic into a single block, use:

#[cfg(any(test, fuzzing))]

Fuzzing-specific Dependencies

In your Cargo.toml files, you can define dependencies that are only compiled when the fuzzing feature is active:

[target.'cfg(fuzzing)'.dependencies]
# fuzzing-only dependencies here

When setting up a new platform, you can choose between implementing a custom filestore or reusing existing ones:

• Reuse existing filestores: You can use gsutil to support Google Cloud Storage Buckets or Amazon S3 Buckets.
• Use no_filestore: If your platform does not support file storage, use the no_filestore implementation. This makes all filestore operations no-ops. This allows ClusterFuzzLite to run without exceptions, but most important features (like saving crashes or coverage) will not function.

ClusterFuzzLite uses sanitizers to detect bugs by instrumenting code at compile-time. When configuring ClusterFuzzLite, use the following shorthand names to specify the sanitizer:

• address: Refers to AddressSanitizer (ASan). Used for detecting memory safety issues and memory leaks. This is the most critical sanitizer for fuzzing.
• ubsan: Refers to UndefinedBehaviorSanitizer (UBSan). Used for detecting undefined behavior, such as integer overflows.
• memory: Refers to MemorySanitizer (MSan). Used for detecting the use of uninitialized memory.

Note on MSan: To avoid false positives, an MSan instrumented binary must be entirely instrumented with MSan; if any part of the binary lacks MSan instrumentation, it will report errors.

ClusterFuzzLite provides several key capabilities for vulnerability discovery:

• Quick code change (pull request) fuzzing: Finds bugs during the PR process before code is merged.
• Crashing testcase downloads: Allows users to download the specific inputs that caused a crash.
• Continuous batch fuzzing: Runs longer-term fuzzing asynchronously to find deeper bugs and build a corpus to improve code-change fuzzing efficiency.
• Coverage reports: Provides visibility into which parts of the codebase are being exercised by the fuzzer.
• Modular functionality: Users can opt-in to specific features as needed.

To begin using ClusterFuzzLite, choose your starting point based on your familiarity with fuzzing:

1. New to fuzzing? If you are unfamiliar with libFuzzer and sanitizers, review the project's [Overview] documentation to understand the fuzzing process and terminology.
2. Experienced with fuzzing? If you already understand libFuzzer and sanitizers, proceed directly to [Step 1: Build Integration] to integrate fuzzing into your build system.

Since Google Cloud Build does not provide an easy way to download build files directly, you must access them via your Google Cloud Storage bucket.

Downloading Crashes:

1. Inspect the build logs to find the name of the crashing input file.
2. Download the crash file from: <your-cloud-bucket>/crashes/<fuzzer>/<sanitizer>/<crash-file>

Viewing via Browser: You can navigate to the following URL in a web browser: https://console.cloud.google.com/storage/browser/<your-cloud-bucket-without-gs>/crashes/<fuzzer>/<sanitizer>

Note: <your-cloud-bucket-without-gs> is your bucket name without the gs:// prefix (e.g., if your bucket is gs://my-bucket, use my-bucket).