Lista de Verificação de Escopo de Ferramentas de Mínimo Privilégio para Agentes Claude de Produção
Cada ferramenta que você fornece a um agente Claude é uma capacidade que um invasor pode tentar acionar por meio de injeção de prompt. Esta lista de verificação detalha o escopo de cada ferramenta para o mínimo necessário, antes que o agente vá para produção.
Trabalhe nela uma vez por ferramenta, não uma vez por agente; um único agente com cinco ferramentas precisa que isso seja aplicado cinco vezes.
Trate os itens da Camada 1 como bloqueadores; não implante uma ferramenta que falhe em um deles.
Releia esta lista de verificação sempre que o input_schema, a descrição ou as permissões de backup de uma ferramenta mudarem, não apenas no lançamento inicial.
Mantenha um registro da resposta para cada item por ferramenta; este registro é o que uma revisão de segurança ou auditoria SOC2 pedirá para ver.
Nomeie a capacidade exata que a ferramenta concede: Escreva uma frase descrevendo o que a ferramenta pode fazer no mundo real, não para que ela serve. "Envia um e-mail para qualquer endereço" é a descrição honesta de uma ferramenta genérica send_email, mesmo que seu propósito pretendido seja redefinição de senha.
Pergunte se uma ferramenta mais restrita funcionaria: Uma ferramenta send_password_reset_email que aceita apenas um user_id e procura o endereço internamente é mais segura do que uma ferramenta geral send_email, porque o modelo nunca tem um parâmetro de endereço para manipular.
Identifique quais dados a ferramenta pode ler: Liste cada campo, tabela ou documento que a execução da ferramenta toca, incluindo qualquer coisa que ela leia internamente para atender a uma chamada, não apenas o que está em seu input_schema.
Identifique quais dados a ferramenta pode escrever ou alterar: Liste separadamente cada gravação, atualização, exclusão ou efeito colateral externo; esta é geralmente a metade de maior risco da superfície da ferramenta.
Decida se a ferramenta precisa de acesso de gravação: Uma grande parte das ferramentas de "ação" pode ser redesenhada como leitura mais confirmação humana, onde Claude propõe uma ação e um humano ou uma etapa de confirmação separada a executa.
Escreva um input_schema restrito: Restrinja tipos, use enums em vez de strings de texto livre sempre que os valores válidos forem um conjunto finito e conhecido, e marque todos os campos que devem estar presentes como required.
Evite parâmetros de string abertos para qualquer coisa que mapeie para uma ação real: Um campo query: string em uma ferramenta de banco de dados é muito mais perigoso do que um conjunto de parâmetros de consulta específicos e enumerados.
Escreva a descrição da ferramenta de forma defensiva: Declare explicitamente para que a ferramenta não deve ser usada, além do que ela serve, pois a própria descrição molda quando o modelo recorre à ferramenta.
Limite o raio de explosão de uma única chamada: Para ferramentas que operam em vários registros, adicione um limite explícito (max_records, paginação) para que uma chamada não possa tocar em um conjunto de dados inteiro.
Escopo de credenciais por ferramenta, não por aplicativo: Dê a cada ferramenta sua própria chave de API com escopo, função de banco de dados ou conta de serviço limitada exatamente ao que essa ferramenta precisa, nunca compartilhe uma credencial ampla entre todas as ferramentas do agente.
Valide cada argumento antes de executar, independentemente do que o modelo afirma: Trate os argumentos que Claude passa como entrada não confiável, da mesma forma que trataria um valor de um corpo de solicitação HTTP.
Liste destinos permitidos para qualquer ferramenta que envia dados externamente: Um e-mail, webhook ou ferramenta de chamada de API deve verificar o endereço ou URL de destino em uma lista de permissões antes de enviar, não confiar no que o modelo forneceu.
Aplique limites de taxa por ferramenta, por sessão: Limite quantas vezes uma determinada ferramenta pode ser chamada dentro de uma conversa ou janela de tempo, para limitar o dano de um agente sequestrado fazendo chamadas repetidas.
Registre cada chamada de ferramenta com seus argumentos e resultado: Mantenha uma trilha de auditoria (com PII redigido de acordo com sua política de log) que permita reconstruir exatamente o que uma ferramenta fez e por quê, depois do fato.
Falhe fechando em erros de validação: Se a entrada de uma ferramenta falhar na validação, retorne um erro no qual o modelo possa agir, não coaja silenciosamente a entrada malformada em algo que "parece próximo o suficiente" para executar.
Execute uma passagem de teste adversarial: Tente fazer com que o agente use indevidamente cada ferramenta por meio de um documento recuperado ou mensagem de usuário criada, e confirme se o escopo e a validação se mantêm.
Confirme que nenhuma ferramenta tem acesso permanente além de seu propósito declarado: Rederive o escopo da credencial para cada ferramenta a partir de seu input_schema e descrição, e sinalize qualquer incompatibilidade onde o acesso subjacente for mais amplo do que a ferramenta precisa.
Mapeie o acesso da ferramenta contra o modelo de ameaça combinado: Para cada ferramenta com capacidade de gravação ou comunicação externa, confirme qual conteúdo não confiável (se houver) pode alimentar uma chamada para essa ferramenta; este é o fator de risco multiplicador do modelo de ameaça.
Obtenha aprovação de alguém que não escreveu a ferramenta: Um segundo revisor detecta o acúmulo de escopo que o autor original parou de notar.
Documente um caminho de revogação: Saiba, com antecedência, como desabilitar ou restringir uma ferramenta específica rapidamente se for descoberto que ela foi mal utilizada em produção, sem derrubar o agente inteiro.
Camadas 1-2 (itens 1-10) ocorrem no tempo de design, antes que qualquer código seja escrito, e são as mais baratas para acertar cedo; refazer o escopo de uma ferramenta após o lançamento significa migrar chamadores e credenciais.
Camada 3 (itens 11-15) é aplicada em código, no ponto em que a ferramenta realmente executa, e deve ser coberta por testes automatizados, não apenas revisão manual.
Camada 4 (itens 16-20) é um portão antes da implantação, não uma etapa única; repita-a sempre que a definição de uma ferramenta ou suas permissões de backup mudarem.
Tratar o input_schema como todo o limite de segurança. Um esquema restrito ajuda, mas se a credencial de backup ou a função de banco de dados for ampla, um bug de validação ou caso de borda ainda pode atingir dados que a ferramenta nunca deveria ter tocado. Correção: escopo a própria credencial, não confie apenas na validação do esquema.
Compartilhar uma chave de API ou conta de serviço entre todas as ferramentas em um agente. Isso colapsa o raio de explosão de todo o conjunto de ferramentas para o que essa única credencial pode fazer, derrotando o propósito do escopo por ferramenta. Correção: emita uma credencial separada e minimamente escopada por ferramenta ou por categoria de ferramenta.
Escrever uma descrição de ferramenta que apenas explica o caminho feliz. Uma descrição que diz "envia uma notificação" sem declarar "apenas para endereços na lista de permissões interna" não dá ao modelo, nem a qualquer instrução injetada, nenhum sinal sobre o limite pretendido. Correção: declare restrições explicitamente na descrição, não apenas no código.
Preciso executar toda esta lista de verificação para uma ferramenta puramente somente leitura?
Sim, mas as apostas são diferentes. Ferramentas somente leitura ainda precisam de escopo nas Camadas 1-2 (quais dados ela pode ler, o esquema é restrito) e validação na Camada 3, pois uma ferramenta de leitura com acesso a dados confidenciais ainda pode ser um caminho de exfiltração se sua saída atingir um canal não confiável.
Por que o item 10 insiste em uma credencial separada por ferramenta em vez de uma credencial compartilhada para todo o agente?
Uma credencial compartilhada significa que cada ferramenta herda as permissões combinadas de todas elas, portanto, uma lacuna de validação em qualquer ferramenta única expõe tudo o que a credencial compartilhada pode acessar. Credenciais por ferramenta mantêm o raio de explosão real de cada ferramenta igual ao seu escopo declarado.
Qual é a maneira mais rápida de transformar uma ferramenta ampla em uma restrita?
Substitua parâmetros abertos (uma consulta de texto livre, um endereço de destino arbitrário) por valores enumerados ou resolvidos internamente. Uma ferramenta send_notification(user_id, template) que procura o endereço internamente é mais restrita do que send_notification(to_address, message).
A lógica de validação deve residir na função Python da ferramenta ou em outro lugar?
Deve residir na mesma função que executa o efeito colateral da ferramenta, como a primeira coisa que essa função faz, para que não haja caminho de código onde um argumento não validado possa atingir a ação real. Centralizá-la lá também facilita o teste unitário independentemente de uma chamada de API ativa.
Como esta lista de verificação difere das práticas gerais de validação de entrada?
A validação geral de entrada assume que um humano ou um cliente confiável é a fonte da entrada. Aqui, o "cliente" que chama a ferramenta é um modelo cujos argumentos podem ser influenciados pelo conteúdo que ele leu (incluindo instruções injetadas), portanto, a validação deve assumir que a entrada é adversarial por padrão, não apenas malformada por acidente.
O que significa "falhar fechando" no item 15, concretamente?
def send_notification(user_id: str, template: str) -> dict: if template not in ALLOWED_TEMPLATES: raise ValueError(f"Unknown template: {template!r}") # nunca substitua silenciosamente um modelo padrão aqui return
Um limite de taxa por ferramenta é realmente necessário se a própria ferramenta tiver um escopo restrito?
Sim. Escopo restrito limita o que uma única chamada pode fazer, um limite de taxa limita quantas vezes ela pode ser repetida. Uma ferramenta que só pode enviar um tipo de notificação de baixo risco ainda é um problema se puder ser acionada mil vezes em uma sessão.
Quem deve ser o "segundo revisor" no item 19?
Qualquer pessoa com contexto suficiente para avaliar a capacidade real da ferramenta, não apenas seu propósito pretendido, e que não escreveu o código, pois o modelo mental do autor original de "para que serve esta ferramenta" facilita ignorar o que ela é realmente capaz de fazer.
Como esta lista de verificação se relaciona com o risco combinado descrito no modelo de ameaça de segurança e RAG?
O escopo da ferramenta é um dos três fatores multiplicadores nesse modelo de ameaça (conteúdo não confiável, acesso à ferramenta, escopo de permissão). Esta lista de verificação visa diretamente os dois últimos, reduzindo o que uma ferramenta pode fazer e quão amplamente ela tem permissão para fazê-lo, independentemente de quaisquer defesas existentes contra o fator de conteúdo não confiável.
O que é um caminho de revogação e por que o item 20 o solicita com antecedência?
Um caminho de revogação é uma maneira rápida e testada de desabilitar ou restringir uma ferramenta específica (flag de recurso, rotação de credenciais, alternância de configuração) sem reimplantar o agente inteiro. Tê-lo pronto antes de um incidente, em vez de improvisar durante um, é o que faz a diferença entre um problema contido e uma interrupção prolongada.
Esta lista de verificação deve ser aplicada a agentes internos voltados para desenvolvedores também, ou apenas aos voltados para o cliente?
Agentes internos ainda combinam conteúdo não confiável (documentos internos, tickets, código, entrada de outros funcionários) com acesso a ferramentas, portanto, os mesmos fatores de risco se aplicam. Somente interno reduz quem poderia ser um invasor, não elimina a necessidade de escopo.
Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.
dispatch(user_id, template)
Rejeitar com um erro claro, em vez de silenciosamente usar um comportamento de fallback, mantém a falha visível em vez de executar silenciosamente algo não intencional.