AI安全性操作指南

概况

Cato AI 安全性记录了用户在 GenAI 应用程序中的活动，以及家用代理上传到其调用的模型的请求。 事件在 Cato 管理应用程序 (CMA) 的主页 > 事件页面上可见，并可转发到 SIEM、数据湖或其他外部平台进行保留、关联和警报。

事件仅携带元数据。 与模型交换的提示和响应不会存储在事件中。 该内容由持有所需权限的API密钥的调用者按需从Cato的GraphQL API中单独检索。

因此，调查AI安全发现是一个两步工作流程：

1. 将事件转发到您的SIEM。 配置一个事件集成，过滤到AI安全事件类型，以便AI安全事件与您其他的Cato遥测数据一起到达。

2. 使用API提取符合条件的事件的敏感内容。 当某个事件需要调查时，使用事件携带的标识符查询API以检索提示和模型响应。

注意：可以在CMA中直接查看AI安全交互，包括敏感提示和响应，而无需使用API。 AI安全适用于应用程序>交互探查器列出您自制代理的调用，AI安全适用于用户>会话探查器列出带有GenAI应用程序的用户会话。 两者都允许您深入查看单个记录。 该API适用于从您的SIEM中开始的调查以及编程的检索。

Cato事件

所有AI安全事件都携带事件类型AI安全。 事件子类型标识了AI安全生成事件的哪个部分，并确定事件携带哪些字段以及API查询返回的内容。 Cato事件模式。提供交互式事件模式浏览器。

AI用户交互字段

注意： 并非每个事件都具有可检索内容。 session_id 和 message_id 仅在 app_activity_type 是 Prompt、Detection 或 LLM Response 的事件中出现。 Web 请求和文件交易事件不携带它们。

应用程序运行时保护字段

术语。 CMA 所称为自制代理的内容在事件中被视为应用程序。 application_id 字段标识 Guard 正在保护的自制代理。

将事件发送到 SIEM

事件集成会自动将 Cato 事件数据转发到外部平台和存储目的地，无需手动导出或连续轮询。 在 CMA 中，在 资源> 集成> 已配置的集成中配置集成。 有关概述，请访问事件集成入门。

如果本地集成不可用，可以使用自定义 HTTP 推送集成以 JSON 格式将事件推送到您选择的目的地。 可以配置自定义标头，使其与多种供应商兼容。 有关更多信息，请参阅使用自定义 HTTP 推送集成发送数据。

AI 安全事件筛选

无论您选择哪种集成，都将其范围限定为 AI 安全事件，而不是转发账户的完整事件量。 这在 事件过滤器中完成，使用一个或多个过滤器组构建：组内条件与 AND 结合，组与 OR 结合，因此事件如果匹配任何一个组就会被转发。 任何事件字段都可作为条件使用。

1. 向事件过滤器添加一个过滤器组。 在集成配置中，打开事件过滤器并添加一个过滤器组。

2. 设置事件类型条件。 字段事件类型，值为AI 安全性。 这将组限定为所有子类型的 AI 安全事件。
    

3. （可选）设置子类型条件。 字段子类型，其值为 AI 用户互动和应用程序运行时保护，或者仅为此次集成所需的值。 由于这两个条件在同一个组中，它们与 AND 结合，因此只有所选子类型的 AI 安全事件会被转发。
   

4. （可选）分别路由这两种子类型。 一个包含这两个值的单组会将这两种子类型发送到同一个目的地。 要将它们发送到不同的目的地，配置两个事件集成，分别设置一个组的范围为每个子类型。

5. 进一步缩小范围，如有需要。 可以在同一组中添加额外的条件以减少体积。 例如，可以添加一个守护名称过滤器，仅转发与特定守护匹配的应用程序运行时保护事件。
    

使用 API 提取敏感内容

AI 安全事件故意排除互动的内容：它们不包含提示、模型响应或与模型交换的原始消息数据。 这些内容随需而从 Cato 的 GraphQL API 中检索，并且仅能由拥有所需权限的 API 密钥调用者提取。 提供了两个查询，每个事件子类型一个。

API 密钥和权限

通过在 CMA 中生成的 Cato API 密钥对查询进行身份验证。 有关如何创建 API 密钥的详细信息，请参阅生成 Cato API 的 API 密钥。

访问互动内容是通过密钥上的 RBAC 权限控制的：

API 端点和架构

