1Fuzzing LLDB 2============ 3 4Overview 5-------- 6 7LLDB has fuzzers that provide automated `fuzz testing <https://en.wikipedia.org/wiki/Fuzzing>`_ for different components of LLDB. The fuzzers are built with `libFuzzer <https://llvm.org/docs/LibFuzzer.html>`_ . Currently, there are fuzzers for target creation, LLDB's command interpreter and LLDB's expression evaluator. 8 9Building the fuzzers 10-------------------- 11 12Building the LLDB fuzzers requires a build configuration that has the address sanitizer and sanitizer coverage enabled. In addition to your regular CMake arguments, you will need these argumets to build the fuzzers: 13 14:: 15 16 -DLLVM_USE_SANITIZER='Address' \ 17 -DLLVM_USE_SANITIZE_COVERAGE=On \ 18 -DCLANG_ENABLE_PROTO_FUZZER=ON 19 20More information on libFuzzer's sanitizer coverage is available here: `<https://llvm.org/docs/LibFuzzer.html#fuzzer-usage>`_ 21 22If you want to debug LLDB itself when you find a bug using the fuzzers, use the CMake option ``-DCMAKE_BUILD_TYPE='RelWithDebInfo'`` 23 24To build a fuzzer, run the desired ninja command for the fuzzer(s) you want to build: 25 26:: 27 28 $ ninja lldb-target-fuzzer 29 $ ninja lldb-commandinterpreter-fuzzer 30 $ ninja lldb-expression-fuzzer 31 32Once built, the binaries for the fuzzers will exist in the ``bin`` directory of your build folder. 33 34Continuous integration 35---------------------- 36 37Currently, there are plans to integrate the LLDB fuzzers into the `OSS Fuzz <https://github.com/google/oss-fuzz>`_ project for continuous integration. 38 39Running the fuzzers 40------------------- 41 42If you want to run the fuzzers locally, you can run the binaries that were generated with ninja from the build directory: 43 44:: 45 46 $ ./bin/lldb-target-fuzzer 47 $ ./bin/lldb-commandinterpreter-fuzzer 48 $ ./bin/lldb-expression-fuzzer 49 50This will run the fuzzer binaries directly, and you can use the `libFuzzer options <https://llvm.org/docs/LibFuzzer.html#options>`_ to customize how the fuzzers are run. 51 52Another way to run the fuzzers is to use a ninja target that will both build the fuzzers and then run them immediately after. These custom targets run each fuzzer with command-line arguments that provide better fuzzing for the components being tested. Running the fuzzers this way will also create directories that will store any inputs that caused LLDB to crash, timeout or run out of memory. The directories are created for each fuzzer. 53 54To run the custom ninja targets, run the command for your desired fuzzer: 55 56:: 57 58 $ ninja fuzz-lldb-target 59 $ ninja fuzz-lldb-commandinterpreter 60 $ ninja fuzz-lldb-expression 61 62Investigating and reproducing bugs 63---------------------------------- 64 65When the fuzzers find an input that causes LLDB to crash, timeout or run out of memory, the input is saved to a file in the build directory. When running the fuzzer binaries directly this input is stored in a file named ``<crash/timeout/oom>-<hash>``. 66 67When running the fuzzers using the custom ninja targets shown above, the inputs will be stored in ``fuzzer-artifacts/<fuzzer name>-artifacts``, which is created in your build directory. The input files will have the name ``<fuzzer name>-<crash/timeout/oom>-<hash>``. 68 69If you want to reproduce the issue found by a fuzzer once you have gotten the input, you can pass the individual input to the fuzzer binary as a command-line argument: 70 71:: 72 73 $ ./<fuzzer binary> <input you are investigating> 74