History

README.md

This directory contains files related to GitPython's suite of fuzz tests that are executed daily on automatedinfrastructure provided byOSS-Fuzz. This document aims to provide necessary information for workingwith fuzzing in GitPython.

The latest details regarding OSS-Fuzz test status, including build logs and coverage reports, is availableonthe Open Source Fuzzing Introspection website.

There are many ways to contribute to GitPython's fuzzing efforts! Contributions are welcomed through issues,discussions, or pull requests on this repository.

Areas that are particularly appreciated include:

• Tackling the existing backlog of open issues. While fuzzing is an effective way to identify bugs, that informationisn't useful unless they are fixed. If you are not sure where to start, the issues tab is a great place to get ideas!
• Improvements to this (or other) documentation make it easier for new contributors to get involved, so even smallimprovements can have a large impact over time. If you see something that could be made easier by a documentationupdate of any size, please consider suggesting it!

For everything else, such as expanding test coverage, optimizing test performance, or enhancing error detectioncapabilities, jump into the "Getting Started" section below.

Before contributing to fuzzing efforts, ensure Python and Docker are installed on your machine. Docker is required forrunning fuzzers in containers provided by OSS-Fuzz and for safely executing test files directly.Install Docker following the official guide if you do not already have it.

Review thefuzz-targets/ directory to familiarize yourself with how existing tests are implemented. SeetheFiles & Directories Overview for more details on the directory structure.

Start by reviewing theAtheris documentation and the sectiononRunning Fuzzers Locally to begin writing or improving fuzz tests.

Thefuzzing/ directory is organized into three key areas:

Contains Python files for each fuzz test.

Things to Know:

• Each fuzz test targets a specific part of GitPython's functionality.
• Test files adhere to the naming convention:fuzz_<API Under Test>.py, where<API Under Test> indicates thefunctionality targeted by the test.
• Any functionality that involves performing operations on input data is a possible candidate for fuzz testing, butfeatures that involve processing untrusted user input or parsing operations are typically going to be the mostinteresting.
• The goal of these tests is to identify previously unknown or unexpected error cases caused by a given input. For thatreason, fuzz tests should gracefully handle anticipated exception cases with atry/except block to avoid falsepositives that halt the fuzzing engine.

Includes scripts for building and integrating fuzz targets with OSS-Fuzz:

• container-environment-bootstrap.sh - Sets up the execution environment. It is responsible for fetching defaultdictionary entries and ensuring all required build dependencies are installed and up-to-date.
• build.sh - Executed within the Docker container, this script builds fuzz targets with necessary instrumentationand prepares seed corpora and dictionaries for use.

Where to learn more:

• OSS-Fuzz documentation on the build.sh
• See GitPython's build.sh and Dockerfile in the OSS-Fuzz repository

Contains tools to make local development tasks easier.Seethe "Running Fuzzers Locally" section below for further documentation and use cases related to files found here.

Directly executing fuzz targets allows for quick iteration and testing of changes which can be helpful during earlydevelopment of new fuzz targets or for validating changes made to an existing test.TheDockerfile located in thelocal-dev-helpers/ subdirectory provides a lightweightcontainer environment preconfigured withAtheris that makes it easy to execute a fuzz target directly.

From the root directory of your GitPython repository clone:

1. Build the local development helper image:

docker build -f fuzzing/local-dev-helpers/Dockerfile -t gitpython-fuzzdev.

2. Then execute a fuzz target inside the image, for example:

 docker run -it -v"$PWD":/src gitpython-fuzzdev python fuzzing/fuzz-targets/fuzz_config.py -atheris_runs=10000

The above command executesfuzz_config.py and exits after10000 runs, or earlier ifthe fuzzer finds an error.

Docker CLI's-v flag specifies a volume mount in Docker that maps the directory in which the command is run (whichshould be the root directory of your local GitPython clone) to a directory inside the container, so any modificationsmade between invocations will be reflected immediately without the need to rebuild the image each time.

This approach uses Docker images provided by OSS-Fuzz for building and running fuzz tests locally. It offerscomprehensive features but requires a local clone of the OSS-Fuzz repository and sufficient disk space for Dockercontainers.

Clone the OSS-Fuzz repository and prepare the Docker environment:

git clone --depth 1 https://github.com/google/oss-fuzz.git oss-fuzzcd oss-fuzzpython infra/helper.py build_image gitpythonpython infra/helper.py build_fuzzers --sanitizer address gitpython

python infra/helper.py build_fuzzers --sanitizer address gitpython~/code/GitPython

Verify the build of your fuzzers with the optionalcheck_build command:

python infra/helper.py check_build gitpython

Setting an environment variable for the fuzz target argument of the execution command makes it easier to quickly selecta different target between runs:

# specify the fuzz target without the .py extension:export FUZZ_TARGET=fuzz_config

Execute the desired fuzz target:

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

For detailed instructions on advanced features like reproducing OSS-Fuzz issues or using the Fuzz Introspector, refertothe official OSS-Fuzz documentation.

All files located within thefuzzing/ directory are subject tothe same licenseasthe other files in this repository with one exception:

fuzz_config.py was migrated to this repository from the OSS-Fuzz project's repositorywhere it was originally created. As such,fuzz_config.py retains its original licenseand copyright notice (Apache License, Version 2.0 and Copyright 2023 Google LLC respectively) as in a headercomment, followed by a notice stating that it has have been modified contributors to GitPython.LICENSE-APACHE contains the original license used by the OSS-Fuzz project repository at the time thefile was migrated.