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。