Josh9281/defi-sentinel
GitHub: Josh9281/defi-sentinel
一款基于链上数据与 AI Agent 的 DeFi 合约 rug-pull 和漏洞利用风险自动分析工具，输入合约地址即可在 60 秒内生成带引用来源的风险报告。
Stars: 0 | Forks: 0
# DeFi Sentinel
利用链上数据和 AI 自动化进行 rug-pull 风险分析。
输入一个合约地址。60 秒内获取附带引用来源的风险报告。
## 架构
```
POST /api/investigate
└─► Django creates Case record (UUID)
└─► Temporal workflow starts
├─ Activity 1: Etherscan V2 (deployer, source verification, holders, recent txs)
├─ Activity 2: Rekt News RSS (exploit history matching)
├─ Activity 3: DeFiHackLabs + Slowmist (audit / hack records)
├─ Activity 4: OpenAI Agents SDK (gpt-4o, structured output → cited disposition)
└─ Activity 5: Persist disposition + evidence to PostgreSQL
GET /api/case/{id}
└─► Returns disposition + evidence with source citations
```
## 技术栈
| 层级 | 技术 |
| ---------------- | -------------------------------------------- |
| 后端 | Django 4.2 + DRF |
| 编排 | Temporal（持久化工作流执行） |
| AI Agent | OpenAI Agents SDK（gpt-4o，结构化输出）|
| 数据库 | PostgreSQL 15 |
| 链上数据 | Etherscan V2 API（Ethereum 主网） |
## 快速开始
```
# 1. 启动 Temporal + Postgres
docker-compose up -d
# 2. Python 环境 (3.11+，已在 3.13 上测试)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 3. 配置 secrets
cp .env.example .env
# 编辑 .env：设置 ETHERSCAN_API_KEY 和 OPENAI_API_KEY
# 4. 迁移数据库
python manage.py migrate
# 5. 启动 Temporal worker (终端 1)
python workflows/worker.py
# 6. 启动 Django (终端 2)
python manage.py runserver
```
打开 访问 UI。
打开 访问 Temporal Web UI。
## 冒烟测试
```
curl -X POST http://localhost:8000/api/investigate \
-H "Content-Type: application/json" \
-d '{"contract_address":"0x1F98431c8aD98523631AE4a59f267346ea31F984","protocol_name":"Uniswap V3 Factory"}'
# → {"case_id": "...", "status": "running", "poll_url": "/api/case/..."}
curl http://localhost:8000/api/case/
# 轮询直到 status == "complete"
```
## 验证
```
python scripts/backtest.py
```
针对 3 个已知的 Ethereum 主网攻击受害者和 3 个已知的合法协议运行完整 pipeline。
| 协议 | 真实状态 | 预测结果 | 分数 | 是否匹配 |
| ------------------ | ---------- | ---------- | ----- | ----- |
| BeanstalkFarms | COMPROMISED | CRITICAL | 90 | ✓ |
| EulerFinance | COMPROMISED | CRITICAL | 90 | ✓ |
| Nomad Bridge | COMPROMISED | CRITICAL | 90 | ✓ |
| Uniswap V3 Factory | LEGITIMATE | LOW | 20 | ✓ |
| Aave V3 Pool | LEGITIMATE | LOW | 20 | ✓ |
| Compound V3 USDC | LEGITIMATE | LOW | 20 | ✓ |
**准确率：6/6 (100%)** — 确认受到攻击的项目通过 DeFiHackLabs 匹配被标记为 CRITICAL；合法协议则基于验证和良好的 30 天活动记录被标记为 LOW。
注意：最初的 PRD 主要针对 rug-pull 合约（AnubisDAO, Frosties），但 PRD 中列出的这两个地址从未在 Ethereum 主网上部署过——它们要么是错误的地址，要么是 BSC 合约。回测使用了 DeFiHackLabs 实际追踪的三个真实的 ETH 主网攻击受害者，这测试了相同的信号路径（`hack_references` → CRITICAL）。
## 局限性
- 仅支持 Ethereum 主网 — BSC、Polygon、Arbitrum 需要不同的区块链浏览器 API。
- 风险评分是启发式的，不构成财务建议。
- Etherscan 的 `tokenholderlist` endpoint 属于付费层级；在使用免费 key 时，持币者分布证据将被报告为“不可用”，Agent 将在没有该项数据的情况下进行推理。
- Rekt News RSS 有时会不可用（rekt.news 宕机）；发生这种情况时，工作流会优雅降级。
- 前端仅支持桌面端。
## License
MIT
标签：DeFi, Django, 区块链安全, 智能合约审计, 请求拦截, 逆向工具