conditional-team/SENTINEL
GitHub: conditional-team/SENTINEL
跨 16 条 EVM 链的钱包授权扫描与智能合约漏洞检测平台，支持字节码反编译、风险评分和一键撤销危险授权。
Stars: 1 | Forks: 0
# SENTINEL SHIELD
多链钱包安全扫描器 — 16 条 EVM 链
快速开始 •
API 参考 •
架构 •
测试 •
安全 •
贡献
## 概述
SENTINEL 扫描 **16 条主网 EVM 链**上的钱包授权，反编译合约字节码，检测 30 多种漏洞模式，并允许用户直接从单一仪表板撤销危险授权。
**核心流程：** 用户钱包 → Go API（并发多链 RPC）→ Rust 反编译器（字节码 → 操作码）→ Python 分析器（启发式风险评分）→ React 前端（可操作的结果）。
## 支持的链
| Ethereum & L2s | Alt L1s |
|:---|:---|
| Ethereum (1) • Arbitrum One (42161) • Optimism (10) • Base (8453) | BNB Chain (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 (stable) | 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/conditional-team/SENTINEL.git
cd SENTINEL
cp config/.env.example config/.env # edit with your RPC keys
docker-compose up -d # starts all 6 services
```
服务可通过以下地址访问：
| 服务 | URL |
|---------|-----|
| 前端 | `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
# 反编译器
cd decompiler && cargo run -- --server --port 3000 # :3000
# 分析器
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 密钥） |
### 认证
**选项 A — API Key：**
```
curl -H "X-API-Key: YOUR_KEY" http://localhost:8080/api/v1/chains
```
**选项 B — JWT Token：**
```
# 1. 获取 token（需要 admin API key）
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. 使用 token
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` | Counter | 按端点、方法、状态统计的请求数 |
| `sentinel_http_request_duration_seconds` | Histogram | 每个端点的延迟（10ms–10s 桶） |
| `sentinel_scans_total` | Counter | 执行的钱包扫描数 |
| `sentinel_analyzes_total` | Counter | 执行的合约分析数 |
| `sentinel_rate_limit_blocks_total` | Counter | 被速率限制器阻止的请求数 |
| `sentinel_auth_failures_total` | Counter | 失败的认证尝试次数 |
| `sentinel_uptime_seconds` | Gauge | 服务器运行时间 |
`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
```
## 漏洞检测
| 类别 | 模式 |
|----------|----------|
| **代币骗局** | 蜜罐、隐藏铸造、隐藏费用、黑名单函数 |
| **授权风险** | 无限额度、未验证的支出者、过期授权 |
| **代理风险** | 无时间锁的可升级、近期升级、实现不匹配 |
| **重入攻击** | 外部调用后的状态更改、跨函数重入 |
| **访问控制** | 单一所有者、无多重签名、中心化熔断开关 |
| **闪电贷** | 价格预言机操纵、未检查的回调 |
| **逻辑错误** | 整数溢出、未检查的返回值、tx.origin 认证 |
## 测试
跨越所有组件进行**约 90,000 次测试执行**（包括 Fuzz 和基于属性的运行）。
| 组件 | 测试数 | 类型 | 运行器 |
|-----------|-------|------|--------|
| **Go API** | 15,000+ | 单元 + Fuzz + 集成 + 基准 | `go test` |
| **Rust 反编译器** | 20,031 | 单元 + Fuzz | `cargo test` |
| **Solidity 合约** | 30,000+ | Foundry Fuzz (30k 次运行) | `forge test` |
| **Python 分析器** | 12,000+ | Hypothesis 基于属性 | `pytest` |
| **React 前端** | 54+ 单元, 15,000+ fast-check | Vitest + @testing-library | `npx vitest` |
| **E2E** | 套件 | API 集成测试 | `go test ./tests/e2e/` |
有关完整详情、Fuzz 配置和 CI 配方，请参阅 [TESTING.md](TESTING.md)。
## CI/CD 流水线
GitHub Actions 在每次推送到 `main`/`develop` 以及 PR 时运行：
| 阶段 | 功能 |
|-------|-------------|
| **Lint** | golangci-lint, `cargo clippy`, `ruff + mypy`, ESLint, `forge fmt` |
| **Test** | 所有 5 种语言测试套件，带覆盖率阈值 |
| **Build** | 为 api、decompiler、analyzer、frontend 构建 Docker 镜像 (GHCR) |
| **E2E** | 针对 Redis + PostgreSQL 服务的集成测试 |
| **Security** | `gosec`, `cargo-audit`, `safety`, Slither (智能合约) |
| **Deploy** | 合约部署（发布时）+ 服务部署（main 推送时） |
## 安全
- 每个 IP 的速率限制（Redis 分布式 + 内存回退）
- JWT (HS256) + API Key 双重认证
- 可配置来源的 CORS
- 安全头
- 请求体大小限制（1 MB）
- 优雅关闭，含 10秒 排空超时
- 漏洞赏金计划 — 详见 [SECURITY.md](SECURITY.md)
## 许可证
[MIT](LICENSE)
SENTINEL 团队 — @conditional-team
Go · Rust · Python · Solidity · Yul · TypeScript
“由懂攻击者构建的防御。”
标签：AMSI绕过, Arbitrum, Avalanche, BNB Chain, DeFi 安全, EVM 安全, Golang, IP 地址批量处理, Optimism, Polygon, Python, React, Rust, Solidity, Syscalls, Web3 安全, 云安全监控, 代码分析, 以太坊, 凭证管理, 加密货币, 区块链安全, 反编译器, 可视化界面, 合规科技, 域名收集, 多链扫描器, 威胁检测, 安全仪表盘, 安全编程, 密码管理, 授权管理, 搜索引擎查询, 无后门, 日志审计, 智能合约审计, 测试用例, 网络流量审计, 误配置预防, 请求拦截, 足迹探测, 跨链安全, 逆向工具, 通知系统, 钓鱼防护, 钱包安全, 静态分析, 风险评分