bitcoinfuzz/bitcoinfuzz
GitHub: bitcoinfuzz/bitcoinfuzz
一个针对比特币和闪电网络协议实现的差异化模糊测试框架，通过同时对比多个主流实现的输出差异来发现共识漏洞、解析错误和安全缺陷。
Stars: 69 | Forks: 54
# bitcoinfuzz
比特币实现与库的差异化模糊测试。
注意：本项目正在进行中（WIP），可能不稳定。
# 安装
## 平台支持
*bitcoinfuzz 仅在 Linux 上开发和提供支持。*
### MacOS 或 Windows 用户：
如果你使用的是 macOS 或 Windows，我们建议使用 Docker 来运行 bitcoinfuzz。这能提供最可靠的模糊测试体验以及完整的工具链支持。
## 依赖项
### llvm 工具集 (clang 和 libfuzzer)
* 为了支持某些模块中使用的编译标志 `-fsanitize=address,fuzzer -std=c++20`，最低需要 clang 版本 10.0
* 对于 ubuntu/debian，可以使用包管理器进行安装：
sudo apt install clang lld llvm-dev
* 要从源码安装，请查看 [clang_get_started](https://clang.llvm.org/get_started.html)。你必须使用以下 cmake 选项进行构建：`-DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt"`
# 运行
该模糊测试器包含大量依赖，这源于它所支持的项目数量（及其运行时/语言），因此我们提供了 docker 工作流，以减轻设置和构建项目的负担。
请参阅 [RUNNING.md](./RUNNING.md) 以更好地了解相关选项及其配置。
如果你幸运地发现了更多漏洞，请负责任地报告（请参阅项目仓库中相应的 SECURITY.md 文件）。你可以将你的模糊测试语料库与我们的[公共语料库](https://github.com/bitcoinfuzz/corpora)合并。
# 使用 AFL++ 进行模糊测试
要快速开始使用 [afl++](https://github.com/AFLplusplus/AFLplusplus) 进行模糊测试：
```
$ git clone https://github.com/AFLplusplus/AFLplusplus
$ make -C AFLplusplus/ source-only
# 要选择/使用任何其他 afl 编译器，请参阅
# 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
```
请阅读 [afl++ 文档](https://github.com/AFLplusplus/AFLplusplus) 获取更多信息。
# 构建选项
你可以通过两种方式构建模块：**手动**或**自动**。自动方法由 `auto_build.py` 脚本提供，它简化了构建和清理过程。此外，你可以使用 **Docker** 或 **Docker Compose** 来运行应用程序，而无需直接在计算机上安装依赖项。
## 自动方法：`auto_build.py`
`auto_build.py` 脚本允许你根据 `CXXFLAGS` 中定义的标志自动构建模块。它还提供了在编译前清理构建的选项。
### 如何使用：
1. **自动构建**：
- 要自动构建模块，请在 `CXXFLAGS` 中定义标志并运行脚本：
CXXFLAGS="-DLDK -DLND" ./auto_build.py
这将自动构建 `LDK` 和 `LND` 模块。
2. **自动清理**：
- 该脚本支持在构建前进行三种清理模式：
- **完全清理**：在构建选定模块前清理所有模块。
CLEAN_BUILD="FULL" CXXFLAGS="-DLDK -DLND" ./auto_build.py
- **清理**：仅清理基于 `CXXFLAGS` 将要构建的模块。
CLEAN_BUILD="CLEAN" CXXFLAGS="-DLDK -DLND" ./auto_build.py
- **选择清理**：清理 `CLEAN_BUILD` 中定义的特定模块，无论 `CXXFLAGS` 如何设置。
CLEAN_BUILD="-DLDK -DBTCD" CXXFLAGS="-DLDK -DLND" ./auto_build.py
在这种情况下，脚本将对 `LDK` 和 `BTCD` 运行 `make clean`，但仅构建 `CXXFLAGS` 中定义的模块（`LDK` 和 `LND`）。
## Docker
更多信息请参阅 [RUNNING.md](./RUNNING.md)。
## 手动方法
如果你愿意，仍然可以手动构建模块。以下是每个模块的步骤：
### Bitcoin 模块：
- 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](https://github.com/piotrnar/gocoin) 是一个用 Go 编写的完整比特币节点实现。
cd modules/gocoin
make
export CXXFLAGS="$CXXFLAGS -DGOCOIN"
**注意：** 由于 cgo 符号冲突（两者都嵌入了 Go 运行时），gocoin 不能与 btcd 在同一个构建中一起使用。
- NBitcoin
cd modules/nbitcoin
make
export CXXFLAGS="$CXXFLAGS -DNBITCOIN"
- embit
要使用 `embit` 模块运行模糊测试器，你需要安装 `embit` 库。
要安装 `embit` 库，你可以使用以下命令：
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
要使用 `py-bitcoinkernel` 模块运行模糊测试器，你需要安装 `py-bitcoinkernel` 库。
要安装 `py-bitcoinkernel` 库，你可以使用以下命令：
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"
- libwally-core
git submodule update --init --recursive external/libwally-core
cd modules/libwallycore
make
export CXXFLAGS="$CXXFLAGS -DLIBWALLY_CORE"
### Lightning 模块：
- 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 模块：
- 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"
## 最终构建与执行
模块编译完成后，你可以编译 `bitcoinfuzz` 并执行它：
```
make
FUZZ=target_name ./bitcoinfuzz
```
## 选择性模块加载
默认情况下，运行模糊测试器时会加载所有已编译的模块。你可以使用 `MODULES` 环境变量在运行时仅加载特定模块，**无需重新编译**。
### 用法
将 `MODULES` 环境变量设置为以逗号分隔的模块名称列表：
```
MODULES="BITCOIN_CORE,RUST_BITCOIN" FUZZ=target_name ./bitcoinfuzz
```
### 示例
仅加载 Bitcoin Core 和 rust-bitcoin 进行比较：
```
MODULES="BITCOIN_CORE,RUST_BITCOIN" FUZZ=bip32_master_keygen ./bitcoinfuzz
```
仅加载 Lightning 实现：
```
MODULES="LDK,LND,CLIGHTNING" FUZZ=deserialize_invoice ./bitcoinfuzz
```
加载所有已编译模块（默认行为）：
```
FUZZ=target_name ./bitcoinfuzz
```
### 注意事项
- 如果 `MODULES` 未设置或为空，则加载所有已编译模块（现有行为）
- 如果你请求的模块未编译，模糊测试器将报错并中止
- 模块名称周围的空格会被修剪（例如，`"BTCD, LND"` 有效）
### Bitcoinfuzz 发现的漏洞/不一致/不匹配
- sipa/miniscript: https://github.com/sipa/miniscript/issues/140
- rust-miniscript: https://github.com/rust-bitcoin/rust-miniscript/issues/633
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/2681
- btcd: https://github.com/btcsuite/btcd/issues/2195 (与 Bitcoin Core 的 API 不匹配)
- Bitcoin Core: https://github.com/brunoerg/bitcoinfuzz/issues/34
- rust-miniscript: https://github.com/rust-bitcoin/rust-miniscript/issues/696 (非此工具直接发现但可复现)
- rust-miniscript: https://github.com/brunoerg/bitcoinfuzz/issues/39
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/2891
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/2879
- btcd: https://github.com/btcsuite/btcd/issues/2199
- rust-bitcoin: https://github.com/brunoerg/bitcoinfuzz/issues/57
- rust-miniscript: CVE-2024-44073
- rust-miniscript: https://github.com/rust-bitcoin/rust-miniscript/issues/785
- rust-miniscript: https://github.com/rust-bitcoin/rust-miniscript/issues/788
- LND: https://github.com/lightningnetwork/lnd/issues/9591
- Embit: https://github.com/diybitcoinhardware/embit/issues/70
- btcd: https://github.com/btcsuite/btcd/issues/2351
- Core Lightning: https://github.com/ElementsProject/lightning/pull/8219
- LND: https://github.com/lightningnetwork/lnd/issues/9808
- Core Lightning: https://github.com/ElementsProject/lightning/pull/8282
- btcd: https://github.com/btcsuite/btcd/issues/2372
- bolts: https://github.com/lightning/bolts/pull/1264
- rust-lightning: https://github.com/lightningdevkit/rust-lightning/pull/3814
- LND: https://github.com/lightningnetwork/lnd/issues/9904
- LND: https://github.com/lightningnetwork/lnd/issues/9915
- Eclair: https://github.com/ACINQ/eclair/issues/3104
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/4617
- NBitcoin: https://github.com/MetacoSA/NBitcoin/issues/1278
- lightning-kmp: https://github.com/ACINQ/lightning-kmp/issues/799
- lightning-kmp: https://github.com/ACINQ/lightning-kmp/pull/801
- bitcoin-kmp: https://github.com/ACINQ/bitcoin-kmp/issues/157
- secp256k1: https://github.com/bitcoin-core/secp256k1/issues/1718
- lightning-kmp: https://github.com/ACINQ/lightning-kmp/issues/802
- rust-lightning: https://github.com/lightningdevkit/rust-lightning/pull/3998
- bolts: https://github.com/lightning/bolts/pull/1279
- rust-lightning: https://github.com/lightningdevkit/rust-lightning/pull/4018
- btcd: https://github.com/btcsuite/btcd/issues/2402
- btcd: https://github.com/btcsuite/btcd/issues/2424
- rust-lightning: https://github.com/lightningdevkit/rust-lightning/pull/4090
- btcd: https://github.com/btcsuite/btcd/issues/2431
- LND: https://github.com/lightningnetwork/lnd/pull/10249
- NBitcoin: https://github.com/MetacoSA/NBitcoin/issues/1283
- tinyminiscript: https://github.com/unldenis/tinyminiscript/issues/54
- NBitcoin: https://github.com/MetacoSA/NBitcoin/pull/1288
- bolts: https://github.com/lightning/bolts/pull/1303
- lightning-onion: https://github.com/lightningnetwork/lightning-onion/pull/74
- NBitcoin: https://github.com/MetacoSA/NBitcoin/pull/1294
- Floresta: https://github.com/bitcoinfuzz/bitcoinfuzz/issues/383 / https://github.com/getflorest/Floresta/pull/781
- gocoin: https://github.com/piotrnar/gocoin/commit/42763e1efb5f09ab563aa95a288b1dbe92b90cce
- bitcoinj: https://github.com/bitcoinj/bitcoinj/issues/4054
- libwally-core: https://github.com/ElementsProject/libwally-core/commit/a3fd0aa8ba78d37819ea3b03d22c77028e958cf5
- libwally-core: https://github.com/ElementsProject/libwally-core/commit/a1de7372913092cc664ceb98e7b96dd57fec44e7
- NBitcoin: https://github.com/MetacoSA/NBitcoin/issues/1297
- btcd: https://github.com/btcsuite/btcd/pull/2485
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/5617
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/5697
- LND: https://github.com/lightningnetwork/lnd/pull/10597
- gocoin: https://github.com/piotrnar/gocoin/commit/3234dfcf5433718a5aa521db618e40f7c89c3690
- rust-lightning: https://github.com/lightningdevkit/rust-lightning/issues/4442
- rust-bitcoin: https://github.com/rust-bitcoin/rust-bitcoin/issues/5730
标签：AFL++, ASN解析, C++20, Clang, Docker, JS文件枚举, LibFuzzer, pocsuite3, WIP, 代码覆盖率, 共识逻辑, 加密货币, 区块链安全, 协议实现, 去中心化, 可视化界面, 多人体追踪, 安全防御评估, 差分测试, 日志审计, 比特币, 请求拦截, 软件测试, 逆向工具