Ferramentas HTTP genéricas apagam os limites de permissão

Uma chamada HTTP genérica parece uma única ferramenta para o host de um agente. Na prática, ela pode conter milhares de capacidades. Basta mudar a URL, a credencial, o método, os cabeçalhos ou o corpo para que a mesma função leia uma página de status, exporte registros de clientes, altere um segredo de assinatura ou exclua um recurso de produção.

Essa diferença torna a permissão no nível da ferramenta um limite de segurança fraco. Aprovar o uso de http_request por um agente não diz o que ele pode fazer. A decisão útil fica uma camada abaixo, onde o sistema pode vincular uma credencial específica a um destino resolvido, um método permitido e detalhes restritos da requisição.

A distinção importa mesmo quando o agente se comporta bem. Prompts contêm erros, textos recuperados podem trazer instruções hostis e uma ferramenta ampla pode transformar um pequeno erro de planejamento em uma ação real de API. Dar à ferramenta um nome mais simpático não resolve isso. É preciso autorizar a ação que atravessará a rede.

Uma ferramenta de chamada contém muitas capacidades

Uma ferramenta só é um limite de capacidade quando suas entradas não conseguem mudar radicalmente sua autoridade. Uma consulta de clima com provedor, método GET e formato de resposta fixos se aproxima de uma capacidade única. Uma função que aceita qualquer URL, verbo, cabeçalho e corpo é um cliente de rede programável.

Considere um esquema com cinco campos comuns: url, method, headers, body e credential_name. O host pode apresentá-lo como um único item na lista de ferramentas. Ainda assim, GET /projects/42 com um token de leitura e DELETE /projects/42 com um token de administrador não merecem a mesma decisão. Uma requisição para uma API pública e outra que resolve para um serviço na rede privada também não.

As anotações de ferramentas do Model Context Protocol não corrigem esse colapso. A especificação de ferramentas MCP descreve anotações de somente leitura e comportamento destrutivo como indicações e orienta clientes a não confiar nelas quando não vierem de servidores confiáveis. Um chamador genérico também não pode dar um valor sempre verdadeiro a readOnlyHint, pois seu comportamento depende de argumentos que ainda não chegaram.

Esta é a distinção que as equipes costumam confundir: selecionar uma ferramenta responde qual implementação será executada, enquanto autorizar uma ação responde qual efeito externo pode ocorrer. Se o host aprova apenas o nome da implementação, toda requisição materialmente diferente herda essa aprovação. Um seletor organizado pode, portanto, esconder um canal de saída quase irrestrito.

Dividir cada operação de API em uma ferramenta separada pode melhorar descrições e planejamento, mas não é uma resposta completa de segurança. As ferramentas geradas ainda precisam de um ponto de aplicação, as credenciais mantêm sua própria autoridade e redirecionamentos podem levar uma operação aparentemente estreita para outro lugar. Use ferramentas específicas para facilitar o uso. Aplique permissões à requisição final.

A permissão precisa de quatro coordenadas

Uma decisão HTTP defensável tem quatro coordenadas: a credencial, o destino resolvido, o método e os detalhes da requisição. Remova uma delas e a requisição pode manter a aparência aprovada enquanto muda seu efeito.

A credencial identifica a autoridade exercida. Um token de implantação e outro de cobrança podem apontar para o mesmo host e caminho, mas expor poderes sem relação. O destino identifica onde essa autoridade pode ser apresentada. O método expressa a intenção HTTP geral. Os demais detalhes, como caminho, consulta, cabeçalhos selecionados, tipo de conteúdo e campos do corpo, determinam a operação real.

Um registro compacto de autorização pode ser assim:

credential: issue-tracker-read
origin: https://api.example.test:443
path_prefix: /v2/issues/
methods:
  - GET
redirects: deny
headers:
  allow:
    - Accept
query:
  deny:
    - include_deleted
body: forbidden

Esse trecho evita várias falhas de uma vez. O agente não pode trocar por uma credencial mais poderosa, enviá-la a outra origem, transformar a leitura em POST, seguir um redirecionamento, acrescentar um cabeçalho parecido com autorização, pedir registros excluídos por esse parâmetro nem inserir um corpo em uma operação esperada como somente leitura.

O objeto de política não é um modelo universal. Algumas APIs exigem caminhos exatos, outras precisam de um identificador de locatário no caminho e outras colocam uma ação no corpo de um POST. O formato da decisão é o ponto: avaliar as quatro coordenadas em conjunto após análise e normalização, e só então injetar a credencial se a requisição passar.

