Gokul0211/SENTINEL
GitHub: Gokul0211/SENTINEL
面向生产级 LLM 系统的五层语义安全代理，通过实时拦截与分析防御 prompt 注入、RAG 投毒和 Agent 劫持等新型攻击。
Stars: 0 | Forks: 0
# SENTINEL：面向生产级 LLM 系统的语义安全网
## 概述
SENTINEL 是一种内联的语义层安全网，位于用户输入、检索到的上下文、LLM agent 环境以及最终系统输出之间。标准的 Web Application Firewalls (WAFs) 无法保护 LLM，因为其攻击面由自然语言而非语法异常组成。SENTINEL 通过实现五个实时语义分析层来解决这个问题。
此仓库包含 SENTINEL 架构的完整实现，涵盖代理引擎、五个安全层、跨层关联引擎，以及用于监控威胁事件的实时 HUD 仪表板。
## 架构
系统作为中间代理 (`/v1/chat/completions`) 运行，拦截进出 LLM 的流量。
### 核心组件
* **Threat Intelligence Bus (TIB)：** 一个内存中的事件总线和会话状态管理器 (`sentinel/core/threat_bus.py`)。它跟踪对话历史，聚合各层的威胁分数，并通过 WebSockets 向前端广播 `ThreatEvent` 结构。
* **关联引擎：** 在每个请求 pipeline 的末端运行 (`sentinel/core/correlation_engine.py`)。它评估跨层信号以识别复杂攻击（例如，缓慢的语义偏移与系统 prompt 提取探测相结合）。
### 安全层
1. **Layer 1：文本与图像注入扫描器 (`sentinel/layers/layer1.py`)**
* *功能：* 对显式的 prompt 注入、越狱和提取探测进行同步过滤。
* *机制：* 两层分析。Tier 1 使用高性能 regex 模式。Tier 2 使用通过 `all-MiniLM-L6-v2` embedding 针对精选的已知攻击特征向量集生成的语义相似度。
2. **Layer 2：RAG 完整性监视器 (`sentinel/layers/layer2_rag/`)**
* *功能：* 通过在注入和检索前验证文档块来防止知识中毒。
* *机制：* 使用 L1 embedding 模型计算“指令密度”，以检测某个 chunk 是否正试图发布指令。采用 HMAC-SHA256 签名进行数据溯源，以检测注入后的篡改。
3. **Layer 3：对话偏移跟踪器 (`sentinel/layers/layer3.py`)**
* *功能：* 识别试图通过多轮升级绕过静态过滤器的慢热型攻击。
* *机制：* 通过计算连续用户轮次之间 embedding 的余弦距离来跟踪语义速度。监控相对于基准主题的累积偏移。
4. **Layer 4：Agentic 推理审计器 (`sentinel/layers/layer4_agentic/`)**
* *功能：* 保护 function-calling 和工具执行。
* *机制：* 在执行前拦截工具调用。解析思维链 trace 以获取自我授权启发式信息。使用编辑距离追踪参数来源，以确定参数是源自用户输入、检索到的上下文还是模型幻觉。包含用于工具分类的静态风险矩阵。
5. **Layer 5：输出语义防火墙 (`sentinel/layers/layer5_output/`)**
* *功能：* 对 LLM 输出进行最后阶段的验证。
* *机制：* 使用 regex 模式扫描 PII 泄漏（SSN、信用卡、API 密钥）。使用 Jaccard 相似度（token 重叠）和针对已知系统 prompt 的语义相似度，检测系统 prompt 窃取。执行 `sentinel_policy.yaml` 中定义的策略。
## 设置与安装
### 前置条件
* Python 3.10+
* Windows 环境（或者是 Linux/macOS，尽管当前的路径/脚本假定环境为 Windows）
### 安装
1. 导航到项目根目录。
2. 安装依赖：
pip install fastapi uvicorn sentence-transformers pydantic websockets pyyaml pdfplumber Pillow
*注意：ChromaDB 集成目前通过 `chunk_store.py` 中的内存字典进行模拟，以绕过标准 Windows 环境上的 C++ 编译器依赖问题。完整性逻辑保持完全可用。*
## 运行系统
使用 Uvicorn 启动 FastAPI 服务器：
```
python main.py
```
* API 将在 `http://localhost:8080` 可用。
* HUD 仪表板在 `http://localhost:8080/` 提供。
## 接口
### 核心代理
* `POST /sentinel/chat`：主要拦截器端点。接收 `{ "content": "string", "session_id": "string" }` 并将其通过 L1 和 L3 分析，模拟 LLM 响应，并运行 L5 输出扫描。
### RAG 操作 (Layer 2)
* `POST /sentinel/rag/ingest`：注入文档 chunk。计算信任分数并对其进行签名。
* `GET /sentinel/rag/chunks`：列出所有活动和隔离的 chunk。
* `POST /sentinel/rag/quarantine/{chunk_id}`：手动将 chunk 移至隔离区。
### Agentic 操作 (Layer 4)
* `POST /sentinel/agent/tool_call`：拦截并审计工具调用。接收 `{ "tool_name": "string", "parameters": {}, "reasoning_trace": "string", "session_id": "string", "history": [] }`。
### 输出扫描 (Layer 5)
* `POST /sentinel/output/scan`：用于最终输出扫描的独立端点。
### 演示场景
* `POST /sentinel/demo/{scenario_id}`：触发通过真实安全层处理的自动化攻击序列。
* `rag_agent`：注入一个中毒 chunk 并触发匹配该 chunk 参数的工具调用，以演示 `RAG_PLUS_AGENT_ATTACK` 关联规则。
* `slow_burn`：通过 L3 和 L5 运行预定义的 5 轮对话序列，以演示 `SLOW_BURN_INJECTION` 和 `EXFIL_AFTER_PROBE` 关联规则。
## 可解释性与 UI
前端仪表板 (`dashboard/static/index.html`) 订阅 `/ws/events` WebSocket。UI 中的所有组件均由 `ThreatEvent` 数据结构驱动。当某一层阻止请求时，它会使用详细的发现链填充 `explanation` 字典，前端会在会话面板中原生渲染该字典。UI 可视化中未使用任何模拟数据；所有层指示器和指标均反映实时分析输出。
标签：AI防御设施(AIWAF), 大语言模型安全, 恶意代码分类, 提示词注入防御, 机密管理, 检索增强生成(RAG)安全, 流量代理拦截, 逆向工具