Guia Operacional de Segurança de IA

Visão geral

Cato AI Security registra a atividade dos usuários com aplicativos GenAI e as convocações que seus Agentes Caseiros enviam para os modelos que eles chamam. Os eventos são visíveis no Aplicativo de Gerenciamento Cato (CMA) na página Inicial > Eventos, e podem ser encaminhados para um SIEM, data lake ou outra plataforma externa para retenção, correlação e alerta.

Eventos carregam apenas metadados. Os prompts e respostas trocadas com o modelo não são armazenados no evento. Esse conteúdo é recuperado separadamente, sob demanda, da API GraphQL da Cato por um solicitante cuja chave da API possui a permissão necessária.

Investigar uma descoberta de Segurança de IA é, portanto, um fluxo de trabalho em duas etapas:

1. Encaminhe eventos para o seu SIEM. Configure uma Integração de Eventos, filtrada para o tipo de evento de Segurança de IA, para que os eventos de Segurança de IA cheguem junto com o restante da sua telemetria Cato.

2. Use a API para extrair o conteúdo sensível dos eventos que justificam isso. Quando um evento requer investigação, faça uma consulta à API com os identificadores carregados nesse evento para recuperar o prompt e a resposta do modelo.

Nota: Interações de Segurança de IA, incluindo prompts e respostas sensíveis, podem ser revisados diretamente no CMA sem usar a API. Segurança de IA para Apps > Explorador de Interação lista as invocações para seus Agentes Casoar, e Segurança de IA para Usuários > Explorador de Sessões lista sessões de usuários com aplicativos GenAI. Ambos permitem que você aprofunde em um registro individual. A API destina-se a investigações que começam no seu SIEM e para recuperação programática.

Eventos Cato

Todos os eventos de Segurança de IA carregam o Tipo de Evento Segurança de IA. O subtipo do evento identifica qual parte da Segurança de IA gerou o evento e determina quais campos o evento carrega e qual consulta da API retorna seu conteúdo. Um explorador de esquema de eventos interativo está disponível em Esquema de Eventos Cato.

Campos de Interação de Usuário de IA

Nota: Nem todos os eventos têm conteúdo recuperável. session_id e message_id aparecem apenas em eventos onde o tipo de atividade do aplicativo é Prompt, Detecção ou Resposta do LLM. Eventos de Solicitação da Web e Transação de Arquivo não os carregam.

Campos de Proteção em Tempo de Execução de Aplicação

Terminologia. O que a CMA refere como Agente Desenvolvido Internamente é referido como uma aplicação no evento. O campo application_id identifica o Agente Desenvolvido Internamente que o Guardião está protegendo.

Enviando Eventos para um SIEM

Integrações de Eventos direcionam dados de eventos Cato automaticamente para plataformas externas e destinos de armazenamento, sem exportação manual ou pesquisa contínua. As integrações são configuradas em Recursos > Integrações > Integrações Configuradas no CMA. Para uma visão geral, veja Começando com Integrações de Eventos.

Se uma integração nativa não estiver disponível, a integração Custom HTTP Push pode ser usada para enviar eventos em formato JSON para o destino de sua escolha. Cabeçalhos personalizados podem ser configurados, tornando-se compatível com uma ampla variedade de fornecedores. Para mais informações, consulte Enviando Dados com a Integração Custom HTTP Push.

Filtrando eventos de Segurança de IA

Qualquer que seja a integração que você selecionar, limite-a a eventos de Segurança de IA, em vez de encaminhar todo o volume de eventos da conta. Isso é feito no Filtro de Eventos, que é construído a partir de um ou mais grupos de filtros: condições dentro de um grupo são combinadas com E, e grupos são combinados com OU, então um evento é encaminhado se corresponder a qualquer grupo. Qualquer campo de evento está disponível como condição.

1. Adicionar um grupo de filtros ao Filtro de Eventos. Na configuração da integração, abra o Filtro de Eventos e adicione um grupo de filtros.

2. Defina a condição do Tipo de Evento. Campo Tipo de Evento, valor Segurança de IA. Isso direciona o grupo para eventos de Segurança de IA de todos os subtipos.
    

3. (Opcional) Configure a condição de Subtipo. Campo Subtipo, com os valores Interação do Usuário de IA e Proteção em Tempo de Execução da Aplicação, ou apenas o necessário por esta integração. Como ambas as condições estão no mesmo grupo, elas são combinadas com E, então apenas eventos de Segurança de IA dos subtipos selecionados são encaminhados.
   

