E5CC GitHub - bitcoinfuzz/bitcoinfuzz: Differential Fuzzing of Bitcoin protocol implementations and libraries
[go: up one dir, main page]
Skip to content

bitcoinfuzz/bitcoinfuzz

BranchesTags

Repository files navigation

bitcoinfuzz

Differential Fuzzing of Bitcoin implementations and libraries. Note this project is a WIP and might be not stable.

Installation

Platform Support

bitcoinfuzz is developed and supported on Linux only.

MacOS or Windows Users:

We recommend using Docker to run bitcoinfuzz if you're on macOS or Windows. This provides the most reliable fuzzing experience with full toolchain support.

Dependencies

llvm toolset (clang and libfuzzer)

  • To support the flags used in some modules -fsanitize=address,fuzzer -std=c++20 the minimum clang version required is 10.0

  • For ubuntu/debian it can be installed using the package manager:

    sudo apt install clang lld llvm-dev

  • To install it from source check clang_get_started. You must build it with this cmake option: -DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt"

Running

The fuzzer has a lot of dependencies from the number of projects (and their runtime/lang) it supports and for that reason we provide a docker workflow to ease the burden of setting up and building the project.

See RUNNING.md to understand better the options and their configurations.

If you ended up luckily finding more bugs report them responsibly (see the respective SECURITY.md file on the project repo). You can merge your fuzzing corpus with our public corpora.

Fuzzing with AFL++

To quickly get started fuzzing using afl++:

$ git clone https://github.com/AFLplusplus/AFLplusplus
$ make -C AFLplusplus/ source-only
# To choose/use any other afl compiler, see
# https://github.com/AFLplusplus/AFLplusplus/blob/stable/docs/fuzzing_in_depth.md#a-selecting-the-best-afl-compiler-for-instrumenting-the-target
$ CC="AFLplusplus/afl-clang-fast" CXX="AFLplusplus/afl-clang-fast++" make
$ mkdir -p inputs/ outputs/
$ echo A > inputs/thin-air-input
$ FUZZ=addrv2 ./AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- ./bitcoinfuzz

Read the afl++ documentation for more information.

Build Options

You can build the modules in two ways: manual or automatic. The automatic method is provided by the auto_build.py script, which simplifies the build and clean processes. Additionally, you can use Docker or Docker Compose to run the application without installing dependencies directly on your machine.

Automatic Method: auto_build.py

The auto_build.py script allows you to automatically build the modules based on the flags defined in CXXFLAGS. It also provides options to clean the builds before compiling.

How to use:

  1. Automatic Build:

    • To automatically build the modules, define the flags in CXXFLAGS and run the script: 
      CXXFLAGS="-DLDK -DLND" ./auto_build.py
      This will automatically build the LDK and LND modules.

  2. Automatic Clean:

    • The script supports three cleaning modes before building:
      • Full Clean: Cleans all modules before building the selected ones. 
        CLEAN_BUILD="FULL" CXXFLAGS="-DLDK -DLND" ./auto_build.py
      • Clean: Cleans only the modules that will be built based on CXXFLAGS. 
        CLEAN_BUILD="CLEAN" CXXFLAGS="-DLDK -DLND" ./auto_build.py
      • Select Clean: Cleans specific modules defined in CLEAN_BUILD, regardless of CXXFLAGS. 
        CLEAN_BUILD="-DLDK -DBTCD" CXXFLAGS="-DLDK -DLND" ./auto_build.py
        In this case, the script will run make clean for LDK and BTCD, but will only build the modules defined in CXXFLAGS (LDK and LND).

Docker

See RUNNING.md for more information.

Manual Method

If you prefer, you can still build the modules manually. Below are the steps for each module:

Bitcoin modules:

  • rust-bitcoin

    cd modules/rustbitcoin
make
export CXXFLAGS="$CXXFLAGS -DRUST_BITCOIN"

  • tinyminiscript

    cd modules/tinyminiscript
