From 055f9836f308a9c568653b60002c84d4c35204fa Mon Sep 17 00:00:00 2001 From: Abhishek Arya Date: Thu, 15 Aug 2019 15:07:23 -0700 Subject: [PATCH] Documentation fixes. (#2705) --- README.md | 14 ++-- docs/README.md | 16 +++-- docs/advanced-topics/code_coverage.md | 42 +++++------ docs/advanced-topics/corpora.md | 6 +- docs/advanced-topics/ideal_integration.md | 33 ++++----- docs/advanced-topics/reproducing.md | 11 +-- docs/furthur-reading/fuzzer_environment.md | 6 +- docs/getting-started/new_project_guide.md | 81 ++++++++-------------- docs/glossary.md | 1 + docs/ideal_integration.md | 1 + docs/index.md | 11 +-- docs/new_project_guide.md | 2 +- docs/reference/glossary.md | 17 ++--- docs/reference/useful_links.md | 17 +++-- 14 files changed, 122 insertions(+), 136 deletions(-) create mode 100644 docs/glossary.md create mode 100644 docs/ideal_integration.md diff --git a/README.md b/README.md index fbf68f4d4580..58c3b77d61bc 100644 --- a/README.md +++ b/README.md @@ -26,20 +26,16 @@ Currently, OSS-Fuzz supports C and C++ code, though other languages supported by Read our [detailed documentation](https://google.github.io/oss-fuzz) to learn how to use OSS-Fuzz. ## Trophies -As of August 2019, OSS-Fuzz has found [~14,000] bugs in over [200] open source +As of August 2019, OSS-Fuzz has found over [14,000] bugs in over [200] open source projects. -[~14,000]: https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=-status%3AWontFix%2CDuplicate+-Infra +[14,000]: https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=-status%3AWontFix%2CDuplicate+-Infra [200]: https://github.com/google/oss-fuzz/tree/master/projects ## Blog posts -* 2016-12-01 ([Open Source](https://opensource.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), -[Testing](https://testing.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), -[Security](https://security.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html)) -* 2017-05-08 ([Open Source](https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), -[Testing](https://testing.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), -[Security](https://security.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html)) -* 2018-11-06 ([Security](https://security.googleblog.com/2018/11/a-new-chapter-for-oss-fuzz.html)) +* 2016-12-01 - [Announcing OSS-Fuzz: Continuous fuzzing for open source software](https://opensource.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html). +* 2017-05-08 - [OSS-Fuzz: Five months later, and rewarding projects](https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html) +* 2018-11-06 - [A New Chapter for OSS-Fuzz](https://security.googleblog.com/2018/11/a-new-chapter-for-oss-fuzz.html) diff --git a/docs/README.md b/docs/README.md index edfbdfff4b9c..db0358faa62d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,18 @@ -# Prerequisites +# Readme + +Use the following instructions to make documentation changes locally. + +## Prerequisites ```bash -sudo apt install ruby bundler -bundle install --path vendor/bundle +$ sudo apt install ruby bundler +$ bundle install --path vendor/bundle ``` -# Serving locally +## Serving locally ```bash -bundle exec jekyll serve +$ bundle exec jekyll serve ``` -# Theme documentation +## Theme documentation We are using the [just the docs](https://pmarsceill.github.io/just-the-docs/) theme. diff --git a/docs/advanced-topics/code_coverage.md b/docs/advanced-topics/code_coverage.md index e67f6f05eb14..d7da3b452ea4 100644 --- a/docs/advanced-topics/code_coverage.md +++ b/docs/advanced-topics/code_coverage.md @@ -20,64 +20,63 @@ Code Coverage]. Docker images get regularly updated with a newer version of build tools, build configurations, scripts, and other changes. It is recommended to use the most -recent images for a better user experience. +recent images. ```bash -python infra/helper.py pull_images +$ python infra/helper.py pull_images ``` ## Build fuzz targets Code Coverage report generation requires a special build configuration to be -used. In order to produce such build for your project, run: +used. To create a code coverage build for your project, run: ```bash -python infra/helper.py build_image $project_name -python infra/helper.py build_fuzzers --sanitizer=coverage $project_name +$ python infra/helper.py build_image $PROJECT_NAME +$ python infra/helper.py build_fuzzers --sanitizer=coverage $PROJECT_NAME ``` ## Establish access to GCS -To get a good understanding of quality of the fuzz testing established for your -project, code coverage should be generated by running fuzz targets against the -corpus aggregated by OSS-Fuzz. The helper script will download the corpus -automatically using `gsutil` tool. To make it work, you need: +To get a good understanding of quality of fuzz testing established for your +project, code coverage reports should be generated by running fuzz targets +against the corpus aggregated by OSS-Fuzz. Set up `gsutil` and ensure that +you have access to the corpora using: * Install [gsutil tool] * Check whether you have access to the corpus for your project: ```bash -gsutil ls gs://${project_name}-corpus.clusterfuzz-external.appspot.com/ +$ gsutil ls gs://${PROJECT_NAME}-corpus.clusterfuzz-external.appspot.com/ ``` If you see an authorization error from the command above, run: ```bash -gcloud auth login +$ gcloud auth login ``` and try again. Once `gsutil` works, you can run the report generation. - -## Generating code coverage reports +## Generate code coverage reports ### Full project report To generate code coverage report using the corpus aggregated on OSS-Fuzz, run: ```bash -python infra/helper.py coverage $project_name +$ python infra/helper.py coverage $PROJECT_NAME ``` If you want to generate code coverage report using the corpus you have locally, -copy the corpus into `build/corpus/$project_name/$fuzz_target/` directories for +copy the corpus into `build/corpus/$PROJECT_NAME//` directories for each fuzz target, then run: ```bash -python infra/helper.py coverage --no-corpus-download $project_name +$ python infra/helper.py coverage --no-corpus-download $PROJECT_NAME ``` ### Single fuzz target @@ -86,14 +85,15 @@ You can generate a code coverage report for a particular fuzz target with `--fuzz-target` argument: ```bash -python infra/helper.py coverage --fuzz-target= $project_name +$ python infra/helper.py coverage --fuzz-target= $PROJECT_NAME ``` In this mode, you can specify an arbitrary corpus location for the fuzz target via `--corpus-dir` to be used instead of the corpus downloaded from OSS-Fuzz: ```bash -python infra/helper.py coverage --fuzz-target= --corpus-dir= $project_name +$ python infra/helper.py coverage --fuzz-target= \ + --corpus-dir= $PROJECT_NAME ``` ### Additional arguments for `llvm-cov` @@ -102,14 +102,16 @@ You may want to use some of the options of [llvm-cov tool], for example, `-ignore-filename-regex=`. You can pass those to the helper script after `--`: ```bash -python infra/helper.py coverage $project_name -- -ignore-filename-regex=.*code/to/be/ignored/.* +$ python infra/helper.py coverage $PROJECT_NAME -- \ + -ignore-filename-regex=.*code/to/be/ignored/.* ``` To specify particular source files or directories to show in the report, list their paths at the end of the extra arguments sequence, for example: ```bash -python infra/helper.py coverage zlib -- /src/zlib/inftrees.c /src/zlib_uncompress_fuzzer.cc /src/zlib/zutil.c +$ python infra/helper.py coverage zlib -- \ + /src/zlib/inftrees.c /src/zlib_uncompress_fuzzer.cc /src/zlib/zutil.c ``` If you want OSS-Fuzz to use some extra arguments when generating code coverage diff --git a/docs/advanced-topics/corpora.md b/docs/advanced-topics/corpora.md index 8bb48f218588..dd4ccc7fd6e4 100644 --- a/docs/advanced-topics/corpora.md +++ b/docs/advanced-topics/corpora.md @@ -52,12 +52,14 @@ And then run the following command to copy the corpus to a directory on your machine. ```bash -gsutil -m rsync gs:// +$ gsutil -m rsync gs:// ``` Following the expat example above, this would be: ```bash -gsutil -m rsync gs://expat-corpus.clusterfuzz-external.appspot.com/libFuzzer/expat_parse_fuzzer +$ gsutil -m rsync \ + gs://expat-corpus.clusterfuzz-external.appspot.com/libFuzzer/expat_parse_fuzzer \ + ``` ## Corpus backups diff --git a/docs/advanced-topics/ideal_integration.md b/docs/advanced-topics/ideal_integration.md index 6174077a8818..e0926a10e803 100644 --- a/docs/advanced-topics/ideal_integration.md +++ b/docs/advanced-topics/ideal_integration.md @@ -25,10 +25,10 @@ Every [fuzz target](http://libfuzzer.info/#fuzz-target): * Is [maintained by code owners](#fuzz-target) in their RCS (Git, SVN, etc). * Is [built with the rest of the tests](#build-support) - no bit rot! * Has a [seed corpus](#seed-corpus) with good [code coverage](#coverage). +* Has a [dictionary](#dictionary), if applicable. * Is [continuously tested on the seed corpus](#regression-testing) with [ASan/UBSan/MSan](https://github.com/google/sanitizers). * Is [fast and has no OOMs](#performance). -* Has a [fuzzing dictionary](#fuzzing-dictionary), if applicable ## Fuzz Target The code of the [fuzz target(s)](http://libfuzzer.info/#fuzz-target) should be @@ -41,7 +41,8 @@ arise as source code changes over time. Make sure to fuzz the target locally for a small period of time to ensure that it does not crash, hang, or run out of memory instantly. -See details at http://libfuzzer.info and http://tutorial.libfuzzer.info. +You can read more about what makes a good fuzz target [here] +(https://github.com/google/fuzzing/blob/master/docs/good-fuzz-target.md) The interface between the [fuzz target]((http://libfuzzer.info/#fuzz-target)) and the fuzzing engines is C, so you may use C or C++ to implement the fuzz target. @@ -102,19 +103,7 @@ Examples: [openssl](https://github.com/openssl/openssl/tree/master/fuzz), [nss](https://github.com/mozilla/nss-fuzzing-corpus) (corpus in a separate repo). -## Regression Testing -The fuzz targets should be regularly tested (not necessarily fuzzed!) as a part -of the project's regression testing process. -One way to do so is to link the fuzz target with a simple standalone driver -(e.g. [this one](https://github.com/llvm-mirror/compiler-rt/tree/master/lib/fuzzer/standalone)) -that runs the provided inputs and use this driver with the seed corpus created -in previous step. It is recommended to use -[sanitizers](https://github.com/google/sanitizers) during regression testing. - -Examples: [SQLite](https://www.sqlite.org/src/artifact/d9f1a6f43e7bab45), -[openssl](https://github.com/openssl/openssl/blob/master/fuzz/test-corpus.c) - -## Fuzzing dictionary +## Dictionary For some input types, a simple dictionary of tokens used by the input language can have a dramatic positive effect on fuzzing efficiency. For example, when fuzzing an XML parser, a dictionary of XML tokens will help. @@ -137,11 +126,23 @@ documentation page. Coverage can often be improved by adding dictionaries, more inputs for seed corpora, and fixing timeouts/out-of-memory bugs in your targets. +## Regression Testing +The fuzz targets should be regularly tested (not necessarily fuzzed!) as a part +of the project's regression testing process. +One way to do so is to link the fuzz target with a simple standalone driver +(e.g. [this one](https://github.com/llvm-mirror/compiler-rt/tree/master/lib/fuzzer/standalone)) +that runs the provided inputs and use this driver with the seed corpus created +in previous step. It is recommended to use +[sanitizers](https://github.com/google/sanitizers) during regression testing. + +Examples: [SQLite](https://www.sqlite.org/src/artifact/d9f1a6f43e7bab45), +[openssl](https://github.com/openssl/openssl/blob/master/fuzz/test-corpus.c) + ## Performance Fuzz targets should also be performant, as high memory usage and/or slow execution speed can slow the down the growth of coverage and finding of new bugs. ClusterFuzz provides a -[performance analyzer]({{ site.baseurl }}/furthur-reading/clusterfuzz) +[performance analyzer]({{ site.baseurl }}/furthur-reading/clusterfuzz/#performance-analyzer) for each fuzz target that shows problems that are impacting the performance of the fuzz target. diff --git a/docs/advanced-topics/reproducing.md b/docs/advanced-topics/reproducing.md index 57384b9a8d50..ea164a54ab22 100644 --- a/docs/advanced-topics/reproducing.md +++ b/docs/advanced-topics/reproducing.md @@ -24,7 +24,7 @@ Download it. If the issue is not public, you will need to login using your [Google account](https://support.google.com/accounts/answer/176347?hl=en) ([why?]({{ site.baseurl }}/faq/#why-do-you-require-a-google-account-for-authentication)) that the bug report CCs. -This file contains the bytes that were fed to the [Fuzz Target](http://libfuzzer.info/#fuzz-target). +This file contains the bytes that were fed to the [fuzz target](http://libfuzzer.info/#fuzz-target). If you have already [integrated]({{ site.baseurl }}/advanced-topics/ideal-integration/) @@ -94,7 +94,8 @@ $ python infra/helper.py reproduce libxml2 libxml2_xml_read_memory_fuzzer ~/Down ## Reproduce using local source checkout ```bash -$ python infra/helper.py build_fuzzers --sanitizer
$PROJECT_NAME +$ python infra/helper.py build_fuzzers \ + --sanitizer
$PROJECT_NAME $ python infra/helper.py reproduce $PROJECT_NAME ``` @@ -118,8 +119,10 @@ correctly configured, even if it succeeded. To reproduce these locally, run: ```bash $ python infra/helper.py build_image $PROJECT_NAME -$ python infra/helper.py build_fuzzers --sanitizer
--engine $PROJECT_NAME -$ python infra/helper.py check_build --sanitizer
--engine $PROJECT_NAME +$ python infra/helper.py build_fuzzers --sanitizer
\ + --engine $PROJECT_NAME +$ python infra/helper.py check_build --sanitizer
\ + --engine $PROJECT_NAME ``` For reproducing a `coverage` build failure, follow diff --git a/docs/furthur-reading/fuzzer_environment.md b/docs/furthur-reading/fuzzer_environment.md index 6c51e4366829..b8138c343bf0 100644 --- a/docs/furthur-reading/fuzzer_environment.md +++ b/docs/furthur-reading/fuzzer_environment.md @@ -27,12 +27,12 @@ are not available on the bot runtime environment (where the fuzz targets run). If you need these dependencies in the runtime environment, you can either - Install the packages via Dockerfile -([example](https://github.com/google/oss-fuzz/blob/master/projects/tor/Dockerfile#L19)) +([example](https://github.com/google/oss-fuzz/blob/2d5e2ef84f281e6ab789055aa735606d3122fda9/projects/tor/Dockerfile#L19)) and then link statically against them -([example](https://github.com/google/oss-fuzz/blob/master/projects/tor/build.sh#L40)) +([example](https://github.com/google/oss-fuzz/blob/2d5e2ef84f281e6ab789055aa735606d3122fda9/projects/tor/build.sh#L40)) - Or build the dependencies statically in [build.sh]({{ site.baseurl }}/getting-started/new-project-guide/#buildsh) -([example](https://github.com/google/oss-fuzz/blob/master/projects/ffmpeg/build.sh#L26)). +([example](https://github.com/google/oss-fuzz/blob/64f8b6593da141b97c98c7bc6f07df92c42ee010/projects/ffmpeg/build.sh#L26)). All build artifacts needed during fuzz target execution should be inside the `$OUT` directory. Only those artifacts are archived and used on the bots. diff --git a/docs/getting-started/new_project_guide.md b/docs/getting-started/new_project_guide.md index e0bab4f6571a..53854e5104ea 100644 --- a/docs/getting-started/new_project_guide.md +++ b/docs/getting-started/new_project_guide.md @@ -65,7 +65,7 @@ $ export PROJECT_NAME= $ python infra/helper.py generate $PROJECT_NAME ``` -Once the template configuration files are available, you can modify them to fit your project. +Once the template configuration files are created, 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. @@ -77,8 +77,7 @@ This configuration file stores project metadata. The following attributes are su - [primary_contact](#primary) - [auto_ccs](#primary) - [sanitizers](#sanitizers) (optional) -- [help_url](#help_url) -- [experimental](#experimental) +- [help_url](#help_url) (optional) ### homepage You project's homepage. @@ -92,8 +91,10 @@ The list of sanitizers to use. If you don't specify a list, `sanitizers` uses a sanitizers (currently ["address"](https://clang.llvm.org/docs/AddressSanitizer.html) and ["undefined"](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)). -[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 +[MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html) ("memory") is also supported +and recommended, but is not enabled by default due to the likelihood of false positives from +un-instrumented system dependencies. 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. @@ -117,7 +118,7 @@ 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 +### help_url (optional) 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 @@ -125,26 +126,6 @@ reproducing and fixing bugs than the standard one outlined in the reproducing gu `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. `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}" -primary_contact: "{primary_contact}" -auto_ccs: - - "{auto_cc_1}" - - "{auto_cc_2}" -sanitizers: - - address - - memory - - undefined -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 configuration file defines the Docker image for your project. Your [build.sh](#build.sh) script will be executed in inside the container you define. @@ -174,7 +155,7 @@ In general, this script should do the following: Resulting binaries should be placed in `$OUT`. -Here's an example from Expat ([source]((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 @@ -203,11 +184,11 @@ alphanumeric characters, underscore(_) or dash(-). Otherwise, they won't run on When your build.sh script is executed, the following locations are available within the image: -| Location|Env| Description | -|---------| -------- | ---------- | +| Location| Env Variable | 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. | +| `/work/`| `$WORK` | Directory to store intermediate files. | Although the files layout is fixed within a container, environment variables are provided so you can write retargetable scripts. @@ -283,7 +264,10 @@ fuzz targets get to the code you expect: ``` **Note:** Currently, we only support AddressSanitizer (address) and UndefinedBehaviorSanitizer (undefined) -configurations. MemorySanitizer is in development mode and not recommended for use. Make sure to test each +configurations. MemorySanitizer is recommended, but needs to be enabled manually once you verify +that all system dependencies are +[instrumented](https://github.com/google/oss-fuzz/blob/master/infra/base-images/msan-builder/Dockerfile#L20). +Make sure to test each of the supported build configurations with the above commands (build_fuzzers -> run_fuzzer -> coverage). If everything works locally, it should also work on our automated builders and ClusterFuzz. If you check in @@ -296,6 +280,9 @@ If you run into problems, our [Debugging page]({{ site.baseurl }}/advanced-topic ## Efficient fuzzing +To improve your fuzz target ability to find bugs faster, you should consider the +following ways: + ### Seed Corpus OSS-Fuzz uses evolutionary fuzzing algorithms. Supplying seed corpus consisting @@ -314,7 +301,6 @@ has an appropriate and consistent license. See also [Accessing Corpora]({{ site.baseurl }}/advanced-topics/corpora/) for information about getting access to the corpus we are currently using for your fuzz targets. - ### Dictionaries Dictionaries hugely improve fuzzing efficiency for inputs with lots of similar @@ -334,35 +320,26 @@ It is common for several [fuzz targets]({{ site.baseurl }}/reference/glossary/#f to reuse the same dictionary if they are fuzzing very similar inputs. (example: [expat](https://github.com/google/oss-fuzz/blob/master/projects/expat/parse_fuzzer.options)). -### Custom libFuzzer options for ClusterFuzz +### Input Size -By default, ClusterFuzz will run your fuzzer without any options. You can specify -custom options by creating a `my_fuzzer.options` file next to a `my_fuzzer` executable in `$OUT`: - -``` -[libfuzzer] -close_fd_mask = 3 -only_ascii = 1 -``` - -[List of available options](http://llvm.org/docs/LibFuzzer.html#options). Use of `max_len` is not recommended as other fuzzing engines may not support that option. Instead, if -you need to strictly enforce the input length limit, add a sanity check to the -beginning of your fuzz target: +By default, the fuzzing engine will generate input of any arbitrary length. +This is often useful to try unexpected use cases that lead to security +vulnerabilities. However, if your API does not expect large inputs and will +fail on parsing early-on, it is important to add those limits in your fuzz target +to avoid those errors altogether. This can also lead to significant performance +improvements. ```cpp if (size < kMinInputLength || size > kMaxInputLength) return 0; ``` -For out of tree [fuzz targets]({{ site.baseurl }}/reference/glossary/#fuzz-target), you will likely add options file using docker's -`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 the OSS-Fuzz repository -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're new to contributing via GitHub. +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're new to contributing +via GitHub. ### Copyright headers diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 000000000000..e3355d3763bc --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1 @@ +This page has moved [here](https://google.github.io/oss-fuzz/reference/glossary/) diff --git a/docs/ideal_integration.md b/docs/ideal_integration.md new file mode 100644 index 000000000000..35de1c082c9a --- /dev/null +++ b/docs/ideal_integration.md @@ -0,0 +1 @@ +This page has moved [here](https://google.github.io/oss-fuzz/advanced-topics/ideal-integration/) diff --git a/docs/index.md b/docs/index.md index 202f531976b1..1611f0d47b35 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,8 +11,11 @@ has_toc: false [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 has found [thousands] 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. +Many of these detectable errors, like [buffer overflow](https://en.wikipedia.org/wiki/Buffer_overflow), +can have serious security implications. Google has found [thousands] 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. [thousands]: https://bugs.chromium.org/p/chromium/issues/list?q=label%3AStability-LibFuzzer%2CStability-AFL%20-status%3ADuplicate%2CWontFix&can=1 @@ -29,8 +32,8 @@ a distributed fuzzer execution environment and reporting tool. 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 +As of August 2019, OSS-Fuzz has found over [14,000] bugs in over [200] open source projects. -[~14,000]: https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=-status%3AWontFix%2CDuplicate+-Infra +[14,000]: https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=-status%3AWontFix%2CDuplicate+-Infra [200]: https://github.com/google/oss-fuzz/tree/master/projects diff --git a/docs/new_project_guide.md b/docs/new_project_guide.md index 4fe87ec8c980..782486ad5a11 100644 --- a/docs/new_project_guide.md +++ b/docs/new_project_guide.md @@ -1 +1 @@ -This page has moved [here](https://google.github.io/oss-fuzz/getting-started/new-project-guide) +This page has moved [here](https://google.github.io/oss-fuzz/getting-started/new-project-guide/) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index d5bf18bc6475..d4f9a9c4d5b6 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -8,7 +8,7 @@ parent: Reference # Glossary -For general fuzzing terms, see the [glossary] from [google/fuzzing] project, +For general fuzzing terms, see the [glossary] from [google/fuzzing] project. [glossary]: https://github.com/google/fuzzing/blob/master/docs/glossary.md [google/fuzzing]: https://github.com/google/fuzzing @@ -69,28 +69,21 @@ A [test input] that causes a specific bug to reproduce. ### Sanitizers Fuzzers are usually built with one or more [sanitizer](https://github.com/google/sanitizers) enabled. -You can select sanitizer configuration by specifying `$SANITIZER` build environment variable using `-e` option: ```bash -python infra/helper.py build_fuzzers --sanitizer undefined json +$ python infra/helper.py build_fuzzers --sanitizer undefined json ``` Supported sanitizers: -| `$SANITIZER` | Description +| Sanitizer | Description | ------------ | ---------- | `address` *(default)* | [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) with [Leak Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer). | `undefined` | [Undefined Behavior Sanitizer](http://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html). | `memory` | [Memory Sanitizer](https://github.com/google/sanitizers/wiki/MemorySanitizer).
*NOTE: It is critical that you build __all__ the code in your program (including libraries it uses) with Memory Sanitizer. Otherwise, you will see false positive crashes due to an inability to see initializations in uninstrumented code.* -| `profile` | Used for generating code coverage reports. See [Code Coverage doc]({{ site.baseurl }}/advanced-topics/code-coverage/). +| `coverage` | Used for generating code coverage reports. See [Code Coverage doc]({{ site.baseurl }}/advanced-topics/code-coverage/). Compiler flag values for predefined configurations are specified in the [Dockerfile](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/Dockerfile). These flags can be overridden by specifying `$SANITIZER_FLAGS` directly. -You can choose which configurations to automatically run your fuzzers with in `project.yaml` file (e.g. [sqlite3](https://github.com/google/oss-fuzz/tree/master/projects/sqlite3/project.yaml)): - -```yaml -sanitizers: - - address - - undefined -``` \ No newline at end of file +You can choose which configurations to automatically run your fuzzers with in `project.yaml` file (e.g. [sqlite3](https://github.com/google/oss-fuzz/tree/master/projects/sqlite3/project.yaml)). \ No newline at end of file diff --git a/docs/reference/useful_links.md b/docs/reference/useful_links.md index 50e57cf777d8..f79e52413d77 100644 --- a/docs/reference/useful_links.md +++ b/docs/reference/useful_links.md @@ -25,13 +25,16 @@ parent: Reference ## Blog posts -* 2016-12-01 ([1](https://opensource.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), -[2](https://testing.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), -[3](https://security.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html)) -* 2017-05-08 ([1](https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), -[2](https://testing.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), -[3](https://security.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html)) -* 2018-11-06 ([1](https://security.googleblog.com/2018/11/a-new-chapter-for-oss-fuzz.html)) +* 2016-12-01 - Announcing OSS-Fuzz: Continuous fuzzing for open source software +([Open Source](https://opensource.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), +[Testing](https://testing.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html), +[Security](https://security.googleblog.com/2016/12/announcing-oss-fuzz-continuous-fuzzing.html)) +* 2017-05-08 - OSS-Fuzz: Five months later, and rewarding projects +([Open Source](https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), +[Testing](https://testing.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html), +[Security](https://security.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html)) +* 2018-11-06 - A New Chapter for OSS-Fuzz +([Security](https://security.googleblog.com/2018/11/a-new-chapter-for-oss-fuzz.html)) ## Tutorials