Saltar para o conteúdo principal
Qualquer prompt que a sua app envia a um modelo pode carregar dados pessoais que não deveria — um e-mail colado em um ticket de suporte, um SSN em uma nota de CRM, um número de cartão que um usuário digitou em uma caixa de chat. Uma vez que esse texto chega a um provedor upstream, está fora do seu controle: registrado, cacheado, talvez usado para treinamento. A resposta do modelo também pode vazar PII de volta, ecoando ou inferindo detalhes que então aterrissam nos logs da sua aplicação. Esta página mostra como parar um llm pii leak no gateway com um guardrail de PII — uma regra com escopo de workspace que mascara ou bloqueia entidades sensíveis na requisição antes que o modelo sequer as veja. É o par na camada de conteúdo do Agent Firewall, e não precisa de mudança no código da sua aplicação.
Um guardrail de PII filtra o texto de prompts e respostas. Para governar as ações que um agente toma com dados — ferramentas de fetch, hosts de egress — veja Exfiltração de dados. Os dois planos se compõem; a maioria das equipes roda ambos.

​
1. Como a exposição acontece

PII chega a um provedor upstream através de tráfego comum e bem-intencionado:
  • Um usuário cola seus próprios dados de contato em um chat e sua app encaminha a mensagem inteira textualmente.
  • Um pipeline RAG recupera um documento contendo registros de clientes e o enfia no prompt como contexto.
  • Um agente lê uma linha de banco de dados e inclui campos brutos em um argumento de ferramenta ou em um prompt subsequente.
  • A resposta do modelo reafirma ou infere PII, que sua app então escreve em seus próprios logs.
Nada disso é um ataque — é a forma normal de apps de LLM. A correção é uma política que filtra cada requisição e resposta em um único ponto de estrangulamento, em vez de auditar cada call site no seu código.

​
2. Defenda o llm pii leak com um guardrail de PII

Um guardrail é uma política de conteúdo nomeada e com escopo de workspace. Uma regra pii dentro dele detecta entidades sensíveis e aplica uma ação a cada correspondência:
AçãoEfeito
maskSubstitui cada correspondência por uma tag tipada — jane@acme.com → [EMAIL] — e encaminha o texto limpo. O modelo nunca vê o original.
blockRejeita a requisição inteira com HTTP 400 guardrail_blocked. Use quando PII nunca deve chegar ao provedor de forma alguma.
flagNão muda nada no tráfego; registra uma correspondência. Meça a exposição antes de aplicar enforcement.
O conjunto de detectores é embutido e determinístico — puro pattern matching, sem chamada de rede, seguro no hot path. Entidades embutidas: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address, mais os identificadores regionais com gate de checksum jp_mynumber, kr_rrn e cn_resident_id. Em uma ação mask, cada correspondência é renderizada como sua tag tipada — [EMAIL], [SSN], [CREDIT_CARD], e assim por diante — de modo que a estrutura do prompt sobrevive enquanto o valor desaparece.
Precisa de um detector que não é embutido (um ID interno de funcionário, um número de conta)? Adicione uma entidade customizada — um regex com checksum Luhn opcional, até 25 por regra — bem ao lado das embutidas. Veja a referência de Guardrails.

​
3. Exemplo concreto — mascarar PII na requisição

O começo mais rápido é o preset PII Shield: uma única regra pii que mascara email, phone, ssn, credit_card e ip. Configure-o no console — sem mudanças de código, sem chave nesta etapa.
1

Crie o guardrail

No console, abra Guardrails e clique em New guardrail. Escolha o preset PII Shield da categoria pii, ou crie à mão uma regra pii com ação mask sobre as entidades acima. Salve. (Escritas exigem o papel de Developer ou superior.)
2

Comprove no sandbox

Abra a aba Test, cole “reply to jane@acme.com”, escolha o estágio input e execute. O sandbox retorna reply to [EMAIL] — localmente, sem chamada upstream e sem cota gasta.
3

Anexe-o a uma chave

