Modelo de permissões para agentes de IA: identidade do usuário, permissões de ferramentas, auditoria e isolamento de secrets

Uma equipe entrega o mesmo token de administrador a um agente, pensando: “é tudo sistema interno mesmo”. Aí o usuário A envia uma consulta, e o agente lê o registro de CRM do usuário B usando identidade de administrador. Permissões fora de controle são mais perigosas do que não ter agente.

Isso não é um cenário hipotético. MCP Security Best Practices marca token passthrough como anti-pattern: ele contorna controles de segurança, quebra o audit trail e atravessa trust boundaries. O OWASP AI Agent Security Cheat Sheet também lista abuso de ferramentas e escalada de privilégios entre os riscos centrais.

O problema se resume a três perguntas: quem o agente representa, com que base ele chama, e o que ele pode acessar. Abaixo está o blueprint completo de engenharia: tabela de mapeamento de identidade, lista de campos de permissões de ferramentas, passos centrais do Secret Vault, schema de audit log com regras de mascaramento, tabela de decisão, checklist de diagnóstico e passos de implementação.

Mapeamento de identidade: quem o agente representa?

Quando um agente chama uma ferramenta, logs e sistema de permissões precisam responder primeiro a uma pergunta: quem iniciou a chamada e em nome de quem a operação acontece? Essas duas entidades podem ser iguais ou diferentes. Confundi-las gera perda de controle de permissões e auditoria confusa.

Tabela de tipos de identidade

Tipo	actor	subject	Cenário	Limite de permissão
user identity	Usuário A	Usuário A	Interação direta do usuário	Herda permissões do usuário
service account	system_bot	null	Tarefas de fundo, jobs agendados	Permissão de sistema, independente do usuário
delegated token	workflow_123	Usuário A	Workflow automatizado autorizado pelo usuário	Scope do workflow, limitado pela autorização do usuário
tenant context	agent_456	tenant_B	Sistemas multi-tenant	Isolamento de tenant, sem acesso entre tenants

Definição dos campos: actor é a entidade que inicia a chamada, como usuário, agente, workflow ou sistema. O log registra o ID do actor. subject é a entidade representada, um usuário ou null. Em interação direta, actor=subject. Quando uma conta de sistema executa uma tarefa de fundo, subject=null. delegatedBy indica qual usuário autorizou o workflow. tenantId identifica o tenant e garante isolamento de dados em sistemas multi-tenant.

Segundo a especificação MCP Authorization, MCP servers precisam verificar se o access token foi emitido para eles como intended audience. O campo audience do token deve apontar para o identificador de recurso daquele MCP server. Tokens não devem ser colocados no URI query string, porque URIs podem aparecer em logs, histórico do navegador e caches de proxy.

O OWASP Access Control Cheat Sheet enfatiza deny by default, least privilege e verificação em cada request. O mapeamento de identidade é o primeiro passo dessa verificação: actor, subject e tenantId determinam a decisão de permissão seguinte.

Permissões de ferramentas: o que o agente pode chamar?

Registrar uma ferramenta não é só definir name, description e input_schema. A referência de ferramentas do OpenAI Agents SDK inclui campos para permissão e controle de execução.

Tabela de decisão de permissões de ferramentas

Controle de permissão	Cenário	Implementação	Risco
per-tool permission	Cada ferramenta tem autorização própria	Definir permission_level no registro da ferramenta, como read/write/admin	Configuração mais complexa, com matriz de permissões para manter
scope minimization	Menor privilégio progressivo	Scope inicial só com operações de baixo risco; privilégios altos via scope challenge	Gestão de scopes custa mais e pode exigir ajuste dinâmico
whitelist	Lista permitida de ferramentas	Permitir apenas combinações específicas, como read_customer + summarize	Custo de manutenção e possível perda de flexibilidade
approval	Aprovação humana	Ferramentas needs_approval=true pausam antes de executar e aguardam aprovação	Aprovação adiciona latência e afeta a experiência do usuário

Os campos de ferramentas do OpenAI Agents SDK incluem is_enabled para controle em tempo de execução. A ferramenta pode ser desativada dinamicamente conforme papel do usuário, tenant ou workflow context. needs_approval marca quando é necessária aprovação humana. Mesmo depois da aprovação, tool_input_guardrails ainda roda. tool_input_guardrails valida entradas, como detecção de PII e limites de parâmetros. tool_output_guardrails valida saídas, como filtragem de conteúdo.

MCP Security Best Practices recomenda menor privilégio progressivo em scope minimization: o scope inicial deve conter apenas operações de descoberta ou leitura de baixo risco, como read:metadata e list:resources. Operações de alto privilégio entram por scope challenge preciso. Evite wildcard/full-access scopes.

O OWASP AI Agent Security Cheat Sheet recomenda per-tool permission scoping: use tool sets diferentes para trust levels diferentes, exija autorização explícita para operações sensíveis e aplique fail closed quando a verificação de permissão falhar.

Isolamento de secrets: como o agente acessa credenciais?

