1--- 2layout: default 3title: Reproducing 4parent: Advanced topics 5nav_order: 5 6permalink: /advanced-topics/reproducing/ 7--- 8 9# Reproducing OSS-Fuzz issues 10{: .no_toc} 11 12You've been CCed on an OSS-Fuzz issue 13([examples](https://bugs.chromium.org/p/oss-fuzz/issues/list?can=1&q=Type%3ABug%2CBug-Security)). 14Now what? Before attempting to fix the bug, you should be able to reliably 15reproduce it. 16 17- TOC 18{:toc} 19--- 20 21## Fuzz target bugs 22 23Every issue has a [reproducer file]({{ site.baseurl 24}}/reference/glossary/#reproducer) (also know as a "testcase" file) attached. 25Download it. This file contains the bytes that were fed to the [fuzz 26target](http://libfuzzer.info/#fuzz-target). 27 28**Note:** If the issue is not public, you will need to login using a 29[Google account](https://support.google.com/accounts/answer/176347?hl=en) 30([why?]({{ site.baseurl 31}}/faq/#why-do-you-require-a-google-account-for-authentication)) that the bug 32report CCs. 33 34If you have already 35[integrated]({{ site.baseurl }}/advanced-topics/ideal-integration/) 36the fuzz target with your build and test system, all you have to do is run this command: 37```bash 38$ ./fuzz_target_binary <testcase_path> 39``` 40 41For timeout bugs, add the `-timeout=65` argument. For OOM bugs, add the 42`-rss_limit_mb=2560` argument. Read more on [how timeouts and OOMs are 43handled]({{ site.baseurl }}/faq/#how-do-you-handle-timeouts-and-ooms). 44 45Depending on the nature of the bug, the fuzz target binary needs to be built 46with the appropriate [sanitizer](https://github.com/google/sanitizers) 47(for example, if it's a buffer overflow, build with 48[AddressSanitizer](http://clang.llvm.org/docs/AddressSanitizer.html)). 49 50If you're not sure how to build the fuzzer using the project's build system, 51you can also use Docker commands to replicate the exact build steps used by 52OSS-Fuzz, then feed the reproducer input to the fuzz target ([how?]({{ 53site.baseurl }}/getting-started/new-project-guide/#prerequisites), [why?]({{ 54site.baseurl }}/faq/#why-do-you-use-docker)). 55 56## Building using Docker 57 58### Pull the latest Docker images 59 60Docker images get regularly updated with a newer version of build tools, build 61configurations, scripts, and other changes. In some cases, a particular issue 62can be reproduced only with a fresh image being used. Pull the latest images 63by running the following command: 64 65```bash 66$ python infra/helper.py pull_images 67``` 68 69### Build the image and the fuzzers 70 71Run the following commands: 72 73```bash 74$ python infra/helper.py build_image $PROJECT_NAME 75$ python infra/helper.py build_fuzzers --sanitizer <address/memory/undefined> \ 76 --architecture <x86_64/i386> $PROJECT_NAME 77``` 78 79The `sanitizer` used in the report is the value in the 80**Sanitizer** column. It's one of the following: 81 * **address** for AddressSanitizer. 82 * **memory** for MemorySanitizer. 83 * **undefined** for UndefinedBehaviorSanitizer. 84 85**Notes**: 86 * The `architecture` argument is only necessary if you want to specify 87`i386` configuration. 88 * Some bugs (specially ones related to pointer and integer overflows) are reproducible only in 32 bit mode or only in 64 bit mode. 89If you can't reproduce a particular bug building for x86_64, try building for i386. 90 91## Reproducing bugs 92 93After you build an image and a fuzzer, you can reproduce a bug by running the following command: 94 95```bash 96$ python infra/helper.py reproduce $PROJECT_NAME <fuzz_target_name> <testcase_path> 97``` 98 99**Note**: The reproduce command only supports `libfuzzer` fuzzing engine. Crashes 100found with other fuzzing engines should be reproducible with `libfuzzer` too. 101 102For example, to build the [libxml2](https://github.com/google/oss-fuzz/tree/master/projects/libxml2) 103project with UndefinedBehaviorSanitizer (`undefined`) instrumentation and 104reproduce a crash testcase for a fuzzer named `libxml2_xml_read_memory_fuzzer`, 105you would run: 106 107```bash 108$ python infra/helper.py build_image libxml2 109$ python infra/helper.py build_fuzzers --sanitizer undefined libxml2 110$ python infra/helper.py reproduce libxml2 libxml2_xml_read_memory_fuzzer ~/Downloads/testcase 111``` 112 113## Reproduce using local source checkout 114 115You can also mount local sources into the running container by using these commands: 116 117```bash 118$ python infra/helper.py build_fuzzers \ 119 --sanitizer <address/memory/undefined> $PROJECT_NAME <source_path> 120$ python infra/helper.py reproduce $PROJECT_NAME <fuzz_target_name> <testcase_path> 121``` 122 123Once you reproduce the bug, you can do the following: 124 125- **Fix issue:** Write a patch to fix the issue in your local checkout, then 126 use the previous command to verify the fix (i.e. no crash occurred). 127 [Use gdb]({{ site.baseurl }}/advanced-topics/debugging/#debugging-fuzzers-with-gdb) 128 if needed. 129- **Submit fix:** Submit the fix in the project's repository. ClusterFuzz will 130 automatically pick up the changes, recheck the testcase, and close the 131 issue (in < 1 day). 132- **Improve fuzzing support:** Consider 133 [improving your integration with OSS-Fuzz]({{ site.baseurl }}/advanced-topics/ideal-integration/). 134 135## Reproducing build failures 136 137Our infrastructure runs some sanity tests to make sure that your build was 138correctly configured, even if it succeeded. To reproduce these locally, run these commands: 139 140```bash 141$ python infra/helper.py build_image $PROJECT_NAME 142$ python infra/helper.py build_fuzzers --sanitizer <address/memory/undefined> \ 143 --engine <libfuzzer/afl/honggfuzz> --architecture <x86_64/i386> $PROJECT_NAME 144$ python infra/helper.py check_build --sanitizer <address/memory/undefined> \ 145 --engine <libfuzzer/afl/honggfuzz> --architecture <x86_64/i386> $PROJECT_NAME \ 146 <fuzz_target_name> 147``` 148 149**Note:** Unless you have a reason to think the build is an `i386` build, the build 150is probably an `x86_64` build and the `architecture` argument can be omitted. 151 152If you need to reproduce a `coverage` build failure, follow the 153[Code Coverage page]({{ site.baseurl }}/advanced-topics/code-coverage) to build 154your project and generate a code coverage report. 155