4. (Opcional) Direcione os dois subtipos separadamente. Um único grupo carregando ambos os valores envia ambos os subtipos para o mesmo destino. Para entregá-los a destinos diferentes, configure duas Integrações de Eventos, cada uma com um grupo voltado para um subtipo.

5. Narrow ainda mais, se necessário. Condições adicionais podem ser adicionadas ao mesmo grupo para reduzir o volume. Por exemplo, um filtro de Nome do Guardião pode ser adicionado para encaminhar apenas eventos de Proteção em Tempo de Execução da Aplicação que correspondem a um Guardião específico.
    

Puxando Conteúdo Sensível com a API

Eventos de Segurança de IA excluem deliberadamente o conteúdo da interação: eles não contêm os prompts, as respostas do modelo ou qualquer um dos dados brutos das mensagens trocadas com o modelo. Esse conteúdo é recuperado da API GraphQL da Cato, sob demanda, e apenas por chamadores cuja chave da API possui a permissão necessária. Duas consultas estão disponíveis, uma por subtipo de evento.

Chave de API e permissões

Consultas são autenticadas com uma chave de API Cato gerada no CMA. Para detalhes sobre como criar uma chave de API, veja Gerar Chaves de API para a API Cato.

Acesso ao conteúdo da interação é controlado por permissões RBAC na chave:

Endpoint e esquema da API

A URL para o endpoint e o esquema da API é específica para o local onde sua instância do CMA está hospedada. Um valor <prefix> pode ser anexado à URL para sua conta CMA e ao endpoint e esquema da API.

Prefixos para as diferentes regiões da CMA

Identifique o prefixo a partir da URL da sua conta CMA e use o endpoint correspondente em cada solicitação. Para mais informações, consulte O que é a API Cato.

Executando consultas no Playground GraphQL

O Playground GraphQL executa consultas contra a API Cato diretamente de um navegador, o que é útil para investigação ad-hoc e para confirmar conectividade antes de escrever um script de consulta. Veja Conectando-se à API Cato a partir do Playground GraphQL para instruções.

Interação do Usuário de IA

Recupere o prompt do usuário e a resposta do modelo por trás de um evento de Interação do Usuário de IA. As mesmas conversas estão disponíveis no CMA em Segurança de IA para Usuários > Explorador de Sessões.

Interações do Usuário de IA que correspondem a detectores configurados em políticas contêm Detecção no campo app_activity_type. Esses eventos são mais relevantes para investigações de segurança.

Campos de Solicitação

GraphQL

consulta SessionConversation(
  $accountId: ID!
  $sessionId: ID!
  $messageId: ID!
  $appId: ID!
) {
  segrançaDeIA(accountId: $accountId) {
    usuáriosFinais {
      sessionConversation(
        input: { sessionId: $sessionId, messageId: $messageId, appId: $appId }
      ) {
        promptDoUsuário
        respostaLlm
      }
    }
  }
}

Variáveis:

{
  "accountId": "<ACCOUNT_ID>",
  "sessionId": "<session_id do evento>",
  "messageId": "<message_id do evento>",
  "appId": "<application_id do evento>"
}

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 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

import json, urllib.request 
 
API_KEY = "<CHAVE_API>" 
 
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": "<ID_CONTA>", 
    "sessionId": "<id_sessão do evento>", 
    "messageId": "<id_mensagem do evento>", 
    "appId": "<id_aplicação do evento>", 
}}).encode("utf-8") 
req = urllib.request.Request( 
    "https://api.<prefixo>.catonetworks.com/api/v1/graphql2", 
    data=payload, 
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"}, 
    method="POST", 
) 
with urllib.request.urlopen(req, timeout=30) as resp: 
    print(json.dumps(json.load(resp), indent=2)) 

Campos de resposta

Exemplo de Resposta

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

Proteção de Tempo de Execução de Aplicações

Recupere os metadados de invocação e as mensagens de bate-papo brutas por trás de um evento de Proteção de Tempo de Execução de Aplicação. As mesmas invocações estão disponíveis no CMA em AI Security for Apps > Interaction Explorer.

Campos de solicitação

GraphQL

consulta GetInvocation($accountId: ID!, $id: ID!) {
  segurançaAi(accountId: $accountId) {
    apps {
      invocação(input: { id: $id }) {
        id
        sessionId
        timestamp
        quantidadeDeTokens
        guarda {
          id
          nome
        }
        ação
        dados {
          mensagem {
            papel
            conteúdo {
              texto
            }
          }
        }
      }
    }
  }
}

