Glossário de segurança de agentes de IA
Um índice de referência rápida de cada termo usado na documentação de Zero Trust. Cada definição tem escopo no que você, como desenvolvedor no gateway hospedado, pode observar e configurar. Os termos vinculam às suas páginas principais para detalhes completos.Identidade e escopo
| Termo | Definição |
|---|---|
| Workspace | O limite de tenant de nível superior. Todas as chaves, guardrails, políticas de firewall e eventos de auditoria pertencem a um workspace; nada cruza fronteiras de tenant. Veja Escopo, chaves e políticas. |
| Chave de API (chave com escopo) | Um token de portador que seu agente apresenta em cada chamada. Carrega sua própria lista de permissão de modelos, restrições de IP, limite de gasto, expiração e a política exata de guardrail + firewall que se aplica a ela. Veja Escopo, chaves e políticas. |
model_limits | O conjunto de modelos (ou globs de modelo) que uma chave tem permissão de chamar. Requisições para um modelo fora da lista são rejeitadas antes de qualquer chamada upstream. |
allow_ips | Uma lista de permissão de IP ou CIDR na chave. Requisições originadas de um endereço fora da lista são rejeitadas na autenticação. |
credit_limit_usd (limite de gasto) | Um teto de gasto fixo na chave, em USD. Uma vez que o uso acumulado da chave alcança o limite, requisições adicionais são rejeitadas. Útil para limitar loops descontrolados de agente. |
| Tag de ambiente | Um rótulo de formato livre (ex.: production, staging) conectado a uma chave para organizá-la e identificá-la por ambiente de deployment. |
is_firewall_gateway | Uma flag que escopa uma chave para as rotas do gateway do Firewall (/api/v1/firewall/*) — os endpoints de dispatch MCP e hook de avaliação. Uma chave regular recebe 403 nessas rotas. |
| Menor agência | O princípio de dar a um agente apenas os modelos, gasto, IPs e políticas de que realmente precisa — nada mais. Implementado combinando model_limits, allow_ips, credit_limit_usd e uma política de firewall restritiva na mesma chave. Veja Escopo, chaves e políticas. |
Guardrails
| Termo | Definição |
|---|---|
| Guardrail | Uma política de conteúdo nomeada e com escopo de workspace — uma lista ordenada de regras que o gateway executa contra a entrada da requisição e a saída do modelo. Conecte-o a uma chave (ou defina-o como padrão do workspace) uma vez; cada chamada vinculada é inspecionada sem redeploy. |
| Regra | Uma verificação dentro de um guardrail: um tipo (o que detectar), um estágio (onde procurar) e uma ação (o que fazer). As regras rodam em ordem. |
| Estágio | input (a requisição do chamador), output (a resposta do modelo) ou both. Uma regra dispara apenas no seu estágio declarado. |
| Ação | block — rejeita a requisição inteira (HTTP 400); mask — redige a correspondência e deixa a chamada passar; flag — apenas registra, sem mudança de tráfego. |
guardrail_blocked | O código de erro retornado quando uma regra de guardrail dispara uma ação block. Retorna HTTP 400. A requisição não custa cota — bloqueios no estágio de entrada disparam antes da medição; bloqueios no estágio de saída reembolsam a cota pré-consumida. |
| PII Shield | Uma regra do tipo pii que detecta tipos de entidade sensíveis embutidos (email, telefone, SSN, cartão de crédito, IP e mais) e os mascara com tags tipadas. (O tipo de regra pii também suporta block por entidade quando você cria a sua própria.) O ponto de partida canônico para prevenção de perda de dados. Segredos e credenciais são cobertos pelo preset separado Secrets Blocker. |
| Guardrail de injeção de prompt | Uma regra de segurança que detecta tentativas de conteúdo não confiável (páginas web, resultados de ferramenta) de sequestrar as instruções do agente. Incluso como o preset Prompt-Injection Basics na categoria de template Safety. |
| Filtro de palavras sensíveis | Uma regra do tipo keyword que corresponde a uma lista de termos literais, sem distinção entre maiúsculas e minúsculas. A denylist mais simples. |
| LLM judge | Uma regra do tipo llm_judge que executa uma verificação semântica (toxicidade, fora de tópico, intenção de jailbreak) contra um modelo no seu workspace. Use para políticas difusas que nenhum regex consegue capturar. Tokens cobrados como uma sub-linha de judge. |
| Contextual grounding | Uma regra do tipo grounding que pontua a resposta do modelo contra as fontes RAG na requisição e sinaliza ou bloqueia respostas que não são fiéis a elas. |
| Log raw content | Um toggle por guardrail — desativado por padrão (conservador em privacidade). Quando desativado, o feed de Matches registra que uma regra disparou mas não a substring correspondente. Ative por guardrail quando precisar da string real para triagem. |
| Feed de Matches | O registro em nível de workspace de cada regra que disparou: tipo de regra, ação, estágio, string de detalhe e (quando Log raw content está ativado) a substring correspondente. Filtrável por guardrail, tipo de regra e ação. |
Agent Firewall
| Termo | Definição |
|---|---|
| Política de Firewall | Um conjunto ordenado de regras nomeado e com escopo de workspace que o gateway avalia em cada chamada de ferramenta. Conecte uma vez a uma chave ou defina como padrão do workspace; sem mudança de código do agente necessária. |
| Veredito | O resultado que uma regra (ou o padrão) produz para uma chamada de ferramenta. Um entre allow, audit, deny, sanitize, pending_approval ou cap_cost. |
| Veredito padrão | O veredito aplicado quando nenhuma regra na política corresponde à chamada de ferramenta. Padrão audit — permite tudo e registra — até que você esteja pronto para aplicar enforcement. |
| Superfície de enforcement | O ponto no ciclo de vida da requisição onde o firewall vê uma chamada: inbound (definições de ferramenta que o agente anuncia), response (chamadas de ferramenta que o modelo emite), mcp (um tools/call pelo gateway MCP) ou egress (um destino outbound reportado por uma ferramenta). Veja Firewall. |
| Lista de permissão de ferramentas (glob) | Um tool_name_glob em uma regra — uma gramática pequena e sensível a maiúsculas e minúsculas (shell.*, *.exec, *) que corresponde a um nome de ferramenta ou família. Primeira correspondência vence contra a lista de regras ordenada. |
| Validação de argumento | Cláusulas args_match em uma regra — operadores eq, contains, regex, in, cidr_match, gt, lt sobre campos JSONPath nos argumentos da ferramenta. A diferença entre “bloquear shell.exec” e “bloquear shell.exec apenas quando o comando é rm -rf.” |
| Sanitize | Um veredito sanitize que redige substrings correspondentes (segredos, PII) dos argumentos da ferramenta e encaminha a chamada limpa, em vez de bloquear a ação inteira. Escala para um bloqueio na superfície inbound. |
| Controle de egress | Uma regra na superfície egress com uma lista de allow ou deny de host/CIDR — a principal defesa contra SSRF e exfiltração de dados. O nível de autonomia tight também nega as ferramentas com formato fetch (http_fetch, fetch_url, web_search, request). |
cap_cost | Um veredito que nega chamadas de ferramenta assim que o gasto acumulado da run do agente (em centavos) excede um teto por regra. Um disjuntor para loops descontrolados de agente; criado como uma regra e resolve para allow ou deny em eventos com base no gasto acumulado. |
| Regra de sequência | Uma regra com um bloco sequence que corresponde a uma cadeia ordenada de múltiplos passos de chamadas de ferramenta dentro de uma janela de tempo (ex.: bulk-read → export → egress). Aplicada reativamente por um matcher assíncrono; aparece no feed de eventos. |
firewall_blocked | O código de erro em uma chamada de ferramenta negada. Retorna HTTP 400 no inbound; um erro de ferramenta no mcp. Marcado como skip-retry. |
Aprovação / HITL (pending_approval) | Um veredito pending_approval retém uma chamada de ferramenta para revisão humana. O agente recebe uma resposta “held” com um id de aprovação, um revisor aprova ou rejeita fora de banda, e o agente reenvia com um token de aprovação de uso único. O código de erro HTTP enquanto retido é firewall_approval_pending. |
| Detecção de anomalias | Camada estatística acima de regras estáticas. Pontua a atividade por ferramenta contra um baseline de hora-da-semana de 14 dias e sinaliza picos, loops de retry e caminhos de transição de ferramenta inéditos em um feed revisável. |
Posturas
| Termo | Definição |
|---|---|
| Observe mode | Uma configuração em nível de workspace. Quando ativado e nenhuma política está conectada a uma chave, chamadas de ferramenta são permitidas mas registradas como gaps de cobertura, populando a visão de Ferramentas Descobertas. |
| Shadow mode | Uma flag em uma política. A política avalia e registra exatamente como faria em produção, mas todo veredito de enforcement é rebaixado para audit (motivo prefixado com [shadow] would …). Interruptor de rollout seguro. |
| Enforce | O estado padrão quando o shadow mode está desligado e uma política está conectada. Os vereditos entram em vigor — deny bloqueia, sanitize redige, pending_approval retém. |
| Nível de autonomia | Um único interruptor (tight / balanced / permissive) que atomicamente substitui a postura de Firewall e Guardrails do workspace em uma transação com desfazer em um clique. Veja Modos de enforcement e Linha de base de Agentes Seguros. |
MCP e skills
| Termo | Definição |
|---|---|
| Servidor MCP | Um servidor Model Context Protocol registrado no seu workspace e exposto pelo gateway MCP do Firewall (api.orcarouter.ai/api/v1/firewall/mcp). Cada tools/call que ele recebe é avaliado inline. Veja MCP do Firewall. |
tools/call | A mensagem do protocolo MCP que despacha uma ferramenta para um servidor MCP. O firewall a avalia na superfície mcp antes de encaminhar. |
| Rug-pull | Um risco de cadeia de suprimentos onde um servidor MCP ou capacidade instalada muda ou expande suas definições de ferramenta após você ter concedido acesso. O OrcaRouter governa o raio de explosão: cada tools/call de MCP é avaliado pelo firewall na superfície mcp contra suas regras, e uma skill que pontua como arriscada é retida em quarantine até que um humano a revise. |
| Skill | Um pacote de capacidade (uma ou mais ferramentas de um ou mais servidores MCP) que o gateway escaneia em busca de riscos no registro. Cada skill recebe uma banda de risco e um modo de enforcement (allow, quarantine, block) que se sobrepõe aos vereditos em nível de política. |
Compliance e dados
| Termo | Definição |
|---|---|
| Pacote de compliance | Um pacote de guardrail + política de firewall pré-construído para um perfil regulatório (GDPR, PCI, HIPAA, dados financeiros). Aplique uma vez da biblioteca de templates; as regras são editáveis após a aplicação. |
| Relatório de compliance assinado | Um relatório de atestação em nível de workspace assinado com Ed25519. A assinatura é publicamente verificável — qualquer pessoa com a chave pública pode confirmar que o relatório não foi adulterado. |
| Residência de dados | A região registrada para sua evidência de compliance. Relatórios de compliance assinados são carimbados e armazenados por região (us, eu, uk, ap, cn, global), e um relatório só é servido sob uma região declarada correspondente. Defina nas configurações de compliance. |
| Direito ao apagamento | Em uma exclusão de workspace ou solicitação explícita de apagamento, o OrcaRouter concede um período de carência de 30 dias e depois purga PII de logs e registros de auditoria para esse workspace. |
| Evento de auditoria | Um registro imutável escrito após cada criação, atualização, exclusão e decisão de enforcement — mudanças de política, edições de regra, resoluções de aprovação, saves de guardrail. Valores de segredo e blobs de regra nunca são escritos no log de auditoria. |
Ameaças (em uma linha)
| Ameaça | O que é |
|---|---|
| Injeção de prompt | Um atacante embute instruções em conteúdo que o agente ingere (direta: na mensagem do usuário; indireta: em uma página web, documento ou resultado de ferramenta) para sequestrar o comportamento do agente. |
| Jailbreak | Um prompt elaborado que tenta bypassar o treinamento de segurança de um modelo, tipicamente enquadrando a requisição como roleplay, hipotético ou uma substituição de sistema. |
| Agência excessiva / confused deputy | Um agente com permissões mais amplas do que sua tarefa exige, tornando-o trivialmente explorável por instruções injetadas — a mitigação principal é a menor agência. |
| Exfiltração de dados | Um agente (ou instrução injetada) direcionando chamadas de ferramenta ou requisições outbound para vazar dados sensíveis para um endpoint controlado pelo atacante. Mitigado por regras de controle de egress. |
| Denial-of-wallet | Um agente descontrolado ou acionado adversarialmente que gera gasto ilimitado de modelo upstream. Mitigado por credit_limit_usd na chave e regras cap_cost na política de firewall. |
Para o quadro completo de como esses controles se compõem, veja Segurança de agentes de IA com OrcaRouter.