Por que credenciais na string de consulta vazam antes de alguém lê-las

Um segredo em uma URL já percorreu um longo caminho. Pode ter passado por uma biblioteca de cliente, um proxy, um log de acesso, um sistema de rastreamento, um banco de dados de histórico do navegador e um CSV exportado antes de a API recebê-lo. O HTTPS protege essa solicitação durante o transporte. Ele não faz com que todas as máquinas e serviços que processam a URL se esqueçam dela.

Por isso, um agente autônomo pode evitar ver um token e ainda provocar o vazamento de uma credencial. Se o agente pedir a um gateway de ações que chame https://api.example.test/v1/builds?access_token=..., o gateway pode manter o token fora da transcrição do agente, mas ainda construir uma URL que outros sistemas costumam registrar. O segredo saiu do alcance do modelo, mas foi parar em um conjunto muito maior de lugares.

A correção é menos chamativa do que a varredura de segredos. Limite a URL à identidade do recurso e a filtros comuns. Coloque as credenciais no cabeçalho da solicitação ou, quando o protocolo exigir, no corpo. Depois, faça o componente que mantém o segredo injetá-lo no último momento possível. Isso separa uma solicitação que pode ser nomeada com segurança, repetida em um teste e incluída em um registro de auditoria de uma solicitação que carrega autorização.

Uma URL é um registro, não apenas uma rota

Uma URL foi feita para ser copiada, exibida, comparada, armazenada em cache, salva nos favoritos e registrada em logs. Essas características a tornam útil para identificar recursos e péssima para transportar credenciais de portador. Um parâmetro de consulta passa a fazer parte do destino da solicitação, que muitas camadas tratam como dado operacional comum.

O CWE-598 chama essa fraqueza de "Use of HTTP Request With Sensitive Query String". Sua descrição cita as rotas de escape mais comuns: histórico do navegador, cabeçalhos Referer, logs da web e outras fontes de registro. A mitigação é igualmente simples: envie informações sensíveis em cabeçalhos ou no corpo da solicitação. Isso não significa que GET seja proibido. É um aviso de que colocar um segredo na URI aumenta o número de pessoas e sistemas capazes de recuperá-lo.

O RFC 9110 faz a mesma distinção em suas considerações de segurança. Ele alerta que campos de consulta da URI criados a partir de dados inseridos pelo usuário podem carregar dados sensíveis e afirma que uma URI diferente, gerada pelo servidor, pode remover dados sensíveis de links posteriores. Para credenciais de API, vale ir além: não crie uma URI que carregue segredo desde o início. Substituí-la depois deixa cópias para trás.

Um parâmetro de URL às vezes é chamado de "apenas uma chave de API" ou "só um token de curta duração". Nenhum desses nomes muda a superfície de exposição. Um token de curta duração ainda pode estar válido quando um serviço de envio de logs o encaminhar. Uma chave de API pode autorizar um endpoint limitado, mas esse endpoint pode bastar para ler dados, gerar custo ou emitir uma credencial melhor. Trate dados de autorização como segredo até que o serviço que os emitiu diga o contrário.

Logs de acesso preservam a parte que as pessoas esquecem

A maioria dos logs de acesso HTTP inclui método, destino da solicitação, status, tamanho e tempo, porque operadores precisam desses campos para diagnosticar o tráfego. O destino da solicitação inclui o caminho e a string de consulta. Uma linha típica se parece com isto:

203.0.113.24 - - [14/Jun/2026:12:42:18 +0000] "GET /v1/builds?access_token=sk_live_example HTTP/1.1" 200 481

A parte prejudicial não vem de uma configuração exótica de depuração. É o campo comum que um operador pesquisa quando uma rota começa a retornar erros. Mascarar um cabeçalho Authorization é comum porque as equipes esperam que ele contenha segredos. Mascarar chaves de consulta arbitrárias é mais difícil: uma origem chama de token, outra usa api_key, uma terceira aceita sig, e uma quarta coloca a credencial dentro de um bloco assinado.

