RunTimeAdmin/sentinel-engine
GitHub: RunTimeAdmin/sentinel-engine
一款面向 EVM 与 Solana 的生产级智能合约安全审计平台，集成 AI 分析与攻击路径可视化，解决自动化深度审计与高效漏洞发现的需求。
Stars: 0 | Forks: 0
# Sentinel 安全引擎
**生产级智能合约安全平台，内置 21 个集成分析器、可配置规则和专业审计报告。**
[](https://pypi.org/project/sentinel-engine/)
[](https://pypi.org/project/sentinel-engine/)
[](https://pypi.org/project/sentinel-engine/)
[](https://www.python.org/downloads/)
## ⚡ **快速开始（5 分钟）**
### **安装**
```
# 1. 从 PyPI 安装（推荐）
pip install sentinel-engine
# 2. 安装并支持 Web UI
pip install sentinel-engine[web]
# 3. 安装并支持 AI/RAG 功能
pip install sentinel-engine[ai]
# 4. 安装开发依赖
pip install sentinel-engine[dev]
# 5. 验证安装
sentinel-engine --help
```
**可选外部工具（完整功能所需）：**
```
# Slither（静态分析）
pip install slither-analyzer
solc-select install 0.8.19
solc-select use 0.8.19
# Aderyn（基于 Rust 的分析器）
cargo install aderyn
# Medusa（模糊测试）
go install github.com/crytic/medusa/cmd/medusa@latest
```
## 免费版与专业版
Sentinel Engine 在单一软件包中同时包含免费版与专业版功能。专业功能需要许可证密钥激活。
| 功能 | 免费版 | 专业版 |
|------|--------|--------|
| 启发式扫描器（23 条 EVM 规则） | ✓ | ✓ |
| Slither 集成 | ✓ | ✓ |
| Aderyn、Medusa、Mythril、Foundry | ✓ | ✓ |
| 供应链与访问矩阵分析 | ✓ | ✓ |
| 意图检查与升级差异检测 | ✓ | ✓ |
| Markdown 与 JSON 报告 | ✓ | ✓ |
| CI/CD 流水线生成器 | ✓ | ✓ |
| AI 审计副驾驶 | ✗ | ✓ |
| 攻击路径可视化 | ✗ | ✓ |
| 漏洞利用 PoC 生成 | ✗ | ✓ |
| 时间旅行扫描器 | ✗ | ✓ |
| 协议指纹识别 | ✗ | ✓ |
| Solana 分析器（35 条规则） | ✗ | ✓ |
| 品牌化 HTML/SARIF 报告 | ✗ | ✓ |
### **激活专业版**
```
export SENTINEL_PRO_LICENSE=your-key-here
sentinel-engine path/to/contract.sol --rag --report html
```
或添加到 `sentinel.toml`：
```
[license]
key = "your-key-here"
```
获取许可证请访问 [sentinel-engine.io/pricing](https://sentinel-engine.io/pricing)。
### **运行你的第一个审计**
**选项 1：GUI（最简单）**
```
python gui.py
# → 选择合约 → 勾选复选框 → 点击“运行所选检查”
```
**选项 2：CLI（专业）**
```
# 快速 PR 检查（仅阻断项）
sentinel-engine --target ./contracts --config sentinel-pr.toml
# 完整审计并生成 HTML 报告
sentinel-engine --target ./contracts --config sentinel-audit.toml --report --project-name "MyDeFi"
# 漏洞赏金模式（最大覆盖）
sentinel-engine --target ./contracts --config sentinel-bounty.toml --medusa
# 替代方法：直接使用 Python
python orchestrator.py --target ./contracts --config sentinel-pr.toml
```
**输出：**
- `ACTION_PLAN_*.md` - 技术发现摘要
- `audit_report_*.html` - 带风险评分的客户端可用报告
- `audit_report_*.md` - 适合 GitHub 的 Markdown
## 🎯 **你将获得什么**
### **21 个集成分析器**
1. **启发式扫描器** - 31 个漏洞模式（重入、预言机问题、访问控制）
2. **Slither** - Trail of Bits 静态分析器
3. **Aderyn** - Cyfrin 基于 Rust 的分析器（与 Slither 互补）
4. **谎言检测器** - NatSpec 注释与实现不匹配检测
5. **访问矩阵** - 函数权限分析
6. **升级差异** - UUPS/代理存储冲突检测
7. **Solana 分析器** - 35 个 Rust/Anchor 安全模式
8. **Medusa** - 覆盖引导模糊测试
9. **Foundry** - 不变量测试
10. **Mythril** - 符号执行
11. **供应链** - OSV.dev 依赖项扫描
12. **威胁情报** - Code4rena、Immunefi、Solodit 历史漏洞数据库
13. **知识获取器** - EVM 特定漏洞研究
14. **通胀脚手架** - ERC4626 攻击测试生成器
15. **AI 审计副驾驶** - 基于 RAG 的知识检索与 LLM 集成
16. **攻击路径可视化器** - 交互式 D3.js 跨合约攻击图
17. **时间旅行扫描器** - 基于 Git 的历史漏洞追踪
18. **Anchor IDL 验证器** - Solana IDL 约束与 CPI 流分析
19. **CI/CD 流水线生成器** - 多平台安全流水线生成
20. **增强型漏洞生成器** - 模式到模板漏洞 PoC 生成
21. **协议指纹扫描器** - 协议相似性与继承漏洞检测
### **专业报告**
- **风险评分**（0-100），基于严重性分布
- **通过/失败状态**（在 CRITICAL 或 >3 个 HIGH 时自动失败）
- **修复步骤**，附带 CWE 映射与引用
- **代码片段**，含精确的文件:行位置
- **HTML + Markdown** 格式，便于客户与 GitHub 使用
### **零误报**
- **可配置的抑制规则**，通过 `sentinel.toml`
- **每条规则严重性覆盖**（例如将时间戳误用降级为适用于定时锁）
- **基于过期时间的接受风险**（“此风险可接受至 2026-12-31”）
- **文件/行级抑制**（仅抑制特定出现，而非全部）
### **3 种执行配置**
**审计模式**（`sentinel-audit.toml`）
- 最大程度彻底性，适用于客户交付物
- 启用所有分析器，深度模糊测试（250K 次测试）
- 在 MEDIUM+ 严重性时失败
- 详细报告，包含全部上下文
**PR 模式**（`sentinel-pr.toml`）
- CI/CD 中快速阻断检查（< 2 分钟）
- 跳过缓慢分析器（Aderyn、模糊测试）
- 仅在 HIGH+ 时失败
- 预抑制常见误报
**赏金猎人模式**（`sentinel-bounty.toml`）
- 最大覆盖范围用于漏洞发现
- 启用所有规则，极端模糊测试（500K 次测试）
- 从不失败（报告所有内容）
- AI 漏洞利用 PoC 生成
- 按严重性分组（优先展示 $$$ 漏洞）
## 📊 **使用示例**
### **客户审计工作流**
```
# 1. 全自动扫描
sentinel-engine --target ./client-project --config sentinel-audit.toml --report --project-name "Client DeFi Protocol"
# 2. 查看 HTML 报告
# → audit_report_2025-12-21.html
# 风险评分：42.3/100
# 状态：警告
# 发现：23（2 个严重，5 个高，12 个中，4 个低）
# 3. 附带修复步骤发送给客户端
```
### **GitHub Actions 集成**
```
# .github/workflows/security.yml 已配置
# 两个任务：
# 1. blocker-checks（在严重/高危时失败 PR）
# 2. advisory-checks（评论中危/低危，永不失败）
on:
pull_request:
branches: [main]
jobs:
sentinel:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Sentinel Engine
run: pip install sentinel-engine
- name: Sentinel PR Check
run: |
sentinel-engine --target ./contracts --config sentinel-pr.toml
```
### **漏洞赏金狩猎**
```
# 最大覆盖模式
sentinel-engine --target ./target-protocol --config sentinel-bounty.toml --medusa --aderyn --report
# 生成利用 PoC（需要 OpenAI API 密钥）
export OPENAI_API_KEY="sk-..."
python exploit_generator.py --finding-json findings.json --output exploits/
# 提交到 Immunefi/Code4rena
```
### **独立模块使用**
**启发式扫描器**（无依赖）：
```
python heuristic_scanner.py ./contracts --config sentinel-pr.toml
# 检测：重入、未检查调用、预言机陈旧、访问控制问题
```
**谎言检测器**（语义分析）：
```
python intent_check.py ./contracts/Token.sol
# 发现：“/// @notice 仅管理员”但函数为 public 且无修饰符
```
**升级差异**（代理安全性）：
```
python upgrade_diff.py ./VaultV1.sol ./VaultV2.sol
# 检测：存储冲突、移除的权限、新重入风险
```
**访问矩阵**（权限审计）：
```
python access_matrix.py ./contracts/Vault.sol
# 显示：🚨 emergencyWithdraw（外部，写入）-> 任何人 [高风险]
```
## 🔧 **配置系统**
### **完整配置参考**
Sentinel Engine 使用 TOML 配置文件。以下为所有可用配置节：
#### `[engine]` - 核心引擎设置
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `name` | 字符串 | "Sentinel Security Engine" | 引擎名称 |
| `version` | 字符串 | "3.0.0" | 引擎版本 |
| `fail_on_severity` | 字符串 | "HIGH" | CI 失败的最小严重性（CRITICAL、HIGH、MEDIUM、LOW、INFO） |
| `max_findings` | 整数 | 0 | 达到最大发现数后停止（0 = 无限制） |
#### `[heuristics]` - 启发式扫描器
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `enabled` | 布尔值 | true | 启用启发式扫描 |
| `severity_overrides` | 表 | {} | 规则严重性覆盖（RULE_ID = "SEVERITY"） |
| `disabled_rules` | 表 | {} | 禁用特定规则（RULE_ID = true） |
#### `[[suppressions]]` - 误报管理
| 键 | 类型 | 必需 | 描述 |
|----|------|------|------|
| `rule_id` | 字符串 | 是 | 要抑制的规则 |
| `file` | 字符串 | 否 | 特定文件 |
| `line` | 整数 否 | 特定行 |
| `reason` | 字符串 | 是 | 抑制原因说明 |
| `expires` | 字符串 | 否 | 过期日期（YYYY-MM-DD） |
#### `[static_analysis]` - 静态分析器
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `slither.enabled` | 布尔值 | true | 启用 Slither 分析 |
| `slither.exclude_detectors` | 字符串 | "" | 排除的检测器（逗号分隔） |
| `slither.include_impact` | 字符串 | "High,Medium" | 包含的影响级别 |
| `aderyn.enabled` | 布尔值 | false | 启用 Aderyn 分析（可选） |
| `aderyn.scope` | 字符串 | "" | 限制分析到特定路径 |
#### `[fuzzing]` - 模糊测试配置
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `foundry.enabled` | 布尔值 | false | 启用 Foundry 模糊测试 |
| `foundry.runs` | 整数 | 10000 | 模糊测试运行次数 |
| `medusa.enabled` | 布尔值 | false | 启用 Medusa 模糊测试 |
| `medusa.test_limit` | 整数 | 100000 | Medusa 测试上限 |
| `medusa.timeout` | 整数 | 300 | 超时时间（秒） |
| `medusa.workers` | 整数 | 10 | 工作线程数 |
#### `[red_team]` - 红队扫描设置
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `severity_allowlist` | 列表 | ["High", "Medium"] | 包含的严重性级别 |
| `ignore_checks` | 列表 | [...] | 忽略的检查 ID（噪声过滤） |
#### `[external_tools]` - 外部工具超时
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `aderyn_timeout` | 整数 | 120 | Aderyn 超时（秒） |
| `mythril_timeout` | 整数 | 600 | Mythril 超时（秒） |
| `foundry_fuzz_runs` | 整数 | 1000 | Foundry 默认模糊测试次数 |
#### `[supply_chain]` - 供应链安全
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `ecosystem` | 字符串 | "npm" | 包生态系统（npm、pypi） |
| `osv_timeout` | 整数 | 10 | OSV API 超时（秒） |
| `osv_max_retries` | 整数 | 3 | OSV API 最大重试次数 |
| `osv_rate_limit` | 整数 | 10 | OSV API 速率限制（请求/秒） |
#### `[threat_intel]` - 威胁情报
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `c4_timeout` | 整数 | 10 | Code4rena API 超时（秒） |
| `immunefi_timeout` | 整数 | 10 | Immunefi RSS 超时（秒） |
| `solana_github_timeout` | 整数 | 10 | Solana GitHub 超时（秒） |
| `api_rate_limit` | 整数 | 5 | 默认 API 速率限制（请求/秒） |
#### `[http]` - HTTP 客户端设置
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `default_timeout` | 整数 | 30 | 默认 HTTP 超时（秒） |
| `max_retries` | 整数 | 3 | 最大重试次数 |
| `base_delay` | 浮点数 | 1.0 | 指数退避基础延迟（秒） |
| `max_delay` | 浮点数 | 30.0 | 最大退避上限（秒） |
| `backoff_factor` | 浮点数 | 2.0 | 退避倍增因子 |
#### `[chains]` - 链特定设置
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `solana.enabled` | 布尔值 | false | 启用 Solana 分析 |
| `solana.project_root` | 字符串 | "./programs" | Solana 项目路径 |
| `evm.solc_version` | 字符串 | ">=0.8.0" | 预期 Solidity 版本 |
| `evm.trusted_contracts` | 列表 | [] | 已知安全外部合约 |
#### `[upgrade_diff]` - 升级安全性
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `old_implementation_path` | 字符串 | "" | 旧实现路径 |
| `new_implementation_path` | 字符串 | "" | 新实现路径 |
| `ignore_patterns.ignore_new_view_functions` | 布尔值 | true | 忽略新视图函数 |
| `ignore_patterns.ignore_comment_changes` | 布尔值 | true | 忽略注释变更 |
#### `[reporting]` - 报告生成
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `format` | 字符串 | "markdown" | 输出格式（markdown、json、sarif、html） |
| `sections.executive_summary` | 布尔值 | true | 包含执行摘要 |
| `sections.supply_chain` | 布尔值 | true | 包含供应链部分 |
| `sections.static_analysis` | 布尔值 | true | 包含静态分析 |
| `sections.heuristic_scan` | 布尔值 | true | 包含启发式扫描 |
| `sections.fuzzing` | 布尔值 | false | 包含模糊测试结果 |
| `sections.threat_intel` | 布尔值 | false | 包含威胁情报 |
| `sections.access_matrix` | 布尔值 | true | 包含访问矩阵 |
| `verbosity` | 字符串 | "standard" | 报告详细程度（minimal、standard、verbose） |
| `group_by` | 字符串 | "severity" | 分组依据（severity、file、rule） |
#### `[ci]` - CI/CD 集成
| 键 | 类型 | 默认值 | 描述 |
|----|------|--------|------|
| `fail_on_findings` | 布尔值 | true | 发现问题时失败流水线 |
| `post_pr_comment` | 布尔值 | true | 以 PR 评论形式发布结果 |
| `upload_sarif` | 布尔值 | false | 上传 SARIF 到 GitHub 安全 |
| `exclude_paths` | 列表 | [...] | 排除扫描的路径 |
### **执行配置对比**
| 特性 | PR 模式 | 审计模式 | 赏金猎人模式 |
|------|---------|----------|--------------|
| **配置文件** | `sentinel-pr.toml` | `sentinel-audit.toml` | `sentinel-bounty.toml` |
| **耗时** | < 2 分钟 | 10-30 分钟 | 1-2 小时 |
| **失败阈值** | HIGH+ | MEDIUM+ | 从不失败 |
| **启发式扫描器** | ✅ 快速 | ✅ 完整 | ✅ 完整 |
| **Slither** | ✅ | ✅ | ✅ |
| **Aderyn** | ❌ | ✅ | ✅ |
| **Medusa 模糊测试** | ❌ | ✅（250K） | ✅（500K） |
| **Mythril** | ❌ | ✅ | ✅ |
| **供应链** | ✅ | ✅ | ✅ |
| **威胁情报** | ❌ | ✅ | ✅ |
| **谎言检测器** | ✅ | ✅ | ✅ |
| **报告格式** | Markdown | HTML + MD | HTML + MD + SARIF |
| **抑制规则** | 预配置 | 项目特定 无（全部规则） |
| **AI 漏洞生成** | ❌ | ❌ | ✅ |
### **配置选择**
```
# 使用预设配置
sentinel-engine --target ./contracts --config sentinel-audit.toml # Full audit
sentinel-engine --target ./contracts --config sentinel-pr.toml # Fast PR check
sentinel-engine --target ./contracts --config sentinel-bounty.toml # Bug bounty
# 或创建自定义配置
sentinel-engine --target ./contracts --config my-custom.toml
```
## 🚨 **核心功能**
### **1. 谎言检测器（语义分析与 NatSpec 解析）**
检测开发者意图（NatSpec 注释）与实际实现之间的不匹配：
**NatSpec 解析能力：**
- 解析 `@notice`、`@dev`、`@param` 和 `@return` 标签
- 支持 `///` 单行与 `/** */` 多行格式
- 提取信任关键词与访问控制声明
- 对比文档化行为与实际函数修饰符和可见性
**支持的 NatSpec 标签：**
- `@notice` - 函数目的的高级描述
- `@dev` - 开发说明与实现细节
- `@param` - 参数文档
- `@return` - 返回值文档
```
/// @notice Only owner can withdraw funds ← Says "owner"
/// @dev Transfers entire balance to owner
/// @param token The token address to withdraw
/// @return success Whether the withdrawal succeeded
function withdraw(address token) public returns (bool success) { ← Code says "public" (NO MODIFIER!)
// ❌ CRITICAL: Intent mismatch detected!
}
```
**输出：**
```
⚠️ CRITICAL: Developer intent does NOT match implementation!
[MISMATCH] Line 42: withdraw
• Comment implies: 'owner'
• Code reality: Public/External with NO detected modifiers.
💡 FIX: Add modifier (onlyOwner, onlyRole) or change visibility to internal.
```
### **2. 专业 HTML 报告**
**客户端可用交付物包含：**
- 风险评分（0-100）的执行摘要
- 通过/失败状态徽章
- 按分析器（Slither、启发式扫描器、谎言检测器 等）分组的发现
- 严重性徽章（CRITICAL/HIGH/MEDIUM/LOW）
- 语法高亮的代码片段
- 附带引用（CWE、OWASP）的修复步骤
- 面向客户与 GitHub 的 HTML + Markdown 格式
**示例：**
```
🛡️ Security Audit Report
━━━━━━━━━━━━━━━━━━━━━━━━
Project: DeFi Vault
Risk Score: 42.3/100
Status: ⚠️ WARNING
Findings:
🔴 CRITICAL: 2
🟠 HIGH: 5
🟡 MEDIUM: 12
🔵 LOW: 4
```
### **3. GitHub Actions 阻断器/建议分离**
**两级 CI/CD 检查：**
**阻断器**（失败 PR）：
- CRITICAL/HIGH 启发式
- 谎言检测器不匹配
- 升级差异存储冲突
- 移除的访问控制
**建议**（仅评论）：
- MEDIUM/LOW 发现
- 时间戳使用（对定时锁安全）
- 硬编码地址（对预言机预期）
- Gas 优化
**PR 评论示例：**
```
## 🔍 咨询安全发现（非阻断）
Found 3 MEDIUM and 5 LOW severity issues that do not block this PR.
### 摘要
- 🟡 MEDIUM: 3
- 🔵 LOW: 5
### 示例发现
[MEDIUM] TX_ORIGIN_USAGE @ contracts/Auth.sol:42
[LOW] HARDCODED_ADDRESS @ contracts/Oracle.sol:15
---
These are advisory findings that **do not block** the PR.
Consider addressing them in a follow-up.
```
### **4. 升级安全性分析**
检测危险的代理升级模式：
```
⚠️ UNSAFE TO UPGRADE - Critical issues found!
[CRITICAL] Storage slot 2 reassigned
Variable 'owner' replaced with 'admin' in slot 2.
Existing data will be misinterpreted!
Old: address owner
New: address admin
[CRITICAL] Authorization removed from emergencyWithdraw()
Function had modifier ['onlyOwner'] which is now removed.
Anyone can call it!
```
## 🌐 **Web 应用**
请在 **https://app.sentinel-engine.io** 试用 Sentinel Engine — 无需安装。
Web 应用提供：
- 通过浏览器上传并审计 `.sol` 或 `.rs` 文件
- 查看风险评分与严重性分解
- 下载 HTML、Markdown、SARIF 或 JSON 格式报告
- 交互式攻击图可视化
## 🐳 **Docker 部署**
### **快速启动**
```
# 构建镜像
docker build -t sentinel-engine .
# 运行审计
docker run --rm -v $(pwd):/scan sentinel-engine --target /scan --config /scan/sentinel-pr.toml
# 生成报告
docker run --rm -v $(pwd):/scan sentinel-engine --target /scan --report
```
### **Docker Compose**
```
docker-compose run --rm audit --target /scan --config /scan/sentinel-audit.toml --report
```
**包含：**
- Python 3.10、Slither、Mythril、solc（0.8.19/0.8.20/0.8.23）
- 所有依赖预安装
- 约 600MB 优化镜像
## 📚 **高级功能**
### **AI 漏洞生成（GPT-4）**
```
# 设置 API 密钥
export OPENAI_API_KEY="sk-..."
# 从发现生成利用
python exploit_generator.py \
--rule-id UNCHECKED_EXTERNAL_CALL \
--file contracts/Vault.sol \
--line 300 \
--description "External call without return check"
# 输出：test/exploits/Exploit_UNCHECKED_EXTERNAL_CALL.t.sol
```
### **威胁情报**
```
# 查询历史利用
python threat_intel.py contracts/Vault.sol
# → 在 Code4rena、Immunefi、Solodit 中搜索类似漏洞
# Solana 特定
python threat_intel.py programs/staking/lib.rs
# → 搜索 Neodyme、OtterSec、Sec3
```
### **Medusa 模糊测试**
```
python medusa_wrapper.py ./foundry-project --test-limit 50000 --timeout 300
# 覆盖引导式模糊测试（比 Echidna 快 10-100 倍）
```
## 🚀 **创新功能**
Sentinel Engine 包含 7 项区分于传统安全扫描器的创新功能：
### **1. AI 审计副驾驶 🤖**
基于 RAG 的知识检索系统，提供智能漏洞解释与修复建议，使用本地嵌入（可选 OpenAI/Anthropic 集成）。
**特性：**
- 本地向量数据库用于审计报告嵌入
- 上下文感知的漏洞解释
- 模式化修复建议
- 多 LLM 支持（OpenAI GPT-4、Anthropic Claude）
**CLI 用法：**
```
# 启用审计期间的 RAG 增强
sentinel-engine --target ./contracts --rag
# 从历史报告构建/更新 RAG 索引
sentinel-engine --build-rag-index ./past-audits
# 使用特定 LLM 提供商
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
sentinel-engine --target ./contracts --rag --llm-provider anthropic
```
**配置：**
```
[ai]
enabled = false
llm_provider = "openai" # "openai" or "anthropic"
embedding_model = "text-embedding-3-small"
context_window = 4000
rag_top_k = 5
local_embeddings = true
embedding_cache_dir = "./.sentinel/embeddings"
```
### **2. 攻击路径可视化器 🕸️**
交互式 D3.js 力导向图，展示跨合约攻击路径与漏洞链。揭示单个检查无法发现的多步骤利用。
**特性：**
- 跨合约交互追踪
- 多步骤攻击链可视化
- 独立 HTML 输出与交互控件
- 导出为 Mermaid/PlantUML
**CLI 用法：**
```
# 生成 HTML 格式的攻击图
sentinel-engine --target ./contracts --format attack-graph
# 输出到指定文件
sentinel-engine --target ./contracts --format attack-graph --output attack_paths.html
```
**配置：**
```
[visualization]
enabled = true
attack_graph = true
output_format = "html" # "html", "mermaid", "dot"
max_nodes = 100
cluster_by_severity = true
include_safe_paths = false
```
### **3. 时间旅行扫描器 ⏰**
基于 Git 的历史漏洞追踪，扫描提交历史以发现漏洞引入与修复的时间点。
**特性：**
- 扫描整个 Git 历史以定位漏洞引入
- 跟踪安全债务随时间积累
- 识别高风险提交与贡献者
- 生成漏洞谱系报告
**CLI 用法：**
```
# 扫描最近 50 个提交
sentinel-engine --target ./contracts --history --commits 50
# 扫描自特定日期
sentinel-engine --target ./contracts --history --since "2025-01-01"
# 带归因的完整历史扫描
sentinel-engine --target ./contracts --history --blame
```
**配置：**
```
[history]
enabled = false
max_commits = 100
since_date = ""
blame_attribution = true
ignore_merge_commits = true
incremental_scan = true
storage_path = "./.sentinel/history"
```
### **4. Anchor IDL 验证器 ⚓**
用于 Solana 程序的专用 Anchor IDL JSON 解析器。验证约束、追踪 CPI 流并生成账户权限矩阵。
**特性：**
- IDL 约束验证
- 跨程序调用（CPI）流追踪
- 账户权限矩阵生成
- Anchor 特定安全模式（35+ 条规则）
**CLI 用法：**
```
# 验证 IDL 文件
python idl_validator.py ./target/idl/my_program.json
# 使用 IDL 验证的完整 Solana 分析
sentinel-engine --target ./programs --solana --idl-path ./target/idl
```
**配置：**
```
[chains.solana]
enabled = false
project_root = "./programs"
idl_path = "./target/idl"
[chains.solana.idl]
validate_constraints = true
trace_cpi_flows = true
generate_permission_matrix = true
check_account_initialization = true
strict_signer_validation = true
```
### **5. CI/CD 流水线生成器 🔄**
为 GitHub Actions、GitLab CI、Azure DevOps 和 Jenkins 动态生成流水线。生成生产就绪的安全流水线，包含 PR 评论与门禁条件。
**特性：**
- 多平台流水线模板
- PR 评论集成
- SARIF 上传配置
- Slack/Discord 通知
- 可定制门禁条件
**CLI 用法：**
```
# 生成 GitHub Actions 工作流
sentinel-generate-pipeline --platform github --output .github/workflows/
# 生成 GitLab CI 配置
sentinel-generate-pipeline --platform gitlab --output .gitlab-ci.yml
# 生成 Azure DevOps 流水线
sentinel-generate-pipeline --platform azure --output azure-pipelines.yml
# 生成 Jenkinsfile
sentinel-generate-pipeline --platform jenkins --output Jenkinsfile
```
**配置：**
```
[ci.generator]
enabled = true
platform = "github" # "github", "gitlab", "azure", "jenkins"
pr_comments = true
sarif_upload = true
slack_webhook = ""
discord_webhook = ""
fail_threshold = "HIGH"
```
### **6. 增强型漏洞生成器 💥**
模式到模板的映射系统，生成可工作的 Foundry 漏洞测试用例，包含合约状态推断与断言预言机。
**特性：**
- 模式到模板漏洞映射
- 合约状态推断
- 断言预言机生成
- 批量漏洞生成
- 输出验证
- 多 LLM 支持
- 包含 6 个 Foundry 漏洞模板
**CLI 用法：**
```
# 从发现生成利用
python exploit_generator.py --finding-json findings.json --output exploits/
# 批量生成所有 HIGH/CRITICAL 发现
python exploit_generator.py --finding-json findings.json --severity HIGH,CRITICAL --batch
# 使用特定模板
python exploit_generator.py --rule-id REENTRANCY --template reentrancy.sol --output test/
```
**配置：**
```
[exploit_generation]
enabled = false
llm_provider = "openai"
templates_dir = "./exploit_templates"
output_dir = "./test/exploits"
validate_output = true
max_attempts = 3
include_setup = true
batch_mode = false
```
**包含模板：**
- `reentrancy.sol` - 重入攻击 PoC
- `flash_loan.sol` - 闪电贷操纵
- `oracle_manipulation.sol` - 预言机操纵
- `access_control.sol` - 权限提升
- `integer_overflow.sol` - 算术利用
- `front_running.sol` - MEV/夹心攻击
### **7. 协议指纹扫描器 🔍**
识别合约与已知协议（Uniswap、Compound、Aave 等）的相似性，并报告来自上游代码的继承漏洞。
**特性：**
- 协议指纹数据库（Uniswap V2/V3、Compound、Aave、OpenZeppelin）
- AST 级相似度对比
- 继承漏洞检测
- 分叉谱系分析
**CLI 用法：**
```
# 对已知协议进行指纹识别合约
sentinel-engine --target ./contracts --fingerprint
# 详细相似性报告
sentinel-engine --target ./contracts --fingerprint --verbose
```
**配置：**
```
[fingerprint]
enabled = false
database_path = "./data/protocol_fingerprints.json"
similarity_threshold = 0.75
include_forks = true
check_known_vulnerabilities = true
report_inherited_risks = true
```
## 🧠 **漏洞模式**
### **高价值漏洞赏金模式**
| 规则 ID | 严重性 | 典型赏金范围 |
|---------|--------|--------------|
| `UNCHECKED_EXTERNAL_CALL` | CRITICAL | $10K-$100K |
| `ORACLE_STALENESS_CHECK` | CRITICAL | $50K-$500K |
| `FLASH_LOAN_REENTRANCY` | CRITICAL | $100K-$1M+ |
| `SIGNATURE_REPLAY` | HIGH | $20K-$100K |
| `STORAGE_COLLISION_RISK` | HIGH | $30K-$200K |
| `UNSAFE_CAST` | HIGH | $0K-$50K |
| `MISSING_SLIPPAGE_PROTECTION` | HIGH | $5K-$30K |
### **Solana/Anchor 模式（35 条规则）**
**账户验证（8 条）：**
- MISSING_SIGNER_CHECK、MISSING_OWNER_CHECK、MISSING_HAS_ONE_CONSTRAINT
- MISSING_DISCRIMINATOR_CHECK、UNVALIDATED_PDA_SEEDS、MISSING_IS_SIGNER_RAW
- MISSING_ACCOUNT_DATA_VALIDATION、UNVALIDATED_ACCOUNT_INFO
**CPI 安全（4 条）：**
- ARBITRARY_CPI、MISSING_CPI_AUTHORITY、UNVERIFIED_PROGRAM_ACCOUNT、UNSAFE_INVOKE_SIGNED
**算术与逻辑（5 条）：**
- UNCHECKED_ARITHMETIC、INTEGER_OVERFLOW_RISK、UNSAFE_CASTING
- DIVISION_BY_ZERO_RISK、PRECISION_LOSS
**状态管理（6 条）：**
- MISSING_RENT_EXEMPTION、UNINITIALIZED_ACCOUNT_USAGE、ACCOUNT_REINITIALIZATION
- MISSING_CLOSE_ACCOUNT、STALE_ACCOUNT_DATA、UNCLOSED_ACCOUNT
**访问控制（4 条）：**
- MISSING_ACCESS_CONTROL、HARDCODED_AUTHORITY、MISSING_MULTISIG、WEAK_AUTHORITY_CHECK
**代币安全（4 条）：**
- MISSING_TOKEN_ACCOUNT_VALIDATION、UNCHECKED_TOKEN_BALANCE
- MISSING_FREEZE_AUTHORITY_CHECK、UNVALIDATED_TOKEN_PROGRAM
**通用验证（4 条）：**
- UNVALIDATED_ACCOUNT_DATA、UNCONSTRAINED_SYSTEM_PROGRAM
- MISSING_CLOCK_VALIDATION、DUPLICATE_MUTABLE_ACCOUNTS
### **DeFi 特定**
- ERC4626 通胀攻击
- 预言机操纵
- AMM 价格操纵
- 闪电贷重入
- 精度丢失（先除后乘）
### **访问控制**
- 缺失修饰符（谎言检测器）
- tx.origin 使用
- 未保护初始化器
- 管理员集中化风险
## 🗂️ **项目结构**
```
sentinel-engine/
│
├── gui.py # Interactive Tkinter interface
├── orchestrator.py # CLI master pipeline + Markdown reports
├── threat_intel.py # Unified launcher (auto-detects EVM vs Solana)
│
├── knowledge_fetcher.py # EVM threat intel (C4 + Immunefi + Solodit)
├── solana_intel.py # Solana threat intel (Neodyme + Sec3 + OtterSec)
│
├── heuristic_scanner.py # Pattern-based vulnerability detection (31 rules)
├── access_matrix.py # Function permission analyzer
├── intent_check.py # 🤥 Liar Detector (NatSpec vs. code mismatch)
│
├── red_team_scan.py # Slither wrapper
├── aderyn_wrapper.py # 🆕 Aderyn analyzer (Rust-based)
├── symbolic_wrapper.py # Mythril wrapper
├── fuzz_wrapper.py # Foundry invariant test wrapper
├── medusa_wrapper.py # 🆕 Medusa coverage-guided fuzzing
├── supply_chain_check.py # OSV.dev dependency scanner
├── inflation_scaffold.py # ERC4626 test generator
│
├── exploit_generator.py # 🤖 GPT-4 PoC generation
├── upgrade_diff.py # 🔍 Proxy upgrade safety checker
│
├── Dockerfile # 🐳 Single-command deployment
├── docker-compose.yml # ⚡ Easy orchestration
├── .dockerignore # Image optimization
```
## 🔧 **配置**
### **Python 解释器路径**
如需使用自定义 Python 安装，请编辑脚本：
```
# 默认：系统 Python
python orchestrator.py
# 自定义路径（Windows）：
& "C:\Python310\python.exe" orchestrator.py
```
### **Slither 配置**
如需跳过特定检查，请编辑 `red_team_scan.py`：
```
IGNORE_CHECKS = [
"solc-version",
"naming-convention",
"assembly",
# Add more...
]
```
### **启发式扫描器调优**
如需调整严重性阈值，请编辑 `heuristic_scanner.py`：
```
SEVERITY_ALLOWLIST = ["HIGH", "MEDIUM"] # Filter out INFO/LOW
```
### **谎言检测器自定义**
如需添加自定义信任关键词，请编辑 `intent_check.py`：
```
TRUST_KEYWORDS = ["admin", "owner", "restrict", "protected", "secure", "authorized"]
AUTH_MODIFIERS = ["onlyOwner", "onlyRole", "auth", "nonReentrant", "whenNotPaused"]
```
## 💼 **使用场景**
### **CyberShield Austin - 客户审计**
```
# 阶段 0：研究历史利用
python threat_intel.py /path/to/client/contracts/Vault.sol
# 阶段 1：快速启发式扫描
python heuristic_scanner.py /path/to/client/contracts
# 阶段 2：带报告的完整审计
python orchestrator.py --target /path/to/client/contracts --heuristic
# → 可交付物：ACTION_PLAN_*.md
```
### **TokenAudit YouTube - 内容创作**
```
# 教育内容的威胁情报演示
python threat_intel.py examples/vulnerable_vault.sol
# 为非技术人员展示 GUI 工作流
python gui.py
```
### **漏洞赏金狩猎**
```
# 扫描目标协议
python heuristic_scanner.py target/contracts
# 检查已知利用模式
python knowledge_fetcher.py target/contracts/Core.sol
```
### **Solana 项目（$PWD123 等）**
```
# 研究 Anchor 程序漏洞
python threat_intel.py programs/staking/lib.rs
# 带 Solodit 引用的手动审计
python solana_intel.py programs/token/lib.rs
```
## 🛡️ **限制与注意事项**
### **本工具的功能**
✅ 快速的基于模式的漏洞检测
✅ 历史漏洞研究与威胁建模
✅ 访问控制验证
✅ **语义分析（意图 vs 实现）**
✅ 自动报告生成
✅ **运行时监控蓝图（Forta 集成）**
✅ **主网分叉测试指导**
### **本工具不替代**
❌ 有经验审计员的手动代码审查
❌ 形式化验证
❌ 运行时监控 / 事件响应（提供模板，非完整部署）
❌ 法律合规审计
### **已知问题**
- **Slither/Mythril 可选** — 未安装时 GUI 会优雅降级
- **误报** — 启发式模式可能标记安全代码（需人工复核）
- **谎言检测器** — 依赖注释关键词，可能遗漏上下文特定的安全假设
- **Solana 支持** — 提供 35 条安全规则与 IDL 验证
- **Watchtower** — 提供 Forta 模板；需手动部署
## 📚 **文档**
- **[入门指南](docs/GETTING_STARTED.md)** — 安装与首次审计
- **[CLI 参考](docs/CLI_REFERENCE.md)** — 所有命令与标志
- **[配置](docs/CONFIGURATION.md)** — 完整的 `sentinel.toml` 参考
- **[Web 应用指南](docs/WEB_APP_GUIDE.md)** — Web UI 功能与 API
- **[部署](docs/DEPLOYMENT.md)** — 生产服务器搭建
### **模块详情**
请查阅源代码以获取模块文档。
## 📝 **日志配置**
Sentinel Engine 通过 `logger.py` 使用集中式日志系统：
### **日志级别**
通过环境变量 `SENTINEL_LOG_LEVEL` 设置：
- `DEBUG` — 详细调试信息
- `INFO` — 常规操作信息
- `WARNING` — 潜在问题的警告
- `ERROR` — 错误信息
- `CRITICAL` — 可能阻止操作的严重错误
### **日志格式**
通过环境变量 `SENTINEL_LOG_FORMAT` 设置：
- `text` — 人类可读彩色输出（默认）
- `json` — 结构化 JSON 行，便于机器解析
### **文件日志**
设置 `SENTINEL_LOG_FILE` 以启用文件日志：
```
export SENTINEL_LOG_FILE=/var/log/sentinel.log
python orchestrator.py --target ./contracts
```
## 📊 **SARIF 报告支持**
Sentinel Engine 支持 SARIF 2.1.0（静态分析结果交换格式），用于与 GitHub 高级安全及其他工具集成。
### **生成 SARIF 报告**
**通过 CLI：**
```
# 使用报告生成器生成 SARIF 报告
python report_generator.py --format sarif --output report
# Aderyn 也支持 SARIF 输出
python aderyn_wrapper.py ./project --format sarif
```
**通过配置：**
```
[reporting]
format = "sarif"
sarif_upload = true # Enable GitHub SARIF upload
```
### **GitHub Actions 集成**
将 SARIF 结果上传至 GitHub 高级安全：
```
- name: Install Sentinel Engine
run: pip install sentinel-engine
- name: Run Sentinel Scan
run: |
sentinel-engine --target ./contracts --report
python report_generator.py --format sarif --output sentinel-results
- name: Upload SARIF to GitHub
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: sentinel-results.sarif
```
## 🌐 **API 弹性功能**
`http_utils.py` 模块为威胁情报 API 提供弹性 HTTP 通信：
### **重试逻辑**
- 失败请求指数退避（带抖动）
- 可配置最大重试次数（默认：3）
- 在 5xx 错误与超时时自动重试
- 尊重 `Retry-After` 头以处理速率限制
### **速率限制**
- 令牌桶速率限制器，控制请求速率
- 可配置每秒/每分钟请求数
- 防止 API 配额耗尽
### **错误分类**
- 自动分类 HTTP 状态码
- 不同错误类型采用不同重试策略
- 通过 `SentinelAPIError` 提供结构化错误报告
## 🐛 **故障排查**
### **缺失外部工具**
**未找到 Slither：**
```
# 安装 Slither
pip install slither-analyzer
# 验证安装
slither --version
```
**未找到 Aderyn：**
```
# 安装 Aderyn（需要 Rust）
cargo install aderyn
# 或通过 Foundry
foundryup
```
**未找到 Medusa：**
```
# 安装 Medusa（需要 Go）
go install github.com/crytic/medusa/cmd/medusa@latest
```
**OpenAI API 密钥未设置：**
若在使用漏洞生成时看到错误：
```
# 设置 OpenAI API 密钥
export OPENAI_API_KEY="sk-..."
# 或在 Windows 上
set OPENAI_API_KEY=sk-...
```
**Solc 版本未安装：**
若 Slither 报错“solc 版本未安装”：
```
# 安装 solc-select
pip install solc-select
# 安装并使用特定 Solidity 版本
solc-select install 0.8.19
solc-select use 0.8.19
```
**威胁情报 API 网络超时：**
若威胁情报查询超时：
```
# 通过环境变量增加超时
export SENTINEL_LOG_LEVEL=DEBUG # See detailed retry attempts
# 检查网络连接
python -c "from http_utils import resilient_get; resilient_get('https://osv.dev')"
# 系统自动使用指数退避重试
# 您也可以检查防火墙/代理设置
```
### **常见问题**
**“找不到合约文件”**
- 确保目标路径存在且可访问
- 使用绝对路径或确认相对于当前目录的路径正确
- 检查文件权限
**“Docker 构建失败”**
- 确保 Docker 守护进程正在运行
- 检查可用磁盘空间（约 600MB 需求）
- 尝试使用 `--no-cache` 标志构建
**“权限被拒绝”**
- Linux/Mac：必要时执行 `chmod +x` 脚本
- 检查输出目录的写入权限
## 🤝 **贡献**
### **添加新启发式规则**
编辑 `heuristic_scanner.py`：
```
HeuristicRule(
id="MY_NEW_RULE",
description="Brief description",
severity="HIGH", # CRITICAL, HIGH, MEDIUM, INFO
pattern=re.compile(r"your_regex_pattern"),
hint="Remediation guidance..."
)
```
### **添加威胁情报源**
- **EVM：** 编辑 `knowledge_fetcher.py` → 添加新 API/RSS 源
**Solana：** 编辑 `solana_intel.py` → 添加审计公司 GitHub 仓库
## 📄 **许可证**
- **社区功能：** MIT 许可证（参见 [LICENSE](LICENSE)）
- **专业功能：** 商业许可证（参见 [LICENSE-PRO](LICENSE-PRO)）
## 🙏 **致谢**
**由以下团队打造：**
- CyberShield Austin（专业安全审计）
- [@defiauditccie](https://twitter.com/defiauditccie)（Twitter/X）
**技术支持：**
- [Slither](https://github.com/crytic/slither) - Trail of Bits
- [Aderyn](https://github.com/Cyfrin/aderyn) - Cyfrin
- [Medusa](https://github.com/crytic/medusa) - Crytic
- [Mythril](https://github.com/ConsenSys/mythril) - ConsenSys
- [Foundry](https://github.com/foundry-rs/foundry) - Paradigm
- [OSV.dev](https://osv.dev) - Google
**威胁情报：**
- EVM：Code4rena、Immunefi、Solodit
- Solana：Neodyme、OtterSec、Sec3
## 🔧 **环境变量**
Sentinel Engine 支持以下环境变量配置：
| 变量 | 描述 | 默认值 | 是否必需 |
|------|------|--------|----------|
| `SENTINEL_LOG_LEVEL` | 日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL） | INFO | 否 |
| `SENTINEL_LOG_FORMAT` | 输出格式（"text" 或 "json"） | text | 否 |
| `SENTINEL_LOG_FILE` | 可选文件路径用于日志输出 | （无） | 否 |
| `OPENAI_API_KEY` | OpenAI API 密钥，用于 GPT-4 漏洞生成 | （无） | AI 功能 |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥，用于 Claude 漏洞生成 | （无） | AI 功能 |
### **使用示例**
```
# 调试日志输出到文件
export SENTINEL_LOG_LEVEL=DEBUG
export SENTINEL_LOG_FILE=/var/log/sentinel.log
sentinel-engine --target ./contracts
# 结构化日志的 JSON 格式
export SENTINEL_LOG_FORMAT=json
sentinel-engine --target ./contracts 2>&1 | jq
# OpenAI 用于利用生成
export OPENAI_API_KEY="sk-..."
python exploit_generator.py --finding-json findings.json
```
## 📧 **支持**
**专业审计：**
- CyberShield Austin
- Twitter: [@defiauditccie](https://twitter.com/defiauditccie)
- 网站: [sentinel-engine.io](https://sentinel-engine.io)
**GitHub：**
- 问题反馈: [github.com/RunTimeAdmin/sentinel-engine/issues](https://github.com/RunTimeAdmin/sentinel-engine/issues)
**版本：** 3.0.0
**最后更新：** 2026年4月19日
**许可证：** MIT
**支持链：** EVM、Solana
**分析器：** 21
**模式：** 31 条 EVM + 35 条 Solana
**配置：** 3
**创新功能：** 7
**⭐ 如果此工具帮助发现了漏洞，请为仓库加星！**
标签：AI安全分析, CI/CD安全, EVM, JSON报告, Llama, Markdown报告, PyPI安全工具, Python安全工具, Solana, 专业审计报告, 云安全监控, 区块链安全, 升级差异检查, 协议指纹识别, 可视化界面, 可配置规则, 合约审计, 后端开发, 安全合规, 安全审计平台, 安全扫描, 开源安全审计, 报告生成, 攻击路径可视化, 数据可视化, 日志审计, 时序注入, 智能合约安全, 生产就绪, 符号执行, 网络代理, 自动化漏洞生成, 访问矩阵, 请求拦截, 运行时分析, 逆向工具, 集成分析器, 静态分析, 黑客工具