Não deixe o agente fornecer o segredo real por headers. Faça com que ele indique uma credencial por um nome opaco e deixe um executor confiável adicionar o token bearer, as credenciais basic ou o cabeçalho personalizado após a autorização. Caso contrário, o agente pode copiar um segredo para outro campo, log ou segundo destino, tornando a regra de destino mera aparência.

As credenciais definem a autoridade

Credenciais devem ser concessões separadas com a menor autoridade permitida pela API de destino. Uma ferramenta HTTP genérica fica muito menos perigosa quando o executor escolhe entre credenciais nomeadas e limitadas, em vez de manter um token para toda a organização.

Escopos OAuth ajudam, mas escopo e público respondem perguntas diferentes. Um escopo pode dizer que o token lê contatos. O público diz qual servidor de recursos deve aceitá-lo. A RFC 8707 define o parâmetro OAuth resource para um cliente pedir um token destinado a um recurso protegido específico e recomenda que os servidores de autorização restrinjam o público do token emitido. O argumento de segurança é prático: um token apresentado a um recurso não deve funcionar em outro.

A especificação atual de autorização MCP aplica a mesma separação. Ela exige que servidores MCP aceitem apenas tokens destinados a eles e proíbe repassar o token MCP recebido para uma API posterior. Quando um servidor MCP chama outra API, ele atua como outro cliente OAuth e usa um token separado. É um limite claro que um executor HTTP genérico deve preservar, mesmo quando o agente não vê nenhum fluxo OAuth.

Chaves de API costumam oferecer controles nativos mais fracos. Mesmo assim, trate cada uma como uma autoridade distinta. Registre quais origens podem recebê-la, qual formato de cabeçalho o executor injetará, quando ela vence e quem responde pela rotação. Não considere uma entrada chamada staging inofensiva só pelo nome. Confira seus privilégios reais no serviço.

A escolha da credencial também deve aparecer na tela de aprovação. Um aviso que mostra apenas POST api.example.test não revela se a chamada usa uma chave de testes ou um token do dono da conta. Mostre um rótulo legível e a conta ou locatário pretendido, mas nunca o segredo. Se o executor não identifica esse contexto, a concessão é ambígua demais para reutilização silenciosa.

Manter segredos fora do modelo reduz a divulgação acidental, mas o segredo por si só não limita o uso. Um agente pode usar mal um segredo sem ver seus bytes se um executor amplo estiver disposto a anexá-lo a qualquer requisição. Não divulgar e limitar a autoridade resolvem problemas diferentes. Ambos são necessários.

O destino é o endpoint resolvido

Verificar uma string de URL uma vez não controla o destino. O executor deve analisar e normalizar a URL, resolver o host, aplicar regras de rede e repetir a decisão em cada redirecionamento antes de anexar uma credencial.

Comece com esquema, host e porta efetiva exatos. https://api.example.test e https://api.example.test:8443 são origens diferentes. Recuse informações de usuário na URL, codificações ambíguas, esquemas não suportados e hosts que apenas parecem ter um sufixo aprovado. Uma verificação que aceita api.example.test.attacker.invalid não é uma lista de permissões.

Depois resolva o DNS e examine todos os endereços retornados. Um nome que parece público pode resolver para loopback, link-local, faixa privada ou metadados de uma instância em nuvem. A resolução também pode mudar entre validação e conexão. O componente que valida deve controlar a conexão e confirmar o endereço realmente usado, em vez de entregar a URL a outro cliente que a resolva novamente.

A Server Side Request Forgery Prevention Cheat Sheet da OWASP recomenda listas de destinos confiáveis quando a aplicação consegue identificá-los. Ela também orienta desativar o seguimento automático de redirecionamentos, pois um redirecionamento pode contornar a validação de entrada. O conselho é especialmente adequado a ferramentas de agentes: o modelo costuma fornecer a URL e a requisição pode carregar uma credencial que só deveria chegar ao primeiro destino.

Redirecionamentos exigem uma nova decisão de autorização. A RFC 9110 pede cuidado com redirecionamentos automáticos de métodos não seguros e recomenda remover campos específicos do recurso, como Authorization e Cookie. Um executor seguro pode simplificar: negar redirecionamentos autenticados por padrão ou apresentar o novo destino como outra ação e reinjetar a credencial só depois que ele passar pela política.

O controle de caminho continua importante dentro de uma origem aprovada. Gateways multilocatários, hosts SaaS compartilhados e rotas administrativas podem existir atrás do mesmo nome. A RFC 8707 observa que um caminho que identifica o locatário pode precisar fazer parte do identificador de recurso em sistemas multilocatários. Uma lista de origens sem restrição de caminho ou locatário pode ser muito mais ampla do que o revisor imagina.

