RogerTzeng/agent-hook-bench

# agent-hook-bench 针对 AI agent hook 和工具防护的 CI 友好型安全测试。 你已经有了 hook。`agent-hook-bench` 能告诉你它们是否足够好。 ## 为什么会有这个项目 大多数 agent 框架已经允许你拦截工具调用。困难的部分在于了解你的 hook 是否真正阻止了不安全的操作、是否要求对高风险操作进行审批，以及是否输出了可审计的 trace。 这个仓库不是另一个 agent 框架，不是可观测性仪表板，也不是模型排行榜。它是一个针对拟议 agent 操作的确定性回归测试工具。 ## 测试内容 - 由 prompt injection 驱动的工具调用 - 密钥泄露 - 不安全的文件写入 - 危险的 shell 命令 - 未经授权的电子邮件 - 缺少人工审批 - 工作区逃逸 - 工具投毒 ## 快速开始 ``` uv sync --extra dev uv run agent-hook-bench eval benchmarks --policy policies/default.yaml ``` 检查一个拟议的操作： ``` uv run agent-hook-bench check action.json \ --policy policies/default.yaml \ --trace traces/action.jsonl ``` ## 核心理念 ``` agent proposes action | adapter normalizes action | policy engine checks action | decision: allow / block / require approval | trace + report ``` ## Python 用法 ``` from agent_hook_bench import Guard, ProposedAction guard = Guard.from_policy("policies/default.yaml") decision = guard.check( ProposedAction( action_id="demo", tool_name="write_file", args={"path": "~/.ssh/authorized_keys", "content": "key"}, user_intent="Summarize the note.", source_framework="custom", ) ) assert decision.decision == "block" ``` ## 框架适配器 这些适配器使得单一策略能够跨 agent runtime 移植： | Runtime | 集成位置 | 适配器 | | --- | --- | --- | | Claude Agent SDK | `PreToolUse` hook | `build_claude_pre_tool_hook` | | OpenAI Agents SDK | 工具输入 guardrail | `from_openai_tool_context` | | LangGraph | `ToolNode` 之前 | `from_langgraph_tool_call` | | MCP | `tools/call` 网关 | `from_mcp_request` | | 自定义循环 | 分发之前 | `CustomHookAdapter` | 运行无依赖的示例 agent： ``` uv run python examples/simple_agent.py ``` Claude 适配器将 `Read`、`Write`、`Edit` 和 `Bash` 映射到默认策略的 标准化工具名称。安全决策交由 Claude 的原生权限系统处理，阻止 操作返回 `deny`，审批决策返回 `ask`。 `agent_hook_bench.examples.simple_agent` 中的 `SimpleAgent` 有意设计为一个极简的示例 runtime，而不是生产级的 agent 框架。请将其 `ToolCall` 对象列表替换为 任何模型生成的调用，同时确保将防护措施保留在工具分发的紧前位置。 ## 架构 ``` models.py normalized action and decision schemas detectors/ deterministic path, secret, shell, and text checks policy/ YAML policy loader, rule registry, and engine evals/ benchmark loading, scoring, and reports tracing/ JSONL trace events adapters/ thin framework normalization helpers ``` Trace 输出会递归地对检测到的密钥以及敏感键下的值进行脱敏处理。 ## 对比 | 类别 | 示例 | 区别 | | --- | --- | --- | | Agent 框架 | OpenAI Agents SDK, LangGraph, CrewAI | 框架提供 hook；本项目验证 hook 行为。 | | 可观测性 | LangSmith, Langfuse, AgentOps | 可观测性展示发生了什么；本项目测试应该发生什么。 | | 红队工具 | Promptfoo, PyRIT, Garak 风格的扫描器 | 许多工具测试模型响应；本项目测试操作级别的防护决策。 | | Agent 基准测试 | AgentDojo, tau-bench | 那些项目评估实际任务；本项目专注于拟议的工具操作。 | ## CI 包含的工作流会安装该包，并运行 lint、类型检查、单元测试和基准测试套件： ``` agent-hook-bench eval benchmarks --policy policies/ci.yaml --fail-on any ``` ## 路线图 - 每个包增加更多基准测试用例 - JUnit、SARIF 和 Markdown 报告 - 可选的框架扩展 - 针对外部 agent 安全基准测试的导入器

标签：AI安全, Chat Copilot, DNS 反向解析, 大模型测试, 安全测试, 攻击性安全, 策略引擎, 网络安全挑战, 逆向工具