排查应用程序的人工智能安全问题

概览

此剧本涵盖了 CMA 中应用程序 AI 安全性的所有问题，包括警卫未检查或操作代理/LLM流量、AI网关集成未转发事件、托管代理集成无法连接或同步，以及警卫策略规则未按预期生效。

受影响的组件包括 AI 安全警卫（Proxy、API 和 AI 网关模式），警卫策略规则及其引擎配置文件、AI 网关集成、托管代理集成以及基础应用程序 AI 安全性许可证。当出现故障时，客户失去对代理/LLM流量和托管代理活动的可视性，访问权限策略无法执行，治理和合规性目标未能实现。

症状

• Guard在应用检测和分析（CMA）中显示调用为零，尽管连接的应用程序正在积极发送流量
• 已配置的守护策略规则从不匹配或在类似请求中匹配不一致
• 匹配了阻止或匿名与阻止规则，但请求仅被监控或没有看到任何操作
• AI网关集成（Portkey、LiteLLM或Kong）已配置，但通过网关路由的流量在应用检测和分析（CMA）中未检查
• 托管代理集成显示为断开连接，测试连接失败或在安装脚本/云信息栈安装期间失败
• 托管代理集成显示为活跃，但在应用检测和分析（CMA）中未出现代理配置或会话

可能原因

• AI应用程序安全许可证过期或未启用
• 全球守护策略启用切换在应用检测和分析（CMA）中关闭
• Guard已创建但未实际接收流量。应用程序或网关未指向Guard的端点（代理/API模式），或AI网关护栏未包含在网关配置中。
• 守护交互策略规则被禁用、未发布或范围错误，指向错误的引擎配置文件、方向（用户、助手、工具输入、工具输出）或操作
• 托管代理可见性所需的平台特定设置未启用
• 预期的数据刷新延迟尚未过去。
• 受影响的语言模型（LLM）提供商、代理平台或网关类型当前不支持守护或托管代理集成

初步评估

在进行深入故障排除之前，请完成这些检查。大多数问题可追溯到这些先决条件之一。

验证AI安全许可证

验证AI安全终端用户许可证（覆盖代理的AI安全）已启用且未过期导航至CMA>账户>许可证>高级安全，确认许可证存在、活跃且在有效期内。
{height="" width=""}
如果许可证缺失、禁用或过期，应用程序的AI安全功能，包括Guard创建、Guard交互策略执行、AI网关集成和托管代理集成，无论配置如何都无法运行。在继续执行本文档中的步骤之前，解决任何许可证问题。

验证Guard策略已启用

导航到 应用检测和分析（CMA） > AI 安全性 > 守护策略 并确保守护策略启用切换被勾选这是一个容易被忽视的简单步骤，在关闭状态下不会生效任何规则。

验证守护部署和流量路由

守护只检查它实际接收到的流量。在假设策略或检测问题之前，确认守护正确位于流量路径中。

1. 导航到 AI 安全性 > 守护 并确认存在受影响的守护，并以正确的 类型 （代理，API 或 AI 网关）进行配置。
2. 从自制代理生成用户提示。 CMA 中显示的调用计数应随着每次提示而增加。如果调用没有增加，这可能指向应用程序配置错误。
   
3. 打开受影响的守护并导航到部署标签页。根据守护类型，此标签页的具体值必须在应用程序的配置中体现：
   • 对于所有守护类型，确认应用程序中配置的 API 密钥与 CMA 中显示的有效、未撤销密钥匹配。如有需要，您可以在 CMA 中重新生成 API 密钥，这将使先前的密钥失效，所以请在重新生成后立即更新应用程序。
     
   • 对于 代理和 API 守护，通过编辑应用程序的配置文件（例如 config.py），并添加 GUARD_API_KEY、BASE_URL、MODEL_ID，以及在守护为代理类型且在 CMA 中未提供 LLM 密钥时，添加 LLM_PROVIDER_API_KEY 来确保应用程序指向守护的端点 URL。
   • 确保所有必需的 请求头 尤其是标记为星号 (*) 的头均包含在应用程序的客户端代码中（例如 client.py）。有关守护部署的更多信息，请参见实施聊天机器人守护的示例{target=_blank}
   • 针对 AI 网关守护，确认相应的网关集成（Portkey、LiteLLM 或 Kong）配置为通过 Cato 路由流量必须将 Cato 颁发的 API 密钥和护栏添加到网关的自身配置中（例如 LiteLLM 的 config.yaml）。