API 端点和架构的 URL 是根据托管您的 CMA 实例的位置特定的。 您的 CMA 账户以及 API 端点和架构的 URL 可能会追加一个 <prefix> 值。

不同 CMA 区域的前缀

从您的 CMA 账户的 URL 中识别前缀，并在每个请求中使用相应的端点。 有关更多信息，请参阅什么是Cato API。

在 GraphQL Playground 中运行查询

GraphQL Playground 通过浏览器直接对 Cato API 运行查询，这对于临时调查和在编写查询脚本前确认连接性很有用。 有关说明，请参阅从 GraphQL Playground 连接到 Cato API。

AI 用户互动

检索 AI 用户互动事件背后的用户提示和模型响应。 CMA 中可以在 用户 AI 安全性 > 会话浏览器下看到相同的对话。

与策略中配置的探测器匹配的 AI 用户互动在 app_activity_type 字段中包含Detection。 这些事件对于安全调查最为相关。

请求字段

GraphQL

查询 SessionConversation(
  $accountId: ID!
  $sessionId: ID!
  $messageId: ID!
  $appId: ID!
) {
  aiSecurity(accountId: $accountId) {
    endUsers {
      sessionConversation(
        input: { sessionId: $sessionId, messageId: $messageId, appId: $appId }
      ) {
        userPrompt
        llmResponse
      }
    }
  }
}

变量:

{
  "accountId": "",
  "sessionId": "<从事件中获取的 session_id="">",
  "messageId": "<从事件中获取的 message_id="">",
  "appId": "<从事件中获取的 application_id="">"
}

Curl

curl -s -X POST https://api..catonetworks.com/api/v1/graphql2 \
 -H "x-api-key: $CATO_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "query SessionConversation($accountId: ID!, $sessionId: ID!, $messageId: ID!, $appId: ID!) { aiSecurity(accountId: $accountId) { endUsers { sessionConversation(input: {sessionId: $sessionId, messageId: $messageId, appId: $appId}) { userPrompt llmResponse } } } }",
 "variables": {
 "accountId": "<ACCOUNT_ID>",
 "sessionId": "<session_id from the event>",
 "messageId": "<message_id from the event>",
 "appId": "<application_id from the event>"
 }
 }' | jq .

Python

导入json,urllib.request 
 
API_KEY = "<API_KEY>" 
 
QUERY = """ 
query SessionConversation($accountId: ID!, $sessionId: ID!, $messageId: ID!, $appId: ID!) {
  aiSecurity(accountId: $accountId) {
    endUsers {
      sessionConversation(input: {sessionId: $sessionId, messageId: $messageId, appId: $appId}) {
        userPrompt
        llmResponse
      }
    }
  }
}
"""
payload = json.dumps({"query": QUERY, "variables": {
    "accountId": "<ACCOUNT_ID>",
    "sessionId": "<session_id from event>",
    "messageId": "<message_id from event>",
    "appId": "<application_id from event>",
}}).encode("utf-8")
req = urllib.request.Request(
    "https://api.<prefix>.catonetworks.com/api/v1/graphql2",
    data=payload,
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    方法="POST",
)
使用urllib.request.urlopen(req, 超时=30)作为resp:
    print(json.dumps(json.load(resp), 缩进=2)) 

响应字段

示例响应

{
 "data": {
 "aiSecurity": {
 "endUsers": {
 "sessionConversation": {
 "userPrompt": "<user prompt>",
 "llmResponse": “<llm response or null>”
 }
 }
 }
 }
}

应用程序运行时保护

检索应用程序运行时保护事件背后的调用元数据和原始聊天消息。 可以在CMA的 应用程序的AI安全性 > 互动浏览器中找到这些调用。

请求字段

GraphQL

query GetInvocation($accountId: ID!, $id: ID!) {
 aiSecurity(accountId: $accountId) {
 apps {
 invocation(input: { id: $id }) {
 id
 sessionId
 timestamp
 tokenCount
 guard {
 id
 name
 }
 action
 data {
 message {
 role
 content {
 text
 }
 }
 }
 }
 }
 }
}

变量：

{
 "accountId": "<ACCOUNT_ID>",
 "id": "<invocation_id from the event>"
}

Curl

