External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 address review comments

Browse Source
This commit is contained in:
Niels Lohmann 2022-05-08 17:06:23 +02:00
parent 13e9ab2373
commit f92e6d0979
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
1 changed files with 14 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
tests/fuzzing.md
View File

@ -1,12 +1,12 @@
# Fuzz testing # Fuzz testing
Each parser of the library (JSON, BJData, BSON, CBOR, MessagePack, and UBJSON) can be fuzz tested. Currently, Each parser of the library (JSON, BJData, BSON, CBOR, MessagePack, and UBJSON) can be fuzz tested. Currently,
[LibFuzzer](https://llvm.org/docs/LibFuzzer.html) and [afl++](https://github.com/AFLplusplus/AFLplusplus) are supported. [libFuzzer](https://llvm.org/docs/LibFuzzer.html) and [afl++](https://github.com/AFLplusplus/AFLplusplus) are supported.
## Corpus creation ## Corpus creation
For most effective fuzzing, a [corpus](https://llvm.org/docs/LibFuzzer.html#corpus) should be provided. A corpus is a For most effective fuzzing, a [corpus](https://llvm.org/docs/LibFuzzer.html#corpus) should be provided. A corpus is a
directory with some simple input files that cover several features of the parser and is hence a good starting point directory with some simple input files that cover several features of the parser and is hence a good starting point
for mutations. for mutations.
```shell ```shell
@ -16,18 +16,19 @@ unzip v$TEST_DATA_VERSION.zip
rm v$TEST_DATA_VERSION.zip rm v$TEST_DATA_VERSION.zip
for FORMAT in json bjdata bson cbor msgpack ubjson for FORMAT in json bjdata bson cbor msgpack ubjson
do do
rm -fr mkdir corpus_$FORMAT rm -fr corpus_$FORMAT
mkdir corpus_$FORMAT mkdir corpus_$FORMAT
find json_test_data-$TEST_DATA_VERSION -size -5k -name "*.$FORMAT" -exec cp "{}" "corpus_$FORMAT" \; find json_test_data-$TEST_DATA_VERSION -size -5k -name "*.$FORMAT" -exec cp "{}" "corpus_$FORMAT" \;
done done
rm -fr json_test_data-$TEST_DATA_VERSION rm -fr json_test_data-$TEST_DATA_VERSION
``` ```
The generated corpus can be used with both LibFuzzer and afl++. The generated corpus can be used with both libFuzzer and afl++. The remainder of this documentation assumes the corpus
directories have been created in the `tests` directory.
## LibFuzzer ## libFuzzer
To use LibFuzzer, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`: To use libFuzzer, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`. In the `tests` directory, call
```shell ```shell
make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer"
@ -36,14 +37,15 @@ make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer"
This creates a fuzz tester binary for each parser that supports these This creates a fuzz tester binary for each parser that supports these
[command line options](https://llvm.org/docs/LibFuzzer.html#options). [command line options](https://llvm.org/docs/LibFuzzer.html#options).
Note the compiler provided by Xcode (AppleClang) does not contain libFuzzer. Please install Clang via Homebrew calling In case your default compiler is not a Clang compiler that includes libFuzzer (Clang 6.0 or later), you need to set the
`brew install llvm` and add `CXX=$(brew --prefix llvm)/bin/clang` to the `make` call: `CXX` variable accordingly. Note the compiler provided by Xcode (AppleClang) does not contain libFuzzer. Please install
Clang via Homebrew calling `brew install llvm` and add `CXX=$(brew --prefix llvm)/bin/clang` to the `make` call:
```shell ```shell
make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" CXX=$(brew --prefix llvm)/bin/clang make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" CXX=$(brew --prefix llvm)/bin/clang
``` ```
Then pass the corpus directory as command-line argument: Then pass the corpus directory as command-line argument (assuming it is located in `tests`):
```shell ```shell
./parse_cbor_fuzzer corpus_cbor ./parse_cbor_fuzzer corpus_cbor
@ -55,13 +57,13 @@ a file starting with `crash-`.
## afl++ ## afl++
To use afl++, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`. It will be replaced by a `libAFLDriver.a` to To use afl++, you need to pass `-fsanitize=fuzzer` as `FUZZER_ENGINE`. It will be replaced by a `libAFLDriver.a` to
re-use the same code written for LibFuzzer with afl++. Furthermore, set `afl-clang-fast++` as compiler. re-use the same code written for libFuzzer with afl++. Furthermore, set `afl-clang-fast++` as compiler.
```shell ```shell
CXX=afl-clang-fast++ make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer" CXX=afl-clang-fast++ make fuzzers FUZZER_ENGINE="-fsanitize=fuzzer"
``` ```
Then the fuzzer is called like this: Then the fuzzer is called like this in the `tests` directory:
```shell ```shell
afl-fuzz -i corpus_cbor -o out -- ./parse_cbor_fuzzer afl-fuzz -i corpus_cbor -o out -- ./parse_cbor_fuzzer
@ -76,4 +78,4 @@ The library is further fuzz-tested 24/7 by Google's [OSS-Fuzz project](https://g
the same `fuzzers` target as above and also relies on the `FUZZER_ENGINE` variable. See the used the same `fuzzers` target as above and also relies on the `FUZZER_ENGINE` variable. See the used
[build script](https://github.com/google/oss-fuzz/blob/master/projects/json/build.sh) for more information. [build script](https://github.com/google/oss-fuzz/blob/master/projects/json/build.sh) for more information.
In case the build at OSS-Fuzz fails, and issue will be created automatically. In case the build at OSS-Fuzz fails, an issue will be created automatically.