Métodos HTTP são sinais, não veredictos

Restringir métodos elimina muitos erros, mas o nome do método não prova que uma requisição é inofensiva. A RFC 9110 define GET, HEAD, OPTIONS e TRACE como seguros porque sua semântica especificada é essencialmente de leitura. Ela define PUT, DELETE e os métodos seguros como idempotentes, ou seja, repetir a operação tem o mesmo efeito pretendido que executá-la uma vez.

Seguro e idempotente não são sinônimos. DELETE pode ser idempotente e ainda destruir um recurso. POST geralmente não é seguro nem idempotente, mas uma API pode usá-lo para uma busca somente de leitura porque a consulta é grande demais para a URL. Um sistema que reduz risco a GET contra POST classifica mal os dois casos.

Pior, APIs reais às vezes violam a semântica dos métodos. A RFC 9110 alerta para recursos que colocam ações como exclusão em uma consulta GET e diz que o proprietário deve impedir o comportamento inseguro por métodos seguros. O executor não pode presumir que todo serviço cumpre a regra. Se GET /jobs?id=7&action=cancel muda o estado, permitir todos os GET não cria uma concessão de somente leitura.

Use o método como uma entrada. Combine-o com um caminho e, quando necessário, com restrições próprias da operação. Para uma API bem descrita, uma operação OpenAPI oferece um mapa útil: a Especificação OpenAPI permite declarar requisitos de segurança por operação, e entradas OAuth listam escopos exigidos. Importe isso como configuração e depois confira com o que o serviço realmente emite e aceita. Um arquivo de descrição não aplica controles sozinho.

O comportamento de nova tentativa também pertence à decisão. Um timeout depois de um POST não diz se o servidor aplicou a ação. Não repita automaticamente uma requisição insegura e não idempotente, a menos que a API forneça um mecanismo de idempotência ou o cliente saiba que a primeira não foi aplicada. A idempotência pode tornar a repetição operacionalmente mais segura, mas não autoriza a ação original.

Os detalhes da requisição decidem o efeito

Duas requisições com a mesma credencial, origem, caminho e método ainda podem gerar efeitos opostos. O corpo, a consulta e certos cabeçalhos costumam conter a operação que realmente importa.

Um endpoint de cobrança pode aceitar POST /v1/subscriptions/update tanto para reduzir assentos quanto para mover uma conta a um plano caro. Um endpoint de repositório pode usar uma única rota de mutação com um campo operation para arquivar, transferir ou excluir. Uma busca pode expor registros ocultos ou excluídos quando recebe include_deleted=true. Autorizar a rota sem restringir esses campos autoriza todos os modos que ela implementa.

Cabeçalhos merecem a mesma desconfiança. O executor deve controlar Authorization, Proxy-Authorization, Host e todo cabeçalho personalizado de credencial. Normalmente deve impedir que o agente os defina. Cabeçalhos que selecionam uma conta, personificam um usuário, substituem o método, pedem execução assíncrona ou levam condições de escrita podem mudar autoridade ou efeito. Repassar cabeçalhos arbitrários é esconder outra ferramenta genérica dentro da primeira.

O tipo de conteúdo controla a análise. Se a política inspeciona JSON, mas o cliente envia formulário, multipart ou bytes compactados, o agente pode tirar o campo sensível do analisador. Exija o tipo declarado, defina limites antes de armazenar em memória, recuse campos duplicados ou ambíguos e autorize a mesma representação de bytes que o executor enviará. Validar um objeto e depois serializar outro abre lacunas.

O tratamento da resposta também faz parte do limite, embora não seja uma coordenada de permissão para o efeito de saída. Limite o tamanho, classifique os tipos e trate instruções retornadas como dados não confiáveis. Um GET permitido pode buscar uma página com injeção de prompt, segredos ou uma carga enorme. Autorizar a saída não torna a resposta segura para devolver ao agente.

Esquemas exatos de corpo custam caro para manter, então concentre o esforço nas rotas mais poderosas. Para leituras de baixo risco, proibir o corpo e limitar nomes de consulta pode bastar. Para mudanças de conta, implantações, rotação de segredos, movimentação de dinheiro ou exclusões, valide campos de objeto, locatário, valor, ambiente e transição solicitada. Se a API oferece um endpoint ou uma credencial mais estreita, prefira isso a uma regra local complexa.

A aprovação deve descrever a ação resolvida

Uma boa aprovação mostra o que o executor confiável enviará depois da normalização, não a chamada proposta pelo modelo. O revisor precisa do rótulo da credencial, conta ou locatário, destino resolvido, método, caminho, campos relevantes e comportamento de redirecionamento.