Um agente não deve manter API keys longas em texto claro. O OWASP Secrets Management Cheat Sheet recomenda centralizar e padronizar a gestão de secrets. O sistema de secrets também deve suportar Authentication, Authorization, Accounting e lifecycle.

Tabela de padrões de acesso a secrets

Padrão	Risco	Cenário	Exemplo
Posse direta, como .env em texto claro	Alto risco de vazamento, sem rastreamento, sem revogação	Não recomendado	API key hardcoded
Variáveis de ambiente	Risco de vazamento em logs, ainda fraco para rastreamento e revogação	Deploy em uma máquina	process.env.API_KEY
secret vault	Gestão centralizada, armazenamento criptografado, audit trail, revogação	Produção	AWS Secrets Manager, HashiCorp Vault
secret reference	O agente mantém a reference e troca por token curto na execução	Multi-tenant e alta segurança	vault.get(secretRef)

O lifecycle de secret tem quatro etapas: creation gera token curto, não key longa; rotation acontece periodicamente, por exemplo a cada 30 dias, com processo automatizado que atualiza o secret e notifica sistemas relacionados; revocation oferece mecanismo de emergência para desativar um secret assim que um vazamento for detectado; expiration define prazo para que o secret deixe de funcionar automaticamente.

MCP Security Best Practices afirma que token passthrough é anti-pattern: passar o token OAuth do usuário diretamente ao agente contorna controles de segurança, quebra audit trail e atravessa trust boundaries. O desenho correto emite um delegated token quando o usuário autoriza o agente: curto, limitado em scope e com audience explícita.

Os princípios do OWASP Secrets Management são centralize, least privilege, automate e auditing. O acesso a secrets segue menor privilégio. Manutenção manual aumenta risco de vazamento e erro; rotation, revocation e expiration fazem parte do lifecycle.

Audit log: quem chamou o quê e quando?

O audit log deve reconstruir “quem chamou qual ferramenta, em nome de quem, que objeto acessou e qual foi o resultado”, enquanto mascara parâmetros e secrets.

Audit Log Schema

Campo	Descrição	Regra de mascaramento
traceId	ID da cadeia de chamadas, reutilizando o conceito trace/runId da N156	Não mascarar
timestamp	Hora da chamada, ISO 8601	Não mascarar
actor	Entidade que iniciou a chamada	Não mascarar
subject	Entidade representada	Não mascarar
tool	Nome da ferramenta	Não mascarar
action	Tipo de operação, como read/write/delete	Não mascarar
resource	Objeto alvo	Mascarar: customer_id → cust_***
outcome	Resultado, como success/failure/denied	Não mascarar

Regras de mascaramento: não registrar token, secret, password, email, phone nem PII. Registre who/what/when/where/outcome. Exemplos: customer_id=12345 vira cust_; email=user@example.com vira e@***.com; token=Bearer xxx vira Bearer ***; password=secret123 não é registrado.

Segundo o OWASP Logging Cheat Sheet, logs de segurança devem apoiar investigação, auditoria e monitoramento, mas não devem registrar passwords, session ids, access tokens ou dados pessoais sensíveis. Eles devem registrar informações rastreáveis como who/what/when/where/outcome.

A família audit and accountability do NIST SP 800-53 reforça: audit logs são a última linha de defesa de um sistema de permissões. Quando uma verificação falha, o log precisa registrar o motivo: actor sem permissão, subject sem permissão sobre o target, ou scope insuficiente.

Tabela de decisão do modelo de permissões: escolha a combinação de controles

Mapeamento de identidade, permissões de ferramentas, isolamento de Secret e audit logs não são controles isolados. Eles funcionam como restrições combinadas. A tabela abaixo mostra combinações para diferentes cenários.

Cenário	identity type	tool permission	secret access	audit log	Aplicação típica
Ferramenta interna de baixo risco	service account	whitelist, apenas ferramentas read	Variáveis de ambiente	actor/tool/outcome	Geração de relatórios internos, sincronização agendada
SaaS multi-tenant	delegated token + tenantId	per-tool permission filtrada por tenant	secret vault com isolamento por tenant	full schema com tenantId	Agente de CRM, assistente de e-mail
Transação financeira	user identity + approval	scope minimization + approval	secret reference com token curto	full schema + approvalId	Aprovação de transação, movimentação de fundos
Operação com dados sensíveis	delegated token + approval	whitelist + approval + guardrails	secret vault com revogação de emergência	full schema + mascaramento	Exportação de dados, consulta de clientes

O OWASP AI Agent Security Cheat Sheet recomenda separate tool sets para trust levels diferentes e explicit authorization para operações sensíveis. O ponto central da tabela é a composição: cenários de alto risco precisam de várias camadas de controle, não de um único controle tentando resolver tudo.

Checklist de diagnóstico: sintomas comuns de problemas de permissão

Veja sintomas comuns, causas prováveis, verificações e soluções.

