akovalenko/lnd.xprv
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
eugene 2021-06-14 16:12:09 -04:00
parent 42099ef5e1
commit 13d7e97a84
No known key found for this signature in database
GPG Key ID: 118759E83439A9B1
2 changed files with 24 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Makefile
View File

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

47
docs/fuzz.md
View File

@ -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. 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 ### ## Setup and Installation ##
This section will cover setup and installation of `go-fuzz` and fuzzing binaries. 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 ```shell
⛰ go get -u github.com/dvyukov/go-fuzz/... ⛰ make fuzz-build
```
* 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>'
``` ```
* This may take a while since this will create zip files associated with each fuzzing target. * 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 ```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: `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 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 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 `fuzz/<package>/<harness>/crashers`. `go-fuzz` also creates a `suppressions` directory
of stacktraces to ignore so that it doesn't create duplicate stacktraces. of stacktraces to ignore so that it doesn't create duplicate stacktraces.
Cover is a number representing edge coverage of the program being fuzzed. Cover is a number representing edge coverage of the program being fuzzed.
### Brontide ### ## Options ##
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. 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.
### Corpus ### ## 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. 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.
### Test Harness ### ## Disclosure ##
If you take a look at the test harnesses that are used, you will see that they all consist of one function: If you find any crashers that affect LND security, please disclose with the information found [here](https://github.com/lightningnetwork/lnd/#security).
```go
func Fuzz(data []byte) int
```
If:
- `-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.
### Conclusion ###
Citizens, do your part and `go-fuzz` `lnd` today!