--- title: "Solução de Problemas de Segurança de IA para Aplicativos" slug: "troubleshooting-ai-security-for-apps" updated: 2026-10-25T00:14:49Z published: 2026-10-25T00:14:49Z canonical: "knowledge.catonetworks.com/troubleshooting-ai-security-for-apps" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.catonetworks.com/llms.txt > Use this file to discover all available pages before exploring further. # Solução de Problemas de Segurança de IA para Aplicativos ## Visão geral Este playbook cobre toda a gama de problemas de segurança de IA para aplicativos no CMA, incluindo Guardas não inspecionando ou agindo sobre tráfego de agente/LLM, integrações de Gateway IA não encaminhando eventos, integrações de Agente Gerenciado falhando ao conectar ou sincronizar, e regras de Política de Guardas não surtindo efeito como esperado. Os componentes afetados abrangem Guardas de Segurança de IA (Proxy, API e modo de Gateway IA), regras de Política de Guardas e seus Perfis de Motor, integrações de Gateway IA, Integrações de Agente Gerenciado e a licença subjacente de Segurança de IA para Aplicações. Quando qualquer um destes falha, os clientes perdem visibilidade no tráfego de agente/LLM e na atividade do agente gerenciado, a aplicação de políticas não pode ocorrer e os objetivos de governança e conformidade não são atingidos. ## Sintomas - Um Guarda mostra zero invocações no CMA, mesmo que a aplicação conectada esteja ativamente enviando tráfego - Uma regra de Política de Guardas está configurada, mas nunca corresponde, ou corresponde de forma inconsistente em solicitações semelhantes - Uma regra de Bloquear ou Anonimizar & Bloquear é correspondida, mas o pedido é apenas monitorado, ou nenhuma ação é visivelmente aplicada - Uma integração de Gateway AI (Portkey, LiteLLM ou Kong) está configurada, mas o tráfego roteado através do gateway nunca aparece como inspecionado no CMA - Uma integração de Agente Gerenciado aparece como desconectada, falha no Teste de Conexão ou falha durante seu script de instalação/configuração de pilha CloudFormation - Uma integração de Agente Gerenciado aparece como ativa, mas nenhuma configuração ou sessão de agente aparece no CMA ## Causas possíveis - Licença de Segurança de IA para Aplicativos expirada ou não ativada - O alternador de Política de Guardas Global Ativada está desligado no CMA - O Guarda está criado, mas não está realmente recebendo tráfego. A aplicação ou gateway não está apontado para o endpoint do Guarda (Modo Proxy/API) ou o guardrail de Gateway AI não está incluído na configuração do gateway. - Uma regra de Política de Interação de Guardas está desativada, não publicada ou com escopo para o perfil de motor incorreto, Direção (Usuário, Assistente, Entrada de Ferramenta, Saída de Ferramenta) ou Ação - Uma configuração específica de plataforma requerida para visibilidade do Agente Gerenciado não foi ativada - A latência esperada para atualização de dados ainda não transcorreu. - O provedor LLM afetado, plataforma de agente, ou tipo de gateway não é atualmente suportado pela integração de Guarda ou Agente Gerenciado em questão ## Avaliação Inicial Complete essas verificações antes de solucionar problemas mais profundos. A maioria dos problemas remonta a um destes pré-requisitos. ### Validar Licença de Segurança de IA Verifique que a licença **de Usuários Finais de Segurança de IA** (cobre Segurança de IA para Agentes) seja ativada e não esteja expirada. Navegue até **CMA > Conta > Licenças > Segurança Premium** e confirme se a licença está presente, ativa e dentro do seu período de validade. ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(220).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=fREbwPBxkF%2B2FwqmIREfgyTI8HMmOpm3DZC8Z1BvQLM%3D){height="" width=""} Se a licença estiver ausente, desativada ou expirada, os recursos de Segurança de IA para Aplicativos — incluindo criação de Guardas, aplicação da Política de Interação de Guardas, integrações de Gateway AI e Integrações de Agente Gerenciado — não funcionarão, independentemente da configuração. Resolva qualquer problema de licenciamento antes de continuar com as etapas neste documento. ### Validar Política de Guardas está Ativada Navegue para **CMA > Segurança de IA > Política de Guards** e certifique-se de que a opção Política de Guards Ativado esteja marcada. Este é um passo simples que é fácil de esquecer, e nenhuma regra será aplicada enquanto estiver desligado. ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(243).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=O%2FR4sgypenbfRglAmREStmAjq7gEwrFrKi3fZjsp9L0%3D) ### Validar Implantação de Guard e Roteamento de Tráfego Um Guard inspeciona apenas o tráfego que realmente recebe. Antes de assumir um problema de política ou detecção, confirme se o Guard está corretamente no caminho do tráfego. 1. Navegue para **Segurança de IA > Guards** e confirme se o Guard afetado existe e está configurado com o **Tipo** correto (Proxy, API ou AI Gateway) para a implantação em questão. 2. Gere um prompt de usuário a partir do agente caseiro. A contagem de invocações mostrada no CMA deve aumentar com cada prompt. Se as invocações não aumentarem, isso indica uma possível má configuração da aplicação. ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(244).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=wjm49k2Wy3on18j2o%2FBXeKn9vrjGiV23au3MTqwYfFQ%3D) 3. Abra o Guard afetado e navegue até a aba Implantação. Dependendo do tipo de Guard, valores específicos desta aba devem estar presentes na configuração da aplicação: - Para todos os tipos de Guard, confirme se a chave API configurada na aplicação corresponde a uma chave ativa e não revogada mostrada no CMA. Você pode regenerar a chave API no CMA se necessário, isso invalida a chave anterior, então atualize a aplicação imediatamente após regenerar. ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(245).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=XswtVeyCI3IEVFB5K%2F5baSrnaGs9nBMod8kdrheFd1U%3D) - Para **Guards de Proxy e API**, confirme se a aplicação está apontando para a URL de endpoint do Guard editando o arquivo de configuração da aplicação (por exemplo, **config.py**) e adicionando **GUARD_API_KEY**, **BASE_URL**, **MODEL_ID**, e quando o guard é do tipo proxy e a chave LLM não foi fornecida no CMA, **LLM_PROVIDER_API_KEY**. - Certifique-se de que todos os **headers de pedido** requeridos, especialmente aqueles marcados com um símbolo de asterisco (*), estejam incluídos no código do cliente da aplicação (por exemplo, **client.py**). Para mais informações sobre a implantação do Guard, veja [Exemplo Implementando Guards para um Bot de Chat](https://knowledge.catonetworks.com/docs/example-implementing-guards){target=`_blank`}. - Para um **Guard de Gateway de IA**, confirme se a integração correspondente ao gateway (Portkey, LiteLLM ou Kong) está configurada para rotear o tráfego através do Cato. A chave API emitida pelo Cato e o guardrail devem ser adicionados à configuração própria do gateway (por exemplo, **config.yaml** para LiteLLM). ### Validar Conexão de Integração de Agente Gerenciado Integrações de Agente Gerenciado são conexões de leitura com plataformas de agentes de terceiros e usam um modelo diferente de Guards. Não há inspeção de tráfego, apenas inventário e sondagem de sessão. 1. Navegue para **Segurança de IA > Integrações > Plataforma de Agente Gerenciado** e confirme que a integração relevante (Amazon Bedrock, Amazon Quick, Microsoft Foundry, Copilot Studio ou Gemini Enterprise Agent Platform) mostra um status **Ativo** e a integração foi totalmente configurada. 2. Para **Amazon Bedrock** ou **Amazon Quick**, confirme que a pilha CloudFormation foi instalada com sucesso na conta AWS correta (ou, para uma implantação de múltiplas contas, na conta de gerenciamento das Organizações AWS) e que todos os [pré-requisitos](https://knowledge.catonetworks.com/docs/configuring-amazon-bedrock){target=`_blank`} documentados da AWS foram atendidos. 3. Para **Microsoft Foundry** ou **Copilot Studio**, confirme que cada etapa de configuração foi concluída pelo titular de função correto e que os [pré-requisitos](https://knowledge.catonetworks.com/docs/configuring-copilot-studio){target=`_blank`} documentados foram atendidos: - Um administrador de Entra ID (Administrador de Aplicações, Administrador de Aplicações em Nuvem ou Administrador Global) concedeu consentimento abrangente ao aplicativo de Integração de Segurança de IA Cato Networks através do link de consentimento do administrador da Cato Networks. - Para Foundry, um Proprietário de Assinatura ou Administrador de Acesso do Usuário atribuiu a função de Usuário dos Serviços Cognitivos à aplicação Cato em cada assinatura contendo recursos Foundry. - Para o Copilot Studio, um Administrador da Power Platform (ou Administrador Global) registrou a aplicação Cato como uma **aplicação de gerenciamento** usando o script de registro PowerShell no Azure Cloud Shell, e ativou **Sessões de Agente** para cada ambiente relevante, não-desenvolvedor. - Um administrador Cato inseriu o **Microsoft Entra ID Tenant ID** correto no CMA e clicou com sucesso em **Testar Conexão** antes de salvar. Um ID de locatário incompatível é uma causa frequente de falhas na Testar Conexão. 4. Para **Gemini Enterprise Agent Platform**, confirme que o script de configuração do Google Cloud foi executado no projeto Google Cloud correto (execute `gcloud config set project PROJECT_ID` se necessário), que a identidade que executou o script tinha permissão para habilitar APIs e criar recursos de Identidade de Trabalho/Federação IAM, e que o token de integração não expirou antes da execução do script. Se a conexão não puder ser verificada imediatamente após uma execução bem-sucedida do script, aguarde alguns minutos para que as alterações do IAM do Google Cloud sejam propagadas antes de tentar novamente. 5. Confirme o tempo esperado de atualização de dados antes de concluir que uma integração está quebrada: - Foundry e Copilot Studio capturam dados imediatamente na conexão e depois a cada hora - A atividade do Bedrock AgentCore depende da AWS entregar traços CloudWatch, o que pode levar tempo após a primeira invocação do agente. ## Solução de problemas do problema As etapas para solucionar os sintomas que administradores ou usuários podem encontrar estão listadas abaixo. Esses passos têm como objetivo identificar causas possíveis para os problemas enfrentados. ### Solução de problemas de um Guard que não mostra invocações Isso se aplica quando a página Guards (**Segurança de AI > Guards**) mostra zero invocações no CMA. 1. Confirme se a licença de Segurança para Aplicativos AI está válida, e se os prompts do usuário foram gerados a partir do aplicativo afetado. 2. Para guardas proxy, confirme que o provedor de IA é suportado pela Cato conforme documentado em [Trabalhando com Guardas de Segurança de IA](https://knowledge.catonetworks.com/docs/working-with-ai-security-guards){target=`_blank`}. 3. Navegue para **Inicial > Eventos**, filtre por **Tipo de Evento = Segurança IA** e confirme se algum evento relacionado aos guardas é gerado. Se nenhum estiver chegando, certifique-se de que o guarda foi implantado na configuração da aplicação, conforme explicado em [Validar Implantação do Guarda e Roteamento de Tráfego](/v1/docs/troubleshooting-ai-security-for-apps#validate-guard-deployment-and-traffic-routing). ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(246).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=jir1kf5UG1MJ%2FJ9FVulUDaDc2PABH73RIcH4g95LH%2Bs%3D) 4. Verifique a acessibilidade da API de Segurança de IA executando **curl -v https://api.aisec.catonetworks.com** via CLI. A saída deve mostrar a resolução do FQDN, um aperto de mão TLS bem-sucedido e uma resposta HTTP (normalmente HTTP 404). 5. Para confirmar que um guarda específico está acessível e responsivo, você pode executar um comando curl usando o exemplo de solicitação (inclua uma chave de guarda válida) de **Segurança IA > Guardas > Implantação**. Uma resposta bem-sucedida deve incluir a regra de política de guarda correspondente e a ação que seria aplicada. ![Imagem](https://cdn.document360.io/81d0367c-2b69-4ba8-b412-1c8f46ce677e/Images/Documentation/image(247).png?sv=2026-02-06&spr=https&st=2026-11-19T05%3A21%3A24Z&se=2026-11-19T06%3A21%3A24Z&sr=b&sp=r&sig=GHMXZG9SojaF7d21qO%2FLUeDT43UGo%2F5Sro2NA4qKh7s%3D) 6. Se o Guarda estiver corretamente configurado na aplicação, o guarda estiver acessível via curl e nenhum evento CMA for gerado, escale para o Suporte Cato com o tipo/configuração do Guarda (Proxy, API ou AI Gateway), detalhes da aplicação e arquivos de configuração (redija as chaves das APIs) ### Resolução de Problemas de Regras de Política dos Guardas que Não Estão em Efeito Isso se aplica quando a página de Guardas mostra invocações, mas as regras de política dos guardas não estão tomando a ação configurada. 1. Navegue para **Segurança IA > Política dos Guardas**, confirme se **Política dos Guardas Ativada** está marcada e se a regra afetada está publicada. 2. Confirme se o **Perfil do Motor** anexado à regra realmente inclui o detector esperado para capturar o conteúdo em questão. Você pode usar o [Playground do Motor](https://knowledge.catonetworks.com/v1/docs/testing-engine-profiles-in-the-playground){target=`_blank`} para validar que o conteúdo do prompt aciona o detector no perfil do motor antes de continuar a resolução de problemas. 3. Confirme se a **Direção** da regra corresponde ao local onde o conteúdo realmente aparece. Um detector direcionado à Saída da Ferramenta não avaliará um prompt de direção do Usuário, e vice-versa. 4. Confirme se a **Ação** configurada na regra é a ação que está sendo esperada. Uma regra configurada como **Anonimizar e Bloquear** ou **Anonimizar e Monitorar** aplicará uma ação com base no tipo de conteúdo detectado dentro do prompt, conforme explicado em [Ação Inesperada Aplicada pela Política](https://knowledge.catonetworks.com/docs/troubleshooting-ai-security-for-users#:~:text=Unexpected%20Action%20Applied%20by%20the%20Policy){target=`_blank`} 5. Se múltiplas regras puderem ser aplicadas ao mesmo evento, confirme qual regra realmente disparou, revisando o detalhe do evento. Regras são avaliadas independentemente e não são dependentes da ordem. Se mais de uma regra for acionada, aplica-se a ação mais rigorosa. Uma ação de evento menos estrita do que o esperado geralmente significa que o escopo da regra mais estrita, Perfil de Motor, ou Direção não correspondem realmente a esse evento. 6. Se a regra estiver ativada, com escopo correto, o conteúdo corresponder, mas a ação esperada ainda não for aplicada, escale para o Suporte da Cato com o ID do evento, uma captura de tela da regra (Perfil de Motor, Direção, Ação), e o Guard ou integração pela qual o tráfego foi recebido. ### Solução de Problemas de Configurações ou Sessões de Agente ausentes Isso se aplica quando as configurações do Agente Gerenciado esperadas ou as sessões de agente estão ausentes ou incompletas no CMA. 1. Confirme que a integração propriamente dita aparece como Ativa, veja [Validar Conexão de Integração do Agente Gerenciado](/v1/docs/troubleshooting-ai-security-for-apps#validate-managed-agent-integration-connection) antes de solucionar problemas de dados ausentes dentro dela. 2. Permita a cadência normal de atualização da plataforma: pelo menos um ciclo de hora em hora para Microsoft Foundry e Copilot Studio, e até o tempo necessário para a AWS gerar e entregar rastreamentos do CloudWatch para Bedrock AgentCore. 3. Valide que a Cato suporta visibilidade de sessões de agentes no CMA para a aplicação gerenciada afetada, conforme documentado em [Trabalhando com Agentes Gerenciados](https://knowledge.catonetworks.com/docs/working-with-managed-agents){target=`_blank`}. 4. Para **Amazon Bedrock AgentCore**, confirme que a **Pesquisa de Transação do CloudWatch** está ativada (Console AWS > Sinais da Aplicação (APM) > Pesquisa de Transação, com ingestão de spans como logs estruturados). Sem isso, a Cato pode mostrar os agentes AgentCore no inventário, mas nunca sua atividade. 5. Para **Copilot Studio**, confirme que **Sessões de Agente** estão ativadas para o ambiente específico ao qual o agente ausente pertence (**Centro Administrativo do Power Platform > Gerenciar > Ambientes > [ambiente] > Configurações > Produto > Recursos > agentes do Copilot Studio**), e confirme que o ambiente não é um ambiente de desenvolvedor, o qual não é suportado para esta configuração. 6. Para **Microsoft Foundry**, confirme que a assinatura específica que contém o recurso Foundry ausente tem a função de Usuário dos Serviços Cognitivos atribuída à aplicação Cato. A atribuição de função não se aplica a nível de locatário e deve ser repetida por assinatura. 7. Para **Plataforma de Agentes da Empresa Gemini**, confirme as expectativas: apenas sessões de agentes e eventos de sessão são mostrados; uso de ferramenta, integração e serviço externo dentro de uma sessão não são coletados por design. 8. Se o intervalo de atualização relevante tiver decorrido e as configurações específicas de rastreamento/função/sessão da plataforma forem todas confirmadas como corretas, escale para o Suporte da Cato com o tipo de integração, a assinatura/ambiente/projeto específico afetado e os dados esperados versus os dados reais observados. ## Levando Casos ao Suporte Cato Antes de abrir um caso com o [Suporte Cato](/v1/docs/opening-a-support-ticket), certifique-se de que todas as etapas relevantes de solução de problemas descritas neste manual foram concluídas. Se o problema permanecer sem solução, escale para o Suporte Cato com as seguintes informações: - **Descrição do Problema** — Uma descrição clara e concisa do sintoma observado e o comportamento esperado - **Componente Afetado** — Nome e tipo do Guard (Proxy, API ou AI Gateway), integração do AI Gateway (Portkey, LiteLLM ou Kong), ou integração do Agente Gerenciado (Amazon Bedrock, Amazon Quick, Microsoft Foundry, Copilot Studio ou Plataforma de Agentes da Empresa Gemini) - **Detalhes do Ambiente** — Para Guards: detalhes da aplicação e arquivos de configuração (redigir chaves de API). Para integrações do Agente Gerenciado: confirmar que os pré-requisitos documentados sejam atendidos e providenciar qualquer erro de configuração observado. - **Detalhes **de Conexão/Política**** — Nome(s) de regra de Política de Guardas, Perfil do Motor, Direção, e Ação; ou a etapa de configuração de integração específica concluída por último e seu resultado - **Etapas de Solução de Problemas Concluídas** — Um resumo das etapas já realizadas deste manual e o resultado de cada uma - **Evidências de Suporte** — links para eventos de segurança de IA, capturas de tela da regra ou configuração de integração, status da pilha CloudFormation ou mensagens de erro de Testar Conexão, e registros de data e hora exatos (UTC e fuso horário do cliente) Quanto mais contexto e evidências fornecidos de antemão, mais rápido o Suporte Cato poderá investigar e resolver o problema.