新发布Jul 27, 2026
echidna v2.3.3
以太坊智能合约模糊测试器
Echidna: 快速智能合约模糊测试工具 
Echidna 是一种奇怪的生物，以吃虫子为生，并且对电高度敏感（致歉 Jacob Stanley）
更严肃地说，Echidna 是一个 Haskell 程序，专为以太坊智能合约的模糊测试/基于属性的测试而设计。它利用基于合约 ABI 的复杂语法引导模糊测试活动，以证伪用户定义的谓词或 Solidity 断言。我们在设计 Echidna 时充分考虑了模块化，因此可以轻松扩展以包含新的变异方式或在特定情况下测试特定合约。
功能特性
- 生成针对实际代码定制的输入
- 可选的语料库收集、变异和覆盖率指导，以发现更深层次的漏洞
- 由 Slither 驱动，在模糊测试活动前提取有用信息
- 源代码集成，用于识别模糊测试活动后覆盖了哪些行
- 交互式终端界面、纯文本或 JSON 输出
- 自动测试用例最小化，以便快速分类
- 无缝集成到开发工作流程中
.. 还有一个精美的高分辨率手工制作徽标。
使用方法
执行测试运行器
Echidna 的核心功能是一个名为 echidna 的可执行文件，它以一个合约和一个不变量列表（应始终为真的属性）作为输入。对于每个不变量，它会生成随机的合约调用序列，并检查该不变量是否成立。如果它能找到某种方式证伪该不变量，则会打印出导致证伪的调用序列。如果找不到，那么您对合约的安全性就有了一定的把握。
编写不变量
不变量通过名称以 echidna_ 开头、无参数并返回布尔值的 Solidity 函数来表达。例如，如果您有一个 balance 变量，它永远不应低于 20，您可以在合约中编写一个额外的函数，如下所示：```solidity
function echidna_check_balance() public returns (bool) {
return(balance >= 20);
}
要检查这些不变量，请运行：```sh
$ echidna myContract.sol
可以找到带有测试的示例合约tests/solidity/basic/flags.sol。要运行它，你应该执行：```sh $ echidna tests/solidity/basic/flags.sol
Echidna 应该能够找到一个调用序列使得 `echidna_sometimesfalse` 返回假，并且应该无法找到使 `echidna_alwaystrue` 返回假的输入。
### 测试模式
上面的例子使用了默认的 **property** 模式，但 Echidna 支持多种测试模式，可以通过配置文件中的 `testMode` 或 CLI 中的 `--test-mode` 进行配置：
* **`property`**（默认）：测试以 `echidna_` 为前缀且返回 `bool` 类型的函数。
* **`assertion`**：检测 `assert()` 和 Foundry 的 `assertX` 辅助函数（如 `assertTrue`、`assertEq` 等）触发的断言失败。
* **`foundry`**：运行 Foundry 风格的以 `test` 为前缀的单元测试和以 `invariant_` 为前缀的状态不变式。
* **`overflow`**：检测整数上溢/下溢（Solidity >= 0.8.0）。
* **`optimization`**：最大化以 `echidna_` 为前缀且返回 `int256` 类型的函数的返回值（使用与 property 模式相同的可配置前缀）。
* **`exploration`**：收集覆盖率而不检查属性。
### 收集和可视化覆盖率
完成一次测试活动后，Echidna 可以将覆盖率最大化的 **语料库** 保存到通过 `corpusDir` 配置选项指定的专用目录中。该目录将包含两个条目：（1）一个名为 `coverage` 的目录，其中包含可由 Echidna 重放的 JSON 文件；（2）一个名为 `covered.txt` 的纯文本文件，该文件是带有覆盖率注释的源代码副本。
如果你运行 `tests/solidity/basic/flags.sol` 示例，Echidna 会将一些序列化的事务文件保存到 `coverage` 目录中，并生成一个包含以下内容的 `covered.$(date +%s).txt` 文件：```text
*r | function set0(int val) public returns (bool){
* | if (val % 100 == 0)
* | flag0 = false;
}
*r | function set1(int val) public returns (bool){
* | if (val % 10 == 0 && !flag0)
* | flag1 = false;
}
我们的工具用以下"行标记"来标记语料库中的每条执行轨迹：
*- 如果执行以STOP结束r- 如果执行以REVERT结束o- 如果执行因gas耗尽而结束e- 如果执行因其他错误而结束（除零、断言失败等）
对智能合约构建系统的支持
Echidna可以测试使用不同智能合约构建系统编译的合约，包括Foundry、Hardhat和Truffle，借助crytic-compile。要使用当前编译框架调用Echidna，请运行echidna .。
此外，Echidna支持两种测试复杂合约的模式。首先，可以利用现有网络状态，并将其作为Echidna的基础状态。其次，Echidna可以通过在CLI中传入对应的Solidity源代码，调用任何具有已知ABI的合约。在配置中使用allContracts: true来启用此功能。
Echidna速成课程
我们的构建安全智能合约仓库包含Echidna的速成课程，包括示例、课程和练习。
在GitHub Actions工作流中使用Echidna
有一个Echidna Action，可用于在GitHub Actions工作流中运行echidna。请查阅crytic/echidna-action仓库获取使用说明和示例。
配置选项
Echidna的CLI可用于选择要测试的合约并加载配置文件。```sh $ echidna contract.sol --contract TEST --config config.yaml
配置文件允许用户选择EVM和测试生成参数。包含默认选项的完整且带有注释的配置文件示例可以在[tests/solidity/basic/default.yaml](https://github.com/crytic/echidna/blob/HEAD/tests/solidity/basic/default.yaml)中找到。有关可用配置选项的更多详细信息，请参阅[文档](https://secure-contracts.com/program-analysis/echidna/configuration.html)。
Echidna支持三种不同的输出驱动程序。默认的是`text`驱动程序，还有`json`驱动程序和`none`驱动程序，后者应抑制所有`stdout`输出。JSON驱动程序报告整个活动如下。```
Campaign = {
"success" : bool,
"error" : string?,
"tests" : [Test],
"seed" : number,
"coverage" : Coverage
}
Test = {
"contract" : string,
"name" : string,
"status" : string,
"error" : string?,
"testType" : string,
"transactions" : [Transaction]?
}
Transaction = {
"contract" : string,
"function" : string,
"arguments" : [string]?,
"gas" : number,
"gasprice" : number
}
Coverage 是一个描述某些覆盖率增加调用的字典。这些接口将来可能会有所调整，以变得更加用户友好。testType 将是 property、assertion、optimization、exploration 或 call 之一，而 status 总是取值 fuzzing、shrinking、solved、passed 或 error。
调试性能问题
诊断 Echidna 性能问题的一种方法是启用性能分析运行 echidna。要以基本性能分析模式运行 Echidna，请在原始 echidna 命令后添加 +RTS -p -s：```sh
$ nix develop # alternatively nix-shell
$ cabal --enable-profiling run echidna -- ... +RTS -p -s
$ less echidna.prof
这会生成一个报告文件 (`echidna.prof`)，显示哪些函数占用了最多的 CPU 和内存。
如果基本的性能分析没有帮助，你可以使用更[高级的性能分析技术](https://haskell.foundation/hs-opt-handbook.github.io/src/Measurement_Observation/Haskell_Profiling/eventlog.html)。
我们观察到的性能问题的常见原因：
- 在热路径中调用的昂贵函数
- 累积 thunk 的惰性数据构造函数
- 在热路径中使用的低效数据结构
检查这些是一个好的起点。如果你怀疑某些计算过于惰性并导致内存泄漏，可以使用 `Control.DeepSeq` 中的 `force` 来确保其被求值。
## 限制和已知问题
EVM 模拟和测试是困难的。Echidna 在最新版本中有一些限制。其中一些继承自 [hevm](https://github.com/argotorg/hevm)，另一些则是设计/性能决策或我们代码中的错误所致。我们在此列出它们，包括对应的问题和状态（"wont fix"、"on hold"、"in review"、"fixed"）。已修复的问题预计将包含在下一个 Echidna 版本中。
| 描述 | 问题 | 状态 |
| :--- | :---: | :---: |
| Vyper 支持有限 | [#652](https://github.com/crytic/echidna/issues/652) | *wont fix* |
| 测试的库支持有限 | [#651](https://github.com/crytic/echidna/issues/651) | *wont fix* |
## 安装
### 预编译二进制文件
开始之前，请确保已[安装](https://github.com/crytic/slither) Slither（`pip3 install slither-analyzer --user`）。如果你想在 Linux 或 macOS 上快速测试 Echidna，我们在[发布页面](https://github.com/crytic/echidna/releases)上提供了在 Ubuntu 上构建的静态链接 Linux 二进制文件和基本静态的 macOS 二进制文件。你也可以从我们的 [CI 流水线](https://github.com/crytic/echidna/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush)获取相同类型的二进制文件，只需点击提交即可找到 Linux 或 macOS 的二进制文件。
### Homebrew (macOS / Linux)
如果你在 Mac 或 Linux 机器上安装了 Homebrew，可以通过运行 `brew install echidna` 来安装 Echidna 及其所有依赖项（Slither、crytic-compile）。
你也可以通过运行 `brew install --HEAD echidna` 来编译并安装最新的 `master` 分支代码。
你可以在 [`echidna` Homebrew Formula](https://formulae.brew.sh/formula/echidna) 页面获取更多信息。该 formula 作为 [homebrew-core 仓库](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/e/echidna.rb) 的一部分维护。
### Docker 容器
如果你更喜欢使用预构建的 Docker 容器，请查看我们的 [docker 包](https://github.com/orgs/crytic/packages?repo_name=echidna)，它通过 GitHub Actions 自动构建。`echidna` 容器基于 `ubuntu:noble`，旨在提供一个小巧且足够灵活的图像来使用 Echidna。它提供了预构建版本的 `echidna`，以及 `slither`、`crytic-compile`、`solc-select`、`nvm` 和 `foundry`（包括 `forge`、`cast`、`anvil` 和 `chisel`），大小低于 200 MB。
请注意，容器镜像目前仅构建在 x86 系统上。不建议在 ARM 设备（例如 Mac M1 系统）上运行它们，因为 CPU 仿真会导致性能损失。
Docker 容器镜像有不同的标签可用：
| 标签 | 构建中的标签
|---------------|-------------
| `vx.y.z` | 对应发布版本 `vx.y.z` 的构建
| `latest` | 最新的 Echidna 标签发布版本。
| `edge` | 默认分支上的最新提交。
| `testing-foo` | 基于 `foo` 分支的测试构建。
要以交互方式运行最新 Echidna 版本的容器，你可以使用类似以下的命令。它将当前目录映射到容器内的 `/src`，并为你提供一个可以使用 `echidna` 的 shell：```sh
$ docker run --rm -it -v "$(pwd)":/src ghcr.io/crytic/echidna/echidna
否则，如果你想在本地构建最新版本的Echidna，我们建议使用Docker。在此仓库的克隆目录中，运行以下命令来构建Docker容器镜像：```sh $ docker build -t echidna -f docker/Dockerfile --target final-ubuntu .
然后，你可以在本地运行 `echidna` 镜像。例如，要安装 solc
0.5.7 并检查 `tests/solidity/basic/flags.sol`，你可以运行：```sh
$ docker run -it -v "$(pwd)":/src echidna bash -c "solc-select install 0.5.7 && solc-select use 0.5.7 && echidna /src/tests/solidity/basic/flags.sol"
Docker 镜像还包含了 Foundry 工具，用于全面的智能合约开发和测试。您可以直接在容器中使用 forge、cast、anvil 和 chisel：```sh
Run an interactive shell with Foundry tools available
$ docker run -it -v "$(pwd)":/src echidna bash
Inside the container, you can use Foundry commands:
$ forge --version $ cast --version $ anvil --version $ chisel --version
Example: Initialize a new Foundry project
$ forge init my-project $ cd my-project $ forge build $ forge test
### 使用 Stack 构建
如果您更倾向于从源代码构建，请使用 [Stack](https://docs.haskellstack.org/en/stable/)。`stack install` 应该会在 `~/.local/bin` 中构建并编译 `echidna`。您需要链接到 libreadline 和 libsecp256k1（需启用恢复功能构建），这些库应通过您选择的包管理器安装。您还需要安装最新版本的 [libff](https://github.com/scipr-lab/libff)。请参考我们的 [CI 测试](https://github.com/crytic/echidna/blob/HEAD/.github/scripts/install-libff.sh) 以获取指导。
某些 Linux 发行版不提供 Haskell 所需的某些静态库，例如 Arch Linux，由于我们使用了 `-static` 标志，这将导致 `stack build` 因链接错误而失败。在这种情况下，请使用 `--flag echidna:-static` 生成动态链接的二进制文件。
如果您遇到与链接相关的构建错误，请尝试调整 `--extra-include-dirs` 和 `--extra-lib-dirs`。
### 使用 Nix 构建（在 Apple M1 系统上原生工作）
[Nix 用户](https://nixos.org/download/) 可以通过以下方式安装最新的 Echidna：```sh
$ nix-env -i -f https://github.com/crytic/echidna/tarball/master
启用 flakes 后，您可以直接从此仓库运行 Echidna：```sh $ nix run github:crytic/echidna # master $ nix run github:crytic/echidna/v2.1.1 # specific ref (tag/branch/commit)
要为非Nix macOS系统构建独立发布版本，以下步骤将在大部分静态二进制文件中构建Echidna。此方法也可用于Linux系统，以生成完全静态的二进制文件。```sh
$ nix build .#echidna-redistributable
Nix 将自动安装开发所需的所有依赖项，包括 crytic-compile 和 solc。快速开始开发 Echidna 的方法：```sh
$ git clone https://github.com/crytic/echidna
$ cd echidna
$ nix develop # alternatively nix-shell
[nix-shell]$ cabal run echidna
[nix-shell]$ cabal run tests
[nix-shell]$ cabal new-repl
## Echidna 的公开使用情况
### 属性测试套件
以下是使用 Echidna 进行测试的智能合约项目部分列表：
* [Curvance](https://github.com/curvance/Curvance-CantinaCompetition/tree/CodeFAQAndAdjustments/tests/fuzzing)
* [Primitive](https://github.com/primitivefinance/rmm-core/tree/main/contracts/crytic)
* [Uniswap-v3](https://github.com/search?q=org%3AUniswap+echidna&type=commits)
* [Balancer](https://github.com/balancer/balancer-core/tree/master/echidna)
* [MakerDAO vest](https://github.com/makerdao/dss-vest/pull/16)
* [Optimism DAI Bridge](https://github.com/makerdao/optimism-dai-bridge/blob/master/contracts/test/DaiEchidnaTest.sol)
* [WETH10](https://github.com/WETH10/WETH10/tree/main/contracts/fuzzing)
* [Yield](https://github.com/yieldprotocol/fyDai/pull/312)
* [Convexity Protocol](https://github.com/opynfinance/ConvexityProtocol/tree/dev/contracts/echidna)
* [Aragon Staking](https://github.com/aragon/staking/blob/82bf54a3e11ec4e50d470d66048a2dd3154f940b/packages/protocol/contracts/test/lib/EchidnaStaking.sol)
* [Centre Token](https://github.com/circlefin/stablecoin-evm/tree/release-2024-03-15T223309/echidna_tests)
* [Tokencard](https://github.com/tokencard/contracts/tree/master/tools/echidna)
* [Minimalist USD Stablecoin](https://github.com/usmfum/USM/pull/41)
### 安全审计
以下列出了使用 Echidna 发现漏洞的公开安全审计报告：
- [Advanced Blockchain](https://github.com/trailofbits/publications/blob/master/reviews/AdvancedBlockchain.pdf)
- [Amp](https://github.com/trailofbits/publications/blob/master/reviews/amp.pdf)
- [Ampleforth](https://github.com/trailofbits/publications/blob/master/reviews/ampleforth.pdf)
- [Atlendis](https://github.com/trailofbits/publications/blob/master/reviews/2023-03-atlendis-atlendissmartcontracts-securityreview.pdf)
- [Balancer](https://github.com/trailofbits/publications/blob/master/reviews/2021-04-balancer-balancerv2-securityreview.pdf)
- [Basis](https://github.com/trailofbits/publications/blob/master/reviews/basis.pdf)
- [Dai](https://github.com/trailofbits/publications/blob/master/reviews/mc-dai.pdf)
- [Frax](https://github.com/trailofbits/publications/blob/master/reviews/FraxQ22022.pdf)
- [Liquity](https://github.com/trailofbits/publications/blob/master/reviews/LiquityProtocolandStabilityPoolFinalReport.pdf)
- [LooksRare](https://github.com/trailofbits/publications/blob/master/reviews/LooksRare.pdf)
- [Maple](https://github.com/trailofbits/publications/blob/master/reviews/2022-03-maplefinance-securityreview.pdf)
- [Optimism](https://github.com/trailofbits/publications/blob/master/reviews/2022-11-optimism-securityreview.pdf)
- [Opyn](https://github.com/trailofbits/publications/blob/master/reviews/Opyn.pdf)
- [Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf)
- [Origin](https://github.com/trailofbits/publications/blob/master/reviews/origin.pdf)
- [Paxos](https://github.com/trailofbits/publications/blob/master/reviews/paxos.pdf)
- [Primitive](https://github.com/trailofbits/publications/blob/master/reviews/Primitive.pdf)
- [RocketPool](https://github.com/trailofbits/publications/blob/master/reviews/RocketPool.pdf)
- [Seaport](https://github.com/trailofbits/publications/blob/master/reviews/SeaportProtocol.pdf)
- [Set Protocol](https://github.com/trailofbits/publications/blob/master/reviews/setprotocol.pdf)
- [Shell protocol](https://github.com/trailofbits/publications/blob/master/reviews/ShellProtocolv2.pdf)
- [Sherlock](https://github.com/trailofbits/publications/blob/master/reviews/Sherlockv2.pdf)
- [Pegasys Pantheon](https://github.com/trailofbits/publications/blob/master/reviews/pantheon.pdf)
- [TokenCard](https://github.com/trailofbits/publications/blob/master/reviews/TokenCard.pdf)
- [Uniswap](https://github.com/trailofbits/publications/blob/master/reviews/UniswapV3Core.pdf)
- [Yearn](https://github.com/trailofbits/publications/blob/master/reviews/YearnV2Vaults.pdf)
- [Yield](https://github.com/trailofbits/publications/blob/master/reviews/YieldProtocol.pdf)
- [88mph](https://github.com/trailofbits/publications/blob/master/reviews/88mph.pdf)
- [0x](https://github.com/trailofbits/publications/blob/master/reviews/0x-protocol.pdf)
### 捕获的漏洞
以下安全漏洞是由 Echidna 发现的。如果您使用我们的工具发现了安全漏洞，请提交包含相关信息的 PR。
| 项目 | 漏洞 | 日期 |
|--|--|--|
[0x Protocol](https://github.com/trailofbits/publications/blob/master/reviews/0x-protocol.pdf) | 如果订单无法成交，则无法取消 | 2019年10月
[0x Protocol](https://github.com/trailofbits/publications/blob/master/reviews/0x-protocol.pdf) | 如果订单可以零额部分成交，则可以用一个代币部分成交 | 2019年10月
[0x Protocol](https://github.com/trailofbits/publications/blob/master/reviews/0x-protocol.pdf) | 当使用有效输入参数时，cobbdouglas 函数不会回退 | 2019年10月
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | 攻击者无法从公共池中窃取资产 | 2020年1月
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | 攻击者无法通过 joinPool 生成免费池代币 | 2020年1月
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | 调用 joinPool-exitPool 不会导致免费池代币 | 2020年1月
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | 调用 exitswapExternAmountOut 不会导致免费资产 | 2020年1月
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | [关闭金库需持有全部铸造的 LUSD 数量](https://github.com/liquity/dev/blob/echidna_ToB_final/packages/contracts/contracts/TestContracts/E2E.sol#L242-L298) | 2020年12月
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | [金库可能被不当移除](https://github.com/liquity/dev/blob/echidna_ToB_final/packages/contracts/contracts/TestContracts/E2E.sol#L242-L298) | 2020年12月
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | 初始赎回可能意外回退 | 2020年12月
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | 无赎回的赎回操作仍可能返回成功 | 2020年12月
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | 用户被允许转移超过自身持有的代币 | 2020年11月
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | 用户余额可能大于总供应量 | 2020年11月
[Yield Protocol](https://github.com/trailofbits/publications/blob/master/reviews/YieldProtocol.pdf) | 买卖代币的算术计算不精确 | 2020年8月
### 研究
我们还可以使用 Echidna 重现智能合约模糊测试论文中的研究示例，以展示其快速解决问题的能力。以下所有示例均可在笔记本电脑上几秒到一两分钟内解决。
| 来源 | 代码
|--|--
[Using automatic analysis tools with MakerDAO contracts](https://forum.openzeppelin.com/t/using-automatic-analysis-tools-with-makerdao-contracts/1021) | [SimpleDSChief](https://github.com/crytic/echidna/blob/master/tests/solidity/research/vera_dschief.sol)
[Integer precision bug in Sigma Prime](https://github.com/muellerberndt/sabre#example-2-integer-precision-bug) | [VerifyFunWithNumbers](https://github.com/crytic/echidna/blob/master/tests/solidity/research/solcfuzz_funwithnumbers.sol)
[Learning to Fuzz from Symbolic Execution with Application to Smart Contracts](https://files.sri.inf.ethz.ch/website/papers/ccs19-ilf.pdf) | [Crowdsale](https://github.com/crytic/echidna/blob/master/tests/solidity/research/ilf_crowdsale.sol)
[Harvey: A Greybox Fuzzer for Smart Contracts](https://arxiv.org/abs/1905.06944) | [Foo](https://github.com/crytic/echidna/blob/master/tests/solidity/research/harvey_foo.sol), [Baz](https://github.com/crytic/echidna/blob/master/tests/solidity/research/harvey_baz.sol)
### 学术出版物
| 论文标题 | 会议/期刊 | 发表日期 |
| --- | --- | --- |
| [echidna-parade: Diverse multicore smart contract fuzzing](https://agroce.github.io/issta21.pdf) | [ISSTA 2021](https://conf.researchr.org/home/issta-2021) | 2021年7月 |
| [Echidna: Effective, usable, and fast fuzzing for smart contracts](https://agroce.github.io/issta20.pdf) | [ISSTA 2020](https://conf.researchr.org/home/issta-2020) | 2020年7月 |
| [Echidna: A Practical Smart Contract Fuzzer](https://github.com/trailofbits/publications/blob/master/papers/echidna_fc_poster.pdf) | [FC 2020](https://fc20.ifca.ai/program.html) | 2020年2月 |
如果您在学术工作中使用 Echidna，请考虑申请 [Crytic 10,000 美元研究奖](https://blog.trailofbits.com/2019/11/13/announcing-the-crytic-10k-research-prize/)。
## 获取帮助
欢迎在我们的 #ethereum slack 频道（位于 [Empire Hacking](https://slack.empirehacking.nyc/)）中咨询有关使用或扩展 Echidna 的问题。
* 从这些简单的 [Echidna 不变量](https://github.com/crytic/echidna/blob/HEAD/tests/solidity/basic/flags.sol) 开始学习
* 如需更详细的问题，请考虑直接[发送邮件](mailto:[email protected])给 Echidna 开发团队
## 许可证
Echidna 根据 [AGPLv3 许可证](https://github.com/crytic/echidna/blob/master/LICENSE) 授权和分发。