Isso não significa despejar JSON bruto em uma caixa. O payload completo esconde o campo perigoso entre timestamps e valores padrão. Mostre primeiro um resumo e depois permita inspecionar a requisição canônica. Uma aprovação de implantação pode dizer que a credencial production-deployer criará a versão 2026.07.24 no locatário de produção, seguida do host exato, caminho POST e diferenças do corpo.

Vincule a aprovação a um resumo da ação canônica. Se host, método, caminho, cabeçalhos protegidos ou corpo mudarem depois do clique, calcule outro resumo e exija uma nova decisão. Isso fecha uma lacuna comum entre verificação e uso, quando a interface aprova um objeto e um middleware depois segue um redirecionamento, acrescenta padrões ou muda o corpo.

Escolha conscientemente o limite de reutilização. Aprovar uma sessão pode ser razoável para leituras repetidas com credencial e destino estreitos. Uma credencial capaz de excluir recursos deve exigir aprovação por chamada ou uma operação pré-autorizada muito mais limitada. Não substitua redução de escopo por avisos repetidos. Pessoas deixam de ler caixas barulhentas, principalmente quando todas parecem iguais.

A aprovação deve negar por padrão quando faltar contexto necessário. Um host não resolvido, tipo de conteúdo desconhecido, substituição de método não reconhecida ou corpo que a política não consegue analisar não são requisições de baixo risco. São ações que o sistema não consegue descrever com precisão.

Um plano inofensivo pode virar uma chamada perigosa

A falha costuma começar com uma tarefa comum e uma requisição que muda de sentido ao atravessar camadas. Suponha que um agente precise ler uma ocorrência e publicar uma breve nota de status. O host aprova o chamador genérico para a sessão porque as duas operações usam o mesmo serviço de projetos.

A credencial de leitura falha no POST, então o planejador escolhe outra entrada cujo texto menciona automação de projetos. Esse token também administra webhooks. Um comentário recuperado manda o agente notificar um callback externo, e o planejador apresenta a URL como destino do status. A ferramenta continua aprovada para a sessão, o nome da credencial parece relacionado e o método continua POST. A permissão da ferramenta não vê nenhuma fronteira sendo cruzada.

O callback inicial responde com redirecionamento 307 para um endereço privado. Uma biblioteca HTTP conveniente preserva o corpo POST nesse status. Ela pode remover um cabeçalho Authorization gerado automaticamente, mas um cabeçalho de credencial personalizado colocado pelo código pode sobreviver se o cliente não o tratar. A requisição agora leva autoridade do projeto e conteúdo da ocorrência a um destino que ninguém revisou. Mesmo que o serviço privado rejeite a credencial, o corpo pode revelar dados ou disparar uma ação sem autenticação.

Quatro verificações coordenadas interrompem a sequência em pontos diferentes. A credencial de leitura não autoriza POST. A credencial de automação não alcança um host de callback não cadastrado. O redirecionamento exige outra decisão de destino. As regras recusam um callback arbitrário no corpo. Nenhuma verificação sustenta toda a defesa e os nomes amigáveis não sustentam parte alguma.

Por isso sou contra aprovar um chamador genérico uma vez por sessão. O padrão é popular porque avisos repetidos interrompem o trabalho e um nome estável parece descrever risco estável. Não descreve. Limite a concessão da sessão a uma credencial e destino com operações restritas, e pergunte de novo quando qualquer coordenada mudar.

A mesma sequência pode falhar sem comentário malicioso. Um agente pode inferir um endpoint de documentação antiga, copiar uma URL de um erro ou escolher uma credencial de nome parecido depois que a esperada retorna 403. São comportamentos normais de recuperação. O projeto de segurança deve esperá-los e manter a tentativa dentro da concessão original.

A canonicalização deve ocorrer antes da comparação. Decodifique segmentos percentuais segundo uma regra documentada, recuse segmentos de ponto que escapem do prefixo, normalize a porta efetiva e decida como a API trata nomes de consulta repetidos. Se a política vê /v2/issues/%2e%2e/admin como caminho de ocorrências e o servidor resolve como /v2/admin, eles autorizam recursos diferentes. Recuse formas ambíguas em vez de adivinhar cada intermediário.

Injete a credencial depois desse trabalho e tão perto da transmissão quanto possível. Construa a requisição canônica, autorize, vincule o resumo, abra a conexão aprovada e só então adicione o segredo no executor. Se um middleware puder reescrever host, método ou corpo após a injeção, inclua sua saída na autorização ou retire essa liberdade.