Não aceite "nós mascaramos os logs" como resposta até que alguém mostre o destino exato da solicitação após o mascaramento, incluindo os valores da consulta, em cada etapa. Uma regra que mascara token deixa passar access_token. Uma regra que mascara access_token deixa passar um fornecedor que chama o mesmo valor de key. Uma regra que mascara nomes conhecidos não faz nada por uma URL pré-assinada cuja credencial está distribuída entre vários parâmetros.

A distinção prática é esta: o mascaramento de cabeçalhos protege uma solicitação que carrega segredo, enquanto a injeção de cabeçalho impede que a URL passe a carregar segredo. Você ainda precisa de controles de log para os cabeçalhos. Também deixa de manter uma lista interminável de exceções para nomes de consultas, que sempre fica atrás das APIs dos fornecedores.

Proxies reversos transformam uma solicitação em vários registros

Um proxy reverso vê a solicitação completa antes de encaminhá-la. O mesmo vale para balanceadores de carga, gateways de API, malhas de serviço, WAFs, serviços de borda de CDN e agentes de observabilidade que instrumentam o ciclo de vida da solicitação. Eles não registram o mesmo formato, não retêm dados pelo mesmo período nem os enviam para a mesma conta.

Isso importa porque um log limpo da aplicação prova muito pouco. Um log de entrada pode conter a URL original. Um log de erro do proxy pode repeti-la quando a conexão com o serviço de origem falha. Um span de rastreamento pode anexar http.target ou um valor de rota. Um pacote de suporte pode reunir vários desses arquivos porque alguém precisou de ajuda com um tempo limite. Cada cópia é operacionalmente razoável isoladamente. Juntas, transformam uma chave vazada em um problema de inventário.

As equipes costumam tentar resolver isso com um filtro global de mascaramento. Use filtros, mas conheça o limite deles. Um filtro só funciona depois que um componente recebeu a URL, interpretou-a corretamente e identificou todas as formas de escrever o segredo. Ele também incentiva a manter credenciais na URL, porque removê-las exigiria alterar o código do cliente. A correção duradoura fica no limite da chamada, onde a credencial entra na solicitação.

Imagine que um agente monte uma solicitação de implantação. Ele pode produzir esta descrição segura da ação:

GET https://deploy.example.test/v2/releases?project=docs-site&limit=20
credential: deploy-read

Um gateway que mantém a credencial resolve deploy-read dentro de seu cofre e envia Authorization: Bearer ... para o serviço de origem. O proxy ainda vê uma solicitação, naturalmente. O destino dela contém project e limit, não o valor de portador. Se o log de cabeçalhos expuser Authorization por acidente, esse é outro defeito, com um teste claro e delimitado. Não esconda esse defeito, mas não o amplifique com vazamento pela URL.

O histórico do navegador é um vazamento local de longa duração

O histórico do navegador não é o principal caminho para um agente sem interface, mas revela um erro comum em fluxos de trabalho humanos. Engenheiros colam uma URL com falha no navegador para inspecionar uma página de erro, reproduzir um callback ou comprovar que uma rota de API funciona. O navegador armazena o endereço completo, sugere-o mais tarde e pode sincronizar o histórico conforme as configurações locais. Uma gravação de tela, uma sessão compartilhada ou um colega usando a máquina podem fazê-lo reaparecer.

O cabeçalho Referer acrescenta outra rota. Quando um navegador carrega uma página cujo endereço contém um segredo na consulta e essa página pede um recurso ou segue um link, um servidor posterior pode receber um valor de referência, sujeito à política do navegador. Políticas modernas de referência reduzem alguns casos, mas não tornam uma URL secreta um bom projeto. A credencial não deveria estar presente para que a política a protegesse.

Por isso, "o agente nunca a viu" não basta. Um desenvolvedor pode ver a URL no resultado de um agente, colá-la em um chamado ou usá-la em uma verificação manual. Qualquer sistema que exibe uma URL incentiva a copiá-la. Na ação voltada a pessoas, coloque um nome opaco para o segredo, não o valor secreto.

