Merge pull request #5383 from Crypt-iQ/update_fuzz_docs_06142021

docs+Makefile: update fuzz.md to explain new build/run process

Makefile

@@ -9,6 +9,7 @@ GOACC_PKG := github.com/ory/go-acc
 GOIMPORTS_PKG := golang.org/x/tools/cmd/goimports
 GOFUZZ_BUILD_PKG := github.com/dvyukov/go-fuzz/go-fuzz-build
 GOFUZZ_PKG := github.com/dvyukov/go-fuzz/go-fuzz
+GOFUZZ_DEP_PKG := github.com/dvyukov/go-fuzz/go-fuzz-dep
 
 GO_BIN := ${GOPATH}/bin
 BTCD_BIN := $(GO_BIN)/btcd
@@ -36,7 +37,7 @@ BTCD_COMMIT := $(shell cat go.mod | \
 
 LINT_COMMIT := v1.18.0
 GOACC_COMMIT :=80342ae2e0fcf265e99e76bcc4efd022c7c3811b 
-GOFUZZ_COMMIT := 21309f307f61
+GOFUZZ_COMMIT := b1f3d6f
 
 DEPGET := cd /tmp && GO111MODULE=on go get -v
 GOBUILD := GO111MODULE=on go build -v
@@ -81,6 +82,8 @@ endif
 
 LINT = $(LINT_BIN) run -v $(LINT_WORKERS)
 
+GOFUZZ_DEP_PKG_FETCH = go get -v $(GOFUZZ_DEP_PKG)@$(GOFUZZ_COMMIT)
+
 GREEN := "\\033[0;32m"
 NC := "\\033[0m"
 define print
@@ -236,6 +239,8 @@ flakehunter-parallel:
 # FUZZING
 # =============
 fuzz-build: $(GOFUZZ_BUILD_BIN)
+	@$(call print, "Fetching go-fuzz-dep package")
+	$(GOFUZZ_DEP_PKG_FETCH)
 	@$(call print, "Creating fuzz harnesses for packages '$(FUZZPKG)'.")
 	scripts/fuzz.sh build "$(FUZZPKG)"
 

docs/fuzz.md

@@ -2,24 +2,19 @@
 
 The `fuzz` package is organized into subpackages which are named after the `lnd` package they test. Each subpackage has its own set of fuzz targets.
 
-### Setup and Installation ###
-This section will cover setup and installation of `go-fuzz` and fuzzing binaries.
+## Setup and Installation ##
+This section will cover setup and installation of the fuzzing binaries.
 
-* First, we must get `go-fuzz`.
+* The following is a command to build all fuzzing harnesses:
 ```shell
-⛰  go get -u github.com/dvyukov/go-fuzz/...
-```
-* The following is a command to build all fuzzing harnesses for a specific package.
-```shell
-⛰  cd fuzz/<package>
-⛰  find * -maxdepth 1 -regex '[A-Za-z0-9\-_.]'* -not -name fuzz_utils.go | sed 's/\.go$//1' | xargs -I % sh -c 'go-fuzz-build -func Fuzz_% -o <package>-%-fuzz.zip github.com/lightningnetwork/lnd/fuzz/<package>'
+⛰  make fuzz-build
 ```
 
 * This may take a while since this will create zip files associated with each fuzzing target.
 
-* Now, run `go-fuzz` with `workdir` set as below!
+* The following is a command to run all fuzzing harnesses for 30 seconds:
 ```shell
-⛰  go-fuzz -bin=<.zip archive here> -workdir=<harness> -procs=<num workers>
+⛰  make fuzz-run
 ```
 
 `go-fuzz` will print out log lines every couple of seconds. Example output:
@@ -28,27 +23,21 @@ This section will cover setup and installation of `go-fuzz` and fuzzing binaries
 ```
 Corpus is the number of items in the corpus. `go-fuzz` may add valid inputs to
 the corpus in an attempt to gain more coverage. Crashers is the number of inputs
-resulting in a crash. The inputs, and their outputs are logged in:
+resulting in a crash. The inputs, and their outputs are logged by default in:
 `fuzz/<package>/<harness>/crashers`. `go-fuzz` also creates a `suppressions` directory
 of stacktraces to ignore so that it doesn't create duplicate stacktraces.
 Cover is a number representing edge coverage of the program being fuzzed.
 
-### Brontide ###
-The brontide fuzzers need to be run with a `-timeout` flag of 20 seconds or greater since there is a lot of machine state that must be printed on panic. 
-
-### Corpus ###
-Fuzzing generally works best with a corpus that is of minimal size while achieving the maximum coverage. However, `go-fuzz` automatically minimizes the corpus in-memory before fuzzing so a large corpus shouldn't make a difference - edge coverage is all that really matters.
-
-### Test Harness ###
-If you take a look at the test harnesses that are used, you will see that they all consist of one function: 
-```go
-func Fuzz(data []byte) int
-```
-If:
+## Options ##
+Several parameters can be appended to the end of the make commands to tune the build process or the way the fuzzer runs.
+- `run_time` specifies how long each fuzz harness runs for. The default is 30 seconds.
+- `timeout` specifies how long an individual testcase can run before raising an error. The default is 20 seconds.
+- `processes` specifies the number of parallel processes to use while running the harnesses.
+- `pkg` specifies the `lnd` packages to build or fuzz. The default is to build and run all available packages (`brontide lnwire wtwire zpay32`). This can be changed to build/run against individual packages.
+- `base_workdir` specifies the workspace of the fuzzer. This folder will contain the corpus, crashers, and suppressions.
 
-- `-1` is returned, the fuzzing input is ignored
-- `0` is returned, `go-fuzz` will add the input to the corpus and deprioritize it in future mutations.
-- `1` is returned, `go-fuzz` will add the input to the corpus and prioritize it in future mutations.
+## Corpus ##
+Fuzzing generally works best with a corpus that is of minimal size while achieving the maximum coverage. `go-fuzz` automatically minimizes the corpus in-memory before fuzzing so a large corpus shouldn't make a difference.
 
-### Conclusion ###
-Citizens, do your part and `go-fuzz` `lnd` today!
+## Disclosure ##
+If you find any crashers that affect LND security, please disclose with the information found [here](https://github.com/lightningnetwork/lnd/#security).