Exemplo de Implementação de Guardas para um Bot de Chat

Protegendo Aplicações de IA com Cato Guards (Configuração de Exemplo)

Visão Geral

Este guia orienta você através do processo completo de proteção de uma aplicação de IA personalizada usando Cato AI Security Guards. É estruturado como um fluxo de três etapas, onde cada uma avança em relação à anterior, para que você possa ver exatamente o que muda em cada passo e por quê.

A aplicação utilizada ao longo deste guia é o TravelBot — um simples chatbot assistente de viagens movido por IA. Embora o exemplo seja específico, os conceitos e etapas se aplicam a qualquer aplicação de IA personalizada que você desenvolver e quiser proteger.

O guia cobre três etapas:

• Etapa 1 estabelece a linha de base: uma aplicação de IA funcionando que se comunica diretamente com um LLM, sem controles de segurança. Esta etapa ajuda você a compreender o ponto de partida e os riscos que ele introduz.
• Etapa 2 traz o guardião: um Cato Proxy Guard é criado e inserido entre a aplicação e o LLM. O tráfego é redirecionado através do guardião, que começa a registrar todas as interações. Ainda não há regras de política configuradas — o objetivo desta etapa é simplesmente verificar se o fluxo ainda funciona com o guardião em funcionamento.
• Etapa 3 ativa a aplicação: as regras de política de interação são configuradas e publicadas, instruindo o guardião a bloquear tentativas de jailbreak e monitorar conteúdos relacionados à saúde. A aplicação agora está totalmente protegida.
  Ao final deste guia, você terá uma visão clara de como uma aplicação de IA personalizada pode ser protegida com Cato Guards — de uma conexão totalmente aberta para um fluxo de trabalho de IA monitorado, protegido e governado.

Etapa 1 — A Linha de Base: Seu Aplicativo de IA Sem um Guardião

O que Esta Etapa Cobre

Antes de introduzirmos qualquer controle de segurança, é importante entender como a aplicação funciona por si só. Esta etapa guia você através da configuração básica — uma aplicação de chat movida por IA que se comunica diretamente com um modelo de linguagem grande (LLM). Considere isto como a imagem "antes": o aplicativo é funcional, mas não há nada ainda entre o usuário e o modelo.

Como o Aplicativo Funciona

A aplicação é um simples chatbot assistente de viagens chamado TravelBot. Consiste em três componentes que trabalham juntos:

1. A Interface do Usuário
É o que o usuário vê e interage — uma interface de chat no navegador onde pode digitar perguntas e receber respostas.

2. O Backend
Este é o motor que opera nos bastidores. Ele recebe a mensagem do usuário, mantém o histórico da conversa e encaminha a mensagem ao LLM. Também trata de erros e retorna a resposta do modelo ao usuário. O backend é construído com Flask, um framework web leve.

3. A Conexão com o LLM
É aqui que a inteligência reside. O backend envia a mensagem do usuário (junto com o histórico da conversa) a um modelo de linguagem grande, que gera uma resposta. Neste estágio, o backend comunica-se diretamente com o LLM — não há nada intermediando.

O fluxo se assemelha a isso:

Usuário (navegador) → Backend (Flask) → LLM → Resposta de volta ao Usuário

Uma Nota sobre Linguagem e Framework

A aplicação de exemplo neste guia é construída com Python, usando um framework web leve chamado Flask. Python é uma escolha popular para desenvolvimento de aplicações de IA, mas não é de forma alguma a única opção. Os mesmos conceitos e fluxos se aplicam, quer sua aplicação seja construída em Node.js, Java, Go ou qualquer outra língua. Os valores de configuração, a estrutura do pedido e a integração do guardião seguem a mesma lógica — apenas a sintaxe muda.

O Arquivo de Configuração

A conexão entre o backend e o LLM é controlada por um arquivo chamado config.py. Este arquivo mantém três valores críticos:

