Document i386 fuzzing (#2704)

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)

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 <address/memory/undefined> $PROJECT_NAME
+$ python infra/helper.py build_fuzzers --sanitizer <address/memory/undefined> --architecture <x86_64/i386> $PROJECT_NAME
 ```
 
+The `architecture` argument is only necessary if you want to specify `i386`.
+
 ## Reproducing bugs
 ```bash
 $ python infra/helper.py reproduce $PROJECT_NAME <fuzz_target_name> <testcase_path>
@@ -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 <address/memory/undefined> \
-    --engine <libfuzzer/afl/honggfuzz> $PROJECT_NAME
+    --engine <libfuzzer/afl/honggfuzz> --architecture <x86_64/i386> $PROJECT_NAME
 $ python infra/helper.py check_build  --sanitizer <address/memory/undefined> \
-    --engine <libfuzzer/afl/honggfuzz> $PROJECT_NAME <fuzz_target_name>
+    --engine <libfuzzer/afl/honggfuzz> --architecture <x86_64/i386> $PROJECT_NAME <fuzz_target_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.

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

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.

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)).
+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
+```