# agent-guardian **Repository Path**: fiagainster/agent-guardian ## Basic Information - **Project Name**: agent-guardian - **Description**: 一个简单的Agent智能网关监测系统 代码中暂时包含了四个智能体的源代码，方便后续开发，最后再删除 - **Primary Language**: Unknown - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-06-03 - **Last Updated**: 2026-07-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Agent Guardian — AI Agent 安全监控网关 > **长城杯网络安全大赛 · 参赛作品** > > 零侵入的 AI 智能体流量安全网关。不修改智能体一行源码，所有进出 HTTP 流量先经过四级漏斗检查。 > > 开源仓库：[https://gitee.com/fiagainster/agent-guardian](https://gitee.com/fiagainster/agent-guardian) --- ## 概述 AI Agent 在调用 LLM、抓取网页、执行工具时本质上是发 HTTP 请求。Agent Guardian 将一个安全检查层插入在智能体与外部世界之间——所有进出流量先经过它，发现危险就阻断，正常就放行。 **覆盖智能体**：nanobot / hermes-agent / OpenClaw / Deer-Flow **关键设计原则**： 1. 关键词绝不直接判决 — 关键词只做触发器，加权得分达标才唤醒 LLM 语义复核 2. 智能体是语义层唯一审判官 — 拥有最终解释权，必须基于完整上下文 3. 成本与精度分层 — 越深的层级越智能、成本越高、处理的请求越少 --- ## 快速开始 ```bash # 1. 配置 API Key cp .env.example .env # 编辑 .env，设置 LLM_API_KEY=sk-你的deepseek密钥 # 2. 启动 docker compose up -d --build # 3. 打开控制台 # http://localhost:3000 # 4. 运行安全测试（38 项） docker compose exec attacker python /app/test_suite.py --base-url http://openclaw:18789 ``` 启动后的服务： | 服务 | 端口 | 说明 | |------|:---:|------| | 监控网关 | 8080 | 所有进出 HTTP 流量检查入口 | | Web 控制台 | 3000 | 实时拦截告警、会话风险、审计 | | monitor-brain | 9001 | (可选) 本地 DeBERTa 推理容器 | | mock-server | 8888 | 攻击测试用模拟服务器 | **当前测试结果：38/38 全部通过。** 拦截率 100%，误报率 0%。 --- ## 四级漏斗架构 不是用同一把尺子量所有风险，而是四把不同精度的尺子。95% 以上的正常流量在前三层零 Token、毫秒级完成检测。 ``` 用户输入 / 外部响应 │ ▼ ┌──────────────────────────────────────────────────────────┐ │ 监控网关 :8080 │ │ │ │ L0 DoS防护（<0.5ms, 零Token） │ │ ├─ 单条用户消息 >8000 tokens 拦截（tiktoken 精确计数） │ │ └─ 请求体 >65536 字节拦截 │ │ ↓ │ │ L1 硬拦截（<1ms, 零Token） │ │ ├─ 31 条已知攻击载荷模板（精确/模糊/子串匹配） │ │ └─ Unicode NFKC 归一化抗编码绕过 │ │ ↓ │ │ L2 规则引擎（<2ms, 零Token） │ │ ├─ 16 条字段级安全策略（DENY/ALERT/ASK 三态决策） │ │ └─ 运行时热更新（3 秒生效） │ │ ↓ │ │ L3 指纹检测（<3ms, 零Token） │ │ ├─ 9 类 64 个攻击指纹词库 + 加权评分 │ │ └─ 语义嵌入余弦相似度防同义词绕过 │ │ ↓ 触发（<5% 流量） │ │ L4 LLM 复核（2-5s, ~800 Token/次） │ │ ├─ 上下文感知审查（按攻击类型路由 Prompt） │ │ ├─ 三后端架构（Brain → API → fallback_safe） │ │ └─ SHA256 缓存（300s TTL） │ │ ↓ │ │ 放行（>95% 流量，零开销） │ │ │ │ 出站 request() ←── 双向 ──→ 入站 response() │ │ 消息是否越狱？ 响应 HTML 是否含注入？ │ │ URL 是否恶意？ JSON 中是否含恶意 payload？ │ │ 是否在窃取数据？ LLM 响应是否被篡改？ │ │ 图片 OCR 是否含越狱文字？ │ └──────────────────────────────────────────────────────────┘ ``` ### 防护能力矩阵 | 攻击类型 | L0 DoS | L1 载荷库 | L2 规则引擎 | L3 指纹 + L4 复核 | |----------|:---:|:---:|:---:|:---:| | 提示注入 | — | 已知模板匹配 | 字段级关键词 | 指令覆盖 + 规则篡改指纹 | | 越狱（DAN/开发者模式） | — | 载荷库精确匹配 | 越狱关键词检测 | 越狱模式 + 角色劫持指纹 | | 响应投毒 | — | 响应体关键词 | 响应字段检测 | 间接注入结构检测 | | LLM API 中转站投毒 | — | 响应内容检查 | Token 一致性校验 | 语义复核确认 | | 数据外泄 | — | URL 黑名单 | 敏感 URL 检测 | 信息收集指纹 | | 工具劫持 | — | 危险命令黑名单 | 命令字段检测 | 参数注入指纹 | | 记忆中毒 | — | — | — | 上下文累积得分 | | 图片越狱 | — | OCR 提取文字匹配 | OCR 文字经策略匹配 | OCR 文字语义复核 | | 编码绕过 | — | NFKC 归一化 | 编码异常检测 | 语义向量匹配 | | DoS 资源滥用 | Token 超限拦截 | — | — | 资源滥用指纹 | --- ## 核心特色 **零侵入部署。** 不修改任何智能体源代码。接入只需三行配置： ```yaml environment: HTTP_PROXY: http://monitor:8080 volumes: - agent-guardian_certs:/certs:ro ``` **双向全流量检测。** 出站方向检测提示注入、越狱、工具劫持、数据外泄；入站方向检测响应投毒（HTML 注释/CSS 隐藏/JSON 元数据）、LLM API 篡改、图片越狱。 **上下文累积检测。** 单条消息看着无害，但最近 12 轮对话里攻击信号累积达标后一次性触发——覆盖多轮记忆中毒和渐进式越狱。 **LLM 响应完整性校验。** 使用 tiktoken 精确统计 API 响应中实际 Token 数与 usage 字段的偏差，>15% 告警——防止第三方中转站篡改响应并掩盖注入内容。 **完整审计。** 每个拦截动作记录完整推理链：触发指纹、LLM 判定理由、置信度、延迟。FUNNEL_* 标签化的日志体系使每一步决策可追溯。 --- ## 项目结构 ``` ├── monitor/ # 监控平台核心 │ ├── addon/ # mitmproxy 插件 + 四级漏斗 │ │ ├── monitor_addon.py # request() + response() 双向钩子 │ │ ├── policy_engine.py # L2 规则引擎（DENY/ASK/ALERT） │ │ ├── payload_library.py # L1 载荷库（精确/模糊/子串匹配） │ │ ├── fingerprint_detector.py # L3 指纹检测器（9 类词库 + 语义向量） │ │ ├── review_agent.py # L4 LLM 复核（Prompt 路由 + SHA256 缓存） │ │ ├── image_analyzer.py # 图片 OCR 提取器（Tesseract/PaddleOCR） │ │ ├── session_risk.py # 会话风险追踪（内存字典 + 时间衰减） │ │ ├── llm_response_checker.py# LLM 响应完整性校验 │ │ ├── payload_decoder.py # Base64/Hex/ROT13 多层解码 │ │ └── streaming.py # SSE 流式响应缓冲 + 检测 │ ├── engine/ # 策略评估引擎 v2 │ ├── config/ # YAML 配置文件 │ │ ├── policies.yaml # 16 条策略规则 │ │ ├── payload_library.yaml # 31 条攻击载荷模板 │ │ ├── fingerprint_words.yaml # 9 类 64 个指纹词库 │ │ └── monitor.yaml # 主配置 │ ├── adapters/ # 四个智能体协议适配器 │ ├── dashboard/ # Vue 3 Web 控制台 │ └── Dockerfile │ ├── attacks/ # 攻击测试套件 │ ├── test_suite.py # 38 项一体化测试（推荐） │ ├── scenarios/ # 结构化攻击场景定义 │ │ ├── prompt_injection/ # 提示注入（12 cases） │ │ ├── tool_hijacking/ # 工具劫持（13 cases） │ │ ├── memory_poisoning/ # 记忆中毒（7 cases） │ │ └── response_tampering/ # 响应投毒（7 cases） │ ├── server.py # 攻击模拟服务器 │ └── compare.py # A/B 对照报告 │ ├── agents/ # 四个智能体原始代码（只读） ├── deploy/ # 部署脚本 + CA 证书 ├── docker-compose.yml # 全量启动 └── docker-compose.prod.yml # 生产模式 ``` --- ## 文档索引 | 文档 | 内容 | |------|------| | [安全风险分析报告.md](安全风险分析报告.md) | AI Agent 攻击面研究 — 10 类攻击向量深度分析、对抗样本变异方式、防御方案与验证 | | [DEPLOYMENT.md](DEPLOYMENT.md) | 部署与测试指南 — 分步部署、智能体接入、安全测试运行、常见问题 | | [attacks/README.md](attacks/README.md) | 攻击测试手册 — 完整测试用例、攻击载荷、策略规则速查、A/B 对照实验 | --- ## 技术选型 | 组件 | 技术 | 说明 | |------|------|------| | 透明代理 | mitmproxy | Python 最成熟的中间人代理，支持 HTTPS 解密 | | 规则引擎 | 自研 YAML 引擎 | 声明式配置，and/or 条件树，3 秒热更新 | | L1 载荷库 | SHA256 + difflib | 精确/模糊/子串三模式，Unicode 归一化抗绕过 | | L3 指纹检测 | 9 类词库 + 加权评分 | 零 Token 唤醒判断，5 种触发条件 | | L3 语义指纹 | all-MiniLM-L6-v2 | Embedding 余弦相似度 ≥ 0.75，防同义词绕过 | | L4 LLM 复核 | GPT-4o-mini / DeepSeek | 按攻击类型路由 Prompt，SHA256 缓存去重 | | L4 Brain | 本地 DeBERTa-v3 | 零网络依赖的注入检测 | | 响应解码 | Base64/Hex/ROT13 | 多层解码器自动展开编码载荷 | | 图片 OCR | Tesseract / PaddleOCR | 双引擎可选，中英文支持 | | 审计日志 | SQLite + JSON Lines | 结构化可查询，完整推理链记录 | | Web 控制台 | Vue 3 + SSE | 实时推送，单 HTML 文件零构建 | --- ## 已知局限 | 场景 | 局限 | 弥补措施 | |------|------|----------| | 智能体在本地执行 bash（不走网络） | 代理只能监控 HTTP 流量 | Docker 容器加固 + cap_drop=ALL | | 纯文本同义词替换绕过关键词 | 关键词匹配本质局限 | L3 语义向量 + L4 LLM 复核 | | 监控网关被绕过 | 智能体不配置 HTTP_PROXY | Docker 网络强制流量经过代理 | | 流式 LLM 响应完整性校验 | chunk 传递无法完整统计 Token | Content 注入检测作为补偿 | --- > **长城杯网络安全大赛 · 参赛作品** | 开源仓库：[https://gitee.com/fiagainster/agent-guardian](https://gitee.com/fiagainster/agent-guardian)