highperfocused/lnd
1
0
Fork 0
mirror of https://github.com/lightningnetwork/lnd.git synced 2025-08-28 14:40:51 +02:00
Code Issues Packages Projects Releases Wiki Activity

make+scripts+docs: update fuzzing script and make fuzz

Browse Source
This commit is contained in:
Conner
2022-08-21 20:28:12 -04:00
committed by Matt Morehouse
parent 404e18afab
commit 25a7bb8b86
4 changed files with 39 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/fuzz.md
View File

@@ -1,43 +1,40 @@
# Fuzzing LND #
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 the fuzzing binaries.
* The following is a command to build all fuzzing harnesses:
The following runs all fuzz tests on default settings:
```shell
$ make fuzz-build
$ make fuzz
```
* This may take a while since this will create zip files associated with each fuzzing target.
* The following is a command to run all fuzzing harnesses for 30 seconds:
The following runs all fuzz tests inside the lnwire package, each for a total of 1 minute, using 4 procs.
It is recommended that processes be set to the number of processor cores in the system:
```shell
$ make fuzz-run
$ make fuzz pkg=lnwire fuzztime=1m parallel=4
```
Alternatively, individual fuzz tests can be ran manually by setting the working directory to the location of the .go file holding the fuzz tests.
The go test command can only test one fuzz test at a time:
```shell
$ cd lnwire
$ go test -fuzz=FuzzAcceptChannel -fuzztime=1m -parallel=4
```
The following can be used to show all fuzz tests in the working directory:
```shell
$ cd lnwire
$ go test -list=Fuzz.*
```
`go-fuzz` will print out log lines every couple of seconds. Example output:
```text
2017/09/19 17:44:23 workers: 8, corpus: 23 (3s ago), crashers: 1, restarts: 1/748, execs: 400690 (16694/sec), cover: 394, uptime: 24s
Fuzz tests can be ran as normal tests, which only runs the seed corpus:
```shell
$ cd lnwire
$ go test -run=FuzzAcceptChannel -parallel=4
```
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 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.
The generated corpus values can be found in the $(go env GOCACHE)/fuzz directory.
## 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.
- `fuzztime` specifies how long each fuzz test runs for, corresponding to the `go test -fuzztime` option. The default is 30s.
- `parallel` specifies the number of parallel processes to use while running the harnesses, corresponding to the `go test -parallel` option.
- `pkg` specifies the `lnd` packages to build or fuzz. The default is to build and run all available packages (`brontide lnwire watchtower/wtwire zpay32`). This can be changed to build/run against individual packages.
## 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.
Fuzzing generally works best with a corpus that is of minimal size while achieving the maximum coverage.
## Disclosure ##
If you find any crashers that affect LND security, please disclose with the information found [here](https://github.com/lightningnetwork/lnd/#security).