fuzz: add guide to fuzzing with Eclipser v1.x

agroce · agroce · commit 6e1150ea3b82 · 2021-08-06T08:51:30.000-07:00
diff --git a/doc/fuzzing.md b/doc/fuzzing.md
@@ -247,6 +247,73 @@ $ honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \
                        -debug
 ```
 
+# Fuzzing Bitcoin Core using Eclipser (v1.x)
+
+## Quickstart guide
+
+To quickly get started fuzzing Bitcoin Core using [Eclipser v1.x](https://github.com/SoftSec-KAIST/Eclipser/tree/v1.x):
+
+```sh
+$ git clone https://github.com/bitcoin/bitcoin
+$ cd bitcoin/
+$ sudo vim /etc/apt/sources.list # Uncomment the lines starting with 'deb-src'.
+$ sudo apt-get update
+$ sudo apt-get build-dep qemu
+$ sudo apt-get install libtool libtool-bin wget automake autoconf bison gdb
+```
+
+At this point, you must install the .NET core.  The process differs, depending on your Linux distribution.
+See [this link](https://docs.microsoft.com/en-us/dotnet/core/install/linux) for details.
+On ubuntu 20.04, the following should work:
+
+```sh
+$ wget -q https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb
+$ sudo dpkg -i packages-microsoft-prod.deb
+$ rm packages-microsoft-prod.deb
+$ sudo apt-get update
+$ sudo apt-get install -y dotnet-sdk-2.1
+```
+
+You will also want to make sure Python is installed as `python` for the Eclipser install to succeed.
+
+```sh
+$ git clone https://github.com/SoftSec-KAIST/Eclipser.git
+$ cd Eclipser
+$ git checkout v1.x
+$ make
+$ cd ..
+$ ./autogen.sh
+$ ./configure --enable-fuzz
+$ make
+$ mkdir -p outputs/
+$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -o outputs --src stdin
+```
+
+This will perform 10 hours of fuzzing.
+
+To make further use of the inputs generated by Eclipser, you
+must first decode them:
+
+```sh
+$ dotnet Eclipser/build/Eclipser.dll decode -i outputs/testcase -o decoded_outputs
+```
+This will place raw inputs in the directory `decoded_outputs/decoded_stdins`.  Crashes are in the `outputs/crashes` directory, and must
+be decoded in the same way.
+
+Fuzzing with Eclipser will likely be much more effective if using an existing corpus:
+
+```sh
+$ git clone https://github.com/bitcoin-core/qa-assets
+$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -i qa-assets/fuzz_seed_corpus/bech32 outputs --src stdin
+```
+
+Note that fuzzing with Eclipser on certain targets (those that create 'full nodes', e.g. `process_message*`) will,
+for now, slowly fill `/tmp/` with improperly cleaned-up files, which will cause spurious crashes.
+See [this proposed patch](https://github.com/bitcoin/bitcoin/pull/22472) for more information.
+
+Read the [Eclipser documentation for v1.x](https://github.com/SoftSec-KAIST/Eclipser/tree/v1.x) for more details on using Eclipser.
+
+
 # OSS-Fuzz
 
 Bitcoin Core participates in Google's [OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/bitcoin-core)
