Merge bitcoin/bitcoin#22585: fuzz: add guide to fuzzing with Eclipser v1.x

6e1150ea3b82d1ab557d4b74aa652b8d974876aa fuzz: add guide to fuzzing with Eclipser v1.x (Alex Groce)

Pull request description:

  MarcoFalke and practicalswift here's an Eclipser guide, reconstructed from their documentation and my docker history getting it up and running.  It might be good if someone confirmed it actually works for them in a fresh ubuntu 20.04.

ACKs for top commit:
  practicalswift:
    ACK 6e1150ea3b82d1ab557d4b74aa652b8d974876aa

Tree-SHA512: ca855932fd7a2c1d1005d572ab5fabc26f42d779f9baf279783f08a43dd72ec60f57239135d30c2a82781e593626fec2c96bb19fb91e1b777cef2d83a54eba35

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/fuzzing.md b/doc/fuzzing.md
index ee9c65d4d4..0880f9f581 100644
--- a/doc/fuzzing.md
+++ b/doc/fuzzing.md
@@ -254,6 +254,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)