OPENAI_API_KEY = "sk-proj-xK92mLqP3nVwTz8YdR5eN1uJbF7cQm4HsAo6WpGi0XvCl"
BASE_URL = "https://bedrock-mantle.eu-north-1.api.aws/v1"
MODEL_ID = "amazon.nova-pro-v1:0"

• OPENAI_API_KEY — Esta é a credencial que prova ao provedor LLMA que sua aplicação está autorizada a fazer solicitações.
• BASE_URL — Este é o endereço para onde o backend envia as requisições. No momento, aponta diretamente para o provedor do LLM.
• MODEL_ID — Isso informa o provedor de LLM qual modelo específico usar ao gerar respostas.

Para colocar o aplicativo em funcionamento nesta etapa, você (ou seu desenvolvedor) preencheria esses três valores com as credenciais fornecidas pelo seu provedor de LLM.

O que o Aplicativo Faz com Sua Mensagem

Quando um usuário envia uma mensagem, aqui está o que acontece passo a passo:

1. O usuário digita uma mensagem na interface de chat e clica em enviar.
2. O navegador envia a mensagem ao backend Flask, junto com um ID de sessão que identifica a conversa.
3. O backend adiciona a mensagem ao histórico da conversa e encaminha tudo ao LLM, adicionando uma instrução do sistema que informa ao modelo para se comportar como TravelBot.
4. O LLM processa toda a conversa e gera uma resposta.
5. A resposta é enviada de volta ao backend, adicionada ao histórico da conversa e retornada ao navegador do usuário.
6. O usuário vê a resposta na interface de chat.

O que Ainda Não Está Acontecendo

Neste estágio, a aplicação está totalmente funcional, mas completamente desprotegida. Isso significa:

• Não há inspeção do que o usuário envia ao modelo.
• Não há inspeção das chamadas de ferramenta e respostas.
• Não há aplicação de política — qualquer mensagem, incluindo as maliciosas, chega ao LLM.
• Não há visibilidade sobre como a aplicação está sendo utilizada.

Um usuário poderia, por exemplo, tentar manipular o modelo para ignorar suas instruções, extrair informações confidenciais ou usar a aplicação de maneiras que violem as políticas da sua organização — e nada disso seria detectado ou parado.

É exatamente esta lacuna que a próxima etapa aborda.

Resumo

Etapa 2 — Introduzindo o Guardião

O que Esta Etapa Cobre

Na Etapa 1, estabelecemos uma aplicação de IA funcionando que se comunica diretamente com um LLM. O aplicativo funciona, mas não há nada entre o usuário e o modelo. Nesta etapa, introduzimos um Cato AI Security Guard — a camada de proteção que fica entre sua aplicação e o LLM, inspecionando o tráfego em tempo real antes de chegar ao modelo e dos retornos ao usuário.

Ao final desta fase, todo o tráfego do LLM, mensagens dos usuários, definições de ferramentas, uso de ferramentas, etc., passam pela Cato. A experiência do usuário permanece idêntica — mas agora, cada interação é inspecionada e pode ser controlada.

O fluxo atualizado se apresenta assim:

O que é um Guardião?

Um guardião é o ponto de aplicação para Segurança de IA. Neste exemplo, em que estamos utilizando o Modo Proxy, ele atua como um intermediário — ficando entre sua aplicação e o LLM — e avalia cada prompt e resposta contra as políticas que você define. Com base nessas políticas, o guardião pode permitir, bloquear ou registrar uma interação.

Existem três tipos de guardiões. Para este guia, estamos usando um Proxy Guard. No modo proxy, o guardião está totalmente online na rota do tráfego. Sua aplicação envia as requisições para o endpoint do guardião em vez de diretamente para o LLM, e o guardião as encaminha após a inspeção. Não são necessárias alterações na lógica de sua aplicação — apenas o endereço de destino é alterado.

Passo 1 — Criar o Guardião na Aplicação de Gerenciamento Cato

O primeiro passo é criar o guardião como uma entidade lógica na Aplicação de Gerenciamento Cato. Isso é feito na interface de usuário — nenhum código é necessário neste ponto.

