davidakpele/sentinel
GitHub: davidakpele/sentinel
一款多链钱包安全扫描器，通过字节码反编译与启发式分析解决 DeFi 授权与合约漏洞问题。
Stars: 1 | Forks: 0
# SENTINEL SHIELD
多链钱包安全扫描器 — 16 条 EVM 链
快速开始 •
API 参考 •
架构 •
测试 •
安全 •
贡献
## 概述
SENTINEL 扫描钱包授权，覆盖 **16 条主网 EVM 链**，反编译合约字节码，检测 30+ 漏洞模式，并允许用户从单个仪表板撤销危险授权。
**核心流水线：** 用户钱包 → Go API（并发多链 RPC） → Rust 反编译器（字节码 → 操作码） → Python 分析器（启发式风险评分） → React 前端（可操作结果）。
## 支持的链
| 以太坊与 L2 | 替代 L1 |
|:---|:---|
| 以太坊（1）• Arbitrum One（42161）• Optimism（10）• Base（8453） | BNB 链（56）• Polygon PoS（137）• Avalanche（43114）• Fantom（250） |
| zkSync Era（324）• Linea（59144）• Scroll（534352）• Polygon zkEVM（1101） | Cronos（25）• Gnosis（100）• Celo（42220）• Moonbeam（1284） |
## 关键特性
| 功能 | 描述 |
|---------|-------------|
| **16 链扫描** | 所有支持的主网并发 RPC 调用 |
| **字节码反编译** | Rust 驱动的操作码分析与控制流图生成 |
| **30+ 漏洞模式** | 蜜罐、隐藏铸造、隐藏费用、代理风险、访问控制缺陷 |
| **一键撤销** | 从仪表板直接撤销危险授权 |
| **风险评分** | 每次授权 + 全局钱包健康评分（0–100） |
| **JWT + API Key 认证** | HS256 JWT 令牌与 API Key 备用认证 |
| **分布式速率限制** | Redis 支持的速率限制器，带自动内存回退 |
| **Prometheus 指标** | `/metrics` 端点 — 请求计数、延迟直方图、业务 KPI |
| **PostgreSQL + Redis** | 扫描历史持久化、分布式缓存（可选，优雅降级） |
## 架构
```
┌──────────────────────────┐
│ Frontend (React + TS) │
│ Vite · Tailwind · wagmi│
└────────────┬─────────────┘
│ HTTPS
┌────────────▼─────────────┐
│ API Server (Go) │
│ JWT · Rate Limit · CORS │
│ Prometheus · Middleware │
└──┬─────────┬──────────┬──┘
│ │ │
┌──────────▼──┐ ┌────▼────┐ ┌───▼──────────┐
│ Decompiler │ │Analyzer │ │ PostgreSQL │
│ (Rust) │ │(Python) │ │ + Redis │
│ Opcodes/CFG │ │Heuristic│ │ Cache/Store │
└─────────────┘ └─────────┘ └──────────────┘
│
┌──────────▼──────────────────────┐
│ On-chain Contracts (Sol + Yul)│
│ SentinelRegistry · BatchRevokeYul│
└─────────────────────────────────┘
```
## 技术栈
| 层 | 技术 | 角色 |
|-------|-----------|------|
| **API** | Go 1.22 | HTTP 服务器、多链 RPC、中间件（JWT、速率限制、CORS、指标） |
| **反编译器** | Rust（稳定版） | EVM 字节码反汇编、操作码解析、CFG 生成 |
| **分析器** | Python 3.11+ | 启发式漏洞检测、风险评分 |
| **前端** | React 18、TypeScript、Vite、Tailwind、RainbowKit | 仪表板、钱包连接、一键撤销 |
| **合约** | Solidity 0.8.x + Yul | 链上注册表、gas 优化的批量撤销 |
| **数据** | PostgreSQL 16、Redis 7 | 扫描历史、分布式缓存、速率限制 |
| **基础设施** | Docker Compose、GitHub Actions CI/CD | 多容器部署、5 阶段流水线 |
## 快速开始
### Docker（推荐）
```
git clone https://github.com/Faraone-Dev/SENTINEL.git
cd SENTINEL
cp config/.env.example config/.env # edit with your RPC keys
docker-compose up -d # starts all 6 services
```
服务地址如下：
| 服务 | 地址 |
|---------|-----|
| 前端 | `http://localhost:80` |
| API | `http://localhost:8080` |
| Prometheus 指标 | `http://localhost:8080/metrics` |
| 反编译器 | `http://localhost:3000` |
| 分析器 | `http://localhost:5000` |
### 手动（开发模式）
```
# API Server
cd api && go run cmd/server/main.go # :8080
# Decompiler
cd decompiler && cargo run -- --server --port 3000 # :3000
# Analyzer
cd analyzer && python src/server.py # :5000
# Frontend
cd frontend && npm install && npm run dev # :5173
```
### Makefile 快捷命令
```
make build # Build all components
make test # Run all test suites
make docker-up # docker-compose up -d
make docker-down # docker-compose down
make help # List all targets
```
## 配置
将 `config/.env.example` 复制为 `config/.env` 并设置：
| 变量 | 是否必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `ALCHEMY_API_KEY` | 推荐 | — | 可靠的链访问 Alchemy RPC 密钥 |
| `ETHERSCAN_API_KEY` | 可选 | — | 区块浏览器 API（免费额度可用） |
| `ADMIN_API_KEY` | 生产环境必需 | — | 受保护端点的 API 密钥 |
| `JWT_SECRET` | 可选 | — | HS256 签名密钥（≥32 字符）；启用 JWT 认证 |
| `DATABASE_URL` | 可选 | — | PostgreSQL 连接字符串 |
| `REDIS_URL` | 可选 | — | Redis 连接字符串 |
| `RATE_LIMIT_RPM` | 可选 | `100` | 每 IP 每分钟最大请求数 |
| `PORT` | 可选 | `8080` | API 服务器端口 |
| `CORS_ORIGINS` | 可选 | `*` | 允许的跨域来源（逗号分隔） |
## API 参考
### 公共端点
| 方法 | 端点 | 认证 | 描述 |
|--------|----------|------|-------------|
| `GET` | `/health` | 无 | 健康检查 + 版本信息 |
| `GET` | `/metrics` | 无 | Prometheus 兼容指标 |
| `GET` | `/api/v1/chains` | 无 | 列出全部 16 条支持的链 |
### 受保护端点（JWT 或 API Key）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/api/v1/scan?wallet=0x...&chains=ethereum,base` | 跨链扫描钱包授权 |
| `GET` | `/api/v1/analyze?contract=0x...&chain=ethereum` | 深度分析单个合约 |
| `POST` | `/api/v1/analyze/batch` | 批量分析最多 10 个合约 |
| `POST` | `/api/v1/auth/token` | 签发 JWT 令牌（需管理员 API Key） |
### 认证
**选项 A — API Key：**
```
curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/api/v1/chains
```
**选项 B — JWT 令牌：**
```
# 1. 获取令牌（需要管理员 API 密钥）
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/token \
-H "X-API-Key: ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"sub":"my-app","role":"reader","ttl":"24h"}' | jq -r .token)
# 2. 使用令牌
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/scan?wallet=0x...
```
### 微服务
| 服务 | 端口 | 端点 |
|---------|------|-----------|
| **反编译器**（Rust） | 3000 | `GET /health` · `POST /analyze` |
| **分析器**（Python） | 5000 | `GET /health` · `POST /api/analyze` · `GET /api/stats` |
## 可观测性
### Prometheus 指标（`GET /metrics`）
| 指标 | 类型 | 描述 |
|--------|------|-------------|
| `sentinel_http_requests_total` | 计数器 | 按端点、方法、状态划分的请求计数 |
| `sentinel_http_request_duration_seconds` | 直方图 | 每端点延迟（10ms–10s 分桶） |
| `sentinel_scans` | 计数器 | 执行的钱包扫描次数 |
| `sentinel_analyzes_total` | 计数器 | 执行的合约分析次数 |
| `sentinel_rate_limit_blocks_total` | 计数器 | 被速率限制器阻止的请求 |
| `sentinel_auth_failures_total` | 计数器 | 失败的认证尝试次数 |
| `sentinel_uptime_seconds` | 仪表 | 服务器运行时长 |
用于 `prometheus.yml` 的抓取配置：
```
scrape_configs:
- job_name: sentinel-api
static_configs:
- targets: ['sentinel-api:8080']
```
## 项目结构
```
SENTINEL/
├── api/ # Go API server
│ ├── cmd/server/
│ │ ├── main.go # Server, routes, middleware (~2300 lines)
│ │ ├── database.go # PostgreSQL client
│ │ ├── redis.go # Redis cache + distributed rate limiting
│ │ ├── metrics.go # Prometheus metrics (zero dependencies)
│ │ ├── jwt.go # JWT auth (HS256, zero dependencies)
│ │ ├── *_test.go # Unit, fuzz, integration, benchmark tests
│ │ └── server.exe # Compiled binary
│ ├── Dockerfile
│ └── go.mod
├── analyzer/ # Python risk analyzer
│ ├── src/ # analyzer.py, server.py
│ ├── tests/
│ └── requirements.txt
├── decompiler/ # Rust bytecode decompiler
│ ├── src/ # main.rs, server.rs
│ └── Cargo.toml
├── contracts/ # Solidity + Yul smart contracts
│ ├── src/ # SentinelRegistry.sol, BatchRevokeYul
│ ├── test/
│ └── foundry.toml
├── frontend/ # React dashboard
│ ├── src/
│ │ ├── App.tsx # Main app (~350 lines)
│ │ ├── components/ # 9 extracted UI components
│ │ └── __tests__/ # 54+ Vitest unit tests
│ └── package.json
├── db/ # PostgreSQL schema (init.sql)
├── tests/e2e/ # End-to-end test suite
├── config/ # .env, .env.example
├── scripts/ # Build & deploy scripts
├── .github/workflows/ci.yml # CI/CD pipeline (6 jobs)
├── docker-compose.yml # Full stack (6 services)
├── Makefile # Build, test, Docker shortcuts
├── TESTING.md # Test suite documentation
├── SECURITY.md # Security policy & bug bounty
└── CONTRIBUTING.md # Contribution guidelines
```
## 漏洞检测
| 类别 | 模式 |
|----------|----------|
| **代币诈骗** | 蜜罐、隐藏铸造、隐藏费用、黑名单函数 |
| **授权风险** | 无限制授权、未经许可的支出者、过期授权 |
| **代理风险** | 无时间锁升级、最近升级、实现不匹配 |
| **重入攻击** | 外部调用后状态变更、跨函数重入 |
| **访问控制** | 单所有者、无多签、集中式 Kill Switch |
| **闪电贷** | 价格预言机操纵、未检查的回调 |
| **逻辑缺陷** | 整数溢出、未校验返回值、tx.origin 认证 |
## 测试
**约 90,000 次总测试执行** 覆盖所有组件（包括模糊测试和基于属性的测试）。
| 组件 | 测试 | 类型 | 运行器 |
|-----------|-------|------|--------|
| **Go API** | 15,000+ | 单元测试 + 模糊测试 + 集成测试 + 基准测试 | `go test` |
| **Rust 反编译器** | 20,031 | 单元测试 + 模糊测试 | `cargo test` |
| **Solidity 合约** | 30,000+ | Foundry 模糊测试（30k 次运行） | `forge test` |
| **Python 分析器** | 12,000+ | Hypothesis 属性基础测试 | `pytest` |
| **React 前端** | 54+ 单元测试，15,000+ 快速检查 | Vitest + @testing-library | `npx vitest` |
| **E2E** | 套件 | API 集成测试 | `go test ./tests/e2e/` |
详见 [TESTING.md](TESTING.md) 获取完整细节、模糊配置和 CI 食谱。
## CI/CD 流水线
GitHub Actions 在每次推送到 `main`/`develop` 以及 PR 时运行：
| 阶段 | 执行内容 |
|-------|-------------|
| **Lint** | golangci-lint、`cargo clippy`、`ruff + mypy`、ESLint、`forge fmt` |
| **测试** | 所有 5 种语言测试套件（含覆盖率阈值） |
| **构建** | Docker 镜像：api、反编译器、分析器、前端（GHCR） |
| **E2E** | 集成测试（Redis + PostgreSQL 服务） |
| **安全** | `gosec`、`cargo-audit`、`safety`、Slither（智能合约） |
| **部署** | 合约部署（发布时）+ 服务部署（推送到 main 时） |
## 安全
- 每 IP 速率限制（Redis 分布式 + 内存回退）
- JWT（HS256）+ API Key 双重认证
- 可配置的 CORS 跨域策略
- 安全响应头（X-Content-Type-Options、X-Frame-Options、X-XSS-Protection）
- 请求体大小限制（1 MB）
- 优雅关闭（10 秒排空超时）
- 漏洞赏金计划 — 详见 [SECURITY.md](SECURITY.md)
标签：16条EVM链, Arbitrum, Avalanche, Base, BNB链, Celo, Cronos, DeFi安全, DeFi监控, EVM字节码反编译, Fantom, Gnosis, Go, Linea, Moonbeam, Optimism, Polygon, Polygon zkEVM, Python, React, Ruby工具, Rust, Scroll, SENTINEL SHIELD, Syscalls, zkSync, 仪表盘, 区块链分析, 区块链安全, 可视化界面, 多链RPC, 多链安全扫描, 安全扫描工具, 实时威胁检测, 密钥授权撤销, 并发扫描, 搜索引擎查询, 无后门, 日志审计, 智能合约审计, 测试用例, 网络流量审计, 自定义请求头, 请求拦截, 逆向工具, 通知系统, 钱包安全扫描, 风险评分