From d8af01c01630ce3d0aa405b0b5afe109330be313 Mon Sep 17 00:00:00 2001 From: kplybon <53794715+kplybon@users.noreply.github.com> Date: Fri, 9 Aug 2019 15:24:43 -0400 Subject: [PATCH] [Docs] Clarify fuzzing process and new projects procedure (#2673) --- README.md | 5 +-- .../getting-started/accepting_new_projects.md | 40 +++++++++---------- docs/index.md | 32 +++++---------- docs/oss-fuzz/architecture.md | 32 +++++++-------- 4 files changed, 47 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 780818f29..2d7b4b25f 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,8 @@ [Fuzz testing](https://en.wikipedia.org/wiki/Fuzz_testing) is a well-known technique for uncovering programming errors in software. -Many of these detectable errors, like [buffer overflow](https://en.wikipedia.org/wiki/Buffer_overflow), can have serious security implications. Google found [hundreds](https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3AStability-LibFuzzer+-status%3ADuplicate%2CWontFix) of security vulnerabilities and stability bugs by deploying -[guided in-process fuzzing of Chrome components](https://security.googleblog.com/2016/08/guided-in-process-fuzzing-of-chrome.html) -and, and we now want to share that service with the open source community. +Many of these detectable errors, like [buffer overflow](https://en.wikipedia.org/wiki/Buffer_overflow), can have serious security implications. Google has found [hundreds](https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3AStability-LibFuzzer+-status%3ADuplicate%2CWontFix) of security vulnerabilities and stability bugs by deploying [guided in-process fuzzing of Chrome components](https://security.googleblog.com/2016/08/guided-in-process-fuzzing-of-chrome.html), +and we now want to share that service with the open source community. In cooperation with the [Core Infrastructure Initiative](https://www.coreinfrastructure.org/), OSS-Fuzz aims to make common open source software more secure and stable by diff --git a/docs/getting-started/accepting_new_projects.md b/docs/getting-started/accepting_new_projects.md index da8f3a8af..a6a2c9b2d 100644 --- a/docs/getting-started/accepting_new_projects.md +++ b/docs/getting-started/accepting_new_projects.md @@ -6,33 +6,29 @@ nav_order: 1 permalink: /getting-started/accepting-new-projects/ --- -## Accepting New Projects +# Accepting New Projects To be accepted to OSS-Fuzz, an open-source project must have a significant user base and/or be critical to the global IT infrastructure. -To submit a new project: +To submit a new project, do the following: -* [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) -with new `projects//project.yaml` file -([example](https://github.com/google/oss-fuzz/tree/master/projects/libarchive/project.yaml)) -giving at least the following information: - * project homepage. - * e-mail of the engineering contact person to be CCed on new issues. It should: - * belong to an established project committer (according to VCS logs). - If this is not you or the email address differs from VCS, an informal - e-mail verification will be required. - * be associated with a Google account +1. [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) +with a new `projects//project.yaml` file +([example](https://github.com/google/oss-fuzz/tree/master/projects/libarchive/project.yaml)). + **Note:** `project_name` can only contain alphanumeric characters, + underscores(_) or dashes(-). +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). + 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 ([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), - it will ONLY give you access to filed bugs in - [issue tracker](https://bugs.chromium.org/p/oss-fuzz/issues/list) and - NOT to [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) - dashboard (due to appengine api limitations). - * Note that `project_name` can only contain alphanumeric characters, - underscores(_) or dashes(-). - -* Once accepted by an OSS-Fuzz project member, follow the - [New Project Guide]({{ site.baseurl }}/getting-started/new-project-guide/) - to configure your project. + you'll only get access to [filed bugs in the issue tracker](https://bugs.chromium.org/p/oss-fuzz/issues/list), not to the [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) + dashboard. This is due to appengine API limitations. +3. Once your project is accepted, configure it by following the + [New Project Guide]({{ site.baseurl }}/getting-started/new-project-guide/). diff --git a/docs/index.md b/docs/index.md index f71850b1c..a8b8426eb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,37 +4,27 @@ title: OSS-Fuzz permalink: / nav_order: 1 has_children: true +has_toc: false --- # OSS-Fuzz [Fuzz testing](https://en.wikipedia.org/wiki/Fuzz_testing) is a well-known -technique for uncovering various kinds of programming errors in software. -Many of these detectable errors (e.g. -[buffer overflow](https://en.wikipedia.org/wiki/Buffer_overflow)) can have -serious security implications. +technique for uncovering programming errors in software. +Many of these detectable errors, like [buffer overflow](https://en.wikipedia.org/wiki/Buffer_overflow), can have serious security implications. Google has found [hundreds](https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3AStability-LibFuzzer+-status%3ADuplicate%2CWontFix) of security vulnerabilities and stability bugs by deploying [guided in-process fuzzing of Chrome components](https://security.googleblog.com/2016/08/guided-in-process-fuzzing-of-chrome.html), +and we now want to share that service with the open source community. -We successfully deployed -[guided in-process fuzzing of Chrome components](https://security.googleblog.com/2016/08/guided-in-process-fuzzing-of-chrome.html) -and found [thousands](https://bugs.chromium.org/p/chromium/issues/list?q=label%3AStability-LibFuzzer%20-status%3ADuplicate%2CWontFix%20OR%20label%3AStability-AFL%20-status%3ADuplicate%2CWontFix&can=1) -of security vulnerabilities and stability bugs. We now want to share the -experience and the service with the open source community. - -In cooperation with the -[Core Infrastructure Initiative](https://www.coreinfrastructure.org/), +In cooperation with the [Core Infrastructure Initiative](https://www.coreinfrastructure.org/), OSS-Fuzz aims to make common open source software more secure and stable by -combining modern fuzzing techniques and scalable +combining modern fuzzing techniques with scalable, distributed execution. -We support [libFuzzer](http://llvm.org/docs/LibFuzzer.html) and -[AFL](http://lcamtuf.coredump.cx/afl/) as fuzzing engines in combination with -[Sanitizers](https://github.com/google/sanitizers). -[ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) -provides a distributed fuzzer execution environment and reporting. You can -checkout ClusterFuzz [here](https://github.com/google/clusterfuzz). +We support the [libFuzzer](http://llvm.org/docs/LibFuzzer.html) and [AFL](http://lcamtuf.coredump.cx/afl/) fuzzing engines +in combination with [Sanitizers](https://github.com/google/sanitizers), as well as +[ClusterFuzz](https://github.com/google/clusterfuzz), +a distributed fuzzer execution environment and reporting tool. -Currently OSS-Fuzz supports C and C++ code (other languages supported by -[LLVM](http://llvm.org) may work too). +Currently, OSS-Fuzz supports C and C++ code, though other languages supported by [LLVM](http://llvm.org) may work too. ## Trophies As of August 2019, OSS-Fuzz has found [~14,000] bugs in over [200] open source diff --git a/docs/oss-fuzz/architecture.md b/docs/oss-fuzz/architecture.md index bf7175c13..79539bc75 100644 --- a/docs/oss-fuzz/architecture.md +++ b/docs/oss-fuzz/architecture.md @@ -7,27 +7,27 @@ parent: OSS-Fuzz --- # Architecture -![diagram]({{ site.baseurl }}/images/process.png?raw=true) +![OSS-Fuzz architecture diagram]({{ site.baseurl }}/images/process.png?raw=true) -The following process is used for projects in OSS-Fuzz: +The process works like this: -- A maintainer of an opensource project or an outside volunteer creates +1. A maintainer of an open source project (or an outside volunteer) creates one or more [fuzz targets](http://libfuzzer.info/#fuzz-target) and [integrates]({{ site.baseurl }}/advanced-topics/ideal-integration/) them with the project's build and test system. -- The project is [accepted to OSS-Fuzz]({{ site.baseurl }}/getting-started/accepting-new-projects/). -- When [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) finds a - bug, an issue is automatically reported in the OSS-Fuzz +1. The project is [accepted to OSS-Fuzz]({{ site.baseurl }}/getting-started/accepting-new-projects/) and the developer commits their build configurations. +1. The OSS-Fuzz [builder](jenkins.io) builds the project from the committed configs. +1. The builder uploads the fuzz targets to the OSS-Fuzz GCS bucket. +1. [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) downloads the fuzz targets and begins to fuzz the projects. +1. When Clusterfuzz finds a + bug, it reports the issue automatically to the OSS-Fuzz [issue tracker](https://bugs.chromium.org/p/oss-fuzz/issues/list) ([example](https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=9)). - ([Why use a different tracker?]({{ site.baseurl }}/faq/#why-do-you-use-a-different-issue-tracker-for-reporting-bugs-in-oss-projects)). - Project owners are CC-ed to the bug report. -- The project developer fixes the bug upstream and credits OSS-Fuzz for the - discovery (commit message should contain the string **'Credit to OSS-Fuzz'**). -- [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) automatically - verifies the fix, adds a comment and closes the issue - ([example](https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=53#c3)). -- 30 days after the fix is verified or 90 days after reporting (whichever is - earlier), the issue becomes *public* - ([guidelines]({{ site.baseurl }}/getting-started/bug-disclosure-guidelines/)). + ([Why use a different tracker?]({{ site.baseurl }}/faq/#why-do-you-use-a-different-issue-tracker-for-reporting-bugs-in-oss-projects)) +1. Project owners are CCed on the bug report. +1. The project developer fixes the bug upstream and credits OSS-Fuzz for the + discovery (the commit message should contain the string **'Credit to OSS-Fuzz'**). + +Once the developer fixes the bug, [ClusterFuzz]({{ site.baseurl }}/furthur-reading/clusterfuzz) automatically +verifies the fix, adds a comment, and closes the issue ([example](https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=53#c3)). 30 days after the fix is verified or 90 days after reporting (whichever is earlier), the issue becomes [public]({{ site.baseurl }}/getting-started/bug-disclosure-guidelines/).