1. No menu de navegação, selecione AI Security > Guards, depois clique em Novo.
2. Digite um Nome do Guardião descritivo. Em nosso exemplo, usamos E2E Sample Use Case.
3. Em Selecione o Tipo de Guardião, escolha Proxy.
4. Em Selecione o Serviço de IA, escolha Endpoint Personalizado na lista suspensa. Esta opção funciona com qualquer endpoint compatível com OpenAI, que é o que nossa aplicação usa.
5. No campo URL do Endpoint, insira a URL do seu provedor de LLM. Em nosso exemplo, é https://bedrock-mantle.eu-north-1.api.aws/v1. Essa é a mesma URL que anteriormente foi definida como BASE_URL em config.py — agora você está passando esse endereço para o guardião ao invés de usá-lo diretamente na sua aplicação.
   Nota: A URL deve incluir o caminho até, e incluindo, o /v1.
6. Em Configurar Configurações do Guardião, deixe Host do Guardião configurado para Nuvem da Cato. Isso significa que o guardião é gerenciado e hospedado pela Cato — você não precisa implantar ou manter nenhuma infraestrutura adicional.
7. Clique em Salvar.

O que acabou de acontecer? Você criou um guardião que sabe onde o seu LLM está. A partir de agora, a Cato atuará como intermediário para todo o tráfego entre sua aplicação e esse LLM. O guardião ainda não tem regras de política — adicionaremos essas na Etapa 3. Por enquanto, estamos apenas estabelecendo a conexão e verificando se o fluxo ainda funciona.

Passo 2 — Obter os Detalhes da Conexão do Guardião

Uma vez que o guardião esteja salvo, abra-o da página Guards e navegue para a página Docs do guardião, que fornece tudo que sua aplicação precisa para se conectar ao guardião em vez de conectar diretamente com o LLM.

Você encontrará aqui duas informações principais:

• O Endpoint do Guardião (seu novo BASE_URL) - Este é o endereço para onde sua aplicação agora enviará requisições: https://api.aisec.catonetworks.com/fw/v1/proxy/openai

  • Isto substitui a URL do endpoint do LLM na sua configuração. De agora em diante, sua aplicação fala com a Cato, e a Cato fala com o LLM em seu nome.

• A Chave da API do Guardião (sua nova OPENAI_API_KEY)

  • A página Docs também fornece uma Chave da API do Guardião — a credencial que sua aplicação usa para autenticar com o guardião. Isso substitui a chave de API do LLM que estava previamente em sua configuração. Parece com isso: cato-1234-abcde

Nota: Cato fornece duas Chaves da API do Guardião. Você precisa de apenas uma para fazer requisições. A segunda chave existe para que você possa rotacionar credenciais com segurança — você pode atualizar sua aplicação para usar a nova chave enquanto a antiga ainda está ativa, evitando qualquer tempo de inatividade.

A Chave da API do LLM

Previamente, a chave da API do LLM residia na configuração da sua aplicação. Com o guardião em funcionamento, essa chave se move para os cabeçalhos das requisições que sua aplicação envia ao guardião — especificamente em um cabeçalho chamado x-cato-provider-api-key. O guardião usa isso para autenticar com o LLM em nome de sua aplicação.

Isso é, na verdade, uma melhoria de segurança: a chave de API do LLM não está mais hardcoded em um arquivo de configuração, e o guardião atua como um intermediário controlado para essa credencial.

Passo 3 — Atualizar a Configuração da Aplicação

Agora que o guardião está criado e você tem seus detalhes de conexão, é hora de atualizar a aplicação. Para manter a Etapa 1 e a Etapa 2 claramente separadas, criamos um novo conjunto de arquivos de configuração ao invés de sobrescrever os originais. Desta forma, ambas as etapas permanecem intactas para referência.

O novo arquivo de configuração, config_stage2.py, reflete os detalhes de conexão atualizados:

