Saltar para o conteúdo principal
Você leu uma página de controle e tem uma pergunta restante antes de aplicar. Este é o faq de segurança de agentes de ia — as perguntas transversais que abrangem toda a seção de Zero-Trust, respondidas em um único lugar, cada uma linkando para a referência para mais profundidade. Se você é totalmente novo na seção, comece em Segurança de agentes de IA e na pilha de controle; esta página assume que você sabe que há dois planos de enforcement — Guardrails (texto de prompt/resposta) e o Firewall (ações de agente) — e só precisa amarrar as pontas.

​
1. faq de segurança de agentes de ia — comece aqui

Um mapa de 30 segundos de qual controle responde qual pergunta:
Você está perguntando sobre…O planoLeia
Texto em prompts ou respostas (PII, segredos, jailbreaks)GuardrailsGuardrails
Chamadas de ferramenta, MCP, egress, skillsFirewallFirewall
Qual deles disparou em um 400Qualquer umPor que foi bloqueado?
Todo bloqueio de segurança no gateway hospedado é HTTP 400 com um code legível por máquina. Leia o código primeiro — ele o bifurca para o feed certo. A tabela completa vive em Códigos de erro.

​
2. Guardrails — filtragem de conteúdo

Nada. A resolução é: guardrail_id explícito na chave (se existir e estiver habilitado) → caso contrário o guardrail is_default do workspace → caso contrário sem enforcement. Um vínculo explícito desabilitado é o interruptor de desligar — ele não cai de volta para o padrão. Com nada resolvido, a requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
Não. Uma ação block retorna 400 guardrail_blocked e não custa cota — um bloqueio em estágio de entrada dispara antes da medição; um bloqueio em estágio de saída reembolsa a cota pré-consumida. Também é marcado skip-retry: reexecutar o prompt idêntico apenas bloqueia de novo.
Tipos de regra: keyword, regex, pii, max_chars, external, llm_judge, grounding. Ações: block (rejeitar), mask (redigir e encaminhar), flag (apenas registrar, sem mudança no tráfego). Estágios: input, output, both. Veja Guardrails para cada um.
Entidades embutidas incluem email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address, mais tipos regionais (jp_mynumber, kr_rrn, cn_resident_id). Uma ação mask renderiza uma tag tipada — jane@acme.com → [EMAIL], um SSN → [SSN]. Você pode adicionar até 25 entidades regex personalizadas por regra (com um checksum Luhn opcional) e sobrescrever a ação por entidade via entity_actions.
O block de saída é aplicado nos dois modos — respostas não-streaming são filtradas antes de retornar, e um scanner de streaming corta o stream em pleno voo. O mask de saída é atualmente apenas não-streaming; em uma resposta em streaming o chunk passa sem máscara (a reescrita de stream em banda está no roadmap). O mascaramento em estágio de entrada — sanitizando a requisição antes que o modelo a veja — está ativo de qualquer forma. O preset PII Shield mascara no estágio de entrada hoje.
Regras keyword / regex / pii / max_chars não fazem chamada de modelo e não cobram nada. Uma regra llm_judge roda uma verificação semântica através de um modelo do workspace (limitada por judge_timeout_ms, fail-open por padrão) e é cobrada como uma sub-linha de juiz separada. Uma regra grounding pontua a fidelidade da resposta contra as fontes recuperadas da requisição (limiar padrão 0.7) da mesma forma.
Abra o feed de Matches (GET /api/guardrail/match, Member). Cada linha registra tipo de regra, ação, estágio e uma string de detalhe — e a substring correspondente apenas se “Log raw content” estiver ligado para aquele guardrail (desligado por padrão, a postura conservadora de privacidade). Bloqueio errado? Marque-o como falso positivo (POST /api/guardrail/match/:id/mark-fp, Admin).
Um guardrail pode decorar um prompt com um aviso de segurança de código (ex.: uma nota de CVE/SBOM sobre um pacote referenciado) sem bloquear ou mascarar o texto. Esta é uma camada de anotação que aumenta a requisição em vez de rejeitá-la — distinta das ações block / mask / flag que você cria diretamente. Conecte um scanner sob Integrações para acioná-la.