Variáveis:

{
  "accountId": "<ACCOUNT_ID>",
  "id": "<id_da_invocação do evento>"
}

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 { invocação(input: {id: $id}) { id sessionId timestamp quantidadeDeTokens guarda { id nome } ação dados { mensagem { papel conteúdo { texto } } } } } } }",
    "variables": {
      "accountId": "<ACCOUNT_ID>",
      "id": "<id_da_invocação do evento>"
    }
  }' | jq .

Python

import json, urllib.request 
 
API_KEY = "<CATO_API_KEY>" 
 
QUERY = """ 
query GetInvocation($accountId: ID!, $id: ID!) { 
  aiSecurity(accountId: $accountId) { 
    apps { 
      invocation(input: {id: $id}) { 
        id 
        sessionId 
        timestamp 
        tokenCount 
        guard { id nome } 
        ação 
        dados { mensagem { role content { text } } } 
      } 
    } 
  } 
} 
""" 
payload = json.dumps({"query": QUERY, "variables": { 
    "accountId": "<ID_CONTA>", 
    "id": "<id_invocação do evento>", 
}}).encode("utf-8") 
req = urllib.request.Request( 
    "https://api.<prefixo>.catonetworks.com/api/v1/graphql2", 
    data=payload, 
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"}, 
    method="POST", 
) 
with urllib.request.urlopen(req, timeout=30) as resp: 
    print(json.dumps(json.load(resp), indent=2)) 

Campos de resposta

Exemplo de Resposta