# Configuração da Etapa 2 — roteando pelo Cato Proxy Guard

GUARD_API_KEY = "cato-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.aisec.catonetworks.com/fw/v1/proxy/openai"
MODEL_ID = "amazon.nova-pro-v1:0"
LLM_PROVIDER_API_KEY = "[SECRET_1]" # Chave da API do seu provedor de LLM — passada ao guardião, não diretamente ao LLM

SYSTEM_PROMPT = (
"Você é o TravelBot, um assistente de viagens amigável e experiente. "
"Ajude os usuários a descobrir destinos, planear itinerários, recomendar hotéis, "
"e compartilhar dicas práticas de viagem. Mantenha as respostas concisas e entusiasmadas. "
"Se a pergunta não estiver relacionada a viagens, encaminhe educadamente a conversa."
)

MAX_TOKENS = 1024

As principais diferenças da Etapa 1:

Passo 4 — Atualizar o Código do Cliente

O código do cliente também recebe uma versão correspondente da Etapa 2 — bedrock_client_stage2.py. A lógica é em grande parte a mesma da Etapa 1, com duas adições:

1. A Chave da API do Guardião é usada para autenticar com o guardião (na autorização do cabeçalho).
2. A chave da API do LLM é passada como um cabeçalho adicional (x-cato-provider-api-key) para que o guardião possa encaminhá-la ao LLM.
3. O ID de sessão é passado como um cabeçalho (x-cato-session-id) para que o guardião possa agrupar requisições da mesma conversa — isso mapeia diretamente para o session_id que já existe na lógica da aplicação.

# bedrock_client_stage2.py

de openai import OpenAI
de config_stage2 import GUARD_API_KEY, BASE_URL, MODEL_ID, LLM_PROVIDER_API_KEY, SYSTEM_PROMPT, MAX_TOKENS


class BedrockClient:
 def __init__(self):
 self._client = None

 def _get_client(self) -> OpenAI:
 if self._client is None:
 self._client = OpenAI(
 api_key=GUARD_API_KEY,
 base_url=BASE_URL,
 default_headers={
 "x-cato-provider-api-key": LLM_PROVIDER_API_KEY,
 }
 )
 return self._client

 def invoke(self, messages: list[dict], session_id: str = "") -> str:
 all_messages = [{"role": "sistema", "content": SYSTEM_PROMPT}] + messages

 response = self._get_client().chat.completions.create(
 model=MODEL_ID,
 messages=all_messages,
 max_tokens=MAX_TOKENS,
 extra_headers={
 "x-cato-session-id": session_id,
 }
 )

 return response.choices[0].message.content

Verificando o Fluxo

Assim que os arquivos de configuração e cliente atualizados estiverem no lugar, a aplicação deve se comportar exatamente como na Fase 1 do ponto de vista do usuário. O TravelBot responde a perguntas de viagem da mesma forma — mas agora toda a interação passa pelo guarda.

Neste ponto, o guarda não possui regras de política configuradas, portanto, não está bloqueando ou modificando nenhum tráfego. No entanto, está registrando todas as interações. Você pode verificar isso abrindo o guarda no Aplicativo de Gerenciamento da Cato e revisando a página Log do Guarda, onde você deve ver as sessões aparecendo à medida que a aplicação é usada.

Isso confirma que a integração está funcionando corretamente e o guarda está recebendo tráfego.

Resumo das Mudanças da Fase 1 para a Fase 2

Fase 3 — Configurando Regras de Política

O que esta fase cobre

Na Fase 2, introduzimos o guarda e verificamos que o tráfego está fluindo por meio dele corretamente. O guarda está ativo, mas ainda não está aplicando regras — está observando o tráfego sem atuar sobre ele. Nesta fase, configuramos a Política de Interação dos Guardas: o conjunto de regras que informa ao guarda o que fazer quando detecta tipos específicos de conteúdo.

Ao final desta fase, o guarda estará aplicando ativamente duas regras contra o tráfego ativo:

