noosi21/codex-solidity
GitHub: noosi21/codex-solidity
面向Solidity智能合约和DeFi协议的激进攻防审计CLI，集34项漏洞检测技能、符号执行、模糊测试、LLM推理与自动化exploit证明于一体。
Stars: 0 | Forks: 0
# ⛓️ Codex Solidity — 激进的智能合约审计 Agent
针对 Solidity 智能合约和 DeFi 协议的 🔴 **RED TEAM** 漏洞挖掘工具。它不仅能发现 bug —— 还能**通过 exploit 代码进行证明**，将低严重性发现链接为关键攻击，并在黑客之前打破不变量。每一项发现都包含 **exploit 合约**、**攻击流程**以及**财务影响计算**，从而证明真实的资金抽干、池冻结和余额操纵场景。
## 🚀 快速开始
### 选项 A：交互式（最简单 — 3 步）
```
# 步骤 1：Clone 并安装
git clone https://github.com/noosi21/codex-solidity.git
cd codex-solidity
npm install
# 步骤 2：运行交互式 quickstart
npm run quickstart
# 步骤 3：从菜单中选择要审计的内容：
# 1) GitHub repo URL → 粘贴任意 repo 链接
# 2) 本地目录 → ./contracts/
# 3) 单个 .sol 文件 → ./Vault.sol
# 4) 列出所有 35 个 skills
# 5) 启动 Codex CLI 会话
```
### 选项 B：单行命令（无需克隆）
```
# 审计任意 GitHub repo — 只需粘贴链接
npx codex-solidity audit -t https://github.com/OpenZeppelin/openzeppelin-contracts
# 审计子目录
npx codex-solidity audit -t https://github.com/Aave/aave-v3-core/tree/main/contracts
# 审计本地 contracts
npx codex-solidity audit -t ./contracts/
```
### 选项 C：全局安装（短命令）
```
# 安装一次
npm install -g codex-solidity
# 现在可以在任何地方使用 'codex-sol'
codex-sol audit -t https://github.com/org/repo # Full audit
codex-sol audit -t ./contracts/ --llm # + GPT-5.4 reasoning
codex-sol audit -t https://github.com/org/repo --aggressive --llm --reasoning-effort xhigh # Full power
codex-sol skill -t ./Vault.sol -n reentrancy # Single skill
codex-sol list # List 35 skills
codex-sol parse -t ./Vault.sol # Parse structure
codex-sol mcp -q reentrancy -s swc # Query SWC Registry
codex-sol config # Show config
```
### 选项 D：Docker（零安装）
```
# Pull 并运行 — 本地无需安装任何内容
docker run -it noosi21/codex-solidity audit -t https://github.com/org/repo
# 使用 LLM reasoning
docker run -it -e OPENAI_API_KEY=sk-... noosi21/codex-solidity audit -t https://github.com/org/repo --llm
# 本地 Build
git clone https://github.com/noosi21/codex-solidity.git
cd codex-solidity
docker build -t codex-solidity .
docker run -it codex-solidity audit -t https://github.com/org/repo
```
### 选项 E：Codex CLI（GPT-5.4 xhigh Agent）
```
# 安装 Codex CLI
npm install -g @openai/codex
# 登录（一次性 — 自动处理 API keys）
codex login
# 在 repo 内启动会话
cd codex-solidity
codex
# 现在只需用简单的英语告诉它要做什么：
> audit https://github.com/Aave/aave-v3-core for bug bounty
> aggressively audit this repo — prove every exploit
> check ./contracts/Vault.sol for reentrancy
> run all 35 skills on this codebase
> what are the most critical findings?
```
### 常见使用示例
```
# Bug bounty 审计（全功率）
codex-sol audit -t https://github.com/org/repo --aggressive --llm --reasoning-effort xhigh
# 快速扫描（无 LLM，速度快）
codex-sol audit -t ./contracts/
# 专注于一种 vulnerability 类型
codex-sol skill -t ./Vault.sol -n reentrancy
codex-sol skill -t ./Vault.sol -n flash-loan
codex-sol skill -t ./Vault.sol -n upgradability
# CI/CD 集成
codex-sol audit -t ./contracts/ --ci --fail-on high
# Diff 审计（仅针对更改的代码）
codex-sol audit -t ./contracts/ --diff main...HEAD
# Interactive mode（在审计后深入 findings）
codex-sol audit -t ./contracts/ --interactive
```
## 🐉 Kali Linux 设置
在 Kali Linux 上的单行命令设置：
```
git clone https://github.com/noosi21/codex-solidity.git
cd codex-solidity
chmod +x setup-kali.sh
./setup-kali.sh
```
此命令会安装：
- **Node.js 20.x** + npm
- **Foundry** (forge, cast, anvil) — 用于 PoC 编译/测试
- **Slither** — Python 静态分析器
- **Echidna** — 基于属性的模糊测试器
- **Codex Solidity** + 所有 npm 依赖
- **OpenAI Codex CLI** (`codex` 命令) — GPT-5.4 xhigh Agent
- **OpenAI API key** 配置（提示输入密钥）
## 🤖 Codex CLI 集成（GPT-5.4 xhigh Agent）
本项目旨在**在 OpenAI Codex CLI 内部**作为智能体审计工作站运行。GPT-5.4 Agent 会读取 `AGENTS.md` 获取指令，并读取 `.agents/skills/*/SKILL.md` 获取技能定义，随后执行我们的 Node.js 工具。
### 设置
```
# 1. 安装 Codex CLI
npm install -g @openai/codex
# 2. 登录
codex login
# 3. Clone 此 repo
git clone https://github.com/noosi21/codex-solidity.git
cd codex-solidity
npm install
# 4. 在项目目录中启动 Codex CLI
codex
```
### 交互式漏洞赏金工作流
进入 Codex CLI REPL 后，只需告诉 Agent 要审计什么：
```
> audit https://github.com/OpenZeppelin/openzeppelin-contracts
> run symbolic execution on the Vault contract
> check invariants on the Pool contract
> generate a fuzzing harness for the Token contract
> find reentrancy in all withdraw functions
> what are the cross-contract risks between Pool and Router?
```
GPT-5.4 xhigh Agent 将会：
1. 读取 `AGENTS.md` 获取审计角色定位和操作规则
2. 读取 `.agents/skills/audit-pro/SKILL.md` 获取审计工作流
3. 执行 `node bin/codex-sol.js audit -t ` 运行完整流水线
4. 审查发现，通过深度推理进行验证
5. 为已确认的漏洞编写 Foundry PoC
6. 按照 Sherlock/Immunefi 漏洞赏金提交格式格式化发现
### 单次模式
```
# 使用一条命令审计 repo
codex "audit https://github.com/Aave/aave-v3-core for bug bounty" --model gpt-5.4-pro --reasoning-effort xhigh
# 专注于特定的 vulnerability
codex "find reentrancy in https://github.com/org/repo" --model gpt-5.4-pro
# 为已知 issue 生成 PoC
codex "write a Foundry PoC for the flash loan vulnerability in ./contracts/Vault.sol"
```
### 工作原理
```
┌─────────────────────────────────────────────────┐
│ Codex CLI (GPT-5.4 xhigh) │
│ Reads AGENTS.md → Gets audit persona + rules │
│ Reads SKILL.md → Gets audit workflow steps │
├─────────────────────────────────────────────────┤
│ Executes Node.js Tools via Shell │
│ node bin/codex-sol.js audit -t │
│ node bin/codex-sol.js symbolic -t │
│ node bin/codex-sol.js invariant -t │
│ node bin/codex-sol.js cross-contract -t │
│ node bin/codex-sol.js fuzz -t │
├─────────────────────────────────────────────────┤
│ GPT-5.4 xhigh Deep Reasoning │
│ • Validates automated findings │
│ • Finds novel vulnerabilities static tools miss │
│ • Traces exploit paths step-by-step │
│ • Quantifies financial impact │
│ • Generates Foundry PoCs │
│ • Formats bug bounty submissions │
└─────────────────────────────────────────────────┘
```
### 独立模式（无需 Codex CLI）
你也可以直接使用 Node.js CLI —— 无需 Codex CLI：
```
# 使用内置 LLM reasoning 的完整审计
node bin/codex-sol.js audit -t https://github.com/org/repo --llm --reasoning-effort xhigh
# 或者无 LLM — 纯 static analysis
node bin/codex-sol.js audit -t ./contracts/
```
## 🤖 LLM 集成（GPT-5.4 xhigh）
### 设置
```
# 设置你的 OpenAI API key
export OPENAI_API_KEY="sk-..."
# 或者 inline 传入
node bin/codex-sol.js audit -t ./contracts/ --llm --api-key "sk-..."
```
### LLM 推理带来的提升
| 功能 | 无 LLM | 结合 GPT-5.4 xhigh |
|---------|-------------|---------------------|
| 发现验证 | 仅静态规则 | LLM 确认真阳性，剔除假阳性 |
| 降低假阳性 | 无 | LLM 审查每一个 critical/high 级别发现 |
| 审计综合 | 原始发现列表 | 包含攻击树和利用路径的连贯叙述 |
| 跨合约推理 | 模式匹配 | 跨合约交互的深度逻辑分析 |
| 新型漏洞检测 | 仅限已知模式 | LLM 识别新型漏洞模式 |
| PoC 生成 | 基于模板 | LLM 生成结合上下文的 exploit 合约 |
### 推理强度等级
| 级别 | 速度 | 用例 |
|-------|-------|----------|
| `low` | ~5秒/发现 | 快速分类 |
| `medium` | ~15秒/发现 | 标准审计 |
| `high` | ~30秒/发现 | DeFi 协议（默认） |
| `xhigh` | ~60秒/发现 | 复杂多合约、新型漏洞、TVL 超过 100 万美元 |
### 示例
```
# 使用最大 reasoning 的完整审计
node bin/codex-sol.js audit -t https://github.com/Aave/aave-v3-core \
--llm \
--llm-model gpt-5.4-pro \
--reasoning-effort xhigh \
--network mainnet
```
此命令会产生：
1. **34 项技能** → 静态发现
2. **符号执行** → 污点分析 + 数据流发现
3. **不变量检查器** → 形式化不变量违规
4. **跨合约分析器** → 多文件重入链
5. **🔴 Exploit Engine** → 包含真实攻击代码、链接攻击、被破坏不变量的已证明 exploit
6. **LLM 验证** → 确认真阳性，剔除假阳性
7. **LLM 综合** → 包含攻击树和建议的 `llm-synthesis.md`
8. **Foundry PoC** → 可运行的 `.t.sol` exploit 测试
9. **模糊测试 Harness** → Echidna + Medusa 配置
## 🔴 激进 Exploit Engine
`--aggressive` 标志会激活 Exploit Engine —— 它不仅仅是发现漏洞，更是证明漏洞：
| 功能 | 实现方式 |
|-------------|-----|
| **证明每一个发现** | 为每个漏洞构建真实的 exploit 代码 (Foundry `.t.sol`) |
| **攻击链** | 将低/中危发现组合成关键利用路径 |
| **打破不变量** | 主动尝试打破 `totalSupply == sum(balances)`、仅限所有者的函数、份额由资产支撑 等不变量 |
| **闪电贷模拟** | 模拟对每个依赖价格的函数进行价格操纵攻击 |
| **治理攻击** | 模拟闪电贷治理接管 |
### 检测到的攻击链
| 攻击链 | 结果 |
|-------|--------|
| 只读重入 + 预言机操纵 | 多协议资金抽干 |
| 访问控制 + Delegatecall | 完整合约接管 |
| 舍入误差 + 闪电贷 | 资金库抽干 |
| 未检查返回值 + 重入 | 账务中断资金抽干 |
| 2+ 高危发现 | 组合关键漏洞利用 |
### 用法
```
# Aggressive mode — 证明每个 bug
node bin/codex-sol.js audit -t https://github.com/org/repo --aggressive
# 全功率：aggressive + LLM reasoning
node bin/codex-sol.js audit -t https://github.com/org/repo --aggressive --llm --reasoning-effort xhigh
# 在 Codex CLI 内
codex "aggressively audit https://github.com/org/repo — prove every exploit" --model gpt-5.4-pro
```
### 完整审计流水线
```
Phase 0: Fetch contracts from GitHub URL
Phase 1: AST-parse all .sol files
Phase 2: 34 skills scan (reentrancy, flash-loan, overflow, access-control, etc.)
Phase 2B: Symbolic execution + Invariant checker + Cross-contract + Fuzzing
Phase 2D: 🔴 Exploit Engine — PROVE bugs, chain attacks, break invariants
Phase 2C: GPT-5.4 xhigh — validate findings, generate audit synthesis
Phase 3: Reports (HTML + MD + JSON) + Foundry PoCs + Exploit code + Fuzzing harnesses
```
## 📋 技能（34 个影响驱动模块）
### 核心 DeFi/协议技能
| 技能 | 严重性 | 影响演示 |
|-------|----------|---------------------|
| **reentrancy** | Critical | 资金池完全抽干 — 攻击者存入 1 个 ETH，通过递归回调抽干整个资金池 |
| **flash-loan** | Critical | 单笔交易中的价格操纵 — 借入 10K ETH，操纵资金池，通过套利抽干资金 |
| **access-control** | Critical | 未经授权的所有者函数 — 任何人都可以调用 withdrawAll()、sweep()、mint() |
| **overflow** | Critical | 存入 1 个代币，提取 2 个代币 → 余额下溢至 2^256-1，抽干所有资金 |
| **pool-freeze** | High | 增长数组超过 gas 限制 → 所有用户被永久锁定，资金被永远冻结 |
| **oracle-manipulation** | High | 过时的 Chainlink，无 TWAP → 使用估值过高的抵押品借款，抽干借贷池 |
| **front-running** | High | 无滑点保护 → 每次兑换均被三明治攻击，损失 5-30%，通胀攻击 |
| **delegatecall** | Critical | 用户控制的 delegatecall 目标 → 覆盖所有者，完全接管合约 |
| **self-destruct** | High | 通过 selfdestruct 强制发送 ETH → 破坏账务，抽干或冻结所有资金 |
### Trail of Bits 技能
| 技能 | 严重性 | 影响演示 |
|-------|----------|---------------------|
| **unchecked-returns** | High | 忽略 .call() 返回值 → 静默失败，余额已减少但 ETH 未发送 |
| **shadowing** | High | 子合约重新声明父合约的 `owner` → 写入不同的插槽，父合约所有者保持为 0x0 |
| **pragma-bugs** | High | 浮动 pragma → 使用存在漏洞的编译器进行编译，导致存储损坏 bug |
| **signature-malleability** | High | ECDSA (r,s,v) 和 (r,n-s,v⊕1) 均有效 → 通过可塑性签名进行双重支付 |
| **erc20-assumptions** | High | 转账扣费代币：存入 100，收到 90，却计入贷方 100 → 资不抵债 |
| **timestamp-dependence** | Medium | block.timestamp 被矿工操纵 → 彩票总是被矿工赢走 |
| **storage-pointer** | High | 未初始化的存储变量指向插槽 0 → 覆盖所有者地址 |
| **inheritance-order** | High | C3 线性化：最右侧的父合约覆盖 → 派发了错误的函数 |
| **assembly-issues** | High | 硬编码的 sstore(0, x) 覆盖所有者，extcodesize 绕过，内存损坏 |
### DeFi/协议技能
| 技能 | 严重性 | 影响演示 |
|-------|----------|---------------------|
| **erc4626-vault** | Critical | 通胀攻击：捐赠 ETH → 抬高份额价格 → 受害者获得 0 份额 → 彻底损失 |
| **read-only-reentrancy** | Critical | View 函数在回调期间返回过时数据 → 预言机读取错误值 → 1 亿美元以上损失 |
| **rounding-errors** | High | 先除法后乘法 → 精度丢失 → 攻击者在每笔交易中提取微量资金 |
| **liquidation-attack** | High | 无宽限期 → MEV 闪电贷清算 → 借款人被立即清算 |
| **proxy-upgrade** | Critical | 未初始化的实现合约 → 任何人调用 initialize() → 合约接管 |
| **amm-math** | High | 无 k 不变量检查 → 兑换在不维持恒定乘积的情况下抽干储备金 |
| **reward-manipulation** | High | 质押/申领/解除质押循环 → 在无需时间投入的情况下抽干奖励 |
| **bridge-vulnerability** | Critical | 无消息 ID 跟踪 → 重放相同消息 → 二次抽干跨链桥流动性 |
| **donation-attack** | High | 直接代币转账抬高份额价格 → 受害者存入资金，获得 0 份额 |
| **eip-2612-permit** | High | 域中无链 ID → 许可在 L2 之间重放 → 其他链上的代币被盗 |
| **nft-reentrancy** | High | 在 safeTransferFrom 期间 onERC721Received 回调重入 → 绕过 ETH 防护 |
| **token-uri-manipulation** | Medium | 链上 NFT 中的 SVG XSS → 窃取市场用户 cookies |
| **soulbound-bypass** | Medium | safeTransferFrom 未被阻止 → “不可转移”的 SBT 实际上可转移 |
| **l2-sequencer** | High | Sequencer 宕机 → Chainlink 冻结 → 以过时价格借款 → 抽干资金池 |
| **gas-griefing** | Medium | 循环中的外部调用 → 增大数组超过 gas 限制 → 永久性 DOS |
| **gas-optimization** | Low | 循环中的存储读取 → gas 浪费，并且当循环修改同一变量时隐藏了逻辑缺陷 |
## 🎯 核心影响场景
### 1. 资金抽干（资金池彻底被盗）
- **重入：** 存入 1 ETH → 递归提取 → 抽干整个资金池
- **溢出/下溢：** 存入 1，提取 2 → 余额包装为 2^256-1 → 提取一切
- **访问控制：** 调用未受保护的 withdrawAll() → 盗取所有资金
- **闪电贷：** 借入 10K ETH → 操纵价格 → 通过套利抽干（零风险，单笔交易）
### 2. 用户池冻结（永久性资金锁定）
- **无限循环 DOS：** 增大数组超过 gas 限制 → withdraw() 永久失败
- **推送支付 DOS：** 一个回滚的接收者会阻塞所有支付
- **强制喂给：** 通过 selfdestruct 将 ETH 强制打入合约 → 打破余额不变量 → 所有操作回滚
- **有暂停无恢复：** pause() 却没有 unpause() → 资金被永远锁定
### 3. 攻击者提取超过存入金额
- **下溢：** balances[user] -= amount， amount > balance → 包装为 2^256-1
- **首批存款者/通胀：** 在受害者存入之前捐赠代币 → 受害者获得 0 份额
- **预言机操纵：** 伪造价格 → 借入超量抵押品
- **Address(this).balance：** 强制注入 ETH → 提取超过记录的存款金额
## 🏗️ 架构
```
codex-solidity/
├── bin/codex-sol.js # CLI entry (commander)
├── lib/
│ ├── agent.js # Orchestrator: parse → skills → correlate → PoC → report
│ ├── parser.js # AST parser (@solidity-parser/parser) + regex fallback
│ ├── skill-loader.js # Auto-discovers skills from /skills
│ ├── impact-engine.js # Calculates drain amounts, generates exploit contracts
│ ├── mcp.js # MCP: SWC Registry + DeFiLlama intelligence
│ ├── foundry-poc.js # Auto-generates Foundry .t.sol exploit test cases
│ ├── correlation-engine.js # Cross-skill correlation: links combined exploit paths
│ ├── dynamic-severity.js # Context-aware severity scoring (TVL, visibility, exploitability)
│ ├── external-tool-parser.js # Normalizes Slither/Aderyn/Mythril JSON into Codex format
│ ├── ci-integration.js # CI mode, SARIF output, GitHub Actions workflow generator
│ ├── diff-auditor.js # Git diff: only audit changed functions between refs
│ ├── interactive-mode.js # REPL: drill into findings, re-score, generate PoCs
│ ├── symbolic-executor.js # Symbolic execution: taint analysis, data-flow, path constraints
│ ├── fuzzing-engine.js # Echidna + Medusa harness generator, invariant derivation
│ ├── invariant-checker.js # Formal invariant verification (access, accounting, reentrancy)
│ ├── shared-state.js # Cross-skill shared state: skills read each other's findings in real-time
│ ├── cross-contract-analyzer.js # Multi-file reentrancy chains, composability, state deps
│ ├── llm-reasoner.js # GPT-5.4 xhigh: finding validation, audit synthesis, exploit PoC
│ ├── github-fetcher.js # Fetch contracts from GitHub URLs (repo/tree/blob/raw)
│ ├── exploit-engine.js # 🔴 Aggressive: prove exploits, chain attacks, break invariants
│ └── report-generator.js # HTML (dark) + Markdown + JSON reports
├── skills/
│ ├── reentrancy/index.js # Reentrancy — recursive callback fund drain
│ ├── flash-loan/index.js # Flash Loan — price manipulation, pool drain
│ ├── access-control/index.js # Access Control — unauthorized privileged functions
│ ├── overflow/index.js # Integer Overflow/Underflow — balance wrapping
│ ├── pool-freeze/index.js # Pool Freeze / DOS — permanent fund lock
│ ├── oracle-manipulation/index.js # Oracle — stale/fake price exploitation
│ ├── front-running/index.js # MEV — sandwich, slippage, inflation attack
│ ├── delegatecall/index.js # Delegatecall — storage collision, proxy takeover
│ ├── self-destruct/index.js # Self-Destruct — force feed, accounting break
│ │
│ │ # Trail of Bits skills
│ ├── unchecked-returns/index.js # Unchecked .call()/.send() return values
│ ├── shadowing/index.js # State variable shadowing in inheritance
│ ├── pragma-bugs/index.js # Floating pragma & known compiler bugs
│ ├── signature-malleability/index.js # ECDSA signature malleability & replay
│ ├── erc20-assumptions/index.js # Fee-on-transfer, rebasing, non-standard tokens
│ ├── timestamp-dependence/index.js # block.timestamp manipulation
│ ├── storage-pointer/index.js # Uninitialized storage pointers
│ ├── inheritance-order/index.js # C3 linearization & missing super calls
│ └── assembly-issues/index.js # Inline assembly vulnerabilities
│ │
│ │ # DeFi/Protocol skills
│ ├── erc4626-vault/index.js # ERC4626 vault inflation/rounding attacks
│ ├── read-only-reentrancy/index.js # Read-only reentrancy via view functions
│ ├── rounding-errors/index.js # Division-before-multiplication precision loss
│ ├── liquidation-attack/index.js # Cascade liquidation & MEV front-running
│ ├── proxy-upgrade/index.js # UUPS/Transparent proxy vulnerabilities
│ ├── amm-math/index.js # AMM constant product invariant violations
│ ├── reward-manipulation/index.js # Staking reward gaming & double claims
│ ├── bridge-vulnerability/index.js # Cross-chain message replay & validator attacks
│ ├── donation-attack/index.js # Direct transfer inflation attack
│ ├── eip-2612-permit/index.js # Permit replay & signature validation
│ ├── nft-reentrancy/index.js # ERC721/ERC1155 callback reentrancy
│ ├── token-uri-manipulation/index.js # SVG XSS & metadata manipulation
│ ├── soulbound-bypass/index.js # SBT transfer restriction bypass
│ ├── l2-sequencer/index.js # L2 sequencer downtime oracle freeze
│ ├── gas-griefing/index.js # Gas DOS & external call in loop
│ └── gas-optimization/index.js # Gas optimization reveals hidden logic flaws
├── .agents/skills/audit-pro/
│ ├── SKILL.md # Audit workflow: recon → analysis → PoC → report
│ ├── scripts/static_scan.sh # Bridge to Slither/Aderyn/Codex
│ └── references/report_template.md # Sherlock/Immunefi submission template
├── config.toml # Agent config: model, reasoning_effort, MCP servers
├── AGENTS.md # Durable auditor persona instructions
├── config/default.yaml
├── package.json
└── README.md
```
## ⚙️ CLI 选项
```
audit -t, --target Path to .sol file or directory (required)
-s, --skills
- Comma-separated skills (default: all)
-o, --output
- Paths to exclude
--ci CI mode: non-zero exit if findings above threshold
--fail-on
标签：CISA项目, CLI, DeFi安全, DLL 劫持, Echidna, Foundry, GitHub安全, GPT, Medusa, MITM代理, PoC生成, Solidity, Web3安全, WiFi技术, 不变性检查, 代码分析, 代码安全, 凭证管理, 加密货币, 区块链安全, 合约漏洞, 大语言模型, 对称加密, 形式化验证, 攻击模拟, 数据展示, 智能合约审计, 漏洞枚举, 漏洞管理, 符号执行, 红队, 网络安全, 自动化审计, 自定义脚本, 请求拦截, 资金安全, 跨合约分析, 重入攻击, 隐私保护, 驱动签名利用