AI-FW 的 Cursor Agent Hooks
通过 AI-FW 策略网关检查 Cursor prompts、shell 命令、文件、MCP 调用和 Agent 操作。
Cursor Agent Hooks 让 AI-FW 检查并治理开发工作站上的 Agent 活动。本地 shim 从 stdin 接收 Cursor payload，发送到 AI-FW，并返回对应事件决策。
| 机制 | 覆盖范围 |
|---|---|
| Model routing | Prompts、responses、streaming、tool calls 和经 OpenAI 兼容 gateway 的模型流量。 |
| Cursor Agent Hooks | Shell、文件读写、MCP、子 Agent 启动、prompts、tab 事件和工作站操作。 |
如需覆盖模型流量和开发机活动，请同时使用。
可检查的事件
| Cursor 事件 | AI-FW 行为 | 可阻止 |
|---|---|---|
| beforeSubmitPrompt | Prompt 规则、PII 和语义分析。 | 是 |
| preToolUse | 用 allow-list 检查工具并扫描输入。 | 是 |
| beforeShellExecution | 执行前检查命令。 | 是 |
| beforeMCPExecution | 治理 server/tool 身份和 payload。 | 是 |
| beforeReadFile | 内容到模型前检查路径和内容。 | 是 |
| subagentStart | 将子 Agent 类型视为声明能力。 | 是 |
| afterFileEdit | 记录文件效果并扫描写入内容。 | 否，仅通知 |
| afterShellExecution | 记录命令结果元数据和输出 digest。 | 否 |
| afterAgentResponse | 扫描 assistant 响应。 | 否 |
| sessionStart / sessionEnd | 记录会话生命周期和时长。 | 否 |
| beforeTabFileRead / afterTabFileEdit | 管理读取并记录自主 tab 编辑。 | 仅读取 |
捕获采用 observe-first，只记录不拒绝。阻止需配置 allow-list 并明确启用。
配置集成
打开 AI Firewall -> Agent Config -> Integrations -> Cursor Agent Hooks。
| 设置 | 默认值 | 含义 |
|---|---|---|
| Enable Cursor Hooks | Off | 启用 POST /hooks/cursor；关闭时返回 404。 |
| Credential | AI-FW API key | 推荐用于归因和撤销；也支持签名认证。 |
| Mask Rules | Allow | mask 匹配允许并记录；设为 Deny 可拒绝。 |
| Ask Permission | On | Shell/MCP 决策可请求人工确认；Off 时只 allow/deny。 |
| Decide Within | 5000 ms | 决策时间预算；超时则拒绝。 |
| Repeat Window | 2000 ms | 同一命令重复投递更新现有记录；0 表示每次都记录。 |
| Events | All | 选择 shim 发送的 Cursor 事件。 |
| Deny Message | 内置 | 拒绝时返回给开发者的消息。 |
设置变更写入审计。
安装本地 shim#
Shim 位于公开 tools/securetron-aifw package，是本地进程，可通过企业流程分发或在项目范围配置。
- 将 shim 放在稳定路径。
- 从模板创建 hooks.json。
- 在企业或用户范围设置绝对路径命令。
- 配置 AI-FW endpoint 和 credential。
- 先 capture、observe-first，审查活动后再启用阻止。
API key 可按 key、Agent label 和 owner 归因。共享签名不提供同等的开发者身份范围。Capture mode 可先检查 Cursor payload，准备执行策略时移除。
IDE Artifacts#
启用 IDE Artifacts 后，AI-FW 记录文件写入/删除、读取、命令元数据和 Agent 响应。默认关闭，可配置类型、digest-first 内容、上限和保留期。
命令输出永不保存为内容；no-log 和敏感数据政策也可抑制内容。导出只包含元数据和 digests。
查看结果
| 问题 | 查看位置 |
|---|---|
| 会话执行了什么？ | Audit Logs -> Activity，按 conversation 筛选。 |
| 记录了哪些文件/命令？ | Artifacts，按 kind/source/agent/session/path 筛选。 |
| 调用了哪些工具？ | Skills & Tools。 |
| 会话何时开始/结束？ | Audit Logs -> Events，source cursor。 |
| 哪些控制有遥测？ | Compliance 中引用已观察来源的控制。 |
Conversation ID 将 prompts、工具调用和 artifacts 连成一条轨迹。声明但未调用的工具不算使用。
故障与隐私
Hook endpoint 需要 credential。Gateway 不可达时，按 hooks.json 中每个事件的故障策略和 shim 的 fail-open/fail-closed 选项处理。权限事件若不能因故障放行命令，应 fail-closed。
参数和内容优先保存 digest。仅在有明确运维需求并审查保留和 no-log 策略后存储内容。企业分发和 workspace trust 也是安全边界的一部分。