/beacon-fuzz

Differential Fuzzer for Ethereum 2.0

Primary LanguageRustMIT LicenseMIT

beacon-fuzz - archive

⚠️ This repository is now deprecated and will be archived (the beacon-fuzz project is still being actively maintained in a private repository, due to the sensitive nature of the work and its potential impact on a live beacon chain) ⚠️

See discord explanation for more info.

Open-source fuzzing framework for Ethereum 2.0 (Eth2) Phase0 implementations. Maintained by Sigma Prime for the Ethereum Foundation.

Eth2fuzz Eth2diff

Community Fuzzing

For details on our community fuzzing initiative, please refer to the eth2fuzz README, along with this blog post.

If you would like to raise any crashes or disclose any bugs identified using this project, please contact us via email and use our PGP key to encrypt sensitive messages.

Overview

This project aims at identifying bugs and vulnerabilities on various Eth2 implementations, by leveraging three different fuzzing tools.

This is a continuation of Guido Vranken's eth2.0-fuzzing. This project and its inner workings are subject to change.

A note on terminology: "client" and "implementation" are used interchangeably here to mean a specific Eth2 implementation.

Architecture overview

The following diagram describes the current architecture of beacon-fuzz:

eth2fuzz - Coverage Guided Fuzzer

The purpose of this tool is to identify crashes (i.e. panics) in Eth2 implementations. It uses multiple different fuzzing engines (AFL++, HonggFuzz, libFuzzer, etc.). By leveraging explicit code coverage, eth2fuzz allows us to flag SSZ containers that are of interest, i.e. those that trigger new code paths.

eth2diff - Replaying Samples Across Implementations

This tool leverages various state transition execution utilities (ncli, zcli, lci, etc.) that replay all samples generated from eth2fuzz. We've created dedicated Docker containers for each implementation, and one central Docker container to orchestrate the execution of eth2diff. The goal of this tool is to detect crashes and differences across all supported implementations, for any given set of inputs (BeaconState + BeaconBlock).

beaconfuzz_v2 - Differential Fuzzing with FFI Bindings

A differential fuzzer of Eth2.0 implementations using libfuzzer and honggfuzz.

This tool is the successor of Guido Vranken's eth2.0-fuzzing C++ project. It is developed in Rust (for ease of maintainability) and leverages Foreign Function Interfaces (FFI) bindings.

By leveraging the latest update to the libfuzzer-sys and cargo_fuzz crates, this tool is able to write fuzz targets that take well-formed instances of custom types by deriving and implementing the Arbitrary trait, which allows us to create structured inputs from raw byte buffers.

Implementations

Operational Fuzz Targets

This project currently focuses on core state transition functions. All fuzzing targets currently use the "mainnet" config.

Corpora

See corpora for examples and explanation of structure.

Usage

Please refer to each tool's README for detailed instructions:

Progress and Roadmap

  • Development of eth2fuzz
  • Development of eth2diff
  • Development of beaconfuzz_v2
    • Integration of Prysm
    • Integration of Lighthouse
    • Integration of Nimbus
    • Integration of Teku
  • Improved onboarding, ease of adding new targets and implementations
  • Improved coverage measurements and visibility
  • Structure-aware fuzzing mutations in beaconfuzz_v2
  • Deploy on dedicated production fuzzing infrastructure

The Beacon Fuzz team regularly posts updates on the Sigma Prime blog. The latest update is available here.

Contributing

Use pre-commit

$ pre-commit install

(see also .pre-commit-config.yaml)

Trophies

The fuzzing tools developed as part of this project (eth2fuzz, eth2diff and beaconfuzz_v2) helped identify the following bugs inside eth2 clients.

Nimbus

Trinity

Teku

Lighthouse

Lodestar

Prysm

BLS

1: NOTE BeaconState objects are considered trusted inputs (for the moment), so client state transition functions are not expected to handle invalid BeaconState values, for now.

License

MIT - see LICENSE