make
export CXXFLAGS="$CXXFLAGS -DTINY_MINISCRIPT"

  • rust-miniscript

    cd modules/rustminiscript
make
export CXXFLAGS="$CXXFLAGS -DRUST_MINISCRIPT"

  • btcd

    cd modules/btcd
make
export CXXFLAGS="$CXXFLAGS -DBTCD"

  • gocoin

    gocoin is a full Bitcoin node implementation written in Go.

    cd modules/gocoin
make
export CXXFLAGS="$CXXFLAGS -DGOCOIN"

    Note: gocoin cannot be used together with btcd in the same build due to cgo symbol conflicts (both embed the Go runtime).

  • NBitcoin

    cd modules/nbitcoin
make
export CXXFLAGS="$CXXFLAGS -DNBITCOIN"

  • embit

    To run the fuzzer with embit module, you need to install the embit library.

    To install the embit library, you can use the following command:

    cd modules/embit
pip install -r ./requirements.txt
    cd modules/embit
make
export CXXFLAGS="$CXXFLAGS -DEMBIT"

  • rust-bitcoinkernel

    cd modules/rustbitcoinkernel
make
export CXXFLAGS="$CXXFLAGS -DRUSTBITCOINKERNEL"

  • py-bitcoinkernel

    To run the fuzzer with py-bitcoinkernel module, you need to install the py-bitcoinkernel library.

    To install the py-bitcoinkernel library, you can use the following command:

    cd modules/pybitcoinkernel
pip install -r ./requirements.txt
    cd modules/pybitcoinkernel
make
export CXXFLAGS="$CXXFLAGS -DPYBITCOINKERNEL"

  • Bitcoin Core

    cd modules/bitcoin
make
export CXXFLAGS="$CXXFLAGS -DBITCOIN_CORE"

  • bitcoinj

    cd modules/bitcoinj
make
export CXXFLAGS="$CXXFLAGS -DBITCOINJ"

Lightning modules:

  • LDK

    cd modules/ldk
make
export CXXFLAGS="$CXXFLAGS -DLDK"

  • LND

    cd modules/lnd
make
export CXXFLAGS="$CXXFLAGS -DLND"

  • NLightning

    cd modules/nlightning
make
export CXXFLAGS="$CXXFLAGS -DNLIGHTNING"

  • C-lightning

    pip install mako
git submodule update --init --recursive external/lightning
cd modules/clightning
make
export CXXFLAGS="$CXXFLAGS -DCLIGHTNING"

  • Eclair

    git submodule update --init --recursive external/eclair
cd modules/eclair
make
export CXXFLAGS="$CXXFLAGS -DECLAIR"

  • lightning-kmp

    cd modules/lightningkmp
make
export CXXFLAGS="$CXXFLAGS -DLIGHTNING_KMP"

Secp256k1 modules:

  • Decred-Secp256k1

    cd modules/decredsecp256k1
make
export CXXFLAGS="$CXXFLAGS -DDECRED_SECP256K1"

  • Libsecp256k1

    git submodule update --init --recursive external/secp256k1
cd modules/secp256k1
make
export CXXFLAGS="$CXXFLAGS -DSECP256K1"

  • NBitcoin-Secp256k1

    cd modules/nbitcoinsecp256k1
make
export CXXFLAGS="$CXXFLAGS -DNBITCOIN_SECP256K1"

  • K256

    cd modules/rustk256
make
export CXXFLAGS="$CXXFLAGS -DRUST_K256"

Final Build and Execution

Once the modules are compiled, you can compile bitcoinfuzz an execute it:

  • Automatic Method:

    FUZZ=target_name ./bitcoinfuzz

  • Manual Method:

    make
FUZZ=target_name ./bitcoinfuzz

Bugs/inconsistences/mismatches found by Bitcoinfuzz

About

Differential Fuzzing of Bitcoin protocol implementations and libraries

Topics

bitcoin fuzzing

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

68 stars

Watchers

9 watching

Forks

53 forks
Report repository

Releases

No releases published

Contributors 22
+ 8 contributors

Languages
0