Rooba
/
oss-fuzz
mirror of https://github.com/google/oss-fuzz.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes (#2689)

This commit is contained in:
Abhishek Arya 2019-08-12 14:15:33 -07:00 committed by GitHub
parent 5b8dcb5d94
commit b97503d279
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 142 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/getting-started/accepting_new_projects.md
View File

@ -21,10 +21,10 @@ with a new `projects/<project_name>/project.yaml` file
2. In the file, provide the following information:
- Your project's homepage.
- An email address for the engineering contact to be CCed on new issues, satisfying the following:
- The address belongs to an established project committer (according to VCS logs).
- The address belongs to an established project committer (according to VCS logs).
If the address isn't you, or if the address differs from VCS, we'll require an informal
email verification.
- The address is associated with a Google account
- The address is associated with a Google account
([why?]({{ site.baseurl }}/faq/#why-do-you-require-a-google-account-for-authentication)).
If you use an alternate email address
[linked to a Google Account](https://support.google.com/accounts/answer/176347?hl=en),

269
docs/getting-started/new_project_guide.md
View File

@ -1,21 +1,25 @@
---
layout: default
title: New project guide
title: Setting up a new project
parent: Getting started
nav_order: 2
permalink: /getting-started/new-project-guide/
---
# Setting up a new project
{: .no_toc}
- TOC
{:toc}
---
## Prerequisites
- [Integrate]({{ site.baseurl }}/advanced-topics/ideal-integration/) one or more [Fuzz Targets]({{ site.baseurl }}/reference/glossary/#fuzz-target)
Before you can start setting up your new project for fuzzing, you must do the following:
- [Integrate]({{ site.baseurl }}/advanced-topics/ideal-integration/) one or more [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target)
with the project you want to fuzz.
Examples:
For examples, see
[boringssl](https://github.com/google/boringssl/tree/master/fuzz),
[SQLite](https://www.sqlite.org/src/artifact/ad79e867fb504338),
[s2n](https://github.com/awslabs/s2n/tree/master/tests/fuzz),
@ -23,38 +27,37 @@ permalink: /getting-started/new-project-guide/
[FreeType](http://git.savannah.gnu.org/cgit/freetype/freetype2.git/tree/src/tools/ftfuzzer),
[re2](https://github.com/google/re2/tree/master/re2/fuzzing),
[harfbuzz](https://github.com/behdad/harfbuzz/tree/master/test/fuzzing),
[pcre2](http://vcs.pcre.org/pcre2/code/trunk/src/pcre2_fuzzsupport.c?view=markup),
[pcre2](http://vcs.pcre.org/pcre2/code/trunk/src/pcre2_fuzzsupport.c?view=markup), and
[ffmpeg](https://github.com/FFmpeg/FFmpeg/blob/master/tools/target_dec_fuzzer.c).
- Install Docker using the instructions
[here](https://docs.docker.com/engine/installation).
Googlers: [go/installdocker](https://goto.google.com/installdocker).
- [Install Docker](https://docs.docker.com/engine/installation)
(Googlers can visit [go/installdocker](https://goto.google.com/installdocker)).
[Why Docker?]({{ site.baseurl }}/faq/#why-do-you-use-docker)
*NOTE: (Optional) If you want to run `docker` without `sudo`, follow the
[Create a docker group](https://docs.docker.com/engine/installation/linux/ubuntulinux/#/create-a-docker-group) section.*
*NOTE: Docker images can consume significant disk space. Run*
*[docker-cleanup](https://gist.github.com/mikea/d23a839cba68778d94e0302e8a2c200f)*
*periodically to garbage collect unused images.*
If you want to run `docker` without `sudo`, you can
[create a docker group](https://docs.docker.com/engine/installation/linux/ubuntulinux/#/create-a-docker-group).
## Overview
**Note:** Docker images can consume significant disk space. Run
[docker-cleanup](https://gist.github.com/mikea/d23a839cba68778d94e0302e8a2c200f)
periodically to garbage-collect unused images.
To add a new OSS project to OSS-Fuzz, you need a project subdirectory
inside the [`projects/`](https://github.com/google/oss-fuzz/tree/master/projects) directory in [OSS-Fuzz repository](https://github.com/google/oss-fuzz).
Example: [boringssl](https://github.com/google/boringssl) project is located in
[`projects/boringssl`](https://github.com/google/oss-fuzz/tree/master/projects/boringssl).
## Creating the file structure
The project directory needs to contain the following three configuration files:
Each OSS-Fuzz project has a subdirectory
inside the [`projects/`](https://github.com/google/oss-fuzz/tree/master/projects) directory in the [OSS-Fuzz repository](https://github.com/google/oss-fuzz). For example, the [boringssl](https://github.com/google/boringssl)
project is located in [`projects/boringssl`](https://github.com/google/oss-fuzz/tree/master/projects/boringssl).
* `projects/<project_name>/project.yaml` - provides metadata about the project.
* `projects/<project_name>/Dockerfile` - defines the container environment with information
Each project directory also contains the following three configuration files:
* [project.yaml](#project.yaml) - provides metadata about the project.
* [Dockerfile](#Dockerfile) - defines the container environment with information
on dependencies needed to build the project and its [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target).
* `projects/<project_name>/build.sh` - build script that executes inside the container and
generates project build.
* [build.sh](#build.sh) - defines the build script that executes inside the Docker container and
generates the project build.
To *automatically* create a new directory for your project and
generate templated versions of these configuration files,
run the following set of commands:
You can automatically create a new directory for your project in OSS-Fuzz and
generate templated versions of the configuration files
by running the following commands:
```bash
$ cd /path/to/oss-fuzz
@ -62,39 +65,44 @@ $ export PROJECT_NAME=<project_name>
$ python infra/helper.py generate $PROJECT_NAME
```
It is preferred to keep and maintain [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) in your own source code repository. If this is not possible due to various reasons, you can store them inside the OSS-Fuzz's project directory created above.
Once the template configuration files are available, you can modify them to fit your project.
**Note:** We prefer that you keep and maintain [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) in your own source code repository. If this isn't possible, you can store them inside the OSS-Fuzz project directory you created.
## project.yaml
This file stores the metadata about your project. The following attributes are supported:
This configuration file stores project metadata. The following attributes are supported:
- [homepage](#homepage)
- [primary_contact](#primary)
- [auto_ccs](#primary)
- [sanitizers](#sanitizers) (optional)
- [help_url](#help_url)
- [experimental](#experimental)
### homepage
Project's homepage.
You project's homepage.
### primary_contact, auto_ccs
Primary contact and CCs list. These people get access to ClusterFuzz
which includes crash reports, fuzzer statistics, etc and are auto-cced on newly filed bugs in OSS-Fuzz
tracker. To get full access to these artifacts, you should use a [Google account](https://support.google.com/accounts/answer/176347?hl=en)
here ([why?]({{ site.baseurl }}/faq/#why-do-you-require-a-google-account-for-authentication)).
### primary_contact, auto_ccs {#primary}
The primary contact and list of other contacts to be CCed. Each person listed gets access to ClusterFuzz, including crash reports and fuzzer statistics, and are auto-cced on new bugs filed in the OSS-Fuzz
tracker. If you're a primary or a CC, you'll need to use a [Google account](https://support.google.com/accounts/answer/176347?hl=en) to get full access. ([why?]({{ site.baseurl }}/faq/#why-do-you-require-a-google-account-for-authentication)).
### sanitizers (optional)
List of sanitizers to use. By default, it will use the default list of supported
sanitizers (currently -
["address"](https://clang.llvm.org/docs/AddressSanitizer.html),
### sanitizers (optional) {#sanitizers}
The list of sanitizers to use. If you don't specify a list, `sanitizers` uses a default list of supported
sanitizers (currently ["address"](https://clang.llvm.org/docs/AddressSanitizer.html) and
["undefined"](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)).
If your project does not build with a particular sanitizer configuration and you need some time fixing
it, then you can use this option to override the defaults temporarily. E.g. For disabling
UndefinedBehaviourSanitizer build, then you can just specify all supported sanitizers, except "undefined".
[MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html) ("memory") is also supported, but is not enabled by default due to the likelihood of false positives.
If you want to use "memory," first make sure your project's runtime dependencies are listed in the OSS-Fuzz
[msan-builder Dockerfile](https://github.com/google/oss-fuzz/blob/master/infra/base-images/msan-builder/Dockerfile#L20).
Then, you can opt in by adding "memory" to your list of sanitizers.
[MemorySanitizer ("memory")](https://clang.llvm.org/docs/MemorySanitizer.html) is also supported, but is not enabled by default due to likelihood of false positives.
For this to work, ensure that your project's runtime dependencies are listed in
[this file](https://github.com/google/oss-fuzz/blob/master/infra/base-images/msan-builder/Dockerfile#L20).
You may opt-in by adding "memory" to this list.
If your project does not build with a particular sanitizer configuration and you need some time to fix
it, you can use `sanitizers` to override the defaults temporarily. For example, to disable the
UndefinedBehaviourSanitizer build, just specify all supported sanitizers except "undefined".
If you want to test a particular sanitizer (e.g. memory) and see what crashes it generates without filing
them in the issue tracker, you can set the experimental flag. The crashes can be accessed on [ClusterFuzz
homepage]({{ site.baseurl }}/furthur-reading/clusterfuzz#web-interface). Example:
If you want to test a particular sanitizer to see what crashes it generates without filing
them in the issue tracker, you can set an `experimental` flag. For example, if you want to test "memory", set `experimental: True` like this:
```
sanitizers:
@ -104,20 +112,21 @@ sanitizers:
- undefined
```
Example: [boringssl](https://github.com/google/oss-fuzz/blob/master/projects/boringssl/project.yaml).
Crashes can be accessed on the [ClusterFuzz
homepage]({{ site.baseurl }}/furthur-reading/clusterfuzz#web-interface).
`sanitizers` example: [boringssl](https://github.com/google/oss-fuzz/blob/master/projects/boringssl/project.yaml).
### help_url
Link to a custom help URL in bug reports instead of the
[default OSS-Fuzz guide to reproducing crashes]({{ site.baseurl }}/advanced-topics/reproducing/). This can be useful if you assign
bugs to members of your project unfamiliar with OSS-Fuzz or if they should follow a different workflow for
reproducing and fixing bugs than standard one outlined in the reproducing guide.
A link to a custom help URL that appears in bug reports instead of the default
[OSS-Fuzz guide to reproducing crashes]({{ site.baseurl }}/advanced-topics/reproducing/). This can be useful if you assign
bugs to members of your project unfamiliar with OSS-Fuzz, or if they should follow a different workflow for
reproducing and fixing bugs than the standard one outlined in the reproducing guide.
Example: [skia](https://github.com/google/oss-fuzz/blob/master/projects/skia/project.yaml).
`help_url` example: [skia](https://github.com/google/oss-fuzz/blob/master/projects/skia/project.yaml).
### experimental
A boolean (either True or False) that indicates whether this project is in evaluation mode. This allows a project to be
fuzzed and generate crash findings, but not file them in the issue tracker. The crashes can be accessed on [ClusterFuzz homepage]({{ site.baseurl }}/furthur-reading/clusterfuzz#web-interface). This should be only used if you are not a maintainer of the project and have
less confidence in the efficacy of your fuzz targets. Example:
A boolean (either True or False) that indicates whether this project is in evaluation mode. `experimental` allows you to fuzz your project and generate crash findings, but prevents bugs from being filed in the issue tracker. The crashes can be accessed on the [ClusterFuzz homepage]({{ site.baseurl }}/furthur-reading/clusterfuzz#web-interface). Here's an example:
```
homepage: "{project_homepage}"
@ -132,10 +141,14 @@ sanitizers:
help_url: "{help_url}"
experimental: True
```
**Note:** You should be only use `experimental` if you are not a maintainer of the project and have
low confidence in the efficacy of your fuzz targets.
## Dockerfile
This file defines the Docker image definition. This is where the build.sh script will be executed in.
It is very simple for most projects:
This configuration file defines the Docker image for your project. Your [build.sh](#build.sh) script will be executed in inside the container you define.
For most projects, the image is simple:
```docker
FROM gcr.io/oss-fuzz-base/base-builder # base image with clang toolchain
MAINTAINER YOUR_EMAIL # maintainer for this file
@ -144,32 +157,24 @@ RUN git clone <git_url> <checkout_dir> # checkout all sources needed to build
WORKDIR <checkout_dir> # current directory for build script
COPY build.sh fuzzer.cc $SRC/ # copy build script and other fuzzer files in src dir
```
Expat example: [expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile)
In the above example, the git clone will check out the source to `$SRC/<checkout_dir>`.
In the above example, the git clone will check out the source to `$SRC/<checkout_dir>`.
For an example in Expat, see [expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile)
## build.sh
This file describes how to build binaries for [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) in your project.
The script will be executed within the image built from `Dockerfile`.
This file defines how to build binaries for [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) in your project.
The script is executed within the image built from your [Dockerfile](#Dockerfile).
In general, this script will need to:
In general, this script should do the following:
1. Build the project using your build system *with* correct compiler and its flags provided as
*environment variables* (see below).
2. Build the [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target), linking your project's build and libFuzzer.
Resulting binaries should be placed in `$OUT`.
- Build the project using your build system with the correct compiler.
- Provide compiler flags as [environment variables](#Requirements).
- Build your [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) and link your project's build with libFuzzer.
Resulting binaries should be placed in `$OUT`.
*Note*:
1. Please don't assume that the fuzzing engine is libFuzzer and hardcode in your build scripts.
We generate builds for both libFuzzer and AFL fuzzing engine configurations.
So, link the fuzzing engine using $LIB_FUZZING_ENGINE, see example below.
2. Please make sure that the binary names for your [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) contain only
alphanumeric characters, underscore(_) or dash(-). Otherwise, they won't run on our infrastructure.
3. Please don't remove source code files. They are needed for code coverage.
For expat, this looks like [this](https://github.com/google/oss-fuzz/blob/master/projects/expat/build.sh):
Here's an example from Expat ([source]((https://github.com/google/oss-fuzz/blob/master/projects/expat/build.sh)):
```bash
#!/bin/bash -eu
@ -187,23 +192,29 @@ $CXX $CXXFLAGS -std=c++11 -Ilib/ \
cp $SRC/*.dict $SRC/*.options $OUT/
```
**Notes:**
### build.sh Script Environment
1. Don't assume the fuzzing engine is libFuzzer by default, because we generate builds for both libFuzzer and AFL fuzzing engine configurations. Instead, link the fuzzing engine using $LIB_FUZZING_ENGINE.
2. Make sure that the binary names for your [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) contain only
alphanumeric characters, underscore(_) or dash(-). Otherwise, they won't run on our infrastructure.
3. Don't remove source code files. They are needed for code coverage.
When build.sh script is executed, the following locations are available within the image:
### build.sh script environment
When your build.sh script is executed, the following locations are available within the image:
| Location|Env| Description |
|---------| -------- | ---------- |
| `/out/` | `$OUT` | Directory to store build artifacts (fuzz targets, dictionaries, options files, seed corpus archives). |
| `/src/` | `$SRC` | Directory to checkout source files |
| `/work/`| `$WORK` | Directory for storing intermediate files |
| `/src/` | `$SRC` | Directory to checkout source files. |
| `/work/`| `$WORK` | Directory for storing intermediate files. |
While files layout is fixed within a container, the environment variables are
provided to be able to write retargetable scripts.
Although the files layout is fixed within a container, environment variables are
provided so you can write retargetable scripts.
### Requirements
### build.sh requirements {#Requirements}
Only binaries without any extension will be accepted as targets. Extensions are reserved for other artifacts like .dict, etc.
Only binaries without an extension are accepted as targets. Extensions are reserved for other artifacts, like .dict.
You *must* use the special compiler flags needed to build your project and fuzz targets.
These flags are provided in the following environment variables:
@ -219,67 +230,69 @@ You *must* use `$CXX` as a linker, even if your project is written in pure C.
Most well-crafted build scripts will automatically use these variables. If not,
pass them manually to the build tool.
See [Provided Environment Variables](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/README.md#provided-environment-variables) section in
See the [Provided Environment Variables](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/README.md#provided-environment-variables) section in
`base-builder` image documentation for more details.
## Disk space restrictions
Our builders have a disk size of 70GB (this includes space taken up by the OS). Builds must keep peak disk usage below this.
In addition to this, please keep the size of the build (everything copied to `$OUT`) small (<10GB uncompressed) -- this will need be repeatedly transferred and unzipped during fuzzing and run on VMs with limited disk space.
In addition, please keep the size of the build (everything copied to `$OUT`) small (<10GB uncompressed). The build is repeatedly transferred and unzipped during fuzzing and runs on VMs with limited disk space.
## Fuzzer execution environment
[This page]({{ site.baseurl }}/furthur-reading/fuzzer-environment/) gives information about the environment that
your [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) will run on ClusterFuzz, and the assumptions that you can make.
For more on the environment that
your [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target) run in, and the assumptions you can make, see the [fuzzer environment]({{ site.baseurl }}/furthur-reading/fuzzer-environment/) page.
## Testing locally
Use the helper script to build docker image and [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target).
You can build your docker image and fuzz targets locally, so you can test them before you push them to the OSS-Fuzz repository.
```bash
$ cd /path/to/oss-fuzz
$ python infra/helper.py build_image $PROJECT_NAME
$ python infra/helper.py build_fuzzers --sanitizer <address/memory/undefined> $PROJECT_NAME
```
1. Run the same helper script you used to create your directory structure, this time using it to build your docker image and [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target):
This should place the built binaries into `/path/to/oss-fuzz/build/out/$PROJECT_NAME`
directory on your machine (and `$OUT` in the container).
```bash
$ cd /path/to/oss-fuzz
$ python infra/helper.py build_image $PROJECT_NAME
$ python infra/helper.py build_fuzzers --sanitizer <address/memory/undefined> $PROJECT_NAME
```
*Note*: You *must* run these fuzz target binaries inside the base-runner docker
container to make sure that they work properly:
The built binaries appear in the `/path/to/oss-fuzz/build/out/$PROJECT_NAME`
directory on your machine (and `$OUT` in the container).
```bash
$ python infra/helper.py check_build $PROJECT_NAME
```
**Note:** You *must* run your fuzz target binaries inside the base-runner docker
container to make sure that they work properly.
Please fix any failures pointed by the `check_build` command above. To test changes against
a particular fuzz target, run using:
2. Find failures to fix by running the `check_build` command:
```bash
$ python infra/helper.py check_build $PROJECT_NAME
```
```bash
$ python infra/helper.py run_fuzzer $PROJECT_NAME <fuzz_target>
```
3. If you want to test changes against a particular fuzz target, run the following command:
If everything works locally, then it should also work on our automated builders and ClusterFuzz.
If it fails, check out [this]({{ site.baseurl }}/furthur-reading/fuzzer-environment/#dependencies) entry.
```bash
$ python infra/helper.py run_fuzzer $PROJECT_NAME <fuzz_target>
```
It's recommended to look at code coverage as a sanity check to make sure that
[fuzz target]({{ site.baseurl }}/reference/glossary/#fuzz-target) gets to the code you expect.
4. We recommend taking a look at your code coverage as a sanity check to make sure that your
fuzz targets get to the code you expect:
```bash
$ python infra/helper.py build_fuzzers --sanitizer coverage $PROJECT_NAME
$ python infra/helper.py coverage $PROJECT_NAME <fuzz_target>
```
```bash
$ python infra/helper.py build_fuzzers --sanitizer coverage $PROJECT_NAME
$ python infra/helper.py coverage $PROJECT_NAME <fuzz_target>
```
*Note*: Currently, we only support AddressSanitizer (address) and UndefinedBehaviorSanitizer (undefined)
**Note:** Currently, we only support AddressSanitizer (address) and UndefinedBehaviorSanitizer (undefined)
configurations. MemorySanitizer is in development mode and not recommended for use. <b>Make sure to test each
of the supported build configurations with the above commands (build_fuzzers -> run_fuzzer -> coverage).</b>
If everything works locally, it should also work on our automated builders and ClusterFuzz. If you check in
your files and experience failures, review your [dependencies]({{ site.baseurl }}/furthur-reading/fuzzer-environment/#dependencies).
## Debugging Problems
[Debugging]({{ site.baseurl }}/advanced-topics/debugging/) document lists ways to debug your build scripts or
[fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target)
in case you run into problems.
If you run into problems, our [Debugging page]({{ site.baseurl }}/advanced-topics/debugging/) lists ways to debug your build scripts and
[fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target).
## Efficient fuzzing
@ -345,11 +358,11 @@ For out of tree [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-targe
`COPY` directive and will copy it into output in build script.
(example: [woff2](https://github.com/google/oss-fuzz/blob/master/projects/woff2/convert_woff2ttf_fuzzer.options)).
## Checking in to OSS-Fuzz repository
## Checking in to the OSS-Fuzz repository
Fork OSS-Fuzz, commit and push to the fork, and then create a pull request with
Once you've tested your fuzzing files locally, fork OSS-Fuzz, commit, and push to the fork. Then create a pull request with
your change! Follow the [Forking Project](https://guides.github.com/activities/forking/) guide
if you are new to contributing via GitHub.
if you're new to contributing via GitHub.
### Copyright headers
@ -373,19 +386,17 @@ Please include copyright headers for all files checked in to oss-fuzz:
################################################################################
```
If you are porting a fuzz target from Chromium, keep the original Chromium license header.
**Exception:** If you're porting a fuzz target from Chromium, keep the original Chromium license header.
## The end
## Reviewing results
Once your change is merged, your project and fuzz targets should be automatically built and run on
ClusterFuzz after a short while (&lt; 1 day)!
ClusterFuzz after a short while (&lt; 1 day). If you think there's a problem, you can check your project's [build status](https://oss-fuzz-build-logs.storage.googleapis.com/index.html).
Check your project's build status [here](https://oss-fuzz-build-logs.storage.googleapis.com/index.html).
Use [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) web interface [here](https://oss-fuzz.com/) to checkout the following items:
Use the [ClusterFuzz web interface](https://oss-fuzz.com/) to review the following:
* Crashes generated
* Code coverage statistics
* Fuzzer statistics
* Fuzzer performance analyzer (linked from fuzzer statistics)
Note that your Google Account must be listed in [project.yaml](#projectyaml) for you to have access to the ClusterFuzz web interface.
**Note:** Your Google Account must be listed in [project.yaml](#projectyaml) for you to have access to the ClusterFuzz web interface.