curl -s -X POST https://api.<prefix>.catonetworks.com/api/v1/graphql2 \
 -H "x-api-key: <CATO_API_KEY>” \
 -H "Content-Type: application/json" \
 -d '{
 "query": "query GetInvocation($accountId: ID!, $id: ID!) { aiSecurity(accountId: $accountId) { apps { invocation(input: {id: $id}) { id sessionId timestamp tokenCount guard { id name } action data { message { role content { text } } } } } } }",
 "variables": {
 "accountId": "<ACCOUNT_ID>",
 "id": "<invocation_id from the event>"
 }
 }' | jq .

Python

导入json,urllib.request 
 
API_KEY = "<CATO_API_KEY>" 
 
QUERY = """ 
query获取调用($accountId: ID!, $id: ID!) {
  aiSecurity(accountId: $accountId) {
    apps {
      调用(input: {id: $id}) {
        id
        sessionId
        timestamp
        tokenCount
        guard {id name}
        操作
        数据 { message {role content {text}} }
      }
    }
  }
}
"""
payload = json.dumps({"query": QUERY, "variables": {
    "accountId": "<ACCOUNT_ID>",
    "id": "<invocation_id from the event>",
}}).encode("utf-8")
req = urllib.request.Request(
    "https://api.<prefix>.catonetworks.com/api/v1/graphql2",
    data=payload,
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    方法="POST",
)
使用urllib.request.urlopen(req, 超时=30)作为resp:
    print(json.dumps(json.load(resp), 缩进=2)) 

响应字段

示例响应

{
 "data": {
 "aiSecurity": {
 "apps": {
 "invocation": {
 "id": "01a00ada-c424-700b-9898-ed1ea05a82fb",
 "sessionId": "8cf9384d-9a45-4d01-aeff-c3eb31164599",
 "timestamp": "2026-08-16T13:55:04.392Z",
 "tokenCount": 30,
 "guard": {
 "id": "d3918cad-ffab-408d-b079-bfecd4842ed1",
 "name": "<guard_name>"
 },
 "action": "BLOCK",
 "data": {
 "message": [
 {
 "role": "user",
 "content": [
 {
 "text": "<user prompt>”
 }
 ]
 }
 ]
 }
 }
 }
 }
 }
}

附录：示例事件和API调用

示例事件及其API调用内容检索，包括所有事件子类别。

用户的AI安全

示例事件

[
 {
 "account_id": <account_id>,
 "account_name": "<account_name>",
 "ad_name": "<ad_name>",
 "ai_app_risk_level": "Medium",
 "app_activity_type": "Prompt",
 "application_id": "microsoft_copilot",
 "application_name": "Microsoft Copilot",
 "application_risk": 5,
 "application_type": "System",
 "categories": [
 "Generative AI Tools"
 ],
 "cato_app": "microsoft_copilot",
 "event_count": 1,
 "event_id": "7c41ae90b2d5f318",
 "event_sub_type": "AI User Interaction",
 "event_type": "AI Security",
 "interaction_intent": "getting information",
 "interaction_sub_topic": "data privacy",
 "interaction_topic": "legal",
 "invocation_id": "01a01f70-9b12-74ac-8f31-2b6ce0d41aa7",
 "is_cloud_app": true,
 "is_sanctioned_app": true,
 "message_id": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
 "session_id": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
 "time": 1787233820104,
 "time_str": "2026-08-20T13:50:20Z",
 "url": "https://copilot.microsoft.com/chats",
 "user_id": <user_id>,
 "user_name": "<user_name>",
 "vpn_user_email": "<user_email>"
 },
 {
 "account_id": <account_id>,
 "account_name": "<account_name>",
 "app_activity_type": "Detection",
 "application_id": "microsoft_copilot",
 "application_name": "Microsoft Copilot",
 "event_count": 1,
 "event_id": "b0d3572ea9146fc7",
 "event_sub_type": "AI User Interaction",
 "event_type": "AI Security",
 "invocation_id": "01a01f70-9b12-74ac-8f31-2b6ce0d41aa7",
 "message_id": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
 "rule_id": "1296751412582697861",
 "rule_name": "<rule_name>",
 "session_id": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
 "time": 1787233820331,
 "time_str": "2026-08-20T13:50:20Z",
 "user_id": <user_id>,
 "user_name": "<user_name>",
 "vpn_user_email": "<user_email>"
 }
]

API调用

