sanbir/evm-hack-registry
GitHub: sanbir/evm-hack-registry
一个自包含、可离线运行的 DeFi 攻击 PoC 档案库，收录了 841 个历史攻击事件的真实合约源码、链上状态快照及 AI 分析报告，无需归档节点即可一键复现。
Stars: 12 | Forks: 2
# evm-hack-registry
一个自包含、可离线运行的档案库，收录了跨越 EVM 攻击完整历史（2017 → 2026）、涵盖 15 条链的 **841 个 DeFi 攻击事件概念验证**。
每个攻击事件都拥有独立的 Foundry 项目，包含从 Etherscan 获取的**真实链上合约源码**、抓取的 **anvil 区块状态快照**（实现无网运行），以及解释该漏洞的 **AI 分析报告 + 堆栈跟踪**。一切都可以通过 `git clone` 实现端到端复现：
```
git clone git@github.com:sanbir/evm-hack-registry.git
cd evm-hack-registry
# 完全离线运行一个 PoC（anvil 从已提交的快照提供链状态）
_shared/run_poc.sh 2018-04-BEC_exp -vvvvv
# 并行运行全部 841 个
_shared/run_all.sh
```
无需 RPC 密钥，无需归档节点，无需连接互联网。
## 为什么会有这个项目
本仓库派生自并非常感谢 [**SunWeb3Sec/DeFiHackLabs**](https://github.com/SunWeb3Sec/DeFiHackLabs) —— 这是一个极其出色的 DeFi 攻击 PoC 社区合集。DeFiHackLabs 是一项宝贵的资源，但要想真正*运行和研究*其中的 PoC 却十分困难：
- **需要归档节点。** PoC 通过实时 RPC 在历史区块处分叉链上状态。复现它们需要为每条链（mainnet、BSC、Arbitrum、Optimism、Base、Polygon、Avalanche、Fantom、Gnosis……）配备**归档**节点——公共 RPC 会修剪状态，而免费的归档访问极为罕见或受到速率限制。没有付费的归档服务商，你根本无法运行大多数 PoC。
- **众多链，众多区块。** 攻击事件横跨 15 条链，每条链在不同的历史区块进行分叉。为每一个 PoC 协调正确的链 + 区块 + 可用的归档节点不仅繁琐，而且极其脆弱。
- **不兼容的 Solidity 版本。** PoC 编写时所用的 solc 版本从 `0.4.x` 到 `0.8.x` 不等，且全部共存于同一个伞形仓库中。对整个项目执行 `forge build` 会因为版本冲突而编译失败。
- **缺失合约源码。** 攻击事件调用的受害合约字节码是在分叉时从节点实时获取的——源码并不包含在仓库中，因此你无法阅读或单步调试存在漏洞的代码。
- **没有保存状态或跟踪信息。** 没有任何内容被缓存，因此运行既不可复现也无法离线进行，也没有保存可供学习的堆栈跟踪。
最终结果就是：在 DeFiHackLabs 中，*运行并分析* PoC 并不容易。本项目正是为了填补这一空白。
## 我们做了什么
本仓库提取了每一个 PoC，并将其打造成**一流的、自包含、可离线运行**的学习单元：
1. **将每个 PoC 迁移至独立的 Forge 测试项目中。** 每个攻击事件对应一个文件夹（`YYYY-MM-Name_exp/`），每个都包含自己的 `foundry.toml`、`test/` 和 `src/`。不再有版本冲突——每个项目都使用自己的 solc 独立编译。
2. **从 Etherscan 下载了合约源码。** 真正存在漏洞的/受害的合约代码被提交在 `sources/` 目录下（按合约展平），因此被利用的逻辑是可读且可调试的，而不仅仅是实时获取的字节码。
3. **确保每个 PoC 使用正确的 Solidity 版本进行编译**，并在正确的归档区块处进行分叉。
4. **为 anvil 捕获链上状态。** 对于每个 PoC，复现攻击事件所需的精确区块状态被一次性下载并转换为 `anvil --load-state` 快照（`anvil_state.json`）。在运行时，由本地 `anvil` 提供该状态——**无需归档 RPC 节点**。
5. **利用 AI 分析了堆栈跟踪。** 每个 PoC 都配有一份 `.md` 报告，根据 `-vvvvv` 跟踪信息生成，解释了漏洞、攻击流程以及关键合约。
所有产物都已保留，可离线查看/运行：
| 产物 | 说明 |
|---|---|
| `src/`, `test/`, `sources/` | 攻击测试脚手架 + 从 Etherscan 获取的受害合约 |
| `anvil_state.json` | 链上区块状态（anvil 快照）——可离线运行 |
| `output.txt` | 参考的 `forge test` 跟踪信息 |
| `.md` | AI 分析报告（根本原因、攻击流程、合约） |
## 如何运行
```
# 一个 PoC，完全离线（详细 trace）
_shared/run_poc.sh 2021-08-PolyNetwork_exp -vvvvv
# 一个 PoC，默认
_shared/run_poc.sh 2021-08-PolyNetwork_exp
# 并行运行全部 841 个（受限于 CPU 核心数）
_shared/run_all.sh
# 将运行结果与每个 PoC 的预期 output.txt 进行比较
_shared/compare_output.sh _shared/results/
```
每个 PoC 都独立运行：`run_poc.sh` 会启动一个私有的 `anvil`（端口由操作系统分配），加载该 PoC 的 `anvil_state.json`，将 `forge` 指向它，运行结束后将其关闭——因此任意数量的 PoC 都可以并行运行而不会发生冲突。
### Docker
```
docker build -t evm-hack-registry .
docker run --rm --network none evm-hack-registry 2018-04-BEC_exp # one PoC, offline
docker run --rm --network none evm-hack-registry # all PoCs, parallel
```
该镜像内置了 Foundry（`forge` + `anvil`）、本仓库以及预下载的 solc 编译器，因此支持 `--network none`。
## 状态
**839 / 841** 个 PoC 包含已提交的 `anvil_state.json` 并且可以完全离线运行。**806 / 841** 个 PoC 能成功复现攻击事件——在提交的 `output.txt` 中显示为 `Suite result: ok`（96%）。其余的 PoC 包含一份已记录未通过的参考跟踪信息或不完整的捕获（详见 `_shared/README.md`）。
- **2 个 PoC**（moonriver 上的 `2022-02-Meter_exp`、sei 上的 `2025-09-Kame_exp`）无法复现：它们的分叉区块在每个公共归档节点上都被修剪了，因此没有 `anvil_state.json`。这是这两条链上仅有的 PoC；其余 13 条链都有可离线运行的复现。
- **没有**任何 `foundry.toml` 中包含 `[rpc_endpoints]`，**没有**外部依赖，**没有**机密信息。
## 许可证
与源项目相同——请查看各个 PoC 和 [DeFiHackLabs](https://github.com/SunWeb3Sec/DeFiHackLabs) 了解许可详情。
## 漏洞分类
每个 PoC 都带有一个或多个**漏洞类别**标签，这些标签源自 [**AuditVault**](https://github.com/forefy/AuditVault) 智能合约安全分类标准（`classifications/bug/vuln/`）。标签写为报告标题正下方的一行可见文本，例如：
单个攻击事件通常会表现出多种不同的类别（根本原因 Bug 加上促成机制），因此多标签是正常的——以 `·` 分隔的列表。要查找给定类别的所有 PoC，请在仓库中 grep：
```
grep -rl "vuln/oracle/price-manipulation" --include='*_exp.md' .
```
**覆盖率：** 841 个 PoC 中有 819 个被标记（22 个未标记——即标记器跳过的多攻击事件变体文件夹，如 `exp1`/`exp2`/`exploit`）。在整个仓库中，共有 **1,851 个标签实例**（平均每个 PoC **2.26** 个类别），涵盖了 **70** 个不同的 `vuln/` 类别名（即 AuditVault 的规范集合，加上少量分类器分配的变体，如 `vuln/business-logic/*`）。
### 按类别划分
| 类别 | 标签数 | 覆盖范围 |
|---|---:|---|
| `vuln/logic/…` | 538 | 业务逻辑 Bug（状态更新、顺序、价格/奖励/费用/清算计算、缺失检查/验证） |
| `vuln/access-control/…` | 425 | 缺失 auth/modifier/owner-check、未初始化的 proxy/owner、泄露的密钥、中心化 |
| `vuln/oracle/…` | 327 | 价格/oracle 操纵、现货价格、过期价格、单一来源、TWAP、错误的 feed |
| `vuln/defi/…` | 166 | AMM slippage、三明治攻击、费用操纵 |
| `vuln/arithmetic/…` | 112 | 溢出/下溢、舍入、精度损失、小数位不匹配、先除后乘 |
| `vuln/dependency/…` | 90 | 不安全的外部调用、未检查的返回值、可升级/proxy 风险 |
| `vuln/governance/…` | 65 | 闪电贷攻击/投票、提案操纵、绕过 timelock |
| `vuln/reentrancy/…` | 63 | 单函数/跨函数/跨合约/只读 reentrancy |
| `vuln/auth/…` | 18 | 签名重放/可塑性/验证 |
| `vuln/bridge/…` | 16 | 跨链消息伪造、缺失验证、重放 |
| `vuln/input-validation/…` | 15 | 缺失/边界/类型错误的输入检查 |
| `vuln/data/…` | 7 | 未初始化的存储、缺失的事件、错误的编码 |
| `vuln/dos/…` | 7 | 资金冻结、gas 限制、恶意阻碍、锁定、无限循环、初始化约束 |
| `vuln/business-logic/…` | 2 | 任意调用 / 混淆代理（`logic` 的分类器变体） |
### 按类划分（完整明细）
| 类（AuditVault `vuln/` 标签名） | 标签数 |
|---|---:|
| `vuln/access-control/missing-auth` | 254 |
| `vuln/oracle/price-manipulation` | 176 |
| `vuln/defi/slippage` | 120 |
| `vuln/oracle/spot-price` | 113 |
| `vuln/logic/state-update` | 94 |
| `vuln/logic/incorrect-state-transition` | 87 |
| `vuln/dependency/unsafe-external-call` | 74 |
| `vuln/logic/missing-check` | 71 |
| `vuln/logic/incorrect-order-of-operations` | 71 |
| `vuln/logic/missing-validation` | 68 |
| `vuln/logic/reward-calculation` | 63 |
| `vuln/governance/flash-loan-attack` | 57 |
| `vuln/access-control/missing-modifier` | 45 |
| `vuln/logic/price-calculation` | 39 |
| `vuln/arithmetic/rounding` | 35 |
| `vuln/reentrancy/single-function` | 33 |
| `vuln/arithmetic/precision-loss` | 32 |
| `vuln/access-control/broken-logic` | 30 |
| `vuln/access-control/missing-validation` | 23 |
| `vuln/defi/sandwich-attack` | 20 |
| `vuln/arithmetic/overflow` | 18 |
| `vuln/access-control/centralization` | 17 |
| `vuln/arithmetic/decimal-mismatch` | 17 |
| `vuln/defi/fee-manipulation` | 16 |
| `vuln/logic/missing-allowance` | 15 |
| `vuln/access-control/uninitialized-proxy` | 14 |
| `vuln/oracle/stale-price` | 14 |
| `vuln/auth/signature-validation` | 14 |
| `vuln/reentrancy/cross-function` | 13 |
| `vuln/logic/wrong-condition` | 13 |
| `vuln/input-validation/missing` | 13 |
| `vuln/dependency/unchecked-return-value` | 12 |
| `vuln/access-control/missing-owner-check` | 12 |
| `vuln/reentrancy/cross-contract` | 11 |
| `vuln/bridge/missing-validation` | 11 |
| `vuln/access-control/secret-exposure` | 10 |
| `vuln/logic/fee-calculation` | 10 |
| `vuln/access-control/missing-check` | 8 |
| `vuln/oracle/missing-validation` | 8 |
| `vuln/defi/flash-loan-attack` | 8 |
| `vuln/data/uninitialized` | 7 |
| `vuln/access-control/fake-account-substitution` | 7 |
| `vuln/reentrancy/read-only` | 6 |
| `vuln/arithmetic/underflow` | 6 |
| `vuln/logic/liquidation-logic` | 6 |
| `vuln/oracle/single-source` | 5 |
| `vuln/oracle/wrong-feed` | 5 |
| `vuln/access-control/uninitialized-owner` | 4 |
| `vuln/bridge/message-spoofing` | 4 |
`vuln/dependency/upgradeable-contract` | 4 |
| `vuln/governance/proposal-manipulation` | 3 |
| `vuln/dos/griefing` | 3 |
| `vuln/governance/timelock-bypass` | 3 |
| `vuln/auth/signature-replay` | 3 |
| `vuln/oracle/manipulable-twap` | 3 |
| `vuln/dos/frozen-funds` | 2 |
| `vuln/governance/flash-loan-voting` | 2 |
| `vuln/input-validation/boundary` | 2 |
| `vuln/oracle/missing-circuit-breaker` | 2 |
| `vuln/arithmetic/rounding-direction` | 2 |
| `vuln/arithmetic/division-before-multiply` | 2 |
| `vuln/defi/price-manipulation` | 2 |
| `vuln/dos/init-constraint` | 2 |
| `vuln/access-control/proxy-storage-collision` | 1 |
| `vuln/auth/signature-malleability` | 1 |
| `vuln/business-logic/arbitrary-call` | 1 |
| `vuln/business-logic/confused-deputy` | 1 |
| `vuln/oracle/price-calculation` | 1 |
| `vuln/logic/missing-state-update` | 1 |
| `vuln/bridge/replay` | 1 |
标签：Cutter, DeFi, EVM, Foundry, 区块链安全, 智能合约审计, 漏洞复现, 请求拦截