Lukentony/AI-guardian-lab

# AI Guardian Lab     AI agents 可以在你的机器上运行 shell 命令。Guardian 决定哪些命令真正执行。 AI 代理框架通常为 LLM 提供直接的 shell 访问权限以完成任务。在大多数实现中，安全性完全依赖于模型遵循系统指令的意愿。但模型合规性并不等同于安全强制。 ## 快速入门（适合初学者）🚀 体验 60 秒内的防护： 1. **部署：** `docker-compose up -d` 2. **攻击：** `./demo.sh` 观察 Guardian 如何实时拦截混淆载荷与意图冲突的命令。 ## 防御流水线（适合资深用户）🛡️ Guardian 实现了一个确定性的多层安全中间件。它**不**仅仅依赖 LLM 的“良好行为”。 ### L1 — 二进制允许列表 严格限制允许的二进制文件。如果不在允许列表（例如 `nc`、`nmap`），则在调用 LLM 之前就被阻断。 ### L2 — 正则引擎 检测混淆技术（shell 中的 base64 解码）、危险标志（`--no-preserve-root`）和已知利用模式。 ### L3 — 意图一致性 交叉引用高级别的**任务意图**（用户所问）与**命令动作**（代码实际执行）。 - *任务：* “列出文件” → *命令：* `rm -rf /` = **BLOCKED**（意图冲突）。 ### L4 — LLM 语义检查 对复杂或模糊命令进行深度语义分析。采用**失败关闭**逻辑：如果 LLM 不可用或响应异常，则阻断命令。 ### 取证完整性 审计日志由**链式哈希**（SHA-256）保护。每个日志条目都通过密码学方式链接到前一个，确保“证据链”并使篡改可检测。 ## 为何存在此项目 AI 生态存在执行缺口。尽管我们有监控输入输出的工具，但主流代理框架并未内置原生的、预工具执行的访问控制。提示工程常被用作防御手段，但这只是建议而非安全边界。Guardian 通过提供一个确定性的中间层，消除了对 LLM 系统级动作的最终决策权。 ## 工作原理 Guardian 运行一个 4 层验证流水线。它是“失败关闭”式设计：如果某层存在疑虑，命令将被阻断。 ``` Agent Request │ ▼ ┌─────────────────────────┐ │ L1: Binary Allowlist │──► BLOCK (unknown or red-zone binary) └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ │ L2: Regex Engine │──► BLOCK (obfuscation / destruction pattern) └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ │ L3: Intent Coherence │──► BLOCK (task intent ≠ command action) └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ │ L4: LLM Semantic Check │──► BLOCK / ALLOW (ambiguous cases only) └───────────┬─────────────┘ │ ▼ EXECUTE ``` 1. **L1: 二进制允许列表**：基于风险区域（绿、黄、红）的即时过滤。如果二进制在当前上下文中未被明确允许，执行在此终止。 2. **L2: 正则模式匹配**：一个 ReDoS 安全的双路径引擎，对原始命令与规范化命令同时检查混淆、渗出与破坏模式。 3. **L3: 意图一致性映射**：这是差异化所在。它使用静态关键词分类法将 `task` 字段与命令映射到四类意图 —— `read`、`write`、`delete`、`network`，然后检查冲突。该分类法故意保持最小化以确保规则可审计且可预测。 | 任务意图 | 命令意图 | 结果 | |----------|----------|-------| | read | delete | BLOCKED | | read | network | BLOCKED | | write | delete | BLOCKED | | write | read | ALLOWED | | delete | delete | ALLOWED | 示例：`task="分析磁盘使用"` + `command="rm -rf /tmp"` → 任务映射为 `read`，命令映射为 `delete` → **BLOCKED**。 4. **L4: LLM 语义检查**：LLM 作为最后手段。仅对确定性层无法解析的模糊情况咨询 LLM，提供额外的语义理解。 ## 为何优先确定性 我将确定性检查置于基于 LLM 的验证之上，原因有三： - **透明性**：你可以审计正则表达式与映射表。清楚知道命令为何被阻断。 - **速度**：确定性检查以毫秒计，且无需消耗令牌。 - **可靠性**：逻辑不会“幻觉”。它提供刚性边界，无法通过提示注入跨越。 **关于 L4**：LLM 层并非作为确定性层“无法处理”情况的备用方案，而是明确的边界定义。L1–L3 覆盖已知攻击面：已知恶意二进制、已知模式、以及具有明确映射的意图冲突。L4 处理残余情况：结构合法、未匹配任何模式、且任务与命令关系在设计上模糊的命令。实践中，L4 触发的请求不到 5%。LLM 无法覆盖 L1–L3 发出的阻断；执行层级严格单向。 ## 基准测试 在包含 100 条标记命令的合成数据集上评估（50 条正常，50 条恶意），旨在覆盖当前策略配置的已知攻击面。 | 指标 | 得分 | |---------------|------------------------| | 精确率 | 100%（合成数据集） | | 召回率 | 100%（合成数据集） | | 误报 | 0 | | 漏报 | 0 | 数据集与测试套件： [`tests/`](tests/) ## 与 Guardian 的对比 | 功能 | AI Guardian Lab | LLM Guard | Guardrails AI | |-----------------------------|-----------------|-----------|---------------| | 确定性强制执行 | ✅ | Partial | ❌ | | 意图一致性检查 | ✅ | ❌ | ❌ | | 框架无关（REST API） | ✅ | ❌ | Partial | | 默认失败关闭 | ✅ | ❌ | ❌ | | LLM 仅作为最后手段 | ✅ | ❌ | ❌ | | 审计日志 | ✅ | Partial | Partial | 对比基于截至 2026 年 3 月的公开文档。LLM Guard 与 Guardrails AI 是输入/输出扫描器，而非命令级执行层——设计目标不同但有部分重叠。本表仅聚焦命令级强制能力。 ## 集成壁垒 代理框架出于 SSRF 防护会默认阻止对私有 IP 的调用。这是有意且正确的选择，但副作用是：Guardian 的执行目前依赖模型合规性（必须被指示调用中间件），而非框架内置的硬钩子。这是整个生态的开放问题：真正的、无可突破的自动强制执行，只有当框架实现原生的预工具钩子时才能实现。 ## 取证：会话后分析 Guardian 还提供一个事后分析模块。虽然验证流水线实时拦截命令，但取证模块分析已完成的代理会话以发现事后行为异常。 它适用于任何产生结构化日志的代理框架——不仅限于内置 Guardian 的代理。 **它能检测到：** - **工具升级**：会话中风险从安全命令逐步演变为危险命令 - **意图漂移**：行为偏离声明的任务 - **提示注入信号**：工具输出中嵌入的指令 **试用：** ``` bash demo_forensics.sh ``` **API：** ``` curl -s -X POST http://localhost:5000/forensics/analyze \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"jsonl": "{\"role\": \"user\", \"content\": \"list files\"}\n..."}' ``` 响应包含异常分数（0–100）、各标志的置信度分析以及可读摘要。 ## 快速开始 #### 1. 安装 ``` git clone https://github.com/Lukentony/AI-guardian-lab.git cd ai-guardian-lab ./install.sh ``` #### 2. 启动 ``` docker-compose up -d ``` ### 3. 试用 ``` # 阻止危险命令 curl -s -X POST http://localhost:5000/validate \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"command": "rm -rf /tmp", "task": "analyze disk usage"}' ``` ``` { "approved": false, "layer": "L3", "reason": "Intent conflict: task maps to 'read', command maps to 'delete'.", "command": "rm -rf /tmp", "task": "analyze disk usage" } ``` ``` # 允许安全命令 curl -s -X POST http://localhost:5000/validate \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"command": "df -h", "task": "analyze disk usage"}' ``` ``` { "approved": true, "layer": null, "reason": null, "command": "df -h", "task": "analyze disk usage" } ``` ## 使用场景 - **本地测试**：在给予完全访问权限前，测试 AI 代理的意图 - **审计与合规**：需要记录代理尝试执行的每条命令（包括被拒绝的） - **硬 chokepoint**：在 LLM 与 Shell 之间放置真实过滤器，而非依赖模型“良好行为” ## 威胁模型与限制 **攻击者模型**：Guardian 假设攻击者： - 通过用户可控输入字段注入恶意指令（提示注入） - 对命令进行混淆以逃避模式匹配（编码、变量展开、链式调用） - 尝试利用任务描述与执行命令之间的差距 - 控制 LLM 输出但无法直接修改 Guardian 的配置或策略文件 Guardian 是一个盾牌，而非奇迹： 1 **正则限制**：极其复杂的混淆理论上可能绕过静态模式。 2. **规范化**：Shell 语法多样性是持续战场；某些边界情况可能需要更新规范化规则。 3. **沙箱依赖**：Guardian 阻断命令，但最终安全还取决于代理运行时的环境隔离（沙箱/Docker）。 ## 文档 - [架构与层级](ARCHITECTURE.md) - [贡献指南](CONTRIBUTING.md) - [安全策略](SECURITY_POLICY.md) ## 📄 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。

标签：AI代理, AI安全, C2, Chain Hashing, Chat Copilot, Cutter, Fail-Closed, FTP漏洞扫描, LLM语义检查, OBFUSCATION, Shell命令拦截, 二进制白名单, 任务意图分析, 命令注入防护, 多层防御, 安全中间件, 安全编排, 实验性, 审计日志, 意图一致性映射, 日志完整性, 权限控制, 正则模式, 确定性安全, 请求拦截, 运行时保护, 逆向工具, 链哈希