Add docs for OSS-Fuzz integration

doc/development_guide/contributor_guide/index.rst

@@ -12,5 +12,6 @@ The contributor guide will help you if you want to contribute to pylint itself.
    contribute
    tests/index
    profiling
+   oss_fuzz
    release
    governance

doc/development_guide/contributor_guide/oss_fuzz.rst

@@ -0,0 +1,165 @@
+======================
+ OSS-Fuzz integration
+======================
+
+Platform overview
+-----------------
+
+`OSS-Fuzz <https://google.github.io/oss-fuzz/>`_ is Google's free fuzzing platform for open source
+software. It runs astroid's fuzz targets to help detect reliability issues that could affect astroid
+and Pylint.
+
+Google provides public `build logs <https://oss-fuzz-build-logs.storage.googleapis.com/index.html#astroid>`_
+and `fuzzing stats <https://introspector.oss-fuzz.com/project-profile?project=astroid>`_, but most
+of the details about bug reports and fuzzed testcases require approved access.
+
+Gaining access
+^^^^^^^^^^^^^^
+
+The configuration files for the OSS-Fuzz integration can be found in the
+`OSS-Fuzz repository <https://github.com/google/oss-fuzz/tree/master/projects/astroid>`_.
+The ``project.yaml`` file controls who has access to bug reports and testcases. Ping the
+maintainers if you'd like to be added to the list (note: a Google account is required for
+access).
+
+Fuzzing progress
+----------------
+
+Once you have access to OSS-Fuzz, you can log in to https://oss-fuzz.com/ with your Google account
+to see a dashboard of astroid's fuzzing progress.
+
+Testcases
+^^^^^^^^^
+
+The dashboard contains a link to a `testcases page <https://oss-fuzz.com/testcases?project=astroid&open=yes>`_
+that lists all testcases that currently trigger a bug in astroid.
+
+Every testcase has a dedicated page with links to view and download a minimized testcase for
+reproducing the failure. Each testcase page also contains a stacktrace for the failure and stats
+about how often the failure is encountered while fuzzing.
+
+Reproducing a failure
+"""""""""""""""""""""
+
+You can download a minimized testcase and run it locally to debug a failure on your machine.
+For example, to reproduce a failure with the ``fuzz_parse`` fuzz target, you can run the following
+commands:
+
+.. code:: bash
+
+  # Note: Atheris doesn't support Python 3.12+ yet:
+  # https://github.com/google/atheris/issues/82
+  mkdir fuzzing-repro
+  cd fuzzing-repro
+
+  pyenv install --skip-existing 3.11
+  pyenv shell 3.11
+
+  python -m venv .venv-fuzzing-repro
+  source .venv-fuzzing-repro/bin/activate
+
+  git clone https://github.com/pylint-dev/astroid.git
+  cd astroid
+
+  pip install atheris
+  pip install --editable .
+
+  # Save the minimized testcase as `minimized.py` in the astroid directory
+
+  cat << EOF > ./run_fuzz_parse.py
+
+  import astroid
+  import atheris
+
+  with open('minimized.py', 'rb') as f:
+      fdp = atheris.FuzzedDataProvider(f.read())
+
+  code = fdp.ConsumeUnicodeNoSurrogates(fdp.ConsumeIntInRange(0, 4096))
+  astroid.builder.parse(code)
+  EOF
+
+  python ./run_fuzz_parse.py
+
+
+If the failure does not reproduce locally, you can try reproducing the issue in an OSS-Fuzz
+container:
+
+.. code:: bash
+
+  git clone https://github.com/google/oss-fuzz.git
+  cd oss-fuzz
+
+  python infra/helper.py build_image astroid
+  python infra/helper.py build_fuzzers astroid
+  python infra/helper.py reproduce astroid fuzz_parse minimized.py
+
+Some failures may only be reproducible in an OSS-Fuzz container because of differences in Python
+versions between the OSS-Fuzz platform and your local environment.
+
+Code coverage
+^^^^^^^^^^^^^
+
+The dashboard also links to code coverage data for individual fuzz targets and combined code
+coverage data for all targets (click on the "TOTAL COVERAGE" link for the combined data).
+
+The combined coverage data is helpful for identifying coverage gaps, insufficient corpus data, and
+potential candidates for future fuzz targets.
+
+Bug reports
+^^^^^^^^^^^
+
+Bug reports for new failures are automatically filed in the OSS-Fuzz bug tracker with an
+`astroid label <https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-astroid>`_.
+Make sure you are logged in to view all existing issues.
+
+Build maintenance
+-----------------
+
+Google runs compiled fuzz targets on Google Compute Engine VMs. This architecture requires each
+project to provide a ``Dockerfile`` and ``build.sh`` script to download code, configure
+dependencies, compile fuzz targets, and package any corpus files.
+
+astroid's build files and fuzz-target code can be found in the
+`OSS-Fuzz repo <https://github.com/google/oss-fuzz/blob/master/projects/astroid/>`_.
+
+If dependencies change or if new fuzz targets are added, then you may need to modify the build files
+and build a new Docker image for OSS-Fuzz.
+
+Building an image
+^^^^^^^^^^^^^^^^^
+
+Run the following commands to build astroid's OSS-Fuzz image and fuzz targets:
+
+.. code:: bash
+
+  git clone https://github.com/google/oss-fuzz.git
+  cd oss-fuzz
+
+  python infra/helper.py build_image astroid
+  python infra/helper.py build_fuzzers astroid
+
+Any changes you make to the build files must be submitted as pull requests to the OSS-Fuzz repo.
+
+Debugging build failures
+""""""""""""""""""""""""
+
+You can debug build failures during the ``build_fuzzers`` stage by creating a container and manually
+running the ``compile`` command:
+
+.. code:: bash
+
+  # Create a container for building fuzz targets
+  python infra/helper.py shell astroid
+
+  # Run this command inside the container to build the fuzz targets
+  compile
+
+The ``build.sh`` script will be located at ``/src/build.sh`` inside the container.
+
+Quick links
+-----------
+
+- `OSS-Fuzz dashboard <https://oss-fuzz.com/>`_
+- `OSS-Fuzz configuration files, build scripts, and fuzz targets for astroid <https://github.com/google/oss-fuzz/tree/master/projects/astroid>`_
+- `All open OSS-Fuzz bugs for astroid <https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-astroid>`_
+- `Google's OSS-Fuzz documentation <https://google.github.io/oss-fuzz/>`_