​
3. Firewall — ações de agente

Uma diferença-chave: uma política de firewall vinculada desabilitada cai de volta para o padrão do workspace, enquanto um guardrail vinculado desabilitado resolve para nenhum. De resto, ambos vinculam via a chave (firewall_policy_id / guardrail_id) e compartilham o fallback para o padrão do workspace. Veja Guardrails vs Firewall.
Vereditos: allow, audit, deny, sanitize, pending_approval, cap_cost. default_verdict é allow / audit / deny (audit por padrão). Superfícies: inbound (ferramentas anunciadas), response (tool_calls emitidos pelo modelo), mcp (um tools/call), egress (host/IP/CIDR outbound). O glossário de vereditos decodifica cada um.
Não — e este é o equívoco comum. Um veredito sanitize redige substrings correspondentes apenas dos argumentos da chamada de ferramenta, nunca o conteúdo que uma ferramenta retorna. Na superfície inbound (ainda sem args em tempo de chamada) sanitize escala para um deny.
Um interruptor define toda a sua postura, escrevendo linhas autonomy_* reais e editáveis:
• balanced (início recomendado) — audit padrão, nega shell destrutivo, PII Shield em apenas-audit (sinaliza PII).
• tight — default-deny, nega shell destrutivo, nega ferramentas de fetch com formato de SSRF, PII Shield + Secrets Blocker aplicados.
• permissive — apenas observa.
O undo em um clique restaura o estado anterior a partir do snapshot de auditoria que a aplicação escreveu. É um único passo — o undo fica indisponível assim que uma aplicação posterior (ou uma edição manual de política) supera aquele snapshot. Veja Modos de enforcement.
Não por preset. O preset de SSRF do nível de autonomia tight nega os nomes de ferramenta comuns com formato de fetch (http_fetch, web_search, fetch_url, request). Para negar por destino — faixas RFC-1918, IPs de metadados de nuvem, CIDRs específicos — crie sua própria regra de deny de host/CIDR na superfície egress. Nenhum preset traz regras CIDR prontas para você. Veja Egress & exfiltração de dados.
Ligue o shadow mode (por política): a política avalia e registra mas rebaixa todo veredito de enforcement para audit, prefixando o motivo com [shadow] would …. Observe as visões de Events e Runs, depois desligue o shadow para aplicar. O observe mode em nível de workspace (firewall_observe_mode) é o controle de descoberta complementar — ele registra chamadas não cobertas como gaps em Discovered Tools.
Um veredito pending_approval retorna 400 firewall_approval_pending com um id de aprovação. Um revisor a resolve a partir do console (Developer+) ou via um callback de webhook HMAC (POST /api/v1/firewall/approvals/:id/callback). O agente consulta GET /api/v1/firewall/approvals/:id e reenvia a chamada original com um header de uso único X-OrcaRouter-Firewall-Approval. Veja Chamadas de ferramenta perigosas.
Picos de taxa/custo pontuados contra um baseline de hora-da-semana aprendido (14 dias), mais retry_loop e novel_path (uma transição ferramenta-para-ferramenta nunca vista antes). O feed é legível por Member; dê snooze em uma anomalia por até 7 dias. Veja Agência excessiva.

​
4. MCP, chaves & acesso ao gateway

