1# Fuzz testing 2 3Each parser of the library (JSON, BJData, BSON, CBOR, MessagePack, and UBJSON) can be fuzz tested. Currently, 4[libFuzzer](https://llvm.org/docs/LibFuzzer.html) and [afl++](https://github.com/AFLplusplus/AFLplusplus) are supported. 5 6## Corpus creation 7 8For most effective fuzzing, a [corpus](https://llvm.org/docs/LibFuzzer.html#corpus) should be provided. A corpus is a 9directory with some simple input files that cover several features of the parser and is hence a good starting point 10for mutations. 11 12```shell 13TEST_DATA_VERSION=3.1.0 14wget https://github.com/nlohmann/json_test_data/archive/refs/tags/v$TEST_DATA_VERSION.zip 15unzip v$TEST_DATA_VERSION.zip 16rm v$TEST_DATA_VERSION.zip 17for FORMAT in json bjdata bson cbor msgpack ubjson 18do 19 rm -fr corpus_$FORMAT 20 mkdir corpus_$FORMAT 21 find json_test_data-$TEST_DATA_VERSION -size -5k -name "*.$FORMAT" -exec cp "{}" "corpus_$FORMAT" \; 22done 23rm -fr json_test_data-$TEST_DATA_VERSION 24``` 25 26The generated corpus can be used with both libFuzzer and afl++. The remainder of this documentation assumes the corpus 27directories have been created in the `tests` directory. 28 29## libFuzzer 30 31To use libFuzzer, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`. In the `tests` directory, call 32 33```shell 34make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" 35``` 36 37This creates a fuzz tester binary for each parser that supports these 38[command line options](https://llvm.org/docs/LibFuzzer.html#options). 39 40In case your default compiler is not a Clang compiler that includes libFuzzer (Clang 6.0 or later), you need to set the 41`CXX` variable accordingly. Note the compiler provided by Xcode (AppleClang) does not contain libFuzzer. Please install 42Clang via Homebrew calling `brew install llvm` and add `CXX=$(brew --prefix llvm)/bin/clang` to the `make` call: 43 44```shell 45make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" CXX=$(brew --prefix llvm)/bin/clang 46``` 47 48Then pass the corpus directory as command-line argument (assuming it is located in `tests`): 49 50```shell 51./parse_cbor_fuzzer corpus_cbor 52``` 53 54The fuzzer should be able to run indefinitely without crashing. In case of a crash, the tested input is dumped into 55a file starting with `crash-`. 56 57## afl++ 58 59To use afl++, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`. It will be replaced by a `libAFLDriver.a` to 60re-use the same code written for libFuzzer with afl++. Furthermore, set `afl-clang-fast++` as compiler. 61 62```shell 63CXX=afl-clang-fast++ make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" 64``` 65 66Then the fuzzer is called like this in the `tests` directory: 67 68```shell 69afl-fuzz -i corpus_cbor -o out -- ./parse_cbor_fuzzer 70``` 71 72The fuzzer should be able to run indefinitely without crashing. In case of a crash, the tested input is written to the 73directory `out`. 74 75## OSS-Fuzz 76 77The library is further fuzz-tested 24/7 by Google's [OSS-Fuzz project](https://github.com/google/oss-fuzz). It uses 78the same `fuzzers` target as above and also relies on the `FUZZER_ENGINE` variable. See the used 79[build script](https://github.com/google/oss-fuzz/blob/master/projects/json/build.sh) for more information. 80 81In case the build at OSS-Fuzz fails, an issue will be created automatically. 82