验证托管代理集成连接

托管代理集成是与第三方代理平台的只读连接，并使用与守护不同的模式。没有流量检查，只有清单和会话轮询。

1. 导航到 AI 安全性 > 集成 > 托管代理平台 并确认相关集成（Amazon Bedrock、Amazon Quick、Microsoft Foundry、Copilot Studio 或 Gemini Enterprise Agent Platform）显示 活跃 状态且集成已完全配置。
2. 对于 Amazon Bedrock 或 Amazon Quick，确认 CloudFormation 堆栈在正确的 AWS 账户（或多账户部署中，在 AWS Organizations 管理账户）中成功完成安装，并且所有记录的 AWS 先决条件均已满足。
3. 对于 Microsoft Foundry 或 Copilot Studio，确认每个设置步骤均由正确的角色持有者完成，并且记录的 先决条件已满足：
   • 一个 Entra ID 管理员（应用程序管理员、云应用程序管理员或全球管理员）通过 Cato Networks 管理员许可链接向 Cato Networks AI 安全集成应用程序授予租户范围的同意。
   • 对于 Foundry，一个订阅所有者或用户访问管理员已将认知服务用户角色分配给每个包含 Foundry 资源的订阅中的 Cato 应用程序。
   • 对于 Copilot Studio，通过使用 Azure Cloud Shell 中的 PowerShell 注册脚本，Power Platform 管理员（或全球管理员）已将 Cato 应用程序注册为 管理应用程序，并为每个相关的非开发者环境启用了 代理会话。
   • 一个 Cato 管理员在 CMA 中输入正确的 Microsoft Entra ID Tenant ID 并在保存之前成功点击了 测试连接。不匹配的租户 ID 是测试连接失败的常见原因。
4. 对于 Gemini Enterprise Agent Platform，确认 Google Cloud 设置脚本在正确的 Google Cloud 项目中运行（如果需要，请执行 gcloud config set project PROJECT_ID），确保运行脚本的身份有权限启用 API 和创建 IAM/工作负载身份联合资源，并且脚本运行之前入门令牌未过期。如果连接不能在成功运行脚本后立即验证，允许几分钟以便 Google Cloud IAM 变更传播后再进行重试。
5. 在得出集成出现故障之前，请确认预期的数据刷新时机：
   • Foundry 和 Copilot Studio 在连接时立即提取数据，然后每小时提取数据
   • Bedrock AgentCore 活动依赖于 AWS 提供 CloudWatch 跟踪，首次代理调用后可能需要时间。

排查问题

管理员或用户可能遇到的症状排查步骤如下所示。这些步骤旨在确定面临问题的可能原因。

故障排除保证显示没有调用

这适用于当守护页面（AI安全性 >守护）在 CMA 中显示零调用。

1. 确认 AI安全性用于应用程序的许可证有效，并且已生成了受影响应用程序的用户提示。
2. 对于代理保护，确认 AI提供商已被 Cato 支持，并在文档中记录于 与AI安全守护协同工作。
3. 导航到 主页 > 事件，过滤事件类型= AI安全性，确认是否生成任何与守护相关的事件如果没有抵达，请确保已根据验证守卫部署和流量路由中的说明，将守卫部署到应用程序的配置中。
   
4. 通过 CLI 运行 curl -v https://api.aisec.catonetworks.com 来验证 AI 安全性 API 的可达性。输出应显示 FQDN 解析、成功的 TLS 握手和 HTTP 响应（通常为 HTTP 404）。
5. 为了确认特定守护是否可达和响应，您可以使用请求示例（包括有效的守护密钥）运行 curl 命令，从AI安全性 > 守护 > 部署成功的响应应包括匹配守卫策略规则和应用的操作。
   
6. 如果守护在应用程序上正确配置，通过curl可达且没有CMA事件生成，请提供守护类型/配置（代理、API或AI网关）、应用程序详情和配置文件（隐藏API密钥），上报给Cato支持

故障排除守卫策略规则未生效

这适用于守卫页面显示调用，但守卫策略规则未采取配置的操作。