• Bloquear e anonimizar qualquer interação que inclua informações como PII ou senhas
• Monitorar qualquer interação que envolva conselhos médicos ou dados relacionados à saúde

Nota: Recomendamos que você primeiro teste suas regras configurando-as para Monitorar e movendo-as para Bloquear após validar que as detecções estão funcionando conforme esperado.

O que é a Política de Interação dos Guardas?

A Política de Interação dos Guardas é a base de regras para seus guardas de Segurança de IA. Pense nisso como um firewall para o tráfego de IA — em vez de inspecionar pacotes de rede, ele inspeciona o conteúdo das interações de IA e aplica a ação que você definir quando uma correspondência for encontrada.

Cada regra na política especifica:

• Qual guarda a regra se aplica
• O que procurar — definido por um Perfil de Motor, que é a categoria de detecção (por exemplo, tentativas de jailbreak, PII ou dados médicos)
• O que fazer quando uma correspondência for encontrada — Bloquear, Monitorar, Anonimizar & Bloquear ou Anonimizar & Monitorar
• Qual direção do tráfego para inspecionar — mensagens de entrada do usuário, respostas do assistente, entradas de ferramentas, ou saídas de ferramentas

Um comportamento importante a ter atenção: as regras na Política de Interação dos Guardas são avaliadas independentemente de sua posição na base de regras. Se mais de uma regra se aplicar a uma interação, a ação mais rigorosa prevalece. Por exemplo, se uma regra disser Monitorar e outra disser Bloquear, a ação de Bloqueio é aplicada.

Etapa 1 — Criar Regra 1: Bloquear Tentativas de Jailbreak

A primeira regra que criamos visa tentativas de jailbreak — esforços deliberados dos usuários para manipular o modelo a ignorar suas instruções ou contornar seus resguardos. Para um aplicativo voltado ao consumidor como o TravelBot, isso é um risco significativo: um usuário pode tentar forçar o modelo a se comportar fora de sua função definida ou expor informações que não deveria.

Para começar, navegue até a página de Política dos Guardas. Você pode fazer isso a partir do menu de navegação principal selecionando Segurança de IA > Política de Interação dos Guardas, ou diretamente da página Visão Geral do guarda clicando em Gerenciar Política na seção Regras Ativas.

Na página de Política dos Guardas, clique em Novo para abrir o editor de regras, depois configure o seguinte:

Geral

• Nome: Bloquear algum Tráfego
• Descrição: Isso bloqueia o tráfego de jailbreak do nosso bot de viagem
• Deixe a alternância Ativado ligada

Guardas

• Selecione Caso de Uso de Amostra E2E — isso limita a regra ao nosso guarda específico e não afeta nenhum outro guarda na conta

Perfil de Motor

• Selecione Identificadores Sensíveis — esta é a categoria de detecção que identifica tentativas de injeção de prompts, padrões de jailbreak e tentativas de extrair segredos ou credenciais do modelo

Ação

• Selecione Anonimizar & Bloquear — quando o guarda detectar uma correspondência, ele anonimiza qualquer dado sensível presente na interação e bloqueia o prompt de chegar ao LLM por completo

Direção

• Verifique Usuário e Entrada de Ferramenta — a regra se aplica ao conteúdo vindo do usuário e de qualquer entrada de ferramenta. Respostas do assistente e saídas de ferramentas não estão dentro do escopo para esta regra.

Clique em Salvar. A regra é salva em uma revisão não publicada e ainda não afetará o tráfego ativo.

Etapa 2 — Criar Regra 2: Monitorar Conteúdo Médico

A segunda regra adota uma abordagem diferente. Em vez de bloquear o tráfego, permite que as interações prossigam enquanto sinaliza-as para revisão. Isso é apropriado para conteúdo que não é necessariamente malicioso, mas pode justificar visibilidade — neste caso, interações envolvendo conselhos médicos ou dados relacionados à saúde.