Sintoma	Causa provável	O que verificar	Solução
O agente recebe 403 Forbidden ao chamar uma ferramenta	actor sem tool permission ou subject sem target permission	Verificar permission_level do actor e permissão de resource do subject	Confirmar o mapeamento de identidade e ajustar a matriz de permissões
Logs mostram actor vazio ou subject confuso	Campos de mapeamento de identidade não foram passados corretamente	Verificar se agent context contém actor/subject/tenantId	Passar campos de identidade por toda a cadeia de chamadas
A chamada da ferramenta funciona, mas o audit log não tem campos necessários	Audit Log Schema incompleto	Verificar se a lógica de escrita de log contém todos os campos	Completar o schema e adicionar traceId/approvalId
A solicitação do usuário A consegue ler dados do usuário B	tenantId ou subject não está isolado, ou token de administrador é compartilhado	Verificar se delegated tokens são usados e se tenantId está correto	Usar delegated token e forçar validação de tenantId
Depois de secret rotation, o agente ainda usa a key antiga	Secret reference não foi atualizada, ou rotation não entrou em vigor	Verificar se o vault retorna o novo secret e se o agente busca novamente	Fazer rotation atualizar a reference automaticamente
Depois da aprovação, a chamada da ferramenta ainda falha	Guardrails falharam, como parâmetros fora do limite ou detecção de PII	Verificar logs de tool_input_guardrails	Ajustar parâmetros ou regras de guardrails

Checklist de implementação: construir um modelo de permissões Agent do zero

Estes são os 5 passos principais para implementar o modelo de permissões.

Passo 1: definir regras de mapeamento de identidade

Pontos de decisão: é necessário isolamento multi-tenant, ou seja, adicionar tenantId? Existem tarefas de fundo, ou seja, definir service account? Existem workflows automatizados, ou seja, usar delegated tokens?

Pseudocódigo:

interface IdentityContext {
  actor: string;        // Entidade que inicia a chamada
  subject: string | null;  // Entidade representada
  delegatedBy?: string;  // Origem da delegação
  tenantId?: string;    // Identificador do tenant
}

Passo 2: desenhar a matriz de permissões de ferramentas

Pontos de decisão: precisa de aprovação, ou seja, needs_approval=true? Precisa de filtro dinâmico, ou seja, implementar is_enabled em tempo de execução? Precisa de validação de parâmetros, ou seja, implementar tool_input_guardrails?

Exemplo de código:

interface ToolPermission {
  name: string;
  permission_level: 'read' | 'write' | 'admin';
  required_scope: string[];
  needs_approval: boolean;
  is_enabled: (context: IdentityContext) => boolean;
}

Passo 3: conectar secret vault

Pontos de decisão: precisa de credenciais curtas, ou seja, usar secret reference? Precisa de revogação de emergência, ou seja, garantir que o vault suporte desativação imediata?

Exemplo de código:

async function getSecret(secretRef: string, context: IdentityContext): Promise<string> {
  // Validar identidade
  await vault.authenticate(context.actor);
  // Validar permissão
  await vault.authorize(context.actor, secretRef);
  // Obter token curto
  const token = await vault.getToken(secretRef, expiresIn: '15m');
  // Registrar auditoria
  await auditLog.record({
    actor: context.actor,
    action: 'get_secret',
    resource: secretRef,
    outcome: 'success'
  });
  return token;
}

Passo 4: implementar audit logs

Pontos de decisão: precisa de mascaramento, ou seja, implementar regras de redaction? Precisa de traceId, ou seja, reutilizar trace/runId da N156?

Exemplo de código:

interface AuditLogEntry {
  traceId: string;
  timestamp: Date;
  actor: string;
  subject: string | null;
  tool: string;
  action: 'read' | 'write' | 'delete';
  resource: string;  // Mascarado
  outcome: 'success' | 'failure' | 'denied';
}

Passo 5: testar limites de permissão

Pontos de decisão: você vai testar acesso indevido, como usuário A acessando dados do usuário B? Vai testar vazamento de token, simulando revogação após vazamento de secret? Vai testar rastreamento de auditoria, voltando toda a cadeia pelo traceId?

Checklist de testes: teste de acesso indevido (actor=user_A, resource=tenant_B → deve retornar 403); teste de vazamento de token (vault.revoke(secretRef) → o agente não deve conseguir obter um novo token); teste de rastreamento Audit (consultar a cadeia completa pelo traceId → deve conter actor/subject/tool/outcome).

Próximo passo: leituras relacionadas

O modelo de permissões de um Agent envolve identidade, ferramentas, Secrets e auditoria em várias camadas. Estas leituras ajudam a completar o mapa.

Artigos publicados:

• Guia de Agent Sandbox: Sandbox resolve isolamento de execução com contêineres/Docker. Este artigo trata limites de permissões e secrets; os dois se complementam.
• Tool Calling na prática: Bases de tool calling. Este artigo expande com tool whitelist, per-tool permission e validação de entrada.
• Monitoramento e recuperação de AI Agents: Bases de monitoramento e alertas. Este artigo adiciona campos de audit e traceId.