1. 导航到 AI 安全性 > 守卫策略，确认 守卫策略已启用 被选中，并且受影响的规则已发布。
2. 确认与规则关联的 引擎配置文件 实际上包括预期捕获相关内容的检测器。您可以使用 引擎游乐场{target=_blank} 来验证提示内容在引擎配置文件中触发检测器，然后再进一步故障排除。
3. 确认规则的 方向 与内容实际出现的方向相匹配。针对工具输出的检测器不会评估用户方向提示，反之亦然。
4. 确认配置在规则上的 操作 是预期的操作。设置为 匿名化并阻止 或 匿名化和监控 的规则将根据提示中检测到的内容类型应用操作，如 策略应用意外操作{target=_blank} 中所述。
5. 如果多个规则可能适用于同一事件，请确认实际触发的规则， 方法是查看事件详细信息。规则独立评估，与顺序无关。如果多条规则匹配，将应用更严格的操作。事件采取的操作较预期不严格，通常意味着较严格规则的范围、引擎配置文件或方向实际上没有匹配该事件。
6. 如果规则已启用、范围设置正确且内容应匹配，但预期操作仍未应用，请提供事件ID、规则截图（引擎配置文件、方向、操作）以及流量通过的Guard或集成信息，上报Cato支持团队进行升级。

故障排除缺失代理配置或会话问题

适用于在CMA中预期的管理代理配置或代理会话缺失或不完整的情况。

1. 确认集成显示为活跃状态，请参阅验证管理代理集成连接然后再进行数据缺失的故障排除。
2. 允许平台正常刷新周期：Microsoft Foundry和Copilot Studio至少每小时一次，AWS生成并交付Bedrock AgentCore的CloudWatch跟踪所需的时间。
3. 验证Cato支持在CMA中查看受影响的管理应用程序的代理会话，请参阅使用管理代理{target=_blank}中的文档。
4. 对于Amazon Bedrock AgentCore，确认CloudWatch交易搜索已启用（AWS控制台>应用程序信号（APM）>交易搜索，结构化日志中包含的跨度）。没有此功能，Cato可以在库存中显示AgentCore代理，但无法显示其活动。
5. 对于Copilot Studio，确认代理会话已针对缺失代理所属的特定环境启用（Power Platform管理中心>管理>环境>[环境]>设置>产品>功能>Copilot Studio代理），并确认该环境不是开发环境，因为此设置不支持开发环境。
6. 对于Microsoft Foundry，确认包含缺失Foundry资源的特定订阅已为Cato应用程序分配认知服务用户角色。角色分配不适用于整个租户，必须在每个订阅中重复。
7. 对于Gemini Enterprise Agent Platform，确认预期：仅显示代理会话和会话事件；会话中的工具、集成和外部服务使用量设计上不被收集。
8. 如果相关的刷新间隔已过且平台特定的跟踪/角色/会话设置均确认无误，请提供集成类型、具体订阅/环境/受影响项目、预期与实际观察到的数据，上报Cato支持团队进行升级。

上传案例到 Cato 支持

在与 Cato 支持建立案例之前，请确保已完成本操作指南中概述的所有相关故障排除步骤。如果问题仍未解决，请向 Cato 支持提供以下信息：

• 问题描述——关于观察到的症状和预期行为的清晰简明描述
• 受影响组件—守护名称和类型（代理、API或AI网关）、AI网关集成（Portkey、LiteLLM或Kong），或托管代理集成（Amazon Bedrock、Amazon Quick、Microsoft Foundry、Copilot Studio或Gemini Enterprise Agent Platform）
• 环境详情——对于Guard：应用程序详细信息和配置文件（编辑API密钥）。对于管理代理集成：确认满足文档中的先决条件，并提供观察到的任何配置错误。
• 连接/策略详细信息—守护策略规则名称、引擎配置文件、方向和操作；或特定集成设置步骤最后完成及其结果
• 已完成的故障排除步骤 — 从此剧本中已采取步骤以及每一步结果的总结
• 支持证据 — 链接到 AI 安全事件、规则或集成配置的屏幕截图、CloudFormation 堆栈状态或测试连接错误信息，以及精确时间戳（UTC 和客户时区）

提供越多的上下文和证据，Cato支持将能够更快地调查和解决问题。