Há uma exceção que merece ser citada: uma URL assinada concede acesso intencionalmente pela própria URL. Esse pode ser o protocolo oferecido por um serviço de armazenamento para um download temporário. Trate-a como uma capacidade restrita, não como uma credencial normal de API. Mantenha a expiração curta, limite-a a um objeto e método quando o provedor permitir, evite imprimi-la e não deixe que um agente escolha parâmetros de consulta arbitrários. Uma URL assinada continua sendo sensível no histórico e nos logs. Sua natureza temporária limita o dano, mas não elimina o caminho de vazamento.

Exportações de auditoria transformam um incidente em distribuição

Uma trilha de auditoria deve ajudar a responder quem solicitou uma ação, qual identidade de credencial a autorizou, qual destino a recebeu e o que aconteceu. Ela não deve virar um segundo armazenamento de credenciais. O esquema de auditoria perigoso registra uma URL completa porque isso parece fiel. Fiel a quê? Ele preserva fielmente um valor de que o investigador nunca deveria precisar.

Use um registro de auditoria que separe identificadores estáveis de material secreto. Um registro útil de ação HTTP pode incluir método, esquema, host, caminho, nomes e valores de consultas não sensíveis, alias da credencial, identidade da sessão, decisão, status, classificação da resposta e horários. Ele pode guardar um resumo criptográfico de componentes selecionados da solicitação se você precisar de evidência contra adulteração. Deve excluir valores de autorização, conteúdo de cookies e valores secretos da consulta.

Esse formato também torna as exportações mais seguras. JSON, CSV e arquivos de suporte saem de sua fronteira original de acesso. Alguém os envia a um fornecedor, anexa a um bug, salva em uma unidade compartilhada ou carrega em uma planilha. Essa é a vida normal de uma exportação. Projete-a para responder a uma investigação sem criar uma fila de rotação de credenciais.

O Sallyport projeta sessões de agentes e chamadas individuais a partir de um único log de auditoria criptografado e encadeado por hash. O comando sp audit verify verifica essa cadeia off-line sobre texto cifrado, sem uma chave. Isso prova que o log não foi alterado. Não justifica registrar URLs secretas. Integridade e confidencialidade resolvem problemas diferentes, e as equipes frequentemente as confundem porque ambas são chamadas de "segurança de auditoria".

Um log à prova de adulteração que contém uma credencial ativa pode provar exatamente quando a credencial vazou. Um log mascarado sem uma garantia de integridade pode ser seguro para compartilhar, mas difícil de confiar. Você precisa das duas propriedades, aplicadas a campos diferentes.

A injeção de cabeçalho mantém o segredo fora da descrição da ação

A injeção de credenciais Bearer e de cabeçalhos personalizados funciona porque quem chama pode descrever o destino sem possuir a credencial. O gateway mantém o mapeamento entre o rótulo da credencial e sua entrada criptografada no cofre. Ele constrói a solicitação, adiciona o cabeçalho, envia-a e retorna o resultado. O agente não recebe o valor do cabeçalho nem um marcador que possa expandir.

Para uma API Bearer, o formato é conceitualmente simples:

agent request
  method: GET
  url: https://metrics.example.test/v1/usage?team=infra
  credential: metrics-production

gateway outbound request
  GET /v1/usage?team=infra HTTP/1.1
  Host: metrics.example.test
  Authorization: Bearer [vault value]

O texto entre colchetes é uma notação explicativa, não um valor que deva aparecer em uma transcrição real. Em um limite bem projetado, o agente não pode pedir que esse valor seja revelado, salvá-lo em um arquivo ou movê-lo para uma string de consulta. O gateway trata a credencial como dado que pode usar, não como dado que pode devolver.

Cabeçalhos personalizados merecem o mesmo tratamento. Alguns serviços usam X-API-Key, Api-Key ou um cabeçalho específico do fornecedor em vez de Authorization. O nome exato muda, mas a regra não: a descrição da solicitação visível ao cliente deve se referir a uma identidade de credencial, e o gateway deve injetar o valor no momento da execução. A autenticação básica também pertence ao cabeçalho, embora seja melhor preferir um método mais forte aceito pelo provedor quando houver um.