Registre um servidor (name, endpoint, auth_mode de none/bearer/oauth/basic, credenciais criptografadas) e o gateway MCP avalia cada tools/call na superfície mcp antes do dispatch. A saúde é rastreada (ok/degraded/down); faça probe dela com POST /api/workspace/firewall/mcp_servers/:id/probe. Um probe também faz baseline do schema de ferramentas anunciado do servidor — drift posterior vira seu schema status de verified para changed (o sinal de “rug-pull”), e você ou faz re-baseline (aprova) ou coloca o servidor em quarantine. Então a governança é avaliação por chamada mais rastreamento de integridade de schema e bandas de risco de skill. Veja Firewall MCP e Envenenamento de ferramenta MCP.
Cada skill é escaneada em uma banda de risco com um modo de enforcement de allow / quarantine / block. Uma skill em quarentena é retida para aprovação; skills auto-detectadas permanecem em quarentena até que um humano as revise. O modo anda por cima do veredito da regra.
model_limits (+ model_limits_enabled), allow_ips, credit_limit_usd (0 = ilimitado), expired_time (-1 = nunca), environment, guardrail_id, firewall_policy_id e is_firewall_gateway. Combine-os para menor agência — veja Escopo, chaves & políticas. As chaves são mascaradas na exibição.
Essas rotas de gateway (POST /evaluate, POST /evaluate_plan, ANY /mcp) exigem uma chave com is_firewall_gateway=true — um token dedicado com escopo de firewall-gateway, não sua chave de relay sk-orca-…. Cunhar uma e ler seu texto em claro é Admin+.
A configuração roda no console — guardrails, políticas de firewall, servidores MCP e compliance são gerenciados sob seu token de sessão/acesso (UserAuth), e toda escrita é controlada por papel (Developer+ para escritas de política e guardrail). Apenas seu tráfego de relay /v1/* usa uma chave sk-orca-…; apenas os hooks de gateway /api/v1/firewall/* usam o token com escopo de firewall-gateway.

​
5. Compliance, residência & dados

O catálogo inclui SOC 2, HIPAA, GDPR, UK GDPR, o EU AI Act, ISO 27001, ISO 42001, o NIST AI RMF, PCI DSS, CCPA, GLBA, o OWASP Top 10 para Aplicações de LLM (como um mapeamento de controles), mais perfis regionais (PIPL, APPI, PIPA, LGPD, PIPEDA, DPDP, os APPs da Austrália, o PDPA de Singapura, DORA e várias leis estaduais dos EUA). Navegue pelo catálogo, packs e prontidão — todos Member, grátis — em /api/compliance/*.
Navegar é grátis; instalar um pack, gerar um relatório, ir ao ar e definir residência exigem Admin do workspace e um plano pago (controlado no servidor). Instalar um pack (POST /api/compliance/packs/:key/install) materializa guardrails + políticas de firewall reais que você pode então editar.
Sim. Um relatório é assinado por Ed25519 + SHA-256 e publicamente verificável: busque a chave pública (GET /api/public/compliance/pubkey), verifique um relatório (POST /api/public/compliance/verify), ou entregue a um auditor um link de compartilhamento (GET /api/public/compliance/share/:token). Exports são CSV / JSON / PDF.
É a região do artefato de relatório de compliance (us, eu, uk, ap, cn, global), definível via PUT /api/compliance/residency (Admin); uma leitura entre regiões é retida. Não é geo-pinning dos seus dados de inferência. Veja Responsabilidade compartilhada.
A retenção de log de requisições é por padrão 30 dias e limitada no servidor a um máximo rígido de 180 dias. Uma exclusão de conta é mantida por uma janela de carência (padrão 30 dias) antes que uma limpeza irreversível de PII rode; essa limpeza purga em cascata os payloads de log de requisição no Mongo, os matches de guardrail e os eventos de firewall atribuídos a você. Arquivar um workspace purga em cascata as mesmas três coleções para aquele workspace. Veja Exposição de PII.
Um 400 de um controle de segurança não é um bug no seu prompt. É uma política fazendo seu trabalho. Não faça retry — esses códigos são skip-retry. Rastreie a regra, depois decida se corrige a chamada ou relaxa a política: Por que foi bloqueado?.

​
6. Ainda travado?

Códigos de erro

Todo bloqueio, hold e rejeição que o gateway pode retornar.

Por que foi bloqueado?

Leia o código, abra o feed certo, encontre a regra exata.

API de Guardrail

Rotas, papéis e payloads para políticas de conteúdo.

API de Firewall

Rotas de console e gateway para governança de ações.

API de Compliance

Endpoints de catálogo, instalação, relatório e residência.

Glossário

Cada termo usado em toda a documentação de Zero-Trust.
Para as ameaças que esses controles interrompem, comece pelo modelo de ameaças. Para uma linha de base limpa, siga a Linha de base de Agentes Seguros.