Falhas também precisam de um caminho fechado. Se a credencial escolhida recebe 401 ou 403, devolva o resultado ao agente sem tentar automaticamente cada entrada. O fallback transforma uma falha estreita em descoberta de privilégios. A próxima tentativa deve nomear outra credencial e passar por nova decisão com sua autoridade e conta.

Trate mensagens de erro do serviço como dados. APIs costumam repetir URLs, nomes de operação ou ações sugeridas. É razoável o planejador usar esse texto para formar a próxima chamada, mas ele não ganha autoridade por vir de um host aprovado. A nova requisição enfrenta as mesmas verificações de destino e detalhes.

Teste o comportamento como sequência, não só como requisições isoladas. Comece com uma leitura permitida, devolva um redirecionamento preparado ou uma sugestão de erro, deixe o planejador criar a continuação e confirme que reutilizar a sessão não amplia a permissão. Depois faça a credencial esperada falhar e verifique que o executor não tenta outra em silêncio. Esses testes pegam herança de permissões que um teste unitário de uma única regra perde.

Logs devem registrar a decisão e a chamada

Logs de invocação de ferramentas são amplos demais para investigar incidentes. Registrar que um agente chamou http_request deixa sem resposta as perguntas centrais: qual credencial foi usada, para onde a requisição foi, qual operação foi permitida e se o envio correspondeu ao aprovado.

Registre identidade da sessão ou processo, identificador da chamada, identificador da credencial, destino canônico, endereço resolvido, método, resumo editado, versão da política, identidade de quem aprovou, resumo da ação, status da resposta, duração e resultado. Mantenha bytes secretos e corpos sensíveis fora dos logs comuns. Para campos necessários como prova, guarde um resumo ou cifre sob controles separados.

Registre recusas e sucessos. Uma série de tentativas negadas contra endereços privados ou hosts alternativos pode revelar injeção de prompt ou um planejador defeituoso antes de qualquer efeito externo. Distinga recusa da política, recusa humana, falha de rede, rejeição do serviço e cancelamento local para não confundir conexão falha com ação bloqueada.

A evidência deve ser difícil de reescrever pelo agente atuante. Armazenamento só de acréscimo, escritores restritos e verificações de integridade mantêm o registro útil depois que uma máquina ou processo é questionado. Sallyport registra sessões e chamadas individuais em um único log de auditoria cifrado, encadeado por hash e ilegível para quem escreve, enquanto sp audit verify verifica a cadeia offline sobre o texto cifrado sem chave. Ele também guarda credenciais de API e SSH em um cofre cifrado e executa ações sem revelar segredos ao agente.

Substitua a concessão ampla no executor

É possível manter uma interface HTTP genérica sem manter autoridade genérica. Mova a injeção e a aplicação das regras para um executor confiável e peça ao modelo uma requisição sem credenciais junto de uma referência opaca.

Uma migração prática começa pelo inventário de chamadas reais. Agrupe requisições recentes por credencial, origem, método e operação. Credenciais amplas e destinos que nunca aparecem juntos são candidatos à separação. Rotas com vários modos destrutivos no corpo precisam de restrições próprias ou credenciais diferentes no serviço.

Depois coloque o tráfego atual em avaliação informativa. Canonicalize cada requisição, resolva o destino e mostre se a concessão proposta permitiria ou negaria, sem mudar ainda a execução. Revise correspondências surpreendentes. Uma regra que parece permitir leitura de ocorrências pode admitir exportações, registros excluídos ou outro locatário por um host compartilhado.

Aplique primeiro os limites simples: credenciais controladas pelo executor, origens HTTPS exatas, nenhum redirecionamento automático, métodos explícitos e recusa de endereços privados salvo necessidade de uma integração específica. Acrescente restrições de caminho, consulta, cabeçalhos e corpo às operações de maior impacto. Mantenha uma saída excepcional com aprovação por chamada e entrada de auditoria visível, sem voltar silenciosamente à ferramenta antiga.

Por fim, teste o limite com variações de requisições sabidamente corretas. Mude sufixo do host, porta, resposta DNS, destino de redirecionamento, referência da credencial, método, tipo de conteúdo, locatário, operação e caminho codificado. Cada variação deve corresponder a uma concessão intencional ou falhar antes da credencial. Confira também se bytes registrados, aprovados e enviados compartilham o mesmo resumo de ação.

A lista de ferramentas ainda ajuda o agente a escolher operações sensatas. Ela apenas não é o lugar certo para encerrar a autorização. Mantenha a interface conveniente se os desenvolvedores gostarem, mas faça cada efeito de rede obter permissão quando credencial, destino, método e detalhes forem conhecidos.