Em API Keys, edite uma chave e selecione o guardrail no dropdown Guardrail, ou defina o guardrail como padrão do workspace para que toda chave não anexada o herde. O vínculo vive na chave dentro do gateway.
4

Chame o gateway como de costume

Usando essa chave, sua chamada de relay fica inalterada:
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Draft a reply to jane@acme.com"}
    ]
  }'
O gateway reescreve o e-mail para [EMAIL] antes de encaminhar. O modelo upstream nunca recebe o endereço.
PII Shield é uma regra de estágio both, mas o mascaramento ao vivo no estágio de requisição é o que ship hoje — o gateway mascara o prompt antes que ele saia para o modelo. O mascaramento no estágio de saída (response) no relay ao vivo está no roadmap. Para verificar como uma regra de estágio de saída se comporta, avalie-a na aba Test. Para streaming, veja §5.

​
4. Mascarar a maioria, bloquear o pior — overrides por entidade

Uma única regra pode aplicar ações diferentes a entidades diferentes via entity_actions. Mascare identificadores de baixo risco mas bloqueie duramente as entidades que você nunca quer encaminhar — uma regra em vez de três sobrepostas: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Aqui e-mails, telefones e IPs são mascarados e passam; um prompt carregando um número de cartão ou SSN é, em vez disso, rejeitado com HTTP 400 guardrail_blocked. Uma requisição bloqueada não custa cota — um block de estágio de input dispara antes da metragem — e é marcada skip-retry. Cada chave de entity_actions deve ser uma entidade declarada na regra (embutida ou customizada); sua ação é validada contra o conjunto de ações da regra.

​
5. O que funciona em streaming hoje

Ação e estágio interagem com streaming de formas diferentes — conheça a matriz antes de depender dela:
Totalmente ao vivo. O prompt é filtrado antes da chamada upstream, de modo que mascaramento e bloqueio funcionam de forma idêntica quer a resposta seja em stream ou não. Esta é a superfície que o PII Shield aplica hoje.
Aplicado tanto em respostas em streaming quanto não-streaming. Em um stream, um scanner corta o stream em pleno voo e emite uma mensagem de substituição antes que qualquer conteúdo bloqueado chegue ao cliente; um block de output reembolsa a cota pré-consumida.
Atualmente apenas não-streaming. Em uma resposta em stream, o chunk original passa sem mascaramento — a reescrita in-band do stream é um aprimoramento planejado. Para mascaramento de resposta hoje, use requisições não-streaming, ou apoie-se no mascaramento de estágio de input. Comprove primeiro a sua combinação exata de estágio/stream na aba Test.

​
6. Veja o que foi capturado

Toda regra que dispara registra uma correspondência — seu tipo, ação, estágio e uma string de detalhe — visível no feed Matches do workspace (GET /api/guardrail/match, aberto a qualquer membro). A partir dali você pode agrupar, filtrar, exportar para CSV e marcar falsos positivos.
Valores brutos não são registrados por padrão. O interruptor Log raw content de um guardrail está desligado — a postura conservadora de privacidade — então o feed Matches registra que uma regra de PII disparou e qual entidade, mas não a substring correspondente (o próprio endereço de e-mail). Ligue-o por guardrail apenas quando você precisar do valor para triagem; a configuração é não-retroativa. Capturar PII na sua própria trilha de auditoria para depurar um vazamento de PII seria autodestrutivo.

​
7. Vá além

Para controles completos de residência, retenção e direito ao apagamento — incluindo instalar um pacote de compliance que materializa estes guardrails para GDPR, HIPAA ou PCI DSS — comece pelas páginas de referência abaixo.

Referência de Guardrails

Cada tipo de regra, estágio, ação, entidades customizadas, versionamento e o eval harness — a referência profunda por trás desta página.

Vazamento de segredos

O irmão em formato de credencial — tokens AWS, OpenAI, GitHub — capturado pelo guardrail Secrets Blocker.

Saída insegura

Filtrar o que o modelo envia de volta, não apenas o que ele recebe.

Guardrails vs Firewall

Quando filtrar texto e quando governar ações — e por que você geralmente quer ambos.