Recon-Fuzz/recon-fuzzer
GitHub: Recon-Fuzz/recon-fuzzer
一个基于 Rust 的高性能智能合约模糊测试器，利用覆盖引导与并行化加速漏洞发现。
Stars: 6 | Forks: 0
# Recon Fuzzer
一个用于 Foundry 项目的高性能智能合约模糊测试器，使用 Rust 编写。灵感来自 Echidna，支持基于覆盖的变异、自动收缩和并行工作线程。
## 功能特性
- **快速并行** — 多线程模糊测试，可配置工作线程数量
- **多种测试模式** — 属性测试、断言测试、优化测试、探索测试
- **基于覆盖** — 按指令或按分支跟踪覆盖率
- **与 ABI 感知的变异** — 基于合约 ABI 的智能语料库驱动变异
- **自动收缩** — 最小化失败序列以生成可重复的报告
- **分叉模式** — 通过 RPC 运行于实时链状态
- **与 Echidna 兼容的语料库** — 可在 Recon 与 Echidna 之间共享 `echidna.yaml` 和语料库
## 安装
### 通过 reconup（推荐）
[`reconup`](https://github.com/Recon-Fuzz/reconup) 是官方安装器和更新器。使用以下命令安装一次：
```
curl -L https://raw.githubusercontent.com/Recon-Fuzz/reconup/refs/heads/main/install | bash
```
然后重启你的 Shell（或执行 `source ~/.zshrc` / `source ~/.bashrc`）并安装 `recon`：
```
reconup
```
**更新** — 再次运行 `reconup`。仅在有更新版本时下载。
**支持平台** — Linux x86_64、macOS ARM64（Apple Silicon）、macOS x86_64（Intel）、Windows x86_64。在 Windows 上，请从 Git Bash 或 WSL 运行 `reconup`。
**安装位置** — `~/.recon/bin/recon`。
**卸载** — 执行 `rm -rf ~/.recon`，然后从你的 Shell 配置文件中移除 PATH 导出。
### 预编译二进制文件（手动）
如果你想跳过 `reconup`，可以直接从 [发布页面](https://github.com/Recon-Fuzz/recon-fuzzer/releases) 下载：
```
# Linux x86_64
wget https://github.com/Recon-Fuzz/recon-fuzzer/releases/latest/download/recon-linux-x86_64.tar.gz
tar -xzf recon-linux-x86_64.tar.gz && sudo mv recon /usr/local/bin/
# macOS Apple Silicon
wget https://github.com/Recon-Fuzz/recon-fuzzer/releases/latest/download/recon-macos-aarch64.tar.gz
tar -xzf recon-macos-aarch64.tar.gz && sudo mv recon /usr/local/bin/
```
### 从源码构建
需要 Rust 1.70+。
```
git clone https://github.com/Recon-Fuzz/recon-fuzzer.git
cd recon-fuzzer
cargo build --release
# binary at target/release/recon
```
## 快速开始
```
recon fuzz /path/to/foundry/project
recon fuzz . --contract MyContract --workers 8 --test-limit 100000
```
## 命令
CLI 只有一个子命令：`fuzz`。其他所有操作均通过标志完成。
```
recon fuzz [OPTIONS]
```
### ``
指向一个 Foundry 项目（包含 `foundry.toml` 的目录）。Recon 会使用 `forge build` 编译该项目并选择一个目标合约。
### 常用选项
| 标志 | 描述 |
|---|---|
| `-c, --contract ` | 要模糊测试的合约（默认为第一个） |
| `--config ` | YAML 配置文件（CLI 标志优先） |
| `-w, --workers ` | 并行工作线程数 |
| `--test-limit ` | 所有工作线程的总测试迭代次数（默认：50000） |
| `--seq-len ` | 每个序列的调用次数（默认：100） |
| `--seed ` | 确定性随机种子 |
| `--timeout ` | 墙钟超时时间 |
| `--stop-on-fail` | 遇到第一个失败即退出 |
| `-q, --quiet` | 降低日志输出级别 |
### 测试模式
```
--test-mode property # functions prefixed with echidna_ returning bool
--test-mode assertion # detect assert() failures
--test-mode optimization # maximize int return value of echidna_opt_* functions
--test-mode exploration # coverage-only, no assertions
```
以下为示例。
### 地址与发送者
```
--contract-addr <0x...> # deployment address (default 0x00a329c0648769a73afac7f9381e08fb43dbea72)
--deployer <0x...> # deployer address (default 0x30000)
--sender <0x...> # sender to cycle through (repeatable)
--all-contracts # generate calls to every deployed contract, not just the target
--mutable-only # skip pure/view functions
```
### 分叉模式
```
--rpc-url
--rpc-block
```
### 覆盖率与性能
| 标志 | 描述 |
|---|---|
| `--coverage-mode full\|branch` | `full` 跟踪每条指令，`branch` 仅跟踪 JUMPI/JUMPDEST（更快） |
| `--fast` | 等价于 `--coverage-mode branch` |
| `--lcov` | 在运行期间输出 LCOV 覆盖率报告 |
### 语料库管理
| 标志 | 描述 |
|---|---|
| `--corpus-dir ` | 语料库目录（与 Echidna 格式兼容） |
| `--recon-corpus-dir ` | Recon 原生语料库目录（详见下文） |
| `--shrink` | 跳过模糊测试；仅对语料库中已有的重现器进行收缩 |
| `--replay ` | 重放某个重现器文件并打印跟踪 |
| `--convert` | 将 Recon 语料库转换为 Echidna 格式并退出 |
### 其他选项
| 标志 | 描述 |
|---|---|
| `--format text\|json\|none` | 最终报告的输出格式 |
| `--shortcuts` | 启动时运行 `shortcut_*` 函数以引导语料库 |
| `--shrink-limit ` | 每个失败测试的收缩尝试次数（默认：5000） |
## Web UI（实验性）
Recon 附带一个可选的浏览器 UI，可用于实时监控运行中的活动。运行 `recon fuzz` 时加上 `--web` 标志即可：
```
recon fuzz . --web
```
## 配置文件
Recon 支持 Echidna 风格的 `echidna.yaml`。CLI 标志会覆盖文件中的值。
```
testMode: property
prefix: echidna_
corpusDir: corpus
testLimit: 50000
shrinkLimit: 5000
seqLen: 100
workers: 4
timeout: 86400
stopOnFail: false
contractAddr: "0x00a329c0648769a73afac7f9381e08fb43dbea72"
deployer: "0x30000"
sender:
- "0x10000"
- "0x20000"
- "0x30000"
rpcUrl: "https://eth-mainnet.alchemyapi.io/v2/..."
rpcBlock: 18000000
allContracts: false
mutableOnly: false
lcovEnable: false
coverageMode: full
shortcutsEnable: false
```
```
recon fuzz . --config echidna.yaml
```
## 测试模式示例
### 属性测试
```
contract Vault {
uint256 public balance;
function echidna_balance_never_negative() public view returns (bool) {
return balance >= 0;
}
}
```
```
recon fuzz . --test-mode property --contract Vault
```
### 断言测试
```
function transfer(uint256 amount) public {
assert(amount <= balance);
balance -= amount;
}
```
```
recon fuzz . --test-mode assertion --contract Vault
```
### 优化测试
```
function echidna_opt_balance() public view returns (int256) {
return int256(balance);
}
```
```
recon fuzz . --test-mode optimization --contract Vault
```
### 探索测试
纯覆盖率探索，不执行属性检查：
```
recon fuzz . --test-mode exploration
```
## 与 Echidna 共享语料库
Recon 可以与 Echidna 语料库互操作，从而无需重新生成输入即可在两者之间切换使用。
### Recon ↔ Echidna 布局
Echidna 在 `corpusDir` 下读写明文重现器。Recon 的原生格式更丰富（包含优先级、延迟对和选择器映射）。为保持兼容：
```
project/
├── echidna.yaml # shared config (corpusDir: corpus/)
├── corpus/ # Echidna-format corpus (shared)
└── corpus-recon/ # Recon-native corpus
```
### 同时使用两个语料库（推荐）
将 Recon 指向其自己的目录（通过 `--recon-corpus-dir`）。它使用原生格式进行模糊测试，并**自动导出**每个新条目到 `--corpus-dir`（或配置中的 `corpusDir:`）的 Echidna 格式：
```
recon fuzz . \
--config echidna.yaml \
--recon-corpus-dir corpus-recon
```
随后运行 Echidna，它会从 `corpus/` 中读取已导出的条目。
### 一次性转换
若想在不进行模糊测试的情况下将现有 Recon 语料库转换为 Echidna 格式，请添加 `--convert`：
```
recon fuzz . \
--config echidna.yaml \
--recon-corpus-dir corpus-recon \
--convert
```
Recon 导出完成后退出。Echidna 格式的文件会输出到 `corpus/`（或解析为 `corpusDir` 的路径）。
### 在 Recon 中使用 Echidna 语料库
将 `--corpus-dir`（或配置中的 `corpusDir:`）指向已有的 Echidna 语料库目录，无需指定 `--recon-corpus-dir`。Recon 会直接读取 Echidna 格式的重现器。
```
recon fuzz . --corpus-dir ./echidna/corpus
```
## 重放与收缩
```
# Replay a saved reproducer and dump the trace
recon fuzz . --replay corpus/reproducers/failure_001.txt
# Re-shrink every reproducer in the corpus without running the fuzzer
recon fuzz . --corpus-dir corpus --shrink
```
## 故障排查
**"Contract not found"** — 请确保先成功运行 `forge build`。
**"Failed to compile project"** — Recon 期望标准的 Foundry 项目结构，包含 `foundry.toml`。
**Slow iterations** — 尝试使用 `--fast`（仅分支覆盖）、降低 `--seq-len` 或提高 `--workers`。
## 浏览器模糊测试（WebAssembly）
`browser-fuzzer/` 是一个实验性的 WebAssembly 构建版本，完全在浏览器中运行模糊测试器——无需服务器或后端。它与 CLI 共享核心引擎。构建需要 **Rust nightly**（使用了 `#![feature(thread_local)]` 实现多线程共享内存）。
```
cd browser-fuzzer
cargo +nightly build --target wasm32-unknown-unknown --release
```
## 许可证
GPL-2.0。详见 [LICENSE](LICENSE)。
## 感谢
本项目还基于以下项目构建：
- [revm](https://github.com/bluealloy/revm) — EVM 执行
- [alloy](https://github.com/alloy-rs/alloy) — 以太坊基础组件
[Foundry](https://github.com/foundry-rs/foundry) — 项目编译
## 免责声明
本代码库的大部分内容是在 AI 编码工具（“氛围编码”）的协助下完成的。维护者已经审查并测试了代码，但无法保证所有路径的正确性、完整性和安全性。**请自行承担风险使用**。不提供任何形式的担保；详细信息请参见 [LICENSE](LICENSE)。不要将 Recon 作为审计生产合约的唯一防线；始终结合独立审查、成熟工具和人类判断。
## 支持
- 问题反馈：https://github.com/Recon-Fuzz/recon-fuzzer/issues
- Discord：https://getrecon.xyz/discord
标签：ABI感知模糊测试, AI工具, Echidna兼容, Foundry, Recon Fuzz, ReconFuzz, RPC分叉测试, Rust, 优化测试, 分支覆盖, 可视化界面, 合约安全测试, 命令行模糊测试, 多线程模糊测试, 实时链测试, 属性测试, 并行模糊测试, 开源模糊测试, 探索性测试, 断言测试, 智能合约安全, 智能合约模糊测试, 模糊测试器, 网络流量审计, 自动收缩, 覆盖引导测试, 覆盖率引导模糊测试, 语料库模糊测试, 通知系统