ClusterFuzz

https://google.github.io/clusterfuzz/
Admin
ClusterFuzz is a scalable fuzzing infrastructure that finds security and stability issues in...
Tokens:12,397
Snippets:224
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Server with Dependency Skip

Source: https://google.github.io/clusterfuzz/getting-started/local-instance

Use this command in a devcontainer environment to bypass dependency installation and accelerate server startup.

```bash
python butler.py run_server --skip-install-deps
```

--------------------------------

### Initialize and Run Local Server

Source: https://google.github.io/clusterfuzz/getting-started/local-instance

Commands to start the local server. Use the bootstrap flag for initial setup or data resets.

```bash
# If you run the server for the first time or want to reset all data.
python butler.py run_server --bootstrap

# In all the other cases, do not use "--bootstrap" flag.
python butler.py run_server
```

--------------------------------

### Example Coverage Information File

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/code-coverage

A concrete example of a zlib coverage report configuration file.

```json
{
    "report_date": "20190112",
    "fuzzer_stats_dir": "gs://oss-fuzz-coverage/zlib/fuzzer_stats/20190112",
    "report_summary_path": "gs://oss-fuzz-coverage/zlib/reports/20190112/linux/summary.json",
    "html_report_url": "https://storage.googleapis.com/oss-fuzz-coverage/zlib/reports/20190112/linux/index.html",
}
```

--------------------------------

### Install Development Dependencies

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Script to install required development dependencies on supported Linux and macOS systems.

```bash
local/install_deps.bash
```

--------------------------------

### Run ClusterFuzz Project Setup Script

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

Automate the setup of a production ClusterFuzz instance by running the `butler.py` script. Ensure you have created an empty directory for configuration and exported the necessary environment variables.

```bash
mkdir /path/to/myconfig  # Any EMPTY directory outside the ClusterFuzz source repository.
export CONFIG_DIR=/path/to/myconfig
python butler.py create_config --oauth-client-secrets-path=$CLIENT_SECRETS_PATH \
  --firebase-api-key=$FIREBASE_API_KEY --project-id=$CLOUD_PROJECT_ID $CONFIG_DIR
```

--------------------------------

### Execute Local Bot Instance

Source: https://google.github.io/clusterfuzz/getting-started/local-instance

Starts a bot instance by creating a local copy of the source code. Replace 'my-bot' with a unique identifier.

```bash
python butler.py run_bot --name my-bot /path/to/my-bot  # rename my-bot to anything
```

--------------------------------

### LibFuzzer and AFL Job Templates

Source: https://google.github.io/clusterfuzz/reference/job-definition

Example job templates for LibFuzzer and AFL fuzzing engines.

```bash
libfuzzer
engine_asan
```

```bash
libfuzzer
engine_ubsan
```

```bash
afl
engine_asan
```

--------------------------------

### macOS Bot Setup Script

Source: https://google.github.io/clusterfuzz/production-setup/setting-up-bots

Use this bash script to set up a ClusterFuzz bot on macOS. Ensure you have a service account key and have set the necessary environment variables.

```bash
export CLOUD_PROJECT_ID=<your project id>
export CONFIG_DIR=/path/to/myconfig
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
export INSTALL_DIRECTORY=/path/where/to/install/clusterfuzz-and-dependencies/to
$CONFIG_DIR/bot/setup/mac.bash

```

--------------------------------

### Activate and Verify Pipenv Environment

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Commands to activate the Python virtual environment and verify the installation.

```bash
pipenv shell
```

```bash
python butler.py --help
```

--------------------------------

### Export OAuth Client Secrets Path

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

Set the environment variable `CLIENT_SECRETS_PATH` to the location where you saved your downloaded OAuth client secrets JSON file. This is required for the project setup script.

```bash
export CLIENT_SECRETS_PATH=/path/to/your/client_secrets.json
```

--------------------------------

### Set Compiler Environment Variables

Source: https://google.github.io/clusterfuzz/setting-up-fuzzing/libfuzzer-and-afl

Set CC and CXX environment variables to point to your Clang installation. This is necessary for using Clang's instrumentation features for fuzzing.

