8000 GitHub - erickcestari/lightningfuzz: Differential Fuzzing of Bitcoin protocol implementations and libraries
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

erickcestari/lightningfuzz

BranchesTags
 
 

Repository files navigation

bitcoinfuzz

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

Installation

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 macOS the llvm tools are installed by default, just check that you have the minimum required version 10.0

    • If not installed or lesser than 10.0 just run:

      brew install llvm

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

Build Options

You can build the modules in two ways: manual or automatic. The automatic method is provided by the auto_build.sh 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.sh

The auto_build.sh 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.sh
      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.sh
      • Clean: Cleans only the modules that will be built based on CXXFLAGS. 
        CLEAN_BUILD="CLEAN" CXXFLAGS="-DLDK -DLND" ./auto_build.sh
      • Select Clean: Cleans specific modules defined in CLEAN_BUILD, regardless of CXXFLAGS. 
        CLEAN_BUILD="-DLDK -DBTCD" CXXFLAGS="-DLDK -DLND" ./auto_build.sh
        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 Method

If you prefer not to install dependencies directly on your machine, you can use Docker to run the application. This method simplifies deployment and ensures a consistent environment.

Using the Dockerfile

  1. Build the Docker Image:

    • Build the Docker image using the provided docker: 
      docker build -t bitcoinfuzz .

  2. Run the Container:

    • Run the container with the required FUZZ and CXXFLAGS environment variables: 
      docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." bitcoinfuzz

  3. Optional Parameters:

    • You can also pass optional parameters:
      • FUZZ_RUNS: Specify the number of fuzzing runs (e.g., 50): 
        docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -e FUZZ_RUNS=50 bitcoinfuzz
      • FUZZ_INPUT: Provide a specific corpus or crash file to test: 
        docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -e FUZZ_INPUT=/path/to/input bitcoinfuzz

  4. Accessing Generated Corpus:

    • The generated corpus is saved in /app/data inside the container. To access it, you can mount a volume: 
      docker run -e FUZZ=target_name -e CXXFLAGS="-DLDK -DLND ..." -v $(pwd)/corpus:/app/data bitcoinfuzz

Using Docker Compose

The docker-compose.yml file simplifies running multiple fuzzing scenarios. Each scenario is preconfigured with the required modules and environment variables.

  1. Run All Scenarios:

    • To run all scenarios, simply execute: 
      docker-compose up

  2. Run a Specific Scenario:

    • To run a specific scenario (e.g., script), use: 
      docker-compose up script

  3. Optional Parameters:

    • You can pass optional parameters like FUZZ_RUNS or FUZZ_INPUT:
      • Run with a specific number of fuzzing runs: 
        FUZZ_RUNS=50 docker-compose up script
      • Run with a specific input file: 
        FUZZ_INPUT=/path/to/input docker-compose up script

  4. Accessing Generated Corpus:

    • The generated corpus for each scenario is saved in the docker directory at the same level as the docker-compose.yml file. Each scenario has its own subdirectory: 
      docker/
├── script/
├── deserialize_block/
├── script_eval/
├── deserialize_offer/
├── descriptor_parse/
├── miniscript_parse/
├── script_asm/
├── deserialize_invoice/
├── address_parse/
├── addrv2/
└── psbt_parse/
    • To ensure the corpus is saved locally, the docker-compose.yml file maps the /app/data directory inside the container to the corresponding subdirectory in docker.

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 cargo && make
export CXXFLAGS="$CXXFLAGS -DRUST_BITCOIN"

  • rust-miniscript

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

  • btcd

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

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

  • Bitcoin Core

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

Lightning modules:

  • LDK

    cd modules/ldk
make cargo && 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"

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

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • C++ 48.7%
  • C 46.6%
  • Sage 1.0%
  • CMake 0.8%
  • Assembly 0.7%
  • M4 0.5%
  • Other 1.7%
0