Para o TravelBot, um usuário pedindo conselhos médicos de viagem (como requisitos de vacinação ou precauções de saúde para um destino) não é inerentemente prejudicial, mas é o tipo de conteúdo que sua organização pode querer rastrear para fins de conformidade ou qualidade.

Na página de Política dos Guardas, clique novamente em Novo e configure o seguinte:

• Geral
  • Nome: Monitorar Dados Potencialmente Nocivos
  • Descrição: Isso permite a comunicação, mas monitora as interações
    Deixe o alternador Ativado ligado

Guardas

• Selecione Caso de Uso de Amostra E2E

Perfil de Motor

• Selecione Exposição de Dados de Saúde — isso detecta interações que envolvem orientação médica, dados de saúde, ou informações clínicas

Ação

• Selecione Anonimizar & Monitorar — a interação é permitida até o LLM e a resposta é retornada ao usuário normalmente. Qualquer informação personalizada é anonimizada para proteger os detalhes pessoais. A interação é registrada na Cato para revisão.

Direção

• Verifique todas as quatro direções: Usuário, Assistente, Entrada de Ferramenta e Saída de Ferramenta — esta regra monitora o tráfego em todas as direções, proporcionando visibilidade total sobre ambos os lados da conversa

Clique em Salvar.

Etapa 3 — Publicar a Política

Após salvar ambas as regras, a página de Política dos Guardas mostrará um status de Revisão Não Publicada e um botão Publicar (2) no canto superior direito, indicando que duas regras estão prontas para entrar em vigor.

Importante: Até que você publique, a política ativa permanece inalterada. Suas regras existem em um estado de rascunho e não são aplicadas contra o tráfego ativo. Isso te dá a oportunidade de revisar suas mudanças antes que entrem em vigor.

Quando estiver pronto, clique em Publicar (2). Ambas as regras tornam-se ativas imediatamente e o guarda começa a aplicá-las em todo o tráfego de entrada.

O que o Guarda está fazendo agora

Com ambas as regras publicadas, toda interação que passa pelo guarda Caso de Uso de Amostra E2E agora é avaliada contra a política. Veja como isso funciona na prática:

Um usuário envia uma mensagem para o TravelBot. Antes que a mensagem chegue ao LLM, o guarda a inspeciona contra ambas as regras:

• Se a mensagem contiver um padrão de jailbreak ou uma tentativa de extrair segredos, o guarda a anonimiza e a bloqueia. O LLM nunca vê a mensagem, e o usuário recebe uma resposta bloqueada.
• Se a mensagem contiver conselhos médicos ou conteúdo relacionado à saúde, o guarda a permite mas registra a interação para revisão.
• Se a mensagem não corresponder a nenhuma regra, ela passa para o LLM sem ser afetada.

A mesma avaliação se aplica às respostas do assistente, entradas de ferramentas e saídas de ferramentas, dependendo das direções configuradas para cada regra.

Verificando se as Regras estão Ativas

Para confirmar que as regras estão ativas e aplicadas ao seu guarda, navegue até a página Visão Geral do guarda. Em Regras Ativas, você agora deve ver ambas as regras listadas. O gráfico Interações ao Longo do Tempo e o painel de Desagregação de Violações começarão a se preencher à medida que o tráfego fluir pelo guarda e as detecções ocorrerem.

Você também pode navegar para Log do Guarda para revisar sessões individuais, ver quais regras foram ativadas e inspecionar os detalhes das interações sinalizadas — desde que tenha as permissões necessárias para visualizar conteúdo sensível.

Resumo

Com essas duas regras em vigor, a aplicação agora tem aplicação de segurança ativa. Tentativas de prompt maliciosas são bloqueadas antes de chegar ao modelo, e interações sensíveis à saúde estão visíveis para sua equipe de segurança — tudo isso sem alterações no código da aplicação ou impacto na experiência do usuário final para interações legítimas.

Isso completa o guia de ponta a ponta para proteger uma aplicação de IA personalizada com os Guardas de Segurança da Cato AI.