```bash
export CC=/path/to/clang
export CXX=/path/to/clang++

```

--------------------------------

### Export Google Cloud Project ID

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

Export your Google Cloud project ID to an environment variable for subsequent use in setup scripts and commands. Replace `<your project id>` with your project's ID.

```bash
export CLOUD_PROJECT_ID=<your project id>
```

--------------------------------

### Describe Google Cloud Project

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

Use this command to verify that your Google Cloud project has been successfully created. Ensure you replace `<your project id>` with your actual project ID.

```bash
gcloud projects describe <your project id>
```

--------------------------------

### Authenticate with Google Cloud

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Commands to authenticate the local environment for production Google Cloud access.

```bash
gcloud auth application-default login
gcloud auth login
```

--------------------------------

### Checkout Specific Release Version

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Command to switch the repository to a specific stable release tag.

```bash
git checkout tags/vX.Y.Z
```

--------------------------------

### Build libFuzzer target for OpenSSL

Source: https://google.github.io/clusterfuzz/setting-up-fuzzing/heartbleed-example

Commands to download, build OpenSSL with ASan and fuzzer instrumentation, and compile a libFuzzer target. Ensure CC points to clang and CXX to clang++.

```bash
# Download and unpack a vulnerable version of OpenSSL:
curl -O https://ftp.openssl.org/source/old/1.0.1/openssl-1.0.1f.tar.gz
tar xf openssl-1.0.1f.tar.gz

# Build OpenSSL with ASan and fuzzer instrumentation:
cd openssl-1.0.1f/
./config

# $CC must be pointing to clang binary, see the "compiler section" link above.
make CC="$CC -g -fsanitize=address,fuzzer-no-link"
cd ..

# Download the fuzz target and its data dependencies:
curl -O https://raw.githubusercontent.com/google/clusterfuzz/master/docs/setting-up-fuzzing/heartbleed/handshake-fuzzer.cc
curl -O https://raw.githubusercontent.com/google/clusterfuzz/master/docs/setting-up-fuzzing/heartbleed/server.key
curl -O https://raw.githubusercontent.com/google/clusterfuzz/master/docs/setting-up-fuzzing/heartbleed/server.pem

# Build OpenSSL fuzz target for ClusterFuzz ($CXX points to clang++ binary):
$CXX -g handshake-fuzzer.cc -fsanitize=address,fuzzer openssl-1.0.1f/libssl.a \
  openssl-1.0.1f/libcrypto.a -std=c++17 -Iopenssl-1.0.1f/include/ -lstdc++fs   \
  -ldl -lstdc++ -o handshake-fuzzer

zip openssl-fuzzer-build.zip handshake-fuzzer server.key server.pem

```

--------------------------------

### Deploy App Engine Changes to Staging

Source: https://google.github.io/clusterfuzz/contributing-code/staging-changes

Use this command to deploy UI or cron changes to a staging server instance. The changes will be visible on the staging URL and use the production database.

```bash
python butler.py deploy --staging --config-dir=$CONFIG_DIR

```

--------------------------------

### Configure ClusterFuzz Linux Instance Template

Source: https://google.github.io/clusterfuzz/production-setup/setting-up-bots

Define properties for a Linux bot instance template, including machine type, disk configuration, and metadata. Ensure to increment the version after making changes.

```yaml
instance_templates:
  - name: clusterfuzz-linux
    description: '{"version": 1}'
    properties:
      machineType: n1-standard-1
      disks:
        - boot: true
          autoDelete: true
          initializeParams:
            sourceImage: projects/cos-cloud/global/images/family/cos-stable
            diskSizeGb: 100
            diskType: pd-standard
      metadata:
        items:
          - key: docker-image
            value: gcr.io/clusterfuzz-images/base:c44bf3f-201902112042
          - key: user-data
            value: file://linux-init.yaml
      serviceAccounts:
        - email: my-project-id-service-account-email
          scopes:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/prodxmon
      networkInterfaces:
        - network: global/networks/default
          accessConfigs:
            - type: ONE_TO_ONE_NAT
              name: 'External NAT'

```

