aswathas/Project-Hail-Mary
GitHub: aswathas/Project-Hail-Mary
一款端到端 EVM 区块链取证工具，通过本地化分析解决链上攻击调查的可追溯性与证据完整性问题。
Stars: 0 | Forks: 0
# ChainSentinel
**EVM 区块链取证工具** — 端到端调查链上漏洞利用。
给定一个交易哈希、钱包地址或区块范围，ChainSentinel 将运行完整的取证流水线：收集原始链数据、解码数据、推导安全事件、通过 ES|QL 运行 20 种启发式信号检测、通过 EQL 匹配 4 种复合攻击模式、追踪 5 跳内的资金流向、聚类攻击者钱包，并在带有 Ollama 驱动的协办的 React 调查工作区中呈现结果，该协办可生成 7 部分取证报告。
为 SISA 构建。完全离线运行 — 无云依赖。
## 快速开始
### 先决条件
| 工具 | 安装 |
|------|------|
| Docker | [docker.com](https://docs.docker.com/get-docker/) |
| Python 3.11+ | `sudo apt install python3.11 python3.11-venv` |
| Node 18+ | `curl -fsSL https://deb.nodesource.com/setup_18.x \| sudo -E bash - && sudo apt install -y nodejs` |
| Foundry (Anvil) | `curl -L https://foundry.paradigm.xyz \| bash && foundryup` |
| Ollama | `curl -fsSL https://ollama.com/install.sh \| sh` |
### 一键启动
```
cd chainsentinel
chmod +x start.sh
./start.sh
```
在浏览器中打开 **http://localhost:5173**。
### 手动启动（5 个终端）
**终端 1 — Elasticsearch：**
```
docker run -d --name chainsentinel-es -p 9200:9200 \
-e "discovery.type=single-node" \
-e "xpack.security.enabled=false" \
-e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
elasticsearch:8.12.0
```
**终端 2 — Ollama：**
```
ollama serve
# 在另一个标签页或服务启动后：
ollama pull gemma3:1b
```
**终端 3 — Anvil（本地 EVM 节点）：**
```
anvil --chain-id 31337
```
**终端 4 — 后端（FastAPI）：**
```
cd chainsentinel
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 8000 --reload
```
**终端 5 — 前端（React）：**
```
cd chainsentinel/frontend
npm install
npm run dev
```
打开 **http://localhost:5173**
## 运行演示
### 第一步：部署模拟
在 Anvil 运行后，部署以下 4 种攻击场景之一：
```
cd simulations
# 重入漏洞排水（测试 AP-005）
forge script scenarios/reentrancy-drain/script/RunAll.s.sol \
--rpc-url http://127.0.0.1:8545 --broadcast
# 闪电贷预言机操纵（测试 AP-001）
forge script scenarios/flash-loan-oracle/script/RunAll.s.sol \
--rpc-url http://127.0.0.1:8545 --broadcast
# 管理员密钥滥用（测试 AP-008）
forge script scenarios/admin-key-abuse/script/RunAll.s.sol \
--rpc-url http://127.0.0.1:8545 --broadcast
# MEV 三明治攻击（测试 AP-014）
forge script scenarios/mev-sandwich/script/RunAll.s.sol \
--rpc-url http://127.0.0.1:8545 --broadcast
```
每个脚本会打印交易哈希 — 复制一个攻击交易哈希。
### 第二步：在 UI 中分析
1. 打开 http://localhost:5173
2. 验证所有 3 个连接点（RPC、Elasticsearch、Ollama）为绿色
3. 选择 **Tx Analysis** 模式
4. 粘贴攻击交易哈希
5. 点击 **Run Analysis**
6. 观察流水线流式输出：
- Collector 获取原始交易数据
- Normalizer 标准化类型
- Decoder 匹配 ABI 签名
- Derived builder 生成安全事件
- Signal engine 触发 ES|QL 启发式
- Pattern engine 匹配攻击序列
7. 自动切换到 **Investigation View**，展示：
- 按严重性着色的攻击时间线
- 已触发信号及其分数
- 实体图谱（攻击者红色、协议蓝色）
- 元栏显示攻击者地址、受害合约、 drained 资金
### 第三步：使用协办
分析完成后，使用右侧面板：
- 点击 **“What signals fired”** 获取信号解释
- 点击 **“Generate Report”** 生成 7 部分取证报告
- 询问关于调查的自由格式问题
### 第四步：尝试范围分析
```
# 运行模拟后，扫描所有区块：
# 在 UI 中：选择范围模式，from_block: 0，to_block: 20
# 点击运行分析
```
## 架构
```
RPC (Anvil/Testnet/Mainnet)
|
v
Collector --> raw txs, receipts, logs, traces
|
v --> ES: forensics-raw
Normalizer --> hex->int, addresses lowercase, timestamps ISO 8601
|
v
Decoder --> ABI decode (case ABIs -> standards -> protocols -> selector cache)
|
v --> ES: forensics (layer: decoded)
Derived Event Builder --> 9 security event types
|
v --> ES: forensics (layer: derived)
Signal Engine --> runs 20 .esql queries
|
v --> ES: forensics (layer: signal)
Pattern Engine --> runs 4 .eql sequence queries
|
v --> ES: forensics (layer: alert)
Correlation --> fund tracing + wallet clustering
|
v --> ES: forensics (layer: attacker)
```
### 关键设计原则
- **Python 是数据管道** — 将数据从链传输到 ES
- **ES 是大脑** — 信号检测和模式匹配使用 ES|QL 与 EQL 查询
- **新增信号** = 在 `detection/signals/` 中添加 `.esql` 文件
- **新增模式** = 在 `detection/patterns/` 中添加 `.eql` 文件
- **证据完整性** — 原始链数据永不修改，单独索引
- **可重现** — 重新运行分析不会产生重复数据
## 项目结构
```
Project_Hail_Mary/
├── chainsentinel/ # The forensic tool
│ ├── config.json # Single source of truth
│ ├── server.py # FastAPI + SSE streaming
│ ├── start.sh # One-command startup
│ ├── requirements.txt
│ │
│ ├── pipeline/ # Data pipeline (Plan 1)
│ │ ├── collector.py # RPC data fetching
│ │ ├── normalizer.py # Type normalization
│ │ ├── decoder.py # ABI decoding
│ │ ├── derived.py # Security event builder
│ │ ├── ingest.py # ES bulk ingest
│ │ ├── runner.py # Pipeline orchestrator
│ │ └── abi_registry/ # ERC20, protocols, case ABIs
│ │
│ ├── detection/ # Detection engine (Plan 2)
│ │ ├── signal_engine.py # Runs .esql files
│ │ ├── pattern_engine.py # Runs .eql files
│ │ ├── signals/ # 20 ES|QL signal queries
│ │ └── patterns/ # 4 EQL attack patterns
│ │
│ ├── correlation/ # Correlation engine (Plan 3)
│ │ ├── fund_trace.py # BFS 5-hop fund tracing
│ │ ├── clustering.py # Wallet clustering
│ │ ├── mixer_detect.py # Tornado Cash/bridge/CEX
│ │ └── label_db.py # OFAC/known exploiter labels
│ │
│ ├── ollama/ # LLM integration (Plan 6)
│ │ ├── copilot.py # Context-aware chat
│ │ ├── report_template.py # Builds JSON context
│ │ └── report_sections.py # 7-section report
│ │
│ ├── es/ # Elasticsearch
│ │ ├── setup.py # Index creation
│ │ └── mappings/ # Strict JSON mappings
│ │
│ ├── frontend/ # React UI (Plan 4)
│ │ └── src/
│ │ ├── components/ # 6 components
│ │ ├── hooks/ # 4 custom hooks
│ │ └── api/ # 3 API modules
│ │
│ └── tests/ # 130 Python tests
│
└── simulations/ # Foundry simulations (Plan 5)
├── shared/contracts/ # MockERC20, MockWETH
└── scenarios/ # 4 attack scenarios
├── reentrancy-drain/
├── flash-loan-oracle/
├── admin-key-abuse/
└── mev-sandwich/
```
## 运行测试
```
# Python 测试（130 个测试）
cd chainsentinel
source .venv/bin/activate
python -m pytest tests/ -v
# 前端测试（28 个测试）
cd chainsentinel/frontend
npx vitest run
# Solidity 编译
cd simulations
forge build
```
## 分析模式
| 模式 | 输入 | 用途 |
|------|-------|------|
| **Tx Analysis** | 交易哈希 | 深入调查单个可疑交易 |
| **Range Analysis** | 起始/结束区块号 | 扫描已知漏洞利用窗口 |
| **Wallet Hunt** | 钱包地址 | 追踪攻击者资金流向 |
| **Watch Mode** | 无（持续运行） | 实时监控 |
## 检测覆盖
### 20 种信号（第 1 阶段）
| 类别 | 信号 |
|------|------|
| 价值 | large_outflow, large_token_transfer, max_approval, value_spike |
| 闪电贷 | flash_loan_detected, flash_loan_with_drain |
| 访问控制 | ownership_transferred, role_granted, proxy_upgraded |
| 结构 | reentrancy_pattern, call_depth_anomaly, repeated_external_call, internal_eth_drain |
| 部署 | new_contract_deployed, failed_high_gas |
| 流动性 | large_liquidity_removal |
| DeFi | vault_first_deposit_tiny, liquidation_event |
| 行为 | new_wallet_high_value, burst_transactions |
### 4 种攻击模式
| ID | 模式 | 置信度 |
|----|------|--------|
| AP-001 | 闪电贷预言机操纵 | 0.90 |
| AP-005 | 重入漏洞 draining | 0.90 |
| AP-008 | 访问控制滥用 | 0.85 |
| AP-014 | MEV 夹击 | 0.80 |
## 配置
编辑 `chainsentinel/config.json`：
```
{
"rpc_url": "http://127.0.0.1:8545",
"es_url": "http://localhost:9200",
"ollama_url": "http://localhost:11434",
"ollama_model": "gemma3:1b",
"chain_id": 31337,
"mode": "simulation"
}
```
切换到主网：将 `rpc_url` 改为你的 Alchemy/Infura 端点，并将 `chain_id` 改为 `1`。无需代码更改。
## 技术栈
| 组件 | 技术 |
|------|------|
| 流水线 | Python 3.11+, web3.py |
| 后端 | FastAPI, SSE |
| 检测 | Elasticsearch 8.x（ES|QL + EQL） |
| 前端 | React 18, Vite, D3.js |
| 样式 | 纯 CSS（Wise 设计系统） |
| LLM | Ollama + Gemma 3 1B |
| 模拟 | Foundry, Solidity 0.8.24+ |
## 在新机器上设置
```
# 1. 克隆仓库
git clone https://github.com/aswathas/Project-Hail-Mary.git
cd Project-Hail-Mary
# 2. 安装 Python 依赖
cd chainsentinel
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 3. 安装前端依赖
cd frontend
npm install
cd ..
# 4. 安装 Foundry（用于模拟）
curl -L https://foundry.paradigm.xyz | bash
foundryup
cd ../simulations
forge install
cd ..
# 5. 拉取 Ollama 模型
ollama pull gemma3:1b
# 6. 启动所有服务
cd chainsentinel
./start.sh
```
由 Aswath 为 SISA 构建。
标签：AI 辅助分析, AI风险缓解, Anvil, AV绕过, Docker, Elasticsearch, EQL, ES|QL, EVM, FastAPI, Foundry, GNU通用公共许可证, LLM评估, Node.js, Ollama, Python 3.11, React, SISA, Syscalls, 事件调查, 交易追踪, 以太坊, 前端可视化, 区块链取证, 区块链安全, 启发式检测, 复合攻击模式, 安全防御评估, 本地部署, 法医报告, 离线取证, 请求拦截, 资金流向分析, 逆向工具, 钱包聚类