athena-mcp 1.0.5 → 1.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +133 -114
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -25,6 +25,130 @@
|
|
|
25
25
|
|
|
26
26
|
将该文档复制给你的 agent，它将自动理解项目价值。
|
|
27
27
|
|
|
28
|
+
## Installation (Claude Code)
|
|
29
|
+
|
|
30
|
+
### Option A: npm (recommended)
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx athena-mcp install
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
This will:
|
|
37
|
+
1. Clone Athena to `~/.athena/`
|
|
38
|
+
2. Install Python dependencies (slither, web3, chromadb, etc.)
|
|
39
|
+
3. Install system tools (Slither, Aderyn, Foundry)
|
|
40
|
+
4. Copy the audit skill to `~/.claude/skills/athena-audit-skill/`
|
|
41
|
+
5. Configure 14 MCP servers in Claude Code
|
|
42
|
+
|
|
43
|
+
### Option B: curl install script
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
curl -fsSL https://athena.degure.me/install.sh | bash
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Or from GitHub directly:
|
|
50
|
+
```bash
|
|
51
|
+
curl -fsSL https://raw.githubusercontent.com/tiyadegure/Athena/main/install.sh | bash
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Options:
|
|
55
|
+
```bash
|
|
56
|
+
SKIP_DEPS=1 curl ... | bash # Skip Python deps
|
|
57
|
+
SKIP_SYSTEM=1 curl ... | bash # Skip slither/aderyn/foundry
|
|
58
|
+
SKIP_CLAUDE=1 curl ... | bash # Skip Claude Code config
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Option C: Manual
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# 1. Clone
|
|
65
|
+
git clone https://github.com/tiyadegure/Athena.git ~/.athena
|
|
66
|
+
cd ~/.athena
|
|
67
|
+
|
|
68
|
+
# 2. Python deps
|
|
69
|
+
pip install -r requirements.txt
|
|
70
|
+
|
|
71
|
+
# 3. System tools
|
|
72
|
+
pip install slither-analyzer
|
|
73
|
+
cargo install aderyn # requires Rust
|
|
74
|
+
curl -L https://foundry.paradigm.xyz | bash && foundryup
|
|
75
|
+
|
|
76
|
+
# 4. Copy skill
|
|
77
|
+
cp -r skills/glm-audit-skill ~/.claude/skills/athena-audit-skill
|
|
78
|
+
|
|
79
|
+
# 5. Register MCP servers (one per tool)
|
|
80
|
+
claude mcp add athena-slither -- python3 ~/.athena/mcp/tools/slither_runner.py
|
|
81
|
+
claude mcp add athena-aderyn -- python3 ~/.athena/mcp/tools/aderyn_runner.py
|
|
82
|
+
claude mcp add athena-poc-generator -- python3 ~/.athena/mcp/tools/poc_generator.py
|
|
83
|
+
claude mcp add athena-fuzz-runner -- python3 ~/.athena/mcp/tools/fuzz_runner.py
|
|
84
|
+
claude mcp add athena-knowledge-base -- python3 ~/.athena/mcp/tools/knowledge_base.py
|
|
85
|
+
claude mcp add athena-eas-attest -- python3 ~/.athena/mcp/tools/eas_attest.py
|
|
86
|
+
claude mcp add athena-exploit-simulator -- python3 ~/.athena/mcp/tools/exploit_simulator.py
|
|
87
|
+
claude mcp add athena-evidence-chain -- python3 ~/.athena/mcp/tools/evidence_chain.py
|
|
88
|
+
claude mcp add athena-halmos-runner -- python3 ~/.athena/mcp/tools/halmos_runner.py
|
|
89
|
+
claude mcp add athena-protocol-scanner -- python3 ~/.athena/mcp/tools/protocol_scanner.py
|
|
90
|
+
claude mcp add athena-repair-validator -- python3 ~/.athena/mcp/tools/repair_validator.py
|
|
91
|
+
claude mcp add athena-incremental-auditor -- python3 ~/.athena/mcp/tools/incremental_auditor.py
|
|
92
|
+
claude mcp add athena-gev-analyzer -- python3 ~/.athena/mcp/tools/gev_analyzer.py
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Quick Start (after install)
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# 1. Install
|
|
99
|
+
npx athena-mcp install
|
|
100
|
+
|
|
101
|
+
# 2. Environment setup (for on-chain attestation + NFT minting)
|
|
102
|
+
export SEPOLIA_PRIVATE_KEY="0xYourPrivateKey"
|
|
103
|
+
export SEPOLIA_RPC_URL="https://rpc.sepolia.org" # or Alchemy/Infura
|
|
104
|
+
|
|
105
|
+
# 3. Full audit flow (scan → PoC → EAS attestation → NFT mint)
|
|
106
|
+
claude "audit contracts/test-cases/Reentrancy.sol and mint NFT certificate"
|
|
107
|
+
|
|
108
|
+
# 4. Scan-only (static analysis, no on-chain actions)
|
|
109
|
+
claude "scan contracts/test-cases/Reentrancy.sol with slither and aderyn"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**What happens:**
|
|
113
|
+
- Slither + Aderyn dual-engine static analysis
|
|
114
|
+
- PoC generation + Foundry fuzz testing
|
|
115
|
+
- EAS attestation on Sepolia (on-chain audit record)
|
|
116
|
+
- NFT certificate minting (ERC-1155, S/A/B/C tiers)
|
|
117
|
+
- Verification links to Etherscan + EAS explorer
|
|
118
|
+
|
|
119
|
+
### Try Different Contracts
|
|
120
|
+
|
|
121
|
+
Pre-crawled test contracts with known vulnerabilities. Each includes difficulty level and expected findings.
|
|
122
|
+
|
|
123
|
+
**Beginner**
|
|
124
|
+
- `contracts/test-cases/Reentrancy.sol` — Classic reentrancy (external call before state update)
|
|
125
|
+
- `contracts/test-cases/AccessControl.sol` — Missing access control (unprotected mint/burn/transfer)
|
|
126
|
+
- `contracts/test-cases/SafeContract.sol` — Reference contract with NO vulnerabilities (false positive test)
|
|
127
|
+
|
|
128
|
+
**Intermediate**
|
|
129
|
+
- `contracts/test-cases/FlashLoan.sol` — Flash loan price manipulation (spot-price oracle, no TWAP)
|
|
130
|
+
- `contracts/test-cases/IntegerOverflow.sol` — Integer overflow in unchecked blocks
|
|
131
|
+
- `contracts/test-cases/AgentEscrow.sol` — Agent-to-agent escrow (reentrancy + missing state checks)
|
|
132
|
+
- `contracts/test-cases/AgentIdentity.sol` — AI agent identity (reputation manipulation)
|
|
133
|
+
|
|
134
|
+
**Advanced**
|
|
135
|
+
- `contracts/test-cases/ReadOnlyReentrancy.sol` — Read-only reentrancy (Curve/Balancer 2023 style)
|
|
136
|
+
- `contracts/test-cases/PrivacyToken.sol` — Privacy token (ZK proof bypass, merkle manipulation)
|
|
137
|
+
- `contracts/test-cases/GEVTest.sol` — Generalized Extractable Value (MEV, oracle, governance)
|
|
138
|
+
|
|
139
|
+
Quick commands:
|
|
140
|
+
```bash
|
|
141
|
+
# Beginner
|
|
142
|
+
claude "audit contracts/test-cases/AccessControl.sol and mint NFT certificate"
|
|
143
|
+
|
|
144
|
+
# Intermediate
|
|
145
|
+
claude "audit contracts/test-cases/FlashLoan.sol and mint NFT certificate"
|
|
146
|
+
|
|
147
|
+
# Advanced
|
|
148
|
+
claude "audit contracts/test-cases/ReadOnlyReentrancy.sol and mint NFT certificate"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
28
152
|
## 核心工作流（8 步闭环）
|
|
29
153
|
|
|
30
154
|
```
|
|
@@ -80,7 +204,7 @@
|
|
|
80
204
|
自建 `athena-audit-skill`，10 轮检查流程：
|
|
81
205
|
scope → architecture → access control → reentrancy → math → oracle → flash loan → governance → upgrade → report
|
|
82
206
|
|
|
83
|
-
### MCP（工具链）—
|
|
207
|
+
### MCP（工具链）— 14 个工具
|
|
84
208
|
|
|
85
209
|
| 工具 | 脚本 | 功能 |
|
|
86
210
|
|------|------|------|
|
|
@@ -113,7 +237,7 @@ scope → architecture → access control → reentrancy → math → oracle →
|
|
|
113
237
|
|------|------|------|
|
|
114
238
|
| **GLM-5.1** | Z.AI Coding Plan | 驱动 Agent，处理长程任务 |
|
|
115
239
|
| **athena-audit-skill** | 自建 | 12 个专项 agent 并行审计方法论 |
|
|
116
|
-
| **MCP 工具链（
|
|
240
|
+
| **MCP 工具链（14 个）** | 自建 | 静态分析、PoC 生成、fuzz 测试、知识库、链上认证等 |
|
|
117
241
|
| **Foundry** | foundry-rs | 合约编译、测试、fuzz |
|
|
118
242
|
| **EAS** | Ethereum Attestation Service | 链上审计认证 |
|
|
119
243
|
| **ERC-1155** | OpenZeppelin | 分级 NFT 审计证书 |
|
|
@@ -185,118 +309,12 @@ Athena/
|
|
|
185
309
|
- AuditTrail (Sepolia): https://sepolia.etherscan.io/address/0xd7913e7749595a9238883bdf0b2dad599f4d0bf0
|
|
186
310
|
- EAS 认证: https://sepolia.easscan.org/attestation/view/0xd02800c960f18f0483af4aa320aff314e34c5a83d1c9a9c963b299a88af958b9
|
|
187
311
|
|
|
188
|
-
## Installation (Claude Code)
|
|
189
|
-
|
|
190
|
-
### Option A: npm (recommended)
|
|
191
|
-
|
|
192
|
-
```bash
|
|
193
|
-
npx athena-mcp install
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
This will:
|
|
197
|
-
1. Clone Athena to `~/.athena/`
|
|
198
|
-
2. Install Python dependencies (slither, web3, chromadb, etc.)
|
|
199
|
-
3. Install system tools (Slither, Aderyn, Foundry)
|
|
200
|
-
4. Copy the audit skill to `~/.claude/skills/athena-audit-skill/`
|
|
201
|
-
5. Configure 14 MCP servers in Claude Code
|
|
202
|
-
|
|
203
|
-
### Option B: curl install script
|
|
204
|
-
|
|
205
|
-
```bash
|
|
206
|
-
curl -fsSL https://athena.degure.me/install.sh | bash
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
Or from GitHub directly:
|
|
210
|
-
```bash
|
|
211
|
-
curl -fsSL https://raw.githubusercontent.com/tiyadegure/Athena/main/install.sh | bash
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
Options:
|
|
215
|
-
```bash
|
|
216
|
-
SKIP_DEPS=1 curl ... | bash # Skip Python deps
|
|
217
|
-
SKIP_SYSTEM=1 curl ... | bash # Skip slither/aderyn/foundry
|
|
218
|
-
SKIP_CLAUDE=1 curl ... | bash # Skip Claude Code config
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
### Option C: Manual
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
# 1. Clone
|
|
225
|
-
git clone https://github.com/tiyadegure/Athena.git ~/.athena
|
|
226
|
-
cd ~/.athena
|
|
227
|
-
|
|
228
|
-
# 2. Python deps
|
|
229
|
-
pip install -r requirements.txt
|
|
230
|
-
|
|
231
|
-
# 3. System tools
|
|
232
|
-
pip install slither-analyzer
|
|
233
|
-
cargo install aderyn # requires Rust
|
|
234
|
-
curl -L https://foundry.paradigm.xyz | bash && foundryup
|
|
235
|
-
|
|
236
|
-
# 4. Copy skill
|
|
237
|
-
cp -r skills/glm-audit-skill ~/.claude/skills/athena-audit-skill
|
|
238
|
-
|
|
239
|
-
# 5. Register MCP servers (one per tool)
|
|
240
|
-
claude mcp add athena-slither -- python3 ~/.athena/mcp/tools/slither_runner.py
|
|
241
|
-
claude mcp add athena-aderyn -- python3 ~/.athena/mcp/tools/aderyn_runner.py
|
|
242
|
-
claude mcp add athena-poc-generator -- python3 ~/.athena/mcp/tools/poc_generator.py
|
|
243
|
-
claude mcp add athena-fuzz-runner -- python3 ~/.athena/mcp/tools/fuzz_runner.py
|
|
244
|
-
claude mcp add athena-knowledge-base -- python3 ~/.athena/mcp/tools/knowledge_base.py
|
|
245
|
-
claude mcp add athena-eas-attest -- python3 ~/.athena/mcp/tools/eas_attest.py
|
|
246
|
-
claude mcp add athena-exploit-simulator -- python3 ~/.athena/mcp/tools/exploit_simulator.py
|
|
247
|
-
claude mcp add athena-evidence-chain -- python3 ~/.athena/mcp/tools/evidence_chain.py
|
|
248
|
-
claude mcp add athena-halmos-runner -- python3 ~/.athena/mcp/tools/halmos_runner.py
|
|
249
|
-
claude mcp add athena-protocol-scanner -- python3 ~/.athena/mcp/tools/protocol_scanner.py
|
|
250
|
-
claude mcp add athena-repair-validator -- python3 ~/.athena/mcp/tools/repair_validator.py
|
|
251
|
-
claude mcp add athena-incremental-auditor -- python3 ~/.athena/mcp/tools/incremental_auditor.py
|
|
252
|
-
claude mcp add athena-gev-analyzer -- python3 ~/.athena/mcp/tools/gev_analyzer.py
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
### Quick Start (after install)
|
|
256
|
-
|
|
257
|
-
```bash
|
|
258
|
-
# 1. Configure environment for on-chain attestation + NFT minting
|
|
259
|
-
export SEPOLIA_PRIVATE_KEY="0x你的测试网私钥"
|
|
260
|
-
export SEPOLIA_RPC_URL="https://rpc.sepolia.org"
|
|
261
|
-
|
|
262
|
-
# 2. Full audit flow (scan → PoC → EAS attestation → NFT mint)
|
|
263
|
-
claude "audit contracts/test-cases/Reentrancy.sol and mint NFT certificate"
|
|
264
|
-
|
|
265
|
-
# Or just scan without on-chain steps
|
|
266
|
-
claude "scan contracts/test-cases/Reentrancy.sol with slither and aderyn"
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
**What happens:**
|
|
270
|
-
- Slither + Aderyn static analysis
|
|
271
|
-
- PoC generation + Foundry fuzz testing
|
|
272
|
-
- EAS attestation on Sepolia (on-chain audit record)
|
|
273
|
-
- NFT certificate minting (ERC-1155, S/A/B/C tiers)
|
|
274
|
-
- Verification links to Etherscan + EAS explorer
|
|
275
|
-
|
|
276
|
-
---
|
|
277
312
|
|
|
278
313
|
## 快速开始（中文）
|
|
279
314
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
```bash
|
|
283
|
-
# 1. 安装
|
|
284
|
-
npx athena-mcp install
|
|
285
|
-
|
|
286
|
-
# 2. 配置环境变量（用于 EAS 上链 + NFT 铸造）
|
|
287
|
-
export SEPOLIA_PRIVATE_KEY="0x你的测试网私钥"
|
|
288
|
-
export SEPOLIA_RPC_URL="https://rpc.sepolia.org"
|
|
315
|
+
Athena 的审计流程由 AI Agent（GLM-5.1）驱动，不是简单的脚本调用。Agent 读取 `AGENT-WORKFLOW-FINAL.md`，自主执行 8 步闭环。
|
|
289
316
|
|
|
290
|
-
|
|
291
|
-
claude "审计 contracts/test-cases/Reentrancy.sol 并铸造 NFT 证书"
|
|
292
|
-
|
|
293
|
-
# 或只做漏洞扫描
|
|
294
|
-
claude "用 slither 和 aderyn 扫描 contracts/test-cases/Reentrancy.sol"
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
Claude Code 会自动发现并调用 14 个 MCP 工具，完成从漏洞发现到链上认证的完整闭环。
|
|
298
|
-
|
|
299
|
-
### 方式二：GLM-5.1 Agent
|
|
317
|
+
### 方式一：用 GLM-5.1 Agent 驱动（推荐）
|
|
300
318
|
|
|
301
319
|
```bash
|
|
302
320
|
# 1. 克隆项目
|
|
@@ -309,13 +327,14 @@ curl -L https://foundry.paradigm.xyz | bash # Foundry
|
|
|
309
327
|
|
|
310
328
|
# 3. 配置环境变量
|
|
311
329
|
export SEPOLIA_PRIVATE_KEY="0x你的测试网私钥"
|
|
312
|
-
export SEPOLIA_RPC_URL="https://rpc.sepolia.org"
|
|
330
|
+
export SEPOLIA_RPC_URL="https://rpc.sepolia.org" # 或 Alchemy/Infura
|
|
313
331
|
|
|
314
|
-
# 4. 用 GLM-5.1
|
|
332
|
+
# 4. 用 GLM-5.1 Agent 执行审计
|
|
315
333
|
# 将 AGENT-WORKFLOW-FINAL.md 的内容作为 prompt 发送给 GLM-5.1
|
|
334
|
+
# Agent 会自主执行：扫描 → PoC → Fuzz → EAS 上链 → NFT 铸造
|
|
316
335
|
```
|
|
317
336
|
|
|
318
|
-
|
|
337
|
+
Agent 会读取 `AGENT-WORKFLOW-FINAL.md`，按照 6 个 Phase 逐步执行，每一步验证通过后才继续下一步，最终输出链上验证链接和本地审计文件。
|
|
319
338
|
|
|
320
339
|
### 方式二：手动逐步执行
|
|
321
340
|
|
|
@@ -424,7 +443,7 @@ cast send 0x3247d57d37bd1878479f03a077aba807649dbaf5 \
|
|
|
424
443
|
|
|
425
444
|
- [x] 竞品调研（20 个项目）
|
|
426
445
|
- [x] 构建 athena-audit-skill（12 agent 并行审计）
|
|
427
|
-
- [x] 构建
|
|
446
|
+
- [x] 构建 14 个独立 MCP 工具
|
|
428
447
|
- [x] Generative NFT（S/A/B/C 四级，262,144 种 trait 组合）
|
|
429
448
|
- [x] 部署 5 个合约到 Sepolia 测试网（AuditCertificate + ZK + Escrow + ERC-7512）
|
|
430
449
|
- [x] EAS Schema 注册 + Attestation 上链
|