CyberStrikeAI/docs/zh-CN/tool-call-guard.md

# 调用拦截

侧边栏「安全防护」包含「人机协同」和「调用拦截」。人机协同保留原有审批、白名单、审计策略和日志功能；调用拦截对内部 MCP、外部 MCP 和 HTTP MCP 工具调用增加独立的执行前检查。

独立的 `cmd/mcp-stdio` 服务也会加载相同拦截规则；该服务是单独进程，网页保存后需重启它以加载更新。

## 使用

1. 打开「安全防护 → 调用拦截」。默认开启「政府网站保护」，匹配 `.gov`、`.gov.cn` 等政府域名及通配符写法，忽略大小写。旧配置没有 `tool_guard` 时也启用默认保护。
2. 规则默认折叠，列表展示名称、提醒摘要和启停开关。点击规则展开编辑；「添加规则」打开独立弹窗，可以填写并验证尚未添加的规则。点击「添加到列表」通过正则校验后加入页面草稿，取消不会留下空规则。校验失败会定位到对应字段。可以单独启停规则，也可以关闭总开关。
3. 点击页面顶部「全部规则验证」按当前顺序及启停状态检查全部规则。在已有规则编辑区点击「验证本条」，就在该规则下方输入工具名和 JSON 参数、查看命中文本与最终提醒；新增规则的单条验证直接在弹窗中完成。单条验证忽略总开关和该规则的启停状态，适合调试未启用规则。单条和全部验证分别保留输入与结果，均使用未保存的表单配置，不执行工具，也不改变运行中的规则。
4. 点击保存。服务端校验全部规则后写入 `config.yaml` 的 `tool_guard`，立即生效，无需重启。校验或写入失败会保留原有规则。直接编辑 YAML 后需要重启服务；非空 `tool_guard` 必须明确填写 `enabled` 和 `rules`，清空规则使用 `[]`。

规则按列表顺序检查，首先命中的启用规则决定提醒。检查对象包括工具名称、参数的 JSON 表示、嵌套字符串和键名，以及最多三轮常见 URL 百分号解码后的文本。使用 Go/RE2 正则语法，例如 `(?i)` 表示忽略大小写；不支持回溯引用和环视。最多 100 条规则，正则和提醒各最多 4096 字节。禁用的规则也须通过校验。

提醒支持以下占位符，留空则使用通用提醒：

| 占位符 | 内容 |
| --- | --- |
| `{match}` | 匹配文本；正则含命名捕获组 `(?P<match>...)` 时使用该组 |
| `{tool}` | 工具名称 |
| `{rule}` | 规则名称 |

示例提醒：`识别到 {match}，禁止攻击政府网站，请检查目标与授权范围。`

命中后，工具处理器或外部客户端不会执行该调用。界面和执行记录使用独立的「已拦截」状态，并保留拦截原因；监控单独统计拦截次数，不计入调用失败或成功率的分母。升级启动时，可明确识别的旧版安全规则拦截记录会自动归入此状态。返回给 Agent 的 MCP 结果仍保留 `isError: true`，同时携带 `blocked: true`，以明确表示请求未执行。外部 MCP 的规则拦截不会算作服务故障而触发熔断。

## 权限与边界

查看和试匹配需要 `config:read`；修改需要 `config:write` 和全局权限范围。规则配置变更写入系统审计日志。HITL 的关闭状态、免审批白名单和审批通过结果均不能覆盖调用拦截；审批后编辑的参数也会在实际执行入口检查。规则更新影响后续执行检查，不能撤销已经发出的调用。

这是文本规则防护，不能代替目标授权或网络隔离：它无法可靠识别仅以 IP 表示的政府目标、DNS 别名背后的机构、工具执行后的重定向、文件中才出现的目标或任意混淆编码。它只覆盖经过本应用 MCP 执行入口的调用；直接终端操作、可选的 Agent 本地执行工具等独立入口不在此范围内。参数中仅引用政府域名的说明文本也可能被保守拦截。请保留人机协同，并结合实际授权范围维护规则。

## API

- `GET /api/tool-guard`：返回生效配置 `{enabled, rules}`。
- `PUT /api/tool-guard`：保存相同结构；每条规则含 `id`、`name`、`enabled`、`pattern`、`message`。必须明确提供总开关和规则数组。
- `POST /api/tool-guard/test`：请求 `{config, toolName, arguments}`，响应 `{blocked, match?}`；`match` 含 `ruleId`、`ruleName`、`matchedText`、`message`。