krishddd/SEC_Guardrails_Agent

# SEC_Guardrails_Agent [](https://github.com/krishddd/SEC_Guardrails_Agent/actions/workflows/ci.yml) [](#license) [](pyproject.toml) 为 **Odysseus** 自治 agent 提供的防御性、从零构建的 **7 层运行时 guardrails**（Docker，本地端口 `7000`，由 Mistral 提供支持）。一个非侵入式的反向代理 **guardrail 网关** 运行在 Odysseus 前方的端口 `7100` 上，在每一轮对话中强制执行一条 rail 链，并为每个 rail 决策生成一条 OpenTelemetry trace 以及一条仅追加的（append-only）审计记录。 ## 为什么需要 一个能够进行规划、运行工具（bash、文档创建、web/API 调用）、读取不受信任的外部数据并保持记忆的 LLM agent 具有很大的攻击面——包括 prompt 注入、工具滥用、memory 投毒、数据泄露。Guardrails 是一个运行时控制平面，它在每个边界上决定 agent 即将 **读取、说出或执行** 的操作是否被允许。该设计贯穿两个原则：**纵深防御**（不信任任何单一检查）和 **将所有外部内容视为不受信任**（来源标签 + 污点追踪）。 ## 架构 ``` client │ ▼ ┌─────────────────────────────┐ │ Guardrail Gateway :7100 │ FastAPI reverse-proxy │ ── input rails (L1, <30ms) │ secrets · PI/jailbreak · PII · spotlighting │ ── dialog rails (L2, <200ms)│ Task-Shield · deny-by-default topics │ │ │ │ ▼ forward (token)│ │ Odysseus :7000 ────────┼──▶ tool trace (export hook, ADR-0005) │ │ ◀─────────────┤ L4 tool · L5 memory · multi-agent rails │ ▼ │ │ ── output rails (L6, <50ms) │ schema · content · grounding · redact · sanitize │ ── oversight critic (L7) │ └─────────────────────────────┘ │ every decision → OTel span + append-only audit ▼ client ``` **7 个控制层**：L1 输入 · L2 对话/主题 · L3 推理/IFC（双 LLM + 污点） · L4 工具/动作 · L5 检索/memory · 多 agent 通信 · L7 验证/监督 ·（+ L6 输出） · 横切可观测性。每一层都映射到其防御的特定攻击——参见 [`docs/architecture/odysseus-guardrails.md`](docs/architecture/odysseus-guardrails.md)。 ## 多语言技术栈——各取所长 | 语言 | 角色 | 原因 | |---|---|---| | **Python 3.11** | 控制平面：FastAPI 网关、分类器编排、eval harness | 粘合剂 + ML 生态系统 | | **Rust** (PyO3/maturin → `guardrails_core`) | 确定性安全核心：密钥扫描器、spotlighting、URL/HTML sanitizer、**L4 policy-DSL 解析器 + 评估器**、污点原语 | 在信任边界处，内存安全 *本身* 就是一项安全属性；满足 <30 ms 的预算。包含纯 Python 回退方案 | | **TypeScript/React** (Vite, `web/`) | HITL 审批应用 + 可观测性/审计仪表板 | 无头服务无法提供的人机交互界面。客户端不包含任何安全逻辑 | | **Rego/OPA** | L4 策略 v2 路径 | 当内部 DSL 无法满足需求时，提供基于 Git 版本控制、可进行 CI 测试的策略 | 参见 [ADR-0006](docs/architecture/adr/0006-polyglot-rust-core.md) 和 [ADR-0007](docs/architecture/adr/0007-typescript-frontend.md)。 ## 生态系统（兄弟项目——复用而非重造） - **攻击性 oracle** — `Agent_security_testing/Security_module` (ASI01–10 + ext01–17)。评估 guardrail 所抵御的攻击套件（A/B：直接攻击 vs 通过网关攻击）。 - **评分器** — `Agent eval pipeline`（Odysseus 质量/安全指标，基础验证评判器）。 - **目标** — `odysseus/`（受保护的 agent）。 ## 构建方式——研究文档驱动 pipeline 每个阶段都在 Claude Code skills 的驱动下，在 `docs/` 下读取/写入结构化的 markdown 产物： ``` research/ → docs/specs/ → docs/architecture/ (+adr) → docs/plans/ → code /research-distill → /explore → /design → /plan → /scaffold → /implement → /test → /review → /docs-sync → /ship ``` ## 快速开始 ``` # 1. 安装（control plane；Rust core + ML detectors 为额外组件） python -m pip install -e ".[dev]" # add ".[ml]" for deberta/Presidio, ".[bench]" for AgentDojo # 2. 测试 + lint pytest -q # 230+ pass; Rust↔Python parity runs in CI ruff check . && ruff format --check . # 3. 查看每一层 end-to-end 触发（无需外部服务） python scripts/demo.py # 4. 在 Odysseus :7000 前面的 :7100 端口上运行 guardrail gateway python scripts/run_gateway.py # → 将 Odysseus 指向它：GUARDRAIL_TRACE_URL=http://localhost:7100/api/_trace # 5. 实时 A/B 测试（red-team 直接测试对比通过 engine 测试）以及 AgentDojo benchmark python scripts/run_ab_live.py # AB_USE_ML=1 to use the deberta backend python scripts/run_benchmark_live.py ``` 通过环境变量进行配置（参见 [`.env.example`](.env.example)）；`.env` 永远不会被提交。复用 eval pipeline 中的 `ODYSSEUS_TOKEN` + `OPENAI_API_KEY` —— **在使用前请轮换 OpenAI 密钥**。 ## 仓库布局 | 路径 | 用途 | |---|---| | `research/` | 原始研究 / 产出摘要 | | `docs/specs/` | 提炼的、结构化的规范 | | `docs/architecture/` | 探索性笔记、架构文档、ADR | | `docs/plans/` | 有序、可检查的任务列表 (`T1–T40`) | | `src/gateway/` | FastAPI 反向代理网关 (`:7100`) | | `src/rails/` | Rail 实现（输入/对话/输出/工具/memory/推理/多 agent/监督） | | `src/core/` | Rail 框架、配置、审计、可观测性 | | `src/eval/` | A/B 攻击 harness、AgentDojo 基准驱动程序、延迟/FPR 报告 | | `src/agent/` | 运行在引擎 *之下* 的参考工具执行 agent（进程内 trace） | | `docs/eval/` | 实测的 A/B、基准、延迟及防御升级结果 | | `crates/guardrails-core/` | Rust 安全核心（PyO3/maturin → `guardrails_core`） | | `web/` | TypeScript/React HITL 审批 + 可观测性仪表板 | | `tests/` | 单元测试 + 对抗性 fixtures，离线 Odysseus stub | | `.claude/` | Skills、子 agent、编辑前 guard hook、设置 | ## 评估与结果 安全指标始终 **分开** 报告——攻击成功率 (ASR) / 拦截率和误报率 (FPR) / 效用分别报告，**绝不混合为单一的 F1**。A/B harness 运行 Security_module 攻击，对比直接攻击与通过网关攻击针对真实的 Odysseus；AgentDojo 作为复用的外部基准运行。完整报告详见 [`docs/eval/`](docs/eval/)。 **针对真实 Odysseus 的实测结果**（拦截率 = 被硬阻断的攻击比例；这是确定性的、可归因的指标）： | 套件 | 指标 | 结果 | |---|---|---| | Security_module (红队) | 总体拦截率，启发式 → ML | **0.19 → 0.47** | | Security_module | 角色重定向拦截率（检测器升级后） | **0.00 → 1.00** | | AgentDojo (银行/slack/旅行/工作区) | 注入拦截率 | **1.00** (12/12) | | 所有套件 | **FPR / 过度拒绝** | **0.00** | | 通过投毒工具结果进行的间接注入 (XPIA) | 在网关被捕获，实时 | ✅ | 延迟：确定性输入 rail < 15 ms p50；ML 检测器（deberta-v3，323 ms CPU）仅通过条件性第二阶段在灰带（gray-band）输入上运行，因此良性流量几乎无需付出代价（~0）（参见 [`docs/architecture/T7-latency-spike.md`](docs/architecture/T7-latency-spike.md))。 ## 状态 - ✅ **基础架构、全部 7 层 rail、Rust 核心、React HITL/仪表板、CI** —— 完整的安全网。 - ✅ **统一的 `GuardrailEngine`** + 参考受保护 agent；与 agent 无关的 `guard_*` API。 - ✅ **实时集成** —— `:7100` 网关位于 Odysseus 前方；工具 trace 摄取（`/api/_trace`），实时 A/B (Security_module) 和 AgentDojo 基准测试，真实 ML 模型带来的延迟峰值。 - ✅ **防御研发 (D1–D5)** —— 检测器召回率升级、条件性第二阶段、集成 + PromptGuard 2 后端，以及已在实时环境中验证的工具输出（间接/XPIA）扫描。 运行 `python scripts/demo.py` 以查看每一层的端到端触发。在 [`docs/plans/odysseus-guardrails-plan.md`](docs/plans/odysseus-guardrails-plan.md) 中跟踪详细信息，并在 [`docs/plans/defense-improvements.md`](docs/plans/defense-improvements.md) 中查看防御路线图。 ## 安全性 发现漏洞？请参见 [`SECURITY.md`](SECURITY.md)。对于敏感报告，请勿创建公开的 issue。 ## 许可证 许可证：**TBD** —— 在添加许可证文件之前，作者保留所有权利。

标签：AI安全, Chat Copilot, DLL 劫持, LLM防护栏, XSS注入, 反向代理, 可视化界面, 大语言模型, 深度防御, 用户代理, 请求拦截, 逆向工具