EresusSecurity/Eresus-sentinel
GitHub: EresusSecurity/Eresus-sentinel
面向 AI/LLM 全栈安全的一体化扫描工具包，覆盖模型工件静态分析、Prompt 防火墙、MCP Agent 验证、供应链审计与红队自动化评估。
Stars: 12 | Forks: 1
# Eresus Sentinel
**Alpha 阶段，确定优先的 AI 安全工具包，用于本地审计、MCP/Agent 检查、模型工件扫描和 Prompt 防火墙测试。**
Sentinel 提供基于确定性、YAML 驱动的跨 AI 技术栈安全扫描——从模型工件和 Prompt 防火墙到供应链审计和红队自动化。生成发现结果无需依赖 AI；AI/Judge 适配器是可选的丰富层。
## 检测范围
- **序列化 RCE** — 针对 300+ 个黑名单 `module.function` 对的 Pickle/joblib/dill `GLOBAL` 操作码
- **框架代码注入** — Keras Lambda 字节码、TorchScript `code/` 后门、PMML/Jinja2 SSTI、`auto_map` RCE
- **压缩包漏洞利用** — ZIP / TAR / 7z / `.mar` / `.nemo` 中的 Zip Slip、路径遍历、符号链接攻击
- **嵌入的机密信息** — 2000+ 种 API 密钥模式、连接字符串、模型元数据中的硬编码 Token
- **网络回调** — Pickle 中的 socket/urllib/requests 全局变量；GGUF 元数据中的 C2 URL
- **供应链篡改** — 缺失哈希完整性、Typosquatting（误植域名）、OSV.dev CVE 查询
- **Prompt / Agent 注入** — 模型卡中的指令注入、MCP 工具描述劫持
- **后门权重** — 统计异常、熵离群值、可疑权重分布（启发式）
## 支持的格式
涵盖模型、压缩包和配置格式的 70 多个扫描器。**绝不加载或执行任何模型。**
| 格式 | 扩展名 | 风险 |
|--------|-----------|------|
| **Pickle / Joblib** | `.pkl` `.pickle` `.p` `.dill` `.dat` `.data` `.joblib` | CRITICAL |
| **PyTorch** | `.pt` `.pth` `.bin` `.ckpt` | CRITICAL |
| **TorchScript** | `.torchscript` (ZIP) | HIGH |
| **TorchServe** | `.mar` | HIGH |
| **Torch7 (Lua)** | `.t7` `.th` `.net` | HIGH |
| **NumPy** | `.npy` `.npz` | HIGH |
| **Keras** | `.keras` `.h5` `.hdf5` | HIGH |
| **TensorFlow** | `.pb` `.meta` `saved_model/` | HIGH |
| **Skops** | `.skops` | HIGH |
| **R Serialized** | `.rds` `.rda` `.rdata` | HIGH |
| **NeMo** | `.nemo` | HIGH |
| **CNTK** | `.dnn` `.cmf` | HIGH |
| **ONNX** | `.onnx` | MEDIUM |
| **JAX / Orbax / Flax** | `.jax` `.checkpoint` `.orbax` `.msgpack` | MEDIUM |
| **TFLite** | `.tflite` | MEDIUM |
| **ExecuTorch** | `.pte` `.ptl` | MEDIUM |
| **TensorRT** | `.engine` `.plan` `.trt` | MEDIUM |
| **CoreML** | `.mlmodel` `.mlpackage` | MEDIUM |
| **CatBoost / XGBoost / LightGBM** | `.cbm` `.bst` `.lgb` | MEDIUM |
| **PaddlePaddle** | `.pdmodel` `.pdiparams` | MEDIUM |
| **MXNet** | `*-symbol.json` `*.params` | MEDIUM |
| **SafeTensors** | `.safetensors` | LOW |
| **GGUF / GGML** | `.gguf` `.ggml` `.ggmf` `.ggjt` `.ggla` `.ggsa` | LOW |
| **OpenVINO / PMML** | `.xml` `.pmml` | LOW |
| **Llamafile** | `.llamafile` | LOW |
| **ZIP / TAR / 7z** | `.zip` `.tar` `.tar.gz` `.7z` | HIGH (traversal) |
| **RAR** | `.rar` | Fail-closed |
| **JSON / YAML manifests** | `config.json` `*.yaml` | HIGH |
| **Jinja2 templates** | `.j2` `.jinja` `.jinja2` | CRITICAL |
→ [包含检测详情的完整格式文档](docs/SUPPORTED_FORMATS.md)
## 安全领域
| 领域 | 模块 | 覆盖范围 |
|--------|--------|----------|
| 🔬 **Artifact (工件)** | `artifact/` | 70+ 个扫描器 — Pickle, Torch, Keras, ONNX, GGUF, Safetensors, TFLite, 压缩包 |
| 🛡️ **输入防火墙** | `firewall/input/` | 22 项防护栏 — 注入、机密信息、PII、编码攻击、隐形文本、毒性 |
| 🔒 **输出防火墙** | `firewall/output/` | 24 项防护栏 — 偏见、合规、版权、水印、格式强制 |
| 🔍 **SAST** | `sast/` | 静态分析 + 120+ 种机密信息模式 + 熵 + Git 历史扫描 |
| 🤖 **Agent/MCP** | `agent/` | 信任映射、权限、MCP Schema 验证、实时 MCP 发现 |
| 📦 **供应链** | `supply_chain/` | 依赖扫描、Typosquatting、OSV.dev、来源 |
| ⚔️ **红队 / 评估** | `redteam/` | 48 个探针 + 13 个检测器 + 14 个生成器 + YAML Playbook/Eval 引擎 |
| 🔗 **MCP 代理** | `mcp_proxy.py` | 带有 OPA 策略执行的实时拦截代理 |
| 🚦 **运行时网关** | `runtime_gateway.py` | 带有监控/执行模式且与提供商无关的 LLM 网关契约 |
| 📓 **Notebook** | `notebook_scanner/` | Jupyter 安全扫描（14 个插件） |
| 📝 **Diff** | `diff_scanner/` | Git diff/PR ML 反模式检测 |
## 领域成熟度
| 领域 | 成熟度 |
|--------|----------|
| Pickle/Artifact 免加载扫描 | Beta |
| Prompt 防火墙确定性检查 | Beta |
| SAST/机密信息/Notebook/Diff | Beta |
| MCP 清单/实时扫描 | Beta |
| MCP 代理运行时执行 | Experimental |
| Dashboard/API | Experimental |
| HF/供应链实时集成 | Experimental |
| 运行时网关提供商适配器 | Experimental |
| AI/Judge 丰富层 | 可选实验性 |
## 快速开始
```
# 安装
pip install -e ".[dev]"
# 验证安装
sentinel doctor
sentinel doctor --json
# 预览扫描计划，然后扫描项目
sentinel scan ./my-project --plan --profile fast
sentinel scan ./my-project/
# Firewall 一个 prompt
sentinel firewall "user input text"
# 扫描模型 artifacts
sentinel artifact ./models/
# Red team 评估
sentinel redteam --target openai/gpt-4o
# Config 驱动的 eval
sentinel evaluate eval.yaml
# Live/manifest MCP 扫描
sentinel mcp scan ./mcp-manifest.json
# 交互式 shell
sentinel shell
```
## 架构
```
┌──────────────────────────────────────────────────────────────┐
│ Eresus Sentinel CLI │
│ (Python · Click + Rich terminal) │
├──────────┬──────────┬──────────┬──────────┬──────────────────┤
│ Artifact │ Firewall │ SAST │ Agent/ │ Supply Chain │
│ Scanner │ (I/O) │ Analyzer │ MCP │ Auditor │
├──────────┴──────────┴──────────┴──────────┴──────────────────┤
│ YAML Rule Engine │
│ (rules/ — zero hardcoded regex) │
├──────────────────────────────────────────────────────────────┤
│ Finding Universal Data Model │
│ (7 domain factories + dedup fingerprints) │
├──────────────────────────────────────────────────────────────┤
│ MCP Proxy │ Eval Runner │ Runtime Gateway │ Telemetry │
├──────────────────────────────────────────────────────────────┤
│ AI-Assisted Layer (optional, pluggable) │
│ OpenAI / Anthropic / Local GGUF / Generic REST │
└──────────────────────────────────────────────────────────────┘
```
### 核心设计原则
- **确定优先** — 所有扫描均基于 regex/AST/操作码。生成发现结果不依赖 AI。
- **YAML 驱动的规则** — 所有模式位于 `rules/*.yaml` 中。代码中零硬编码正则表达式。
- **插件自动发现** — 放入一个扫描器类，它就会自动注册。
- **懒加载** — 模块按需加载，实现快速 CLI 启动。
- **SARIF v2.1.0 输出** — 原生 GitHub Security 选项卡集成。
## CLI 命令
最常用的命令有：
```
sentinel scan ./project --profile fast -f json
sentinel artifact ./models -f sarif
sentinel firewall "user input text" -f json
sentinel mcp scan ./mcp-manifest.json
git diff main...HEAD | sentinel diff - -f sarif
```
完整命令表请参见 [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)
有关退出代码和输出结构，请参见 [docs/CLI_CONTRACT.md](docs/CLI_CONTRACT.md)。
## Python SDK
```
from sentinel import Sentinel
s = Sentinel()
# 扫描输入
result = s.scan_input("user prompt here")
print(result.findings)
# 扫描输出
result = s.scan_output("prompt", "llm response")
# 完整对话扫描
result = s.scan_conversation("prompt", "response")
# 导出至 SARIF
s.export_sarif(result.findings, "report.sarif")
```
## 配置驱动评估
```
# eval.yaml
providers:
- id: local-echo
name: echo
prompts:
- id: greeting
prompt: "hello {{name}}"
tests:
- id: alice
vars: { name: Alice }
assertions:
- type: contains
expected: Alice
```
```
sentinel evaluate eval.yaml --fail-on-threshold 0.95
sentinel evaluate eval.yaml -f json -o eval-report.json
```
## MCP 实时扫描器
扫描离线清单或实时 MCP JSON-RPC 端点：
```
sentinel mcp scan ./mcp-manifest.json
sentinel mcp scan --url http://localhost:3000/mcp
sentinel mcp scan --stdio-command npx my-mcp-server
```
该扫描器会发现工具、Prompt、资源、服务器指令、身份验证元数据和就绪信号。
## 运行时网关
```
from sentinel.runtime_gateway import SentinelGateway, EchoProviderAdapter
gateway = SentinelGateway(provider=EchoProviderAdapter())
decision = gateway.complete("user prompt")
if decision.blocked:
print(decision.response.text)
```
## REST API
```
# 启动 Web UI dashboard
export SENTINEL_PASSWORD=change-me
sentinel dashboard
# 打开 http://127.0.0.1:8080
# 如果从源码运行且 UI 缺失：
# Vite/React Router 需要 Node.js 20.19+。
cd frontend && npm install && npm run build
# 启动 API server
sentinel serve --host 0.0.0.0 --port 8080
# 扫描 endpoint
curl -X POST http://localhost:8080/scan/input \
-H "Content-Type: application/json" \
-d '{"text": "user prompt"}'
```
## MCP 代理
实时拦截和检查所有 MCP 协议流量：
```
# Stdio 模式 — 包装任何 MCP server
sentinel proxy --transport stdio --mode enforce --server-cmd npx my-mcp-server
# HTTP 模式 — 反向代理
sentinel proxy --transport http --mode enforce --upstream http://localhost:3000 --port 8080
```
## 配置
引擎通过 `sentinel.toml` 进行配置：
```
[engine]
mode = "deterministic" # "ai-assisted" | "full"
min_severity = "MEDIUM"
action_policy = "balanced" # "advisory" | "strict"
[scanners.artifact]
enabled = true
[scanners.firewall.input]
enabled = true
[scanners.firewall.output]
enabled = true
[scanners.sast]
enabled = true
[scanners.redteam]
enabled = false # Opt-in only
[ai]
enabled = false
backend = "ollama"
model = "llama3.2"
```
## Docker
```
# 标准
docker build -t eresus-sentinel .
docker run -v ./models:/data eresus-sentinel scan /data
# GPU 加速 (CUDA)
docker build -f Dockerfile.cuda -t eresus-sentinel:cuda .
# Docker Compose (API + worker)
docker compose up
```
## CI/CD 集成
### GitHub Actions
```
- name: Sentinel Security Scan
run: |
pip install eresus-sentinel
sentinel scan ./src --format sarif --output sentinel.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: sentinel.sarif
```
## 文档
**[完整文档](https://eresussec.com/docs)** | **[快速开始](docs/QUICKSTART.md)** | **[支持的格式](docs/SUPPORTED_FORMATS.md)** | **[安全模型](docs/SECURITY_MODEL.md)**
| 主题 | 链接 |
|-------|------|
| 入门指南 | [快速开始](docs/QUICKSTART.md) · [土耳其语](docs/TR_QUICKSTART.md) |
| 格式覆盖 | [支持的格式](docs/SUPPORTED_FORMATS.md) |
| 扫描器控制 | [扫描器选择](docs/SCANNER_SELECTION.md) |
| 威胁模型 | [安全模型](docs/SECURITY_MODEL.md) |
| 离线部署 | [离线使用](docs/OFFLINE.md) |
| Python/OS 兼容性 | [兼容性矩阵](docs/COMPATIBILITY.md) |
| CLI 标志 | [CLI 参考](docs/CLI_REFERENCE.md) · [CLI 契约](docs/CLI_CONTRACT.md) |
| 编写规则 | [规则编写](docs/RULE_AUTHORING.md) · [YAML 规则](docs/RULES.md) |
| 编写扫描器 | [扫描器编写](docs/SCANNER_AUTHORING.md) |
| CI / Pre-commit | [CI 和 Pre-Commit](docs/CI_PRECOMMIT.md) |
| 减少噪音 | [误报处理](docs/FALSE_POSITIVES.md) |
| 运维 | [MCP 代理](docs/MCP_PROXY_DEPLOYMENT.md) · [故障排除](docs/TROUBLESHOOTING.md) · [常见问题](docs/FAQ.md) |
## 认证与安全
对于生产环境部署：
```
# 启用 API authentication
export SENTINEL_AUTH_TYPE=bearer
export SENTINEL_AUTH_TOKEN=your-secret-token
# 限制 CORS
export SENTINEL_CORS_ORIGINS=https://yourdomain.com
# 启用审计日志
export SENTINEL_AUDIT_LOG=/var/log/sentinel/audit.jsonl
# Rate limiting（通过 SENTINEL_RATE_LIMIT 配置）
export SENTINEL_RATE_LIMIT=100/minute
```
完整的加固指南请参见 [安全策略](SECURITY.md)。
## 系统要求
- Python 3.10+
- 核心依赖：`pyyaml`、`rich`
- API 服务器：`pip install eresus-sentinel[api]`（会增加 `fastapi`、`uvicorn`）
- Web 仪表板：`pip install eresus-sentinel[web]`
- ML 扫描：`pip install eresus-sentinel[ml]`（会增加 `torch`、`transformers`）
- Rust Pickle 后端：`cd rust/sentinel-pickle && maturin develop --release`
- 所有附加组件：`pip install eresus-sentinel[all]`
## Alpha 阶段免责声明
## 许可证
Proprietary — © 2026 Eresus Security。详见 [LICENSE](LICENSE)。
Eresus Security · eresussec.com
标签：AI代理验证, AI漏洞扫描, AI红队, AI防火墙, API接口, AppImage, CISA项目, DNS 反向解析, DNS 解析, GGUF, Go语言工具, IP 地址批量处理, Pickle扫描, Safetensors, URL发现, Web应用防火墙, 人工智能安全, 代码注入防御, 元数据安全, 可视化界面, 合规性, 多语言支持, 大语言模型安全, 安全合规, 安全工具包, 安全检测, 安全测试框架, 密钥泄露防护, 序列化漏洞检测, 恶意代码分类, 恶意模型检测, 提示注入防火墙, 提示词安全, 本地安全审计, 机器学习安全, 机密管理, 模型后门检测, 模型安全分析, 模型安全扫描, 模型工件分析, 模型逆向工程, 模型风险评估, 深度学习安全, 红队自动化, 结构化查询, 网络代理, 网络安全扫描, 自动化安全, 请求拦截, 逆向工具, 配置审计, 防御逃避检测, 零误报