This tool provide an easy way to fuzz eth2 clients using Docker files.
Generated samples/inputs during fuzzing can than be reused as unit tests or testcases for differential fuzzers (
Clone this repository:
$ git clone https://github.com/sigp/beacon-fuzz
Change your current directory to
$ cd beacon-fuzz/eth2fuzz
Make sure the Docker service is running on your machine (we assume that Docker has been setup on your machine. Please refer to the great official instructions, see for example this guide for Ubuntu). For Arch Linux users:
$ sudo systemctl start docker.service
NOTE: docker commands require elevated permissions by default.
If you see an error like
Got permission denied while trying to connect to the Docker daemon socket ..., you likely need to use
You can run all fuzzing targets for 1 hour each with:
$ sudo make fuzz-all
(This will take roughly 7 hours per client)
Similarly, to run all the fuzzers for a single client, for 1 hour each:
# make fuzz-lighthouse # make fuzz-nimbus # make fuzz-prysm # make fuzz-teku # make fuzz-lodestar
Build the fuzzing docker image (without running it) for any given eth2 client:
# make lighthouse # make nimbus # make prysm # make teku # make lodestar
make help for all options.
Interacting with the docker images directly:
Run the docker. You will need to provide the
workspace folder as shared volume):
# docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_lighthouse # docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_nimbus # docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_prysm # docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_lodestar # docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_teku
At this point you will now interact with
eth2fuzz over docker:
# docker run -it -v `pwd`/workspace:/eth2fuzz/workspace eth2fuzz_lighthouse help
Rebuilding after getting updates:
Get the latest code changes:
$ git pull
Build fresh docker image (without caching):
$ sudo make CACHE=--no-cache nimbus
Run your relevant fuzzer:
$ sudo make fuzz-nimbus
List available targets
Current target available can be listed with:
$ ./eth2fuzz list-targets lighthouse_attestation lighthouse_attester_slashing lighthouse_block lighthouse_block_header lighthouse_deposit lighthouse_proposer_slashing lighthouse_voluntary_exit lighthouse_beaconstate
Run one target:
./eth2fuzz target lighthouse_attestation.
Run one target with specific fuzzing engines:
$ # --fuzzer <fuzzer> Which fuzzer to run [default: Honggfuzz] [possible values: Afl, Honggfuzz, Libfuzzer] $ ./eth2fuzz target lighthouse_attestation --fuzzer libfuzzer`.
eth2fuzz can be configured to continuously fuzz all available targets for a given client, using the
continuously CLI parameter. Execution will stop after 30 minutes per target if the
--infinite flag is not provided (the timeout can also be changed, using the
--timeout flag). Make sure to use the
-q flag to select the client you've built your fuzzer for.
$ ./eth2fuzz continuously --help Run all fuzz targets USAGE: eth2fuzz continuously [FLAGS] [OPTIONS] FLAGS: --cargo-update -h, --help Prints help information -i, --infinite -V, --version Prints version information OPTIONS: -q, --filter <filter> Only run target containing this string --fuzzer <fuzzer> Which fuzzer to run [default: Honggfuzz] [possible values: Afl, Honggfuzz, Libfuzzer] -n, --thread <thread> Set number of thread (only for hfuzz) -t, --timeout <timeout> Set timeout per target [default: 10]
Example command for lighthouse:
$ ./eth2fuzz continuously -i -q attestation -t 600 $ # options: $ # -i => infinite mode $ # -q => will run lighthouse_attestation target $ # -t => timeout of 10 min, will restart the fuzzer every 10 min
Join our "fuzzing" channel on Discord to report any bugs you've found, or if you're running into any issues using these fuzzers.