O Sallyport oferece injeção de credenciais Bearer, básicas e em cabeçalhos personalizados para chamadas HTTP. Isso ajuda porque permite que um agente compatível com MCP solicite uma ação HTTP sem manter a chave de API em seu próprio contexto. Esse limite não é um sanitizador mágico: a URL e quaisquer campos fornecidos pelo agente ainda podem conter segredos se você permitir. Valide o formato da solicitação e rejeite valores parecidos com segredos em locais que devem permanecer públicos.

POST não corrige uma credencial na URL

Trocar GET por POST mantendo ?api_key=... na URL quase nada muda nesse vazamento. Proxies ainda recebem o destino da solicitação. Logs de acesso ainda costumam registrá-lo. Navegadores e ferramentas ainda podem exibi-lo. O CWE-598 observa explicitamente que uma string de consulta pode aparecer com métodos além de GET.

Mover uma credencial para o corpo da solicitação pode reduzir registros acidentais em algumas pilhas, pois logs de acesso em geral não incluem corpos por padrão. Isso não é o mesmo que injeção de cabeçalho. Corpos costumam ser capturados por middleware de depuração, clientes de API, relatores de erro e ferramentas de gravação de solicitações. Eles também fazem a credencial parte da carga de uma ação que um agente pode tentar construir ou repetir.

Use o método e o corpo exigidos pela API. Coloque um segredo no corpo somente quando o protocolo exigir isso explicitamente, como em uma troca de token que especifique parâmetros de formulário. Depois, limite o registro do corpo, exclua o endpoint de capturas amplas de solicitações e mantenha a troca dentro do componente que detém a credencial. Não transforme toda solicitação de leitura em POST por superstição. Preserve a semântica HTTP e retire o segredo da URI.

Outra recomendação ruim é "codifique a URL e os logs serão inofensivos". A codificação percentual apenas muda a representação. Quem tiver a URL pode decodificá-la, e muitos visualizadores de logs já fazem isso. Base64 tem o mesmo problema. A codificação pode dificultar a leitura da consulta a olho nu e, ao mesmo tempo, tornar regras de mascaramento mais fáceis de ignorar.

Uma migração segura começa com evidência, não com uma edição em massa

Não substitua todos os parâmetros de consulta. Parâmetros como page, sort, project e fields costumam ser legítimos, úteis e não secretos. Comece encontrando os pontos em que credenciais realmente entram nas URLs, depois altere essas chamadas com um teste que observe a solicitação de saída.

Use esta sequência:

1. Pesquise no código-fonte, nos prompts de agentes, em comandos curl salvos, fixtures de teste, painéis e runbooks por nomes como token, key, secret, signature e credential. Pesquise também URLs completas que contenham ?. Os nomes variam.
2. Reúna logs de acesso e dados de rastreamento representativos de cada camada de entrada. Confirme se o destino de cada solicitação registra valores da consulta, não apenas nomes de parâmetros. Trate exportações retidas e pacotes de suporte como outra camada.
3. Pergunte ao responsável pela API qual mecanismo de cabeçalho ou corpo ela oferece. Se ela aceitar credenciais apenas na consulta, documente a exceção, restrinja fortemente a credencial e isole essa chamada de agentes de uso geral.
4. Altere a interface da ação de url with secret para url plus credential alias. Acrescente um teste que rejeite uma URL contendo um token de teste conhecido e confirme que o cabeçalho de saída o contém.
5. Faça a rotação de todas as credenciais que apareceram em URLs e remova logs e exportações antigos conforme seu processo de retenção. Rotação sem limpeza deixa a exposição histórica. Limpeza sem rotação deixa uma chave ainda ativa circulando.

O teste é onde muitas migrações falham. Um teste unitário que verifica apenas a resposta HTTP final não pode dizer se a chave foi para o cabeçalho ou para a string de consulta. Coloque um servidor de teste local atrás do cliente e capture método, caminho, consulta e cabeçalhos separadamente. Confirme que a consulta não contém o valor de teste e que apenas o cabeçalho pretendido o contém.

