rbwet/excelleron

## 概述 `Excelleron` 是一个模块化的 Foundry 工作区，它将经典的 **价格预言机操纵攻击** 分解为四个协作合约。每个模块独立处理攻击链中的单个关注点，以便您可以依次研究、模糊测试并加固每个攻击面。 它模拟的端到端场景如下： 1. 通过 Aave V3 闪电贷以 **零抵押** 借入资金。 2. 使用该资金推高 Uniswap V2 池中目标资产的现货价格。 3. 将价值膨胀的代币作为抵押品存入读取被操纵价格的借贷市场。 4. 以估值过高的抵押品进行借款，获取利润并偿还闪电贷——所有操作均在原子交易中完成。 如果任何步骤失败，交易将回滚，并且只会损失 Gas 费。正是这种不对称性使得现货价格预言机成为 DeFi 历史中反复出现的失败模式（bZx、Harvest、Cheese Bank、Mango 等数十起事件）。 ## 亮点 - **模块化攻击组合** —— 四个合约，四个职责，它们之间具有清晰的接口。 - **Fork 主网模拟** —— 通过 `forge test --fork-url` 在选定区块重放历史链状态。 - **Dry-run 盈利能力估算器** —— `simulate()` 返回预计的损益，而无需花费 Gas。 - **生产级 ABI** —— 作为 git submodules 集成了 Uniswap V2 Core/Periphery、Aave V3 Core、OpenZeppelin 和 `forge-std`。 - **CI 就绪** —— GitHub Actions 工作流在每次推送和 PR 时运行 `forge fmt --check`、`forge build --sizes` 和 `forge test`。 - **详尽的注解** —— 每个 `VULNERABILITY:` 注释都标明了真实协议必须防范的假设前提。 ## 架构 ``` ┌─────────────────────────────┐ │ AttackOrchestrator │ │ (top-level coordinator) │ └──────────────┬──────────────┘ │ owns / wires ┌────────────────────────┼────────────────────────┐ ▼ ▼ ▼ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ FlashLoanReceiver │ │ OracleManipulator │ │ LendingExploiter │ │ Aave V3 callback │ │ Uniswap V2 swaps │ │ supply / borrow │ └────────┬───────────┘ └─────────┬──────────┘ └─────────┬──────────┘ │ │ │ ▼ ▼ ▼ Aave Pool Uniswap V2 Pair Aave Pool (flash loan) (price manipulation) (collateral / debt) ``` ### 模块 | 文件 | 作用 | |---|---| | [`contracts/orchestrator.sol`](contracts/orchestrator.sol) | 顶层协调器。拥有其他三个合约，暴露 `configure()`、`simulate()` 和 `execute()`。 | | [`contracts/flash-loan-receiver.sol`](contracts/flash-loan-receiver.sol) | 实现 Aave V3 的 `executeOperation` 回调。原子化的“闪电贷内部”入口点。 | | [`contracts/oracle-manipulator.sol`](contracts/oracle-manipulator.sol) | 读取 Uniswap V2 储备金，计算恒定乘积交换影响，并推高价格。 | | [`contracts/lending-exploiter.sol`](contracts/lending-exploiter.sol) | 提供估值过高的抵押品并据此借款；提供用于健康因子和最大借款量估算的辅助函数。 | | [`contracts/interfaces.sol`](contracts/interfaces.sol) | 最小化接口（`ILendingPool`、`IUniswapV2Router02`、`IUniswapV2Pair`、`IUniswapV2Factory`、`IPriceOracle`、`IERC20`）。 | ## 漏洞参考 这些模块有意展示（而非利用）以下类别的弱点。每个弱点都在源代码中用 `VULNERABILITY:` 注释进行了标记。 | # | 类别 | 出现位置 | |---|---|---| | 1 | 直接读取 AMM 储备金的 **现货价格预言机** | `OracleManipulator.getCurrentPriceBps`, `getReserves` | | 2 | 恒定乘积曲线的 **单区块可操纵性** | `OracleManipulator.calculateSwapImpact`, `executeSwap` | | 3 | 无需抵押的 **闪电贷资金放大** | `FlashLoanReceiver.executeOperation` | | 4 | **原子化的高估抵押品借款** | `LendingExploiter.supplyCollateral` → `borrowAsset` | | 5 | 锚定可操纵价格馈送的 **LTV 计算** | `LendingExploiter.estimateMaxBorrow`, `checkHealth` | | 6 | 降低攻击者风险的 **预执行盈利能力预言机** | `AttackOrchestrator.simulate` | ## 防御要点 与之对应的经验教训——协议开发方应当采取的正确做法： - 使用 **时间加权平均价格**（Uniswap V3 TWAP，≥ 10 分钟窗口）或带有陈旧度检查的聚合链下数据源（Chainlink、Pyth、RedStone）。 - 如果池子可以在单个区块内被抽干或转移，**绝不**使用 `getReserves()` 进行定价。 - 限制从现货派生预言机定价的资产的借贷能力；对巨大的估值变动要求 **多区块** 确认。 - 增加支持闪电贷感知的 **速率限制** —— 检测同一区块内的供应 + 借款流。 - 使用正是此类操纵工具针对您自己的预言机适配器运行 **不变量模糊测试**（Foundry `forge test --match-contract Invariant`）。 ## 快速开始 ### 前置条件 - [Foundry](https://book.getfoundry.sh/getting-started/installation) (`forge`, `cast`, `anvil`, `chisel`) - Git ≥ 2.30 （用于 submodules） ### 安装 ``` git clone --recurse-submodules https://github.com//excelleron.git cd excelleron forge install forge build ``` ### 运行本地测试套件 ``` forge fmt --check forge build --sizes forge test -vvv ``` ### Fork 主网模拟 从下面的示例创建一个 `.env` 文件——**切勿将其提交到版本控制**。 ``` # .env (git-ignored) MAINNET_RPC=https://eth.llamarpc.com # or your own provider FORK_BLOCK_NUMBER=15000000 ``` 然后： ``` source .env forge test --fork-url "$MAINNET_RPC" --fork-block-number "$FORK_BLOCK_NUMBER" -vvv ``` 完整的演练——包括 `FlashLoanSimulationTest` 模板、预期输出和安全提示——位于 [`simulations/README.md`](simulations/README.md)。 ## 仓库布局 ``` excelleron/ ├── contracts/ # Reference implementations (annotated) │ ├── orchestrator.sol │ ├── flash-loan-receiver.sol │ ├── oracle-manipulator.sol │ ├── lending-exploiter.sol │ └── interfaces.sol ├── src/ # Foundry source tree (compilation entry) ├── script/ # Forge scripts ├── test/ # Forge tests ├── simulations/ # Forked-mainnet scenario docs & harness ├── analysis/ # Reserved for future post-mortem write-ups ├── lib/ # Submodules: forge-std, OZ, Uniswap V2, Aave V3 ├── foundry.toml └── .github/workflows/ # CI ``` ## 持续集成 每次推送和 PR 都会运行 [`.github/workflows/test.yml`](.github/workflows/test.yml)： 1. 检出代码及 submodules（无持久化凭证）。 2. 安装 Foundry 工具链。 3. `forge fmt --check` —— 格式化检查。 4. `forge build --sizes` —— 合约大小报告。 5. `forge test -vvv` —— 完整测试套件。 ## 路线图 - [ ] 将 `contracts/` 中的完整参考实现移植到 `src/` Foundry 目录树中。 - [ ] 为每个 `VULNERABILITY:` 注释添加不变量测试。 - [ ] 展示 **防御性** 反模式的即插即用型 TWAP 预言机适配器。 - [ ] `analysis/` 中的历史案例研究（bZx、Harvest、Mango 等）。 - [ ] 多跳操纵路径发现（相对于仅直接交易对）。 ## 负责任的使用 此代码库的存在是为了让防御者变得更强。可接受的用途包括： - 研究和教授 DeFi 攻击向量。 - 在私有 fork 上针对这些模式审计您自己的协议。 - 构建防御性工具、模糊器或预言机适配器。 **不可接受的用途包括任何针对您不拥有或未获得明确书面授权测试的系统的部署、交易或活动。** 作者对滥用行为不承担任何责任。 ## 许可证 基于 [MIT License](https://opensource.org/licenses/MIT) 发布。

_{使用 Foundry 构建 · Submodules 来自 Uniswap, Aave, OpenZeppelin}

标签：Aave V3, CISA项目, DeFi, Foundry, Solidity, Uniswap V2, Web3安全, Web报告查看器, 以太坊, 价格预言机操纵, 借贷漏洞利用, 加密货币, 区块链安全, 区块链安全测试, 套利, 安全研究框架, 智能合约安全, 智能合约审计, 漏洞复现, 重放攻击, 闪电贷攻击, 零抵押贷款