{
  "data": {
    "aiSecurity": {
      "apps": {
        "invocação": {
          "id": "01a00ada-c424-700b-9898-ed1ea05a82fb",
          "sessionId": "8cf9384d-9a45-4d01-aeff-c3eb31164599",
          "timestamp": "2026-08-16T13:55:04.392Z",
          "quantidadeDeTokens": 30,
          "guarda": {
            "id": "d3918cad-ffab-408d-b079-bfecd4842ed1",
            "nome": "<nome_do_guarda>"
          },
          "ação": "BLOQUEAR",
          "dados": {
            "mensagem": [
              {
                "papel": "usuário",
                "conteúdo": [
                  {
                    "texto": "<user prompt>”
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

Apêndice: Eventos de Exemplo e Chamadas de API

Exemplos de eventos e as chamadas de API que recuperam seu conteúdo, para ambos os subtipos de evento.

Segurança de AI para Usuários

Eventos de Exemplo

[
  {
    "id_conta": <id_conta>,
    "nome_da_conta": "<nome_da_conta>",
    "nome_ad": "<nome_ad>",
    "nivel_de_risco_aplicativo_ai": "Médio",
    "tipo_de_atividade_app": "Prompt",
    "id_aplicacao": "microsoft_copilot",
    "nome_aplicacao": "Microsoft Copilot",
    "risco_aplicacao": 5,
    "tipo_aplicacao": "Sistema",
    "categorias": [
      "Ferramentas de IA Generativa"
    ],
    "aplicacao_cato": "microsoft_copilot",
    "contador_de_eventos": 1,
    "id_evento": "7c41ae90b2d5f318",
    "subtipo_evento": "Interação de Usuário com IA",
    "tipo_evento": "Segurança de IA",
    "intencao_interacao": "obter informação",
    "subtopico_interacao": "privacidade de dados",
    "topico_interacao": "legal",
    "id_invocacao": "01a01f70-9b12-74ac-8f31-2b6ce0d41aa7",
    "é_app_na_nuvem": true,
    "é_app_sancionada": true,
    "id_mensagem": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
    "id_sessao": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
    "tempo": 1787233820104,
    "tempo_str": "2026-08-20T13:50:20Z",
    "url": "https://copilot.microsoft.com/chats",
    "id_usuário": <id_usuario>,
    "nome_usuario": "<nome_usuario>",
    "email_usuario_vpn": "<email_usuario>"
  },
  {
    "id_conta": <id_conta>,
    "nome_da_conta": "<nome_da_conta>",
    "tipo_de_atividade_app": "Detecção",
    "id_aplicacao": "microsoft_copilot",
    "nome_aplicacao": "Microsoft Copilot",
    "contador_de_eventos": 1,
    "id_evento": "b0d3572ea9146fc7",
    "subtipo_evento": "Interação de Usuário com IA",
    "tipo_evento": "Segurança de IA",
    "id_invocacao": "01a01f70-9b12-74ac-8f31-2b6ce0d41aa7",
    "id_mensagem": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
    "id_regra": "1296751412582697861",
    "nome_regra": "<nome_regra>",
    "id_sessao": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
    "tempo": 1787233820331,
    "tempo_str": "2026-08-20T13:50:20Z",
    "id_usuario": <id_usuario>,
    "nome_usuario": "<nome_usuario>",
    "email_usuario_vpn": "<email_usuario>"
  }
]

Chamada de 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": "<id_conta>",
      "sessionId": "b71f9c02-3ad4-4e8b-90c6-1f5d8e7a4c33",
      "messageId": "6f2b1c48-55d7-4a9e-9c10-8ab3f7e2d114",
      "appId": "microsoft_copilot"
    }
  }' | jq .

Resposta da API

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

Segurança de IA para Aplicativos

Eventos de Exemplo

[
  {
    "id_conta": <id_conta>,
    "nome_da_conta": "<nome_da_conta>",
    "ação": "Bloquear",
    "detetores": [
      "TIPO_DETECTOR_SIMPLES_CONTROLES_SEGURANÇA_SEGURANÇA"
    ],
    "contador_de_eventos": 1,
    "id_evento": "f98820262dfb8aa9",
    "subtipo_evento": "Proteção de Tempo de Execução de Aplicação",
    "tipo_evento": "Segurança de IA",
    "id_guarda": "d3918cad-ffab-408d-b079-bfecd4842ed1",
    "nome_guarda": "<nome_do_guarda>",
    "id_interação": "01a01f71-c3e5-75be-a3cc-d77ec3b9277f",
    "idInterno": "f98820262dfb8aa9",
    "id_interno": "f98820262dfb8aa9",
    "id_da_invocação": "01a01f71-c3e5-75be-a3cc-d77ec3b9277f",
    "é_app_sancionada": false,
    "id_regra": "1296751412582697861",
    "nome_regra": "<nome_da_regra>",
    "id_sessao": "d500d5a4-82cd-4f48-8d70-0ebfc590d605",
    "tempo": 1787233944579,
    "tempo_str": "2026-08-20T13:52:24Z"
  },
  {
    "id_conta": <id_conta>,
    "nome_da_conta": "<nome_da_conta>",
    "ação": "Bloquear",
    "detectores": [
      "TIPO_DETECTOR_SIMPLES_CONTROLES_SEGURANÇA_JAILBREAK",
      "TIPO_DETECTOR_SIMPLES_CONTROLES_SEGURANÇA_SEGURANÇA"
    ],
    "contador_de_eventos": 1,
    "id_evento": "31156257bcf2d54c",
    "subtipo_evento": "Proteção de Tempo de Execução de Aplicação",
    "tipo_evento": "Segurança de IA",
    "id_guarda": "d3918cad-ffab-408d-b079-bfecd4842ed1",
    "nome_guarda": "<nome_do_guarda>",
    "id_interação": "01a01f72-38ce-782f-96c5-5ca071ac9792",
    "idInterno": "31156257bcf2d54c",
    "id_interno": "31156257bcf2d54c",
    "id_da_invocação": "01a01f72-38ce-782f-96c5-5ca071ac9792",
    "é_app_sancionada": false,
    "id_regra": "1296751412582697861",
    "nome_regra": "<nome_da_regra>",
    "id_sessao": "d500d5a4-82cd-4f48-8d70-0ebfc590d605",
    "tempo": 1787233974486,
    "tempo_str": "2026-08-20T13:52:54Z"
  }
]

Chamada de 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": "consulta GetInvocation($accountId: ID!, $id: ID!) { aiSecurity(accountId: $accountId) { apps { invocação(input: {id: $id}) { id sessionId timestamp quantidadeDeTokens guarda { id nome } ação dados { mensagem { papel conteúdo { texto } } } } } } }",
    "variables": {
      "accountId": "<id_conta>",
      "id": "01a01f72-38ce-782f-96c5-5ca071ac9792"
    }
  }' | jq .

Resposta da 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": "<nome_do_guardião>"
          },
          "action": "BLOQUEAR",
          "data": {
            "message": [
              {
                "role": "usuário",
                "content": [
                  {
                    "text": "<aviso_usuário>"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}