diff options
Diffstat (limited to 'doc/fuzzing.md')
| -rw-r--r-- | doc/fuzzing.md | 51 |
1 files changed, 40 insertions, 11 deletions
diff --git a/doc/fuzzing.md b/doc/fuzzing.md index 87df2bbbb9..6fc9077e4c 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -16,7 +16,7 @@ $ FUZZ=process_message src/test/fuzz/fuzz # abort fuzzing using ctrl-c ``` -## Fuzzing harnesses, fuzzing output and fuzzing corpora +## Fuzzing harnesses and output [`process_message`](https://github.com/bitcoin/bitcoin/blob/master/src/test/fuzz/process_message.cpp) is a fuzzing harness for the [`ProcessMessage(...)` function (`net_processing`)](https://github.com/bitcoin/bitcoin/blob/master/src/net_processing.cpp). The available fuzzing harnesses are found in [`src/test/fuzz/`](https://github.com/bitcoin/bitcoin/tree/master/src/test/fuzz). @@ -64,6 +64,8 @@ block^@M-^?M-^?M-^?M-^?M-^?nM-^?M-^? In this case the fuzzer managed to create a `block` message which when passed to `ProcessMessage(...)` increased coverage. +## Fuzzing corpora + The project's collection of seed corpora is found in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. To fuzz `process_message` using the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) seed corpus: @@ -81,6 +83,20 @@ INFO: seed corpus: files: 991 min: 1b max: 1858b total: 288291b rss: 150Mb … ``` +## Reproduce a fuzzer crash reported by the CI + +- `cd` into the `qa-assets` directory and update it with `git pull qa-assets` +- locate the crash case described in the CI output, e.g. `Test unit written to + ./crash-1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` +- make sure to compile with all sanitizers, if they are needed (fuzzing runs + more slowly with sanitizers enabled, but a crash should be reproducible very + quickly from a crash case) +- run the fuzzer with the case number appended to the seed corpus path: + `FUZZ=process_message src/test/fuzz/fuzz + qa-assets/fuzz_seed_corpus/process_message/1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` + +## Submit improved coverage + If you find coverage increasing inputs when fuzzing you are highly encouraged to submit them for inclusion in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Every single pull request submitted against the Bitcoin Core repo is automatically tested against all inputs in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Contributing new coverage increasing inputs is an easy way to help make Bitcoin Core more robust. @@ -108,33 +124,32 @@ Full configure that was tested on macOS Catalina with `brew` installed `llvm`: Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest. -# Fuzzing Bitcoin Core using american fuzzy lop (`afl-fuzz`) +# Fuzzing Bitcoin Core using afl++ ## Quickstart guide -To quickly get started fuzzing Bitcoin Core using [`afl-fuzz`](https://github.com/google/afl): +To quickly get started fuzzing Bitcoin Core using [afl++](https://github.com/AFLplusplus/AFLplusplus): ```sh $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ -$ git clone https://github.com/google/afl -$ make -C afl/ -$ make -C afl/llvm_mode/ +$ git clone https://github.com/AFLplusplus/AFLplusplus +$ make -C AFLplusplus/ source-only $ ./autogen.sh -# It is possible to compile with afl-gcc and afl-g++ instead of afl-clang. However, running afl-fuzz -# may require more memory via the -m flag. -$ CC=$(pwd)/afl/afl-clang-fast CXX=$(pwd)/afl/afl-clang-fast++ ./configure --enable-fuzz +# If afl-clang-lto is not available, see +# https://github.com/AFLplusplus/AFLplusplus#a-selecting-the-best-afl-compiler-for-instrumenting-the-target +$ CC=$(pwd)/AFLplusplus/afl-clang-lto CXX=$(pwd)/AFLplusplus/afl-clang-lto++ ./configure --enable-fuzz $ make # For macOS you may need to ignore x86 compilation checks when running "make". If so, # try compiling using: AFL_NO_X86=1 make $ mkdir -p inputs/ outputs/ $ echo A > inputs/thin-air-input -$ FUZZ=bech32 afl/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/fuzz +$ FUZZ=bech32 AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/fuzz # You may have to change a few kernel parameters to test optimally - afl-fuzz # will print an error and suggestion if so. ``` -Read the [`afl-fuzz` documentation](https://github.com/google/afl) for more information. +Read the [afl++ documentation](https://github.com/AFLplusplus/AFLplusplus) for more information. # Fuzzing Bitcoin Core using Honggfuzz @@ -231,3 +246,17 @@ $ honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \ -nodebuglogfile -bind=127.0.0.1:18444 -logthreadnames \ -debug ``` + +# OSS-Fuzz + +Bitcoin Core participates in Google's [OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/bitcoin-core) +program, which includes a dashboard of [publicly disclosed vulnerabilities](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=bitcoin-core). +Generally, we try to disclose vulnerabilities as soon as possible after they +are fixed to give users the knowledge they need to be protected. However, +because Bitcoin is a live P2P network, and not just standalone local software, +we might not fully disclose every issue within Google's standard +[90-day disclosure window](https://google.github.io/oss-fuzz/getting-started/bug-disclosure-guidelines/) +if a partial or delayed disclosure is important to protect users or the +function of the network. + +OSS-Fuzz also produces [a fuzzing coverage report](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_bitcoin-core/latest). |