From 984b792dd9dcabf968e6c0510fddeef2c8557431 Mon Sep 17 00:00:00 2001 From: jonathanmetzman <31354670+jonathanmetzman@users.noreply.github.com> Date: Mon, 19 Aug 2019 14:07:33 -0700 Subject: [PATCH] Document i386 fuzzing (#2704) --- README.md | 3 ++- docs/advanced-topics/reproducing.md | 12 ++++++++--- docs/getting-started/new_project_guide.md | 25 ++++++++++++++++++++++- docs/index.md | 3 ++- docs/reference/glossary.md | 9 +++++++- 5 files changed, 45 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 739d92333fe1..bc9af6eb74e5 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ in combination with [Sanitizers](https://github.com/google/sanitizers), as well [ClusterFuzz](https://github.com/google/clusterfuzz), 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. +Currently, OSS-Fuzz supports C/C++, Rust, and Go code. Other languages supported by [LLVM](http://llvm.org) may work too. +OSS-Fuzz supports fuzzing x86_64 and i386 builds. ## Overview ![OSS-Fuzz process diagram](docs/images/process.png) diff --git a/docs/advanced-topics/reproducing.md b/docs/advanced-topics/reproducing.md index ea164a54ab22..10acda971ad5 100644 --- a/docs/advanced-topics/reproducing.md +++ b/docs/advanced-topics/reproducing.md @@ -66,9 +66,11 @@ $ python infra/helper.py pull_images ```bash $ python infra/helper.py build_image $PROJECT_NAME -$ python infra/helper.py build_fuzzers --sanitizer
$PROJECT_NAME +$ python infra/helper.py build_fuzzers --sanitizer
--architecture $PROJECT_NAME ``` +The `architecture` argument is only necessary if you want to specify `i386`. + ## Reproducing bugs ```bash $ python infra/helper.py reproduce $PROJECT_NAME @@ -120,11 +122,15 @@ 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 + --engine --architecture $PROJECT_NAME $ python infra/helper.py check_build --sanitizer
\ - --engine $PROJECT_NAME + --engine --architecture $PROJECT_NAME ``` + +Note that unless you have a reason to think the build is an i386 build, the build +is probably an x86_64 build and the `architecture` argument can be omitted. + For reproducing a `coverage` build failure, follow [Code Coverage page]({{ site.baseurl }}/advanced-topics/code-coverage) to build your project and generate a code coverage report. diff --git a/docs/getting-started/new_project_guide.md b/docs/getting-started/new_project_guide.md index 61bc6ae0d0f0..d0c0315df564 100644 --- a/docs/getting-started/new_project_guide.md +++ b/docs/getting-started/new_project_guide.md @@ -77,6 +77,7 @@ This configuration file stores project metadata. The following attributes are su - [primary_contact](#primary) - [auto_ccs](#primary) - [sanitizers](#sanitizers) (optional) +- [architectures](#architectures) (optional) - [help_url](#help_url) (optional) ### homepage @@ -118,7 +119,29 @@ 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 (optional) +### architectures (optional) {#architectures} +The list of architectures to fuzz on. +ClusterFuzz supports fuzzing on x86_64 (aka x64) by default. +However you can also fuzz using AddressSanitizer and libFuzzer on i386 (aka x86, or 32 bit) by specifying "x86_64" and "i386" in "architectures" like this: + +```yaml +architectures: + - x86_64 + - i386 + ``` + +By fuzzing on i386 you might find bugs that: +* Only occur in architecture-specific source code (e.g. code that contains i386 assembly). +* Exist in architecture-independent source code and which only affects i386 users. +* Exist in architecture-independent source code and which affects users on other 32-bit platforms such as AArch32 (aka 32-bit ARM). + +Note that some bugs which affect x86_64 may be discovered on i386 and filed as such. +On the testcase page of each oss-fuzz issue is a list of other jobs where the crash reproduces, this can let you know if the crash exists on x86_64 as well. + +Fuzzing on i386 is not enabled by default because many projects won't build for i386 without some modification to their OSS-Fuzz build process. +For example, you will need to link against `$LIB_FUZZING_ENGINE` and possibly install i386 dependencies within the x86_64 docker image ([for example](https://github.com/google/oss-fuzz/blob/5b8dcb5d942b3b8bc173b823fb9ddbdca7ec6c99/projects/gdal/build.sh#L18)) to get things working. + +### help_url (optional) {#help_url} 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 diff --git a/docs/index.md b/docs/index.md index cac2ab5fa9ea..76f8f3e697db 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,8 @@ in combination with [Sanitizers](https://github.com/google/sanitizers), as well [ClusterFuzz](https://github.com/google/clusterfuzz), 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. +Currently, OSS-Fuzz supports C/C++, Rust, and Go code. Other languages supported by [LLVM](http://llvm.org) may work too. +OSS-Fuzz supports fuzzing x86_64 and i386 builds. ## Trophies As of August 2019, OSS-Fuzz has found over [14,000] bugs in [200] open source projects. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index d4f9a9c4d5b6..01a26b688439 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -86,4 +86,11 @@ Supported sanitizers: 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)). \ 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)). + +### Architectures +ClusterFuzz supports fuzzing on x86_64 (aka x64) by default. However you can also fuzz using AddressSanitizer and libFuzzer on i386 (aka x86, or 32 bit) by specifiying the `$ARCHITECTURE` build environment variable using the `--architecture` option: + +```bash +python infra/helper.py build_fuzzers --architecture i386 json +```