1# libFuzzer Integration Reference 2 3## Additional Sanitizer Configuration 4 5### MSan 6 7Memory Sanitizer (MSan) in Chromium only supports Ubuntu Precise/Trusty and not 8Rodete. 9Thus, our [reproduce tool] cannot reproduce bugs found using MSan. 10You can try to reproduce them manually by using [these instructions] on how to 11run MSan-instrumented code in docker. 12 13### UBSan 14 15By default, UBSan does not crash when undefined behavior is detected. 16To make it crash, the following option needs to be set in environment: 17```bash 18UBSAN_OPTIONS=halt_on_error=1 ./fuzzer <corpus_directory_or_single_testcase_path> 19``` 20Other useful options are (also used by ClusterFuzz): 21```bash 22UBSAN_OPTIONS=symbolize=1:halt_on_error=1:print_stacktrace=1 ./fuzzer <corpus_directory_or_single_testcase_path> 23``` 24 25## Supported Platforms and Configurations 26 27### Builder configurations 28 29The exact GN arguments that are used on our builders can be generated by running 30(from Chromium's `src` directory): 31 32| Builder | Description | 33|---------|-------------| 34|Linux ASan | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux ASan' out/libfuzzer` | 35|Linux ASan (x86) | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 ASan' out/libfuzzer` | 36|Linux ASan Debug | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux ASan Debug' out/libfuzzer` | 37|Linux MSan[*](#MSan) | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux MSan' out/libfuzzer` | 38|Linux UBSan[*](#UBSan)| `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux UBSan' out/libfuzzer` | 39|Chrome OS ASan | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Chrome OS ASan' out/libfuzzer` | 40|Mac ASan | `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Mac ASan' out/libfuzzer` | 41|Windows ASan | `python tools\mb\mb.py gen -m chromium.fuzz -b "Libfuzzer Upload Windows ASan" out\libfuzzer` | 42|Linux ASan V8 ARM Simulator[*](#ARM-and-ARM64)| `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 V8-ARM ASan' out/libfuzzer` | 43|Linux ASan V8 ARM64 Simulator[*](#ARM-and-ARM64)| `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux V8-ARM64 ASan' out/libfuzzer` | 44|Linux ASan Debug V8 ARM Simulator[*](#ARM-and-ARM64)| `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 V8-ARM ASan Debug' out/libfuzzer` | 45|Linux ASan Debug V8 ARM64 Simulator[*](#ARM-and-ARM64)| `tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux V8-ARM64 ASan Debug' out/libfuzzer` | 46 47 48### Linux 49Linux is fully supported by libFuzzer and ClusterFuzz with following sanitizer 50configurations: 51 52| GN Argument | Description | 53|--------------|----| 54| is_asan=true | enables [Address Sanitizer] to catch problems like buffer overruns. | 55| is_msan=true | enables [Memory Sanitizer] to catch problems like uninitialized reads. \[[*](#MSan)\] | 56| is_ubsan_security=true | enables [Undefined Behavior Sanitizer] to catch undefined behavior like integer overflow. \[[*](#UBSan)\] | 57 58Configuration example: 59 60```bash 61# With address sanitizer 62gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true' --check 63``` 64 65### Linux x86 (32-bit) 66Fuzzing targets built for x86 can discover bugs that are not found by x64 67builds. Linux x86 is supported by libFuzzer with `is_asan` configuration. 68 69Configuration example: 70 71```bash 72gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true host_cpu=\"x86\" target_cpu=\"x86\"" --check 73``` 74 75### Chrome OS 76Chrome OS is supported by libFuzzer with `is_asan` configuration. 77 78Configuration example: 79 80```bash 81gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true target_os="chromeos"' --check 82``` 83 84To do a Chrome OS build on Linux (not just for libFuzzer), your `.gclient` file 85must be configured appropriately, see the [Chrome OS build docs] for more 86details. 87 88### Mac 89 90Mac is supported by libFuzzer with `is_asan` configuration. 91 92Configuration example: 93 94```bash 95gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true mac_deployment_target="10.7"' --check 96``` 97 98### Windows 99 100Windows is supported by libFuzzer with `is_asan` configuration. 101 102Configuration example: 103 104```bash 105gn gen out/libfuzzer "--args=use_libfuzzer=true is_asan=true is_debug=false is_component_build=false" --check 106``` 107 108On Windows you must use `is_component_build=false` as libFuzzer does not support 109component builds on Windows. If you are using `is_asan=true` then you must use 110`is_debug=false` as ASan does not support debug builds on Windows. 111You may also want to consider using `symbol_level=1` which will reduce build 112size by reducing symbol level to the level necessary for libFuzzer (useful 113if building many fuzz targets). 114 115### ARM and ARM64 116 117The V8 ARM and ARM64 simulators are supported by libFuzzer with `is_asan` 118configuration. Note that there is nothing special about these builds for non-V8 119fuzz targets. 120 121ARM configuration example: 122 123 124```bash 125gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true host_cpu=\"x86\" target_cpu=\"x86\" v8_target_cpu=\"arm\"" --check 126``` 127 128ARM64 configuration example: 129 130```bash 131gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true target_cpu=\"x64\" v8_target_cpu=\"arm64\"" --check 132``` 133 134## fuzzer_test GN Template 135 136Use `fuzzer_test` to define libFuzzer targets: 137 138``` 139fuzzer_test("my_fuzzer") { 140 ... 141} 142``` 143 144Following arguments are supported: 145 146| Argument | Description | 147|----------|-------------| 148| `sources` | **required** list of fuzzer test source files | 149| `deps` | fuzzer dependencies | 150| `additional_configs` | additional GN configurations to be used for compilation | 151| `dict` | a dictionary file for the fuzzer | 152| `libfuzzer_options` | runtime options file for the fuzzer. See [Fuzzer Runtime Options](#Fuzzer-Runtime-Options) | 153| `seed_corpus` | single directory containing test inputs, parsed recursively | 154| `seed_corpuses` | multiple directories with the same purpose as `seed_corpus` | 155| `libs` | additional libraries to link. Same as [libs] for gn targets. | 156 157 158## Fuzzer Runtime Options 159 160There are many different runtime options supported by libFuzzer. Options 161are passed as command line arguments: 162 163``` 164./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ] 165``` 166 167Most common flags are: 168 169| Flag | Description | 170|------|-------------| 171| max_len | Maximum length of test input. | 172| timeout | Timeout of seconds. Units slower than this value will be reported as bugs. | 173| rss_limit_mb | Memory usage limit in Mb, default 2048. Some Chrome targets, such as Blink, require more than the default to initialize. | 174 175Full list of options can be found at [libFuzzer options] page and by running 176the binary with `-help=1`. 177 178To specify these options for ClusterFuzz, list all parameters in 179`libfuzzer_options` target attribute: 180 181``` 182fuzzer_test("my_fuzzer") { 183 ... 184 libfuzzer_options = [ 185 # Suppress stdout and stderr output (not recommended, as it may silence useful info). 186 "close_fd_mask=3", 187 ] 188} 189``` 190 191[libFuzzer options]: http://llvm.org/docs/LibFuzzer.html#options 192[Address Sanitizer]: http://clang.llvm.org/docs/AddressSanitizer.html 193[Memory Sanitizer]: http://clang.llvm.org/docs/MemorySanitizer.html 194[Undefined Behavior Sanitizer]: http://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html 195[reproduce tool]: https://github.com/google/clusterfuzz-tools 196[these instructions]: https://www.chromium.org/developers/testing/memorysanitizer#TOC-Running-on-other-distros-using-Docker 197[Chrome OS build docs]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/chromeos_build_instructions.md#updating-your-gclient-config 198[libs]: https://gn.googlesource.com/gn/+/master/docs/reference.md#libs 199