--------------------------------

### Configure Linux Bots in clusters.yaml

Source: https://google.github.io/clusterfuzz/production-setup/setting-up-bots

Define regular and preemptible Linux bots for Google Compute Engine by modifying the clusters.yaml file. Adjust instance counts and zones as needed.

```yaml
# Regular bots run all task types (e.g fuzzing, minimize, etc).
clusterfuzz-linux:
  gce_zone: gce-zone
  instance_count: 1
  instance_template: clusterfuzz-linux
  distribute: False

# Pre-emptible bots must have '-pre-' in name. They only run fuzzing tasks.
clusterfuzz-linux-pre:
  gce_zone: gce-zone
  instance_count: 2
  instance_template: clusterfuzz-linux-pre
  distribute: False

```

--------------------------------

### Format Code with Butler

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Run this command before committing to automatically format your code according to project standards. Ensure all updated files are formatted.

```bash
python butler.py format
```

--------------------------------

### Build libFuzzer Target

Source: https://google.github.io/clusterfuzz/setting-up-fuzzing/libfuzzer-and-afl

Compile and link a fuzz target with libFuzzer and AddressSanitizer. The resulting binary can be tested locally or uploaded to ClusterFuzz.

```bash
$CXX -fsanitize=address,fuzzer fuzzer.cc -o fuzzer
# Test out the build by fuzzing it.
./fuzzer -runs=10
# Create a fuzzer build to upload to ClusterFuzz.
zip fuzzer-build.zip fuzzer

```

--------------------------------

### Monitor Bot Logs

Source: https://google.github.io/clusterfuzz/getting-started/local-instance

Navigate to the bot log directory and stream the log file output to the terminal.

```bash
cd /path/to/my-bot/clusterfuzz/bot/logs
tail -f bot.log
```

--------------------------------

### Specify Continuous Build Path and Binary

Source: https://google.github.io/clusterfuzz/production-setup/setting-up-fuzzing-job

Use RELEASE_BUILD_BUCKET_PATH to specify the Google Cloud Storage bucket for build archives using a regular expression. The regex must include a capturing group for the revision number. CUSTOM_BINARY should be set to False if using pre-built binaries.

```python
RELEASE_BUILD_BUCKET_PATH = gs://my-bucket/my-build-([0-9]+).zip
CUSTOM_BINARY = False

# These are only needed for blackbox fuzzing.
APP_NAME = myapp
APP_ARGS = -args -to -pass -to -myapp
...
```

--------------------------------

### Debug Python Dependency Issues

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Commands to resolve Python versioning conflicts and ensure the correct environment is active.

```bash
$ PYTHON=python3.11 ./local/install_deps.bash
```

```bash
$ pipenv shell
$ python --version
```

```bash
$ pipenv install --python 3.11
```

```bash
python3.11 butler.py py_unittest -t appengine
```

```bash
$ cd src; pipenv sync
```

--------------------------------

### Deploy New Changes to Production

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

Deploy updated configurations or code changes to your production ClusterFuzz environment using the `butler.py` script. The `--force` flag is used to overwrite existing deployments.

```bash
python butler.py deploy --config-dir=$CONFIG_DIR --prod --force
```

--------------------------------

### Lint Files with Butler

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Lint all updated files to check for code quality issues. This is a recommended step before committing changes.

```bash
python butler.py lint
```

--------------------------------

### Blackbox Fuzzing Job Environment Variables

Source: https://google.github.io/clusterfuzz/reference/job-definition

Environment variables for blackbox fuzzing, including application name, arguments, and test timeout.

```bash
RELEASE_BUILD_BUCKET_PATH = gs://chromium-browser-asan/linux-release/asan-linux-release-([0-9]+).zip
MIN_REVISION = 441045
CUSTOM_BINARY = False
APP_NAME = chrome
APP_ARGS = --enable-experimental-extension-apis --enable-extension-apps --js-flags="--expose-gc --verify-heap" --no-first-run --use-gl=swiftshader --disable-in-process-stack-traces
REQUIRED_APP_ARGS =  --no-first-run --use-gl=swiftshader --disable-in-process-stack-traces
TEST_TIMEOUT = 15
ADDITIONAL_ASAN_OPTIONS = allocator_may_return_null=0
```

