Dulwich Documentation

The fuzzing/ directory is organized into three main areas:

fuzz-targets/

Contains Python files for each fuzz test.

• Naming Convention: fuzz_<API Under Test>.py.
• Targeting: Tests should target functionality involving input data processing, especially parsing or untrusted user input.
• Error Handling: Fuzz tests should use try/except blocks to handle anticipated exceptions gracefully, preventing false positives from halting the engine.

dictionaries/

Contains .dict files that provide hints to the fuzzing engine about specific input patterns to trigger unique code paths.

• Loading: OSS-Fuzz loads a dictionary file if it shares the same name as the fuzz target.
• Content: Entries are often escaped byte values recommended by the engine.

oss-fuzz-scripts/

Scripts used for building and integrating with OSS-Fuzz:

• container-environment-bootstrap.sh: Sets up the execution environment and dependencies.
• build.sh: Builds targets with instrumentation and prepares seed corpora/dictionaries.

To run Dulwich fuzzers locally, you must use Docker containers provided by OSS-Fuzz. This requires cloning the OSS-Fuzz repository and using its helper scripts to build the execution environment and the fuzzers themselves.

Prerequisites

• Python installed
• Docker installed
• A local clone of the Dulwich repository

Build Steps

1. Clone the OSS-Fuzz repository:

   git clone --depth 1 https://github.com/google/oss-fuzz.git oss-fuzz
   cd oss-fuzz

2. Build the Docker image:

   python infra/helper.py build_image dulwich

3. Build the fuzzers (using the address sanitizer):

   python infra/helper.py build_fuzzers --sanitizer address dulwich

Tip: If you are developing fuzz targets locally in your Dulwich clone, you can point the build_fuzzers command to your local path to avoid modifying the OSS-Fuzz repository:

python infra/helper.py build_fuzzers --sanitizer address dulwich ~/path/to/your/dulwich

Verify Build

Use the check_build command to ensure the fuzzers were built correctly:

python infra/helper.py check_build dulwich

Once the environment is built, you can execute specific fuzz targets using the run_fuzzer command. It is recommended to use the FUZZ_TARGET environment variable to switch between targets easily.

Execution Steps

1. Set the target name (without the .py extension):

   export FUZZ_TARGET=fuzz_configfile

2. Run the fuzzer:

   python infra/helper.py run_fuzzer dulwich $FUZZ_TARGET -- -max_total_time=60 -print_final_stats=1

Passing Arguments to the Fuzzing Engine

Any arguments provided after the -- separator in the run_fuzzer command are passed directly to the underlying fuzzing engine (e.g., LibFuzzer).

Commonly used flags:

• -max_total_time=N: Tells the engine to stop after $N$ seconds.
• -print_final_stats=1: Prints a summary of metrics upon completion.

You can use any LibFuzzer option this way.

A RangeDiffEntry represents a single correspondence in a range-diff. It contains indices, the commit objects, a status, and a diff if applicable.

Status Codes:

• = : Identical patch (the commit's change is the same in both ranges).
• ! : Different patch (the commit exists in both, but the changes differ). The diff field will contain the "diff of diffs".
• > : Only in the second range (new commit).
• < : Only in the first range (deleted commit).

Attributes:

• old_idx: 1-based index in the first range, or None if the commit only exists in the second range.
• new_idx: 1-based index in the second range, or None if the commit only exists in the first range.
• old_commit: The Commit object from the first range, or None.
• new_commit: The Commit object from the second range, or None.
• status: The status string (=, !, >, <).
• diff: A list of bytes representing the diff between the two patches (only populated when status is !).