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:

  ⛰  make fuzz-build

• 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:

  ⛰  make fuzz-run

go-fuzz will print out log lines every couple of seconds. Example output:

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

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.

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.

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.

Disclosure ##

If you find any crashers that affect LND security, please disclose with the information found here.