--------------------------------

### LibFuzzer UBSan Job Environment Variables

Source: https://google.github.io/clusterfuzz/reference/job-definition

Environment variables for a LibFuzzer UBSan job, specifying the build path.

```bash
RELEASE_BUILD_BUCKET_PATH = gs://clusterfuzz-builds/zlib/zlib-undefined-([0-9]+).zip
CUSTOM_BINARY = False
```

--------------------------------

### Clone and Update ClusterFuzz Repository

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

Commands to clone the repository and ensure the local copy is up to date.

```bash
git clone https://github.com/google/clusterfuzz
cd clusterfuzz
git pull
```

--------------------------------

### AFL ASan Job Environment Variables

Source: https://google.github.io/clusterfuzz/reference/job-definition

Environment variables for an AFL ASan job, including a specific build bucket path.

```bash
RELEASE_BUILD_BUCKET_PATH = gs://clusterfuzz-builds-afl/zlib/zlib-address-([0-9]+).zip
CUSTOM_BINARY = False
```

--------------------------------

### GCP Logging Query for Fuzz Target and Revision

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/structured-logs

Query logs containing a specific fuzz target for a given source revision in GCP Logging. Use `*` as a wildcard if needed.

```json
jsonPayload.extras.clusterfuzz_version="b4de7f"
jsonPayload.extras.fuzz_target:*
```

--------------------------------

### Build AFL++ Target

Source: https://google.github.io/clusterfuzz/setting-up-fuzzing/libfuzzer-and-afl

Build AFL++ fuzzing targets using a provided script. This involves compiling the target with AddressSanitizer and coverage instrumentation, then linking against FuzzingEngine.a.

```bash
# Build afl-fuzz and FuzzingEngine.a
./build_afl.bash
# Compile target using ASan, coverage instrumentation, and link against FuzzingEngine.a
$CXX -fsanitize=address -fsanitize-coverage=trace-pc-guard fuzzer.cc FuzzingEngine.a -o fuzzer
# Test out the build by fuzzing it. INPUT_CORPUS is a directory containing files. Ctrl-C when done.
AFL_SKIP_CPUFREQ=1 ./afl-fuzz -i $INPUT_CORPUS -o output -m none ./fuzzer
# Create a fuzzer build to upload to ClusterFuzz.
zip fuzzer-build.zip fuzzer afl-fuzz afl-showmap

```

--------------------------------

### Lint Individual Files with Pylint

Source: https://google.github.io/clusterfuzz/getting-started/prerequisites

An alternative method to lint individual files using pylint. This is not the recommended approach for general use within the project.

```bash
pylint --score=no --jobs=0 <name of directory>
```

--------------------------------

### Run Core Unit Tests

Source: https://google.github.io/clusterfuzz/contributing-code/running-unit-tests

Execute unit tests for the core functionality of ClusterFuzz. Use optional switches like -m for parallel execution, -v for verbose output, -u to show print output, and -p to specify particular tests.

```python
python butler.py py_unittest -t core
```

--------------------------------

### Run App Engine Unit Tests

Source: https://google.github.io/clusterfuzz/contributing-code/running-unit-tests

Execute unit tests for App Engine related code, such as the UI and cron jobs. Any switch available for core tests can also be used here.

```python
python butler.py py_unittest -t appengine
```

--------------------------------

### Set Windows Password Metadata for GCE Bots

Source: https://google.github.io/clusterfuzz/production-setup/setting-up-bots

Add the administrator password for Windows bots using gcloud. The password must meet Windows policy requirements and be stored in a file.

```bash
gcloud compute project-info add-metadata \
  --metadata-from-file=windows-password=/path/to/password-file --project=$CLOUD_PROJECT_ID

```

--------------------------------

### LibFuzzer ASan Job Environment Variables

Source: https://google.github.io/clusterfuzz/reference/job-definition

Environment variables for a LibFuzzer ASan job, including build path and corpus pruning.

```bash
RELEASE_BUILD_BUCKET_PATH = gs://clusterfuzz-builds/zlib/zlib-address-([0-9]+).zip
CUSTOM_BINARY = False
CORPUS_PRUNE = True
```

--------------------------------

### GCP Logging Query for Task and Job

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/structured-logs

Query logs for a specific task name and job name in GCP Logging. Ensure the fields are prefixed with `jsonPayload.extras.`.

```json
jsonPayload.extras.task_name = "minimize"
jsonPayload.extras.task_job_name = "linux_asan_jsc"
```

--------------------------------

### GCP Logging Query for Testcase Lifecycle

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/structured-logs

Query logs related to the lifecycle of a specific testcase ID in GCP Logging. The testcase ID should be prefixed with `jsonPayload.extras.`.

```json
jsonPayload.extras.testcase_id="1234567"
```

--------------------------------

### Export Firebase Web API Key

Source: https://google.github.io/clusterfuzz/production-setup/clusterfuzz

After obtaining your Firebase web app's API key from the Firebase console, export it as an environment variable. Replace `<your api key>` with the actual key.

```bash
export FIREBASE_API_KEY=<your api key>
```

--------------------------------

### Define GCS Coverage Report Path

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/code-coverage

The path format for uploading the project coverage information file to a GCS bucket.

```text
gs://<bucket name>/latest_report_info/<project name>.json
# Example from OSS-Fuzz:
gs://oss-fuzz-coverage/latest_report_info/zlib.json
```

--------------------------------

### Define .srcmap.json structure

Source: https://google.github.io/clusterfuzz/production-setup/build-pipeline

The schema for mapping project dependencies to their respective version control systems and revision identifiers.

```json
{
  "/path/to/library": {
    "type": "type_of_version_control_system",
    "url": "repository_url",
    "rev": "revision_identifier",
  },
  // any number of the projects enumerated in this format
}
```

```json
{
  "/src/libpng": {
    "type": "git",
    "url": "https://github.com/glennrp/libpng.git",
    "rev": "eddf9023206dc40974c26f589ee2ad63a4227a1e"
  },
  "/src/zlib": {
    "type": "git",
    "url": "https://github.com/madler/zlib.git",
    "rev": "cacf7f1d4e3d44d871b605da3b647f07d718623f"
  },
  "/src/libfuzzer": {
    "type": "svn",
    "url": "https://llvm.org/svn/llvm-project/compiler-rt/trunk/lib/fuzzer",
    "rev": "350185"
  }
}
```

--------------------------------

### Stage Bot Changes on a Compute Engine Bot

Source: https://google.github.io/clusterfuzz/contributing-code/staging-changes

Stage code changes on a specific Compute Engine bot. These changes persist for 2 days and can be discarded by rebooting the bot. This functionality is only supported on GCE bots with specific Docker images.

```bash
python butler.py remote \
  --instance-name <your instance name> \
  --project <your project id> \
  --zone <your project zone> \
  stage --config-dir=$CONFIG_DIR

```

--------------------------------

### Define a ClusterFuzz job type

Source: https://google.github.io/clusterfuzz/setting-up-fuzzing/blackbox-fuzzing

Configuration block for specifying target application behavior and execution parameters.

```text
APP_NAME = app
APP_ARGS = --some_interesting_option --some_very_important_option
REQUIRED_APP_ARGS = --some_very_important_option
CUSTOM_BINARY = True
TEST_TIMEOUT = 30
```

--------------------------------

### Define Coverage Information JSON Format

Source: https://google.github.io/clusterfuzz/using-clusterfuzz/advanced/code-coverage

The required JSON structure for the coverage information file uploaded to GCS.

```json
{
    "report_date": "YYYYMMDD",
    "fuzzer_stats_dir": "gs://path_to_directory_with_per_fuzzer_summary.json_files",
    "report_summary_path": "gs://path_to_the_project_summary.json_file",
    "html_report_url": "https://link_to_the_main_page_of_the_report",
}
```
Tokens:
Raw