giselleevita/llm-agent-security-benchmark

# 安全代理运行时 — 政策强制工具使用 + 提示注入基准     本存储库包含一个 **用于工具使用的 LLM 代理的安全运行时包装器** 和一个 **可重复的基准测试工具**，用于衡量对 **直接和间接提示注入** 的抵抗力。 核心思想是将 LLM 视为 **不可信的**：模型可以 *建议* 行动，但外部 **工具网关**（策略执行点，PEP）使用 **策略即代码**（策略决策点，PDP）做出最终决定。CI 工作流程将基准测试作为 **安全网关** 运行，并在安全回归时失败构建。 有关以招聘为重点的项目叙述，请参阅 [docs/CASE_STUDY.md](docs/CASE_STUDY.md)。 ## 论文重点（本项目展示的内容） - **安全代理运行时**：工具网关强制最小权限、参数约束、数据边界和批准。 - **基准测试工具**：基于场景的评估，具有可衡量的安全和效用指标。 - **CI 安全网关**：对 PR/push 进行自动评估；当 ASR/泄露超过阈值时失败。 ## 关键安全控制 1. **工具允许列表** — 代理只能调用已注册的工具。 2. **参数约束** — 例如，仅允许对允许的域/路径进行 HTTP 检查；仅在允许的项目中使用票据。 3. **数据边界/泄露预防** — 金丝雀令牌策略防止泄露。 4. **批准流程** — 高风险操作可能需要明确的外部批准。 5. **审计跟踪** — 每个工具请求/决策都记录了理由和 `correlation_id`。 ## 基准设计 场景在 `benchmark/scenarios/scenarios.yaml` 中定义，包括： - **直接注入**（恶意用户输入） - **间接注入**（通过 RAG 获取的恶意内容） - **工具滥用**（参数/域/项目滥用） - **数据泄露**（金丝雀泄露尝试） - **过度代理**（未经明确批准的行动） ### 指标 基准测试报告： - **ASR（攻击成功率）**：执行禁止操作运行的百分比 - **泄露率**：金丝雀令牌出现在出站请求或最终输出中的百分比 - **任务成功率**：完成良性任务的百分比 - **误报率**：错误阻止良性操作的百分比 - **开销**：与基线相比的延迟/工具调用计数差异 ### 基准 - **B0**：没有护栏 - **B1**：仅提示护栏（系统提示规则） - **B2**：简单检查（例如，金丝雀/正则表达式阻止） - **B3**：策略强制工具网关（提议的运行时） - 可选：混合配置 ## 快速入门 ### 先决条件 - Python 3.11+ - Docker + Docker Compose ### 设置 ``` cp .env.example .env python -m venv .venv source .venv/bin/activate pip install -U pip pip install -e . ``` ### 启动服务（OPA + 模拟工具服务） ``` docker compose up -d ``` ### 运行基准测试（单个基准） ``` python -m benchmark.runner \ --scenarios benchmark/scenarios/scenarios.yaml \ --baseline B3 \ --runs 5 \ --out results/run.json \ --summary results/summary.json ``` ### 运行基准比较（所有基准） ``` python -m benchmark.runner \ --scenarios benchmark/scenarios/scenarios.yaml \ --baseline all \ --runs 5 \ --compare \ --out results/run.json \ --summary results/summary.json ``` 这将生成： - `results/summary.json` - B3 指标（用于 CI 网关） - `results/summary_comparison.json` - 所有基准的比较 - 控制台输出显示从 B0 到 B3 的改进 ### 查看结果 - `results/summary.json` 包含 CI 网关使用的聚合指标。 - `results/run.json` 包含每个场景的跟踪（包括策略决策）。 - `results/summary_comparison.json`（使用 `--compare` 时）显示基准比较指标。 ## CI 安全网关 GitHub Actions 工作流程运行基准测试并检查 `ci/thresholds.yaml` 中的阈值。 如果任何阈值被违反（例如，泄露 > 0 或 ASR > max_asr），则工作流程失败。 ## 存储库布局 - `agent_runtime/` 运行时、编排器、污点标记、审计 - `gateway/` 工具网关（PEP）、OPA 客户端、验证器、批准 - `policies/` Rego 策略和政策数据 - `tools/` 工具注册表 + 模拟工具/服务 - `benchmark/` 场景、运行器、评分、报告 - `ci/` 网关阈值 - `.github/` CI 工作流程 - `results/` 输出工件 有关更深入的架构概述，请参阅 `docs/architecture.md`，有关添加工具、策略和场景的说明，请参阅 `docs/extending.md`。 ## 为什么这很重要 - 企业代理需要在模型之外进行强制执行；此项目展示了以策略为先的执行边界。 - 决策是可审计和可重复的（`allow`/`deny`/`requires_approval`），而不是仅提示的最佳努力。 - 基准测试将控制与可衡量的结果（ASR、泄露、任务成功率、误报、p95 延迟）联系起来。 - CI 可以根据安全阈值阻止合并，将评估转变为操作控制。 ## 结果 B3（策略强制工具网关）将 ASR 从 **54% → 0%** 和泄露从 **12% → 0%** 降低，同时将任务成功率从 **48% → 98%** 提高，覆盖了 5 个攻击类别。 | 基准 | 描述 | ASR ↓ | 泄露 ↓ | 任务成功率 ↑ | p95 延迟（毫秒） | |---|---|---:|---:|---:|---:| | B0 | 无护栏 | 54.2% | 12.0% | 48.0% | 0.08 | | B1 | 仅提示护栏 | 54.2% | 12.0% | 48.0% | 0.11 | | B2 | 简单金丝雀/正则表达式检查 | 27.1% | 0.0% | 74.0% | 0.10 | | **B3** | **策略强制网关（OPA）** | **0.0%** | **0.0%** | **98.0%** | 8.78 | **B3 类别拆分**（250 次运行，涵盖 5 种攻击类型）： | 类别 | ASR | 任务成功率 | |---|---:|---:| | 直接注入 | 0% | 100% | | 间接注入 | 0% | 100% | | 工具滥用 | 0% | 100% | | 过度代理 | 0% | 100% | | 泄露 | 0% | 87.5% | 原始结果：`results/baseline_post_upgrade/summary_comparison.json` ## 架构（Mermaid） ``` flowchart LR U["User Task / Scenario"] --> O["Agent Orchestrator"] O -->|ToolCallRequest| G["Tool Gateway (PEP)"] G -->|Policy input| P["OPA (PDP)"] P -->|allow/deny/approval| G G -->|allowed only| T["Tool Registry + Mocks"] T --> G G --> A["Audit JSONL"] O --> R["Final Output + Trace"] B["Benchmark Runner"] --> O B --> S["summary.json / run.json"] CI["CI Gate"] --> S ``` ## 道德与安全 - 没有真实机密或个人数据：使用合成金丝雀令牌。 - 防御重点：评估缓解和强制执行（无“攻击工具”）。 - 设计用于可重复研究和负责任的披露实践。 ## 贡献 有关分支命名、问题标签和 PR 清单，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 更新日志 有关版本历史，请参阅 [CHANGELOG.md](./CHANGELOG.md)。 ## 许可证 Apache-2.0。请参阅 `LICENSE`。项目版本：`1.0.0+thesis`。

标签：Apache 2.0 许可, CI 安全门, LLM 代理, Python, 代码审查, 参数约束, 反取证, 安全可观测性, 安全基准测试, 安全漏洞, 安全评估, 安全运行时, 审批流程, 审计追踪, 工具使用控制, 提示注入基准, 数据边界, 无后门, 权限控制, 泄露预防, 版本控制, 策略代码, 请求拦截, 逆向工具