curl -s -X POST https://api.catonetworks.com/api/v1/graphql2 \
 -H "x-api-key: <api_key>" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "query SessionConversation($accountId: ID!, $sessionId: ID!, $messageId: ID!, $appId: ID!) { aiSecurity(accountId: $accountId) { endUsers { sessionConversation(input: {sessionId: $sessionId, messageId: $messageId, appId: $appId}) { userPrompt llmResponse } } } }",
 "variables": {
 "accountId": "<account_id>",
 "sessionId": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
 "messageId": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
 "appId": "microsoft_copilot"
 }
 }' | jq .

API响应

{
 "data": {
 "aiSecurity": {
 "endUsers": {
 "sessionConversation": {
 "userPrompt": "<user_prompt>",
 "llmResponse": "<llm_response>"
 }
 }
 }
 }
}

AI安全性为了应用程序

示例事件

[
 {
 "account_id": <account_id>,
 "account_name": "<account_name>",
 "action": "Block",
 "detectors": [
 "SIMPLE_DETECTOR_TYPE_SAFETY_CONTROLS_SAFETY"
 ],
 "event_count": 1,
 "event_id": "f98820262dfb8aa9",
 "event_sub_type": "应用程序运行时保护",
 "event_type": "AI Security",
 "guard_id": "d3918cad-ffab-408d-b079-bfecd4842ed1",
 "guard_name": "<guard_name>",
 "interaction_id": "01a01f71-c3e5-75be-a3cc-d77ec3b9277f",
 "internalId": "f98820262dfb8aa9",
 "internal_id": "f98820262dfb8aa9",
 "invocation_id": "01a01f71-c3e5-75be-a3cc-d77ec3b9277f",
 "is_sanctioned_app": false,
 "rule_id": "1296751412582697861",
 "rule_name": "<rule_name>",
 "session_id": "d500d5a4-82cd-4f48-8d70-0ebfc590d605",
 "time": 1787233944579,
 "time_str": "2026-08-20T13:52:24Z"
 },
 {
 "account_id": <account_id>,
 "account_name": "<account_name>",
 "action": "Block",
 "detectors": [
 "SIMPLE_DETECTOR_TYPE_SECURITY_CONTROLS_JAILBREAK",
 "SIMPLE_DETECTOR_TYPE_SAFETY_CONTROLS_SAFETY"
 ],
 "event_count": 1,
 "event_id": "31156257bcf2d54c",
 "event_sub_type": "应用程序运行时保护",
 "event_type": "AI Security",
 "guard_id": "d3918cad-ffab-408d-b079-bfecd4842ed1",
 "guard_name": "<guard_name>",
 "interaction_id": "01a01f72-38ce-782f-96c5-5ca071ac9792",
 "internalId": "31156257bcf2d54c",
 "internal_id": "31156257bcf2d54c",
 "invocation_id": "01a01f72-38ce-782f-96c5-5ca071ac9792",
 "is_sanctioned_app": false,
 "rule_id": "1296751412582697861",
 "rule_name": "<rule_name>",
 "session_id": "d500d5a4-82cd-4f48-8d70-0ebfc590d605",
 "time": 1787233974486,
 "time_str": "2026-08-20T13:52:54Z"
 }
]

API调用

curl -s -X POST https://api.catonetworks.com/api/v1/graphql2 \
 -H "x-api-key: <api_key>" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "query GetInvocation($accountId: ID!, $id: ID!) { aiSecurity(accountId: $accountId) { apps { invocation(input: {id: $id}) { id sessionId timestamp tokenCount guard { id name } action data { message { role content { text } } } } } } }",
 "variables": {
 "accountId": "<account_id>",
 "id": "01a01f72-38ce-782f-96c5-5ca071ac9792"
 }
 }' | jq .

API响应

{
  "data": {
    "aiSecurity": {
      "apps": {
        "invocation": {
          "id": "01a01f72-38ce-782f-96c5-5ca071ac9792",
          "sessionId": "d500d5a4-82cd-4f48-8d70-0ebfc590d605",
          "timestamp": "2026-08-20T13:52:54.486Z",
          "tokenCount": 38,
          "guard": {
            "id": "d3918cad-ffab-408d-b079-bfecd4842ed1",
            "name": "\u003Cguard_name\u003E"
          },
          "action": "BLOCK",
          "data": {
            "message": [
              {
                "role": "user",
                "content": [
                  {
                    "text": "\u003Cuser_prompt\u003E"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}