Para um gateway, acrescente um caso de recusa. Forneça https://api.example.test/v1/jobs?access_token=test-canary com qualquer alias de credencial e faça-o falhar antes da chamada de rede. Isso detectará um futuro modelo de prompt ou um wrapper de conveniência que tente colocar segredos de volta nas URLs. Um token canário deve ser único e inutilizável fora do teste.

O mascaramento continua necessário depois que o projeto é corrigido

A injeção de cabeçalho reduz o conjunto de vazamentos prováveis. Ela não torna os logs seguros por decreto. Uma aplicação pode repetir um cabeçalho de autorização em uma exceção, um proxy pode registrar todos os cabeçalhos durante um incidente de depuração ou um agente pode colar em um chamado dados de resposta que contêm um segredo. Mantenha mascaramento, controle de acesso, limites de retenção e resposta a incidentes.

Mas aplique esses controles na ordem certa. Primeiro, mantenha credenciais fora das URLs e das descrições de solicitação visíveis ao agente. Em seguida, masque cabeçalhos e corpos sensíveis conhecidos em todos os registradores que possam capturá-los. Depois, restrinja quem pode recuperar registros brutos e por quanto tempo eles permanecem disponíveis. Por fim, ensaie a rotação e a limpeza de exportações para que a equipe possa agir quando um controle falhar.

Essa ordem evita uma armadilha comum: tratar um padrão de mascaramento como permissão para passar segredos por toda parte. Regras de mascaramento são frágeis porque dependem de nomes, formatos e analisadores. Um limite de credenciais é mais forte porque controla quem recebe o valor.

A autorização do agente deve incluir o destino de saída

Um agente que não consegue ler um token ainda pode gastar a autoridade dele. Se puder escolher qualquer URL, poderá enviar uma credencial válida a um host não intencional por meio de uma configuração confusa, um erro de digitação, um caminho de SSRF ou um prompt que explore uma interface de ação permissiva. Não revelar o segredo e controlar o destino são requisitos distintos.

Associe um alias de credencial ao serviço pretendido e deixe explícitos o host, o esquema e o formato de caminho permitido. Um gateway deve rejeitar uma credencial selecionada para metrics.example.test quando a ação indicar metrics.example.test.evil.invalid. Também deve rejeitar truques com informações de usuário, redirecionamentos inesperados que encaminhem credenciais e URLs que escondam uma mudança de host por codificação. Essas verificações devem ficar onde o cabeçalho é injetado, pois esse é o último ponto que tem a identidade da credencial e o destino analisado.

O cartão de autorização por sessão do Sallyport identifica o novo processo de agente pela sua autoridade de assinatura de código, e chaves por chamada podem exigir um clique ou Touch ID a cada uso. Esses controles respondem se esse processo pode invocar uma ação. Eles não tornam seguro um destino arbitrário, portanto mantenha a configuração da ação restrita o bastante para que uma aprovação tenha um significado concreto.

O artefato útil é um registro de solicitação que você pode compartilhar

Um teste prático desse projeto é simples: você consegue colar o registro da ação em um chamado de incidente sem iniciar uma rotação de credenciais? Se a resposta for não, o registro contém informação demais.

Procure ter um registro como este:

request_id: 01J...
agent_session: signed-process-42
method: GET
destination: https://metrics.example.test/v1/usage
query: team=infra
credential_alias: metrics-production
authorization: injected, value omitted
result: 200, 481 bytes

Esse registro dá ao investigador o suficiente para correlacionar a chamada, reproduzir a rota com uma credencial de teste segura e perguntar por que o agente selecionou metrics-production. Ele deliberadamente não autentica ninguém. Se um investigador precisar do segredo em si, isso deve ocorrer em um processo separado e privilegiado de recuperação, não como um campo da telemetria de rotina.

A primeira ação geralmente é uma busca simples por URLs no código, nos prompts e nos logs exportados. Faça-a mesmo assim. A credencial encontrada ali pode ter sido copiada por sistemas cuja existência você esqueceu, e a única resposta realmente limpa é parar de criar esse tipo de URL.