Seus testes de vazamento de segredos de agentes provam alguma coisa?

Um agente não precisa imprimir um token para tê-lo recebido. Se um bearer token entra no ambiente, na linha de comando, no payload de uma ferramenta, na transcrição, em um processo filho ou em um artefato de falha, o limite já foi rompido. Uma resposta educada do modelo não corrige esse erro.

O teste que você quer não é «o agente evitou repetir o segredo?». É «conseguimos executar ações reais por meio de um gateway de teste, coletar todos os artefatos que o lado do agente pode produzir e mostrar que nenhum contém uma credencial exclusiva e válida?». Essa afirmação é específica o bastante para ser testada e forte o bastante para detectar as falhas que aparecem em produção.

Use contas descartáveis, hosts descartáveis e um canário novo em cada execução. Mantenha o segredo apenas na configuração do gateway. Depois faça o agente executar ações HTTP e SSH bem-sucedidas, provoque falhas de propósito e inspecione o lado do agente como se esperasse encontrar um vazamento. Essa postura encontra os caminhos mais problemáticos.

Uma resposta limpa não prova que o limite está limpo

Um agente pode receber um segredo sem jamais colocá-lo em linguagem natural. Um vazamento comum ocorre quando uma implementação de ferramenta manda o agente chamar uma API diretamente e coloca um valor Authorization na entrada da ferramenta. Outro acontece quando um lançador de subprocesso herda API_TOKEN porque ninguém substituiu o ambiente antes da execução. Um terceiro ocorre quando um auxiliar SSH grava um arquivo de identidade temporário onde o agente pode lê-lo.

São falhas diferentes, mas têm a mesma consequência: o processo do agente passa a ter material que permite agir fora do gateway. Depois disso, prompts de aprovação e logs de auditoria descrevem apenas parte do risco. O agente pode copiar o segredo para um repositório, enviá-lo a outro serviço ou deixá-lo em uma transcrição que alguém exportará mais tarde.

Mantenha duas afirmações separadas:

• Isolamento da ação significa que o agente solicita uma operação e recebe o resultado, enquanto outro componente injeta a credencial e executa a comunicação de rede ou SSH.
• Não entrega do segredo significa que a credencial e derivados utilizáveis nunca entram no processo do agente nem em arquivos que ele possa ler.

As equipes costumam testar a primeira afirmação e presumir a segunda. É assim que um agente consegue chamar uma API de teste por meio de um gateway e ainda receber o token em um campo de depuração ou em uma variável de ambiente herdada.

A documentação de Process da Apple é direta sobre herança: um subprocesso recebe seu ambiente do processo que o inicia, a menos que o lançador o altere antes da inicialização. As APIs também expõem os argumentos de comando e os dados do ambiente ao próprio processo. Por isso, um processo filho não é um detalhe de implementação inocente neste teste. Ele é outro ponto de observação.

O padrão do teste deve ser este:

Dada uma nova credencial canário armazenada apenas no gateway, um agente consegue concluir ações HTTP e SSH especificadas, mas nenhum processo acessível pelo agente, transcrição, log, saída de falha ou artefato de diagnóstico coletado contém o canário ou uma codificação identificável dele.

Não prometa que um teste de caixa-preta prova que um segredo nunca ocupou nenhum byte de memória no gateway. Ele não pode fazer isso. O teste estabelece o limite que importa aos usuários: o agente nunca recebe uma credencial utilizável pelas interfaces e pelos artefatos que controla.

Uma credencial de teste precisa de uma função e uma impressão digital

Um token de teste deve fazer uma coisa útil e nada além disso. Para HTTP, crie uma conta de teste que possa chamar um único endpoint, como GET /whoami ou POST /echo-action, e que retorne um identificador de conta inofensivo. Para SSH, crie uma conta restrita em um host descartável e permita um pequeno conjunto de comandos que grave um evento no servidor.

Não use um token como test-token e depois procure por ele. Marcadores curtos e previsíveis geram correspondências falsas e tornam inúteis as verificações de codificação. Gere uma string diferente para cada execução. Coloque nela um prefixo reconhecível seguido de dados aleatórios, para que uma pessoa identifique uma falha sem confundir uma saída comum com um segredo.

Por exemplo, um harness pode criar um canário com este formato:

sallyport_probe_7M3jP4Fqk2rV9dN8xC5a

Essa string é um valor de credencial, não um identificador impresso para o agente. Mantenha um rótulo público separado para os logs, como run-2026-07-22-ssh-04. O rótulo pode aparecer nas transcrições. O canário não pode.

Use canários diferentes para cada canal e cada caminho de falha. Reutilizar um token HTTP em todos os testes transforma um único vazamento em um conjunto confuso de correspondências antigas. Também dificulta saber se um artefato posterior veio da execução atual ou de uma limpeza anterior que falhou.

Um fixture prático tem quatro partes:

1. Uma conta HTTP de teste cujo servidor retorne uma resposta fixa e não secreta depois de uma autenticação válida.
2. Uma conta SSH de teste cujo comando forçado registre um identificador de ação e retorne uma mensagem fixa.
3. Uma entrada de credencial no gateway contendo o canário novo e nenhuma cópia acessível ao agente.
4. Um manifesto fora do diretório de artefatos que associe o rótulo da execução aos canários usados nela.

O manifesto é material sensível de teste. Armazene-o onde o agente não possa lê-lo e exclua os canários depois da execução. A conta de teste deve rejeitar essas credenciais após a limpeza, mesmo que uma falha tenha deixado uma cópia em um arquivo local.

Sallyport permite que o gateway mantenha credenciais HTTP e SSH de teste enquanto o agente recebe resultados de ações, não as próprias credenciais.

O registro no servidor é importante. Ele prova que a autenticação ocorreu e impede que um teste ruim passe porque a ação nunca foi executada. Uma resposta como authenticated action accepted for run-2026-07-22-ssh-04 dá ao agente evidência suficiente de sucesso sem repetir a entrada usada na autenticação.

A captura da inicialização encontra o vazamento antes da primeira chamada de ferramenta

Capture os argumentos e o ambiente iniciais do agente no limite de inicialização. Esse teste encontra segredos passados por scripts de shell, configurações de CI, integrações com editores, wrappers e lançadores de conveniência. Também encontra um erro comum depois da adoção de um gateway: deixar a exportação antiga de API_TOKEN no lugar porque o novo caminho parece funcionar.

Inicie o agente por meio de um wrapper sob seu controle. O wrapper grava um instantâneo exato do vetor de argumentos e do ambiente em um diretório de teste protegido e depois substitui a si mesmo pelo executável do agente. Substituir o processo importa porque isso registra os valores fornecidos à inicialização real do agente, não uma reconstrução presumida depois que várias camadas começaram.

Este pequeno wrapper Python basta para um harness local:

#!/usr/bin/env python3
import json
import os
import pathlib
import sys

out = pathlib.Path(os.environ["PROBE_LAUNCH_RECORD"])
out.parent.mkdir(parents=True, exist_ok=True)
record = {
    "argv": sys.argv[1:],
    "environment": dict(os.environ),
}
out.write_text(json.dumps(record, sort_keys=True), encoding="utf-8")
os.execvp(sys.argv[1], sys.argv[1:])

Execute-o com um ambiente deliberadamente restrito. Inclua apenas o que o agente precisa para encontrar seu executável, seu diretório temporário, o endpoint MCP ou shim stdio e o caminho onde o wrapper grava o registro. Não herde todo o shell do desenvolvedor por hábito. Um ambiente completo importa credenciais sem relação com o teste, configurações de nuvem, tokens de registros de pacotes e configurações SSH antigas, o que pode fazer o teste falhar pelo motivo errado.

O registro esperado da inicialização tem este formato:

{
  "argv": ["agent-command", "run", "tests/agent-task.txt"],
  "environment": {
    "HOME": "/private/tmp/agent-home",
    "PATH": "/usr/bin:/bin",
    "PROBE_LAUNCH_RECORD": "/private/tmp/probe/launch.json"
  }
}

Os caminhos exatos não importam. O resultado importante é que o registro não contenha o canário HTTP ou SSH, sua forma base64, sua forma codificada em URL ou o nome de um arquivo que contenha uma chave privada.

Não mascare esse registro antes que o scanner o veja. O mascaramento pertence aos relatórios destinados às pessoas. O registro bruto é a evidência. Se um teste de release registrar apenas uma versão limpa, ele pode provar que o mascarador funciona enquanto esconde justamente o vazamento que você precisava encontrar.

Um instantâneo de inicialização tem um limite: ele mostra com o que o processo começou. Não mostra se uma chamada posterior de ferramenta coloca um segredo no ambiente de um filho ou em um arquivo temporário. Por isso, os próximos testes fazem o agente criar trabalho depois da inicialização.

Processos filhos fazem parte do limite do agente

Agentes frequentemente iniciam formatadores, gerenciadores de pacotes, executores de testes, comandos Git, clientes SSH e scripts. Se o agente consegue iniciar um filho, esse filho pode gravar o ambiente e os argumentos em disco, devolvê-los como saída ou passá-los a uma solicitação de rede. Trate cada filho como acessível ao agente, a menos que exista uma razão técnica sólida para não fazê-lo.

Dê ao agente uma tarefa inofensiva que execute um programa de sondagem depois de concluir uma ação no gateway. A sonda imprime seus próprios argumentos e o ambiente em formato legível por máquina. Como é filha do runtime do agente, ela observa os valores propagados pelo runtime naquele momento.

Use uma sonda que grave em um diretório controlado, em vez de retornar um despejo enorme do ambiente na conversa do modelo. Você está testando um vazamento, não convidando um vazamento a entrar na transcrição.

#!/usr/bin/env python3
import json
import os
import pathlib
import sys

path = pathlib.Path(os.environ["PROBE_CHILD_RECORD"])
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
    json.dumps(
        {"argv": sys.argv, "environment": dict(os.environ)},
        sort_keys=True,
    ),
    encoding="utf-8",
)
print("child probe completed")

Peça ao agente para executar primeiro uma ação autenticada e depois chamar a sonda com um argumento banal, como after-http-action. Execute a mesma sequência depois do SSH. Se a implementação do gateway injetar uma credencial em uma variável de ambiente para um auxiliar e permitir que esse auxiliar se torne descendente do agente, este teste encontrará o problema.

Verifique os caminhos dos argumentos separadamente. Desenvolvedores sabem que variáveis de ambiente vazam, mas os argumentos de comando muitas vezes são piores porque inspeção de processos, histórico do shell, formatação de erros e coletores de diagnóstico podem registrá-los. A Apple documenta que um processo pode acessar seus próprios argumentos por meio de CommandLine.arguments, e que ProcessInfo expõe argumentos e ambiente. Isso torna segredos passados em argv imediatamente observáveis pelo código executado dentro do processo.

Não aceite um argumento como --token-file=/private/tmp/secret apenas porque os bytes do token estão ausentes. O teste também deve inspecionar esse caminho. Se o agente puder ler o arquivo, ele terá o segredo. Se o arquivo puder ser lido apenas por um processo separado do gateway e nunca passar por diretórios de trabalho controlados pelo agente, registre esse fato na configuração do teste.

Para SSH, procure mais do que texto de chave privada. Falhe se encontrar um caminho de arquivo de identidade, um socket de agente que exponha a identidade de teste, um registro known_hosts gerado contendo material privado ou uma linha de comando que inclua uma senha. Uma chave privada armazenada em um arquivo temporário continua sendo uma chave privada, mesmo quando o agente recebe apenas o caminho.

Ações bem-sucedidas precisam de transcrições hostis

Um caminho feliz que retorna 200 OK prova quase nada. Ele prova apenas que alguém fez uma solicitação. Faça o agente solicitar uma ação real pelo gateway e preserve todas as transcrições e rastros de ferramentas produzidos no lado do agente.

O teste HTTP deve solicitar um endpoint que confirme a conta de teste autenticada sem refletir os cabeçalhos da solicitação. Uma resposta útil é um objeto fixo como este:

{
  "account": "gateway-test-http",
  "accepted": true,
  "request_label": "run-2026-07-22-http-01"
}

O agente pode raciocinar a partir dessa resposta. Ele não precisa do bearer token, do esquema de autorização, do nome do cabeçalho injetado nem de um prefixo de token mascarado. Se a interface da ação retornar um objeto de solicitação para depuração, transforme isso em um alvo de teste separado, pois é um vazamento provável. Um campo chamado request_headers é um erro de projeto, a menos que haja garantia de que o material de credencial será removido antes de atravessar o limite do agente.

Para SSH, faça o host aceitar um comando fixo como report-status <run-label>. O servidor registra a conta autenticada, o comando solicitado e o rótulo. Ele retorna uma resposta como status recorded. O agente não deve receber a chave privada, uma exportação do agente SSH nem uma transcrição da autenticação.

Salve estes artefatos do lado do agente:

• O prompt original do agente e a transcrição do modelo.
• Mensagens MCP brutas ou solicitações e respostas de ações equivalentes.
• Saída padrão e saída de erro de comandos controlados pelo agente.
• Logs de depuração de ferramentas, logs de novas tentativas e arquivos de eventos estruturados.
• Arquivos gravados no workspace do agente, no diretório temporário e no diretório de cache configurado.

Colete esses artefatos antes que uma rotina de limpeza remova as evidências. Depois verifique os bytes exatos, não apenas texto decodificado como UTF-8. Um segredo pode aparecer em escapes JSON, codificação percentual, base64, um rastreamento compactado ou um arquivo cujos bytes inválidos façam uma busca textual casual ignorar a correspondência.

O shim sp mcp do Sallyport é um bom alvo para esse teste porque permite exercitar o mesmo caminho MCP comum usado por um agente, mantendo as credenciais no cofre do aplicativo.

Não confunda uma transcrição mascarada com uma prova. Uma linha de log como Authorization: [REDACTED] pode ser adequada para a saída do operador, mas o objeto de evento bruto que a gerou ainda pode conter o token. Capture antes da formatação de exibição e teste o formatador separadamente. São duas obrigações diferentes.

É no tratamento de erros que o isolamento de segredos costuma falhar

Um gateway pode manter limpa a resposta de sucesso e ainda vazar um segredo quando algo dá errado. Caminhos de erro atraem contexto de depuração, reconstrução de solicitações, encadeamento de exceções e mensagens de novas tentativas. Execute-os de propósito.

Comece com falhas HTTP que ocorram em pontos diferentes:

1. Faça o servidor de teste retornar um 401 sem segredo depois de receber um canário válido. O agente deve saber que a autenticação falhou, não qual foi o valor do cabeçalho enviado.
2. Faça o servidor retornar 500 com um corpo que inclua o rótulo público da execução. O gateway pode retornar um corpo de erro limitado, mas não deve acrescentar cabeçalhos da solicitação nem um equivalente de curl.
3. Feche a conexão depois que o gateway preparar a autenticação. Isso captura exceções de baixo nível que incluam objetos de solicitação em suas descrições.
4. Retorne JSON malformado depois de uma autenticação bem-sucedida. Os analisadores costumam incluir a resposta problemática ou o contexto ao redor em uma exceção.
5. Use um nome DNS que não resolva em uma rota de teste. Isso captura a saída de novas tentativas e diagnósticos do endpoint.

Depois execute falhas SSH que ocorram antes e depois da configuração da conexão. Use um host com a identidade incorreta, um comando remoto que termine com status diferente de zero e um comando forçado que retorne um erro controlado. Não teste uma chave privada incorreta enviando uma chave de teste de volta ao agente nem fazendo o servidor registrá-la. O agente só precisa receber uma classificação como connection rejected ou remote command failed, além de um rótulo seguro da solicitação.

Teste também o estado bloqueado. Enquanto o cofre estiver bloqueado, uma ação deve falhar antes que ocorra a autenticação na rede. A resposta pode dizer que a autorização está indisponível. Ela não pode conter um marcador de token, um caminho para o armazenamento de credenciais, um nome de arquivo de identidade SSH nem o número de caracteres de um segredo. Depois do desbloqueio, repita a ação e exija o registro de sucesso no servidor. Esse par captura implementações que montam uma solicitação de credencial antes de verificar o bloqueio.

Um fixture de falha útil tem afirmações dos dois lados:

Agent side: the canary is absent from every collected artifact.
Gateway side: the attempted action has the expected safe error classification.
Server side: the expected request occurred, or did not occur for a locked vault test.

Essa última afirmação impede uma falsa sensação de segurança. Se o teste espera um erro de nova tentativa, mas o gateway recusou a chamada antes por um erro de configuração, ele pode passar pela verificação de vazamento sem exercitar o código perigoso.

Não envie exceções brutas através do limite. Objetos de erro devem conter um identificador de ação, uma categoria segura, uma mensagem útil para as pessoas e talvez uma indicação de nova tentativa. Eles não devem serializar a configuração da solicitação que causou a exceção. A vontade de facilitar a depuração torna populares os despejos completos das solicitações. Ainda assim, esse não é o padrão certo quando um injetor de credenciais controla a solicitação.

Artefatos de falha merecem uma falha intencional

Uma falha não é um resultado normal de API, e por isso as equipes a ignoram. Isso é um erro. Um desenvolvedor pode anexar um relatório de falha a uma issue, um script de suporte pode arquivá-lo e um sistema de diagnóstico pode coletar logs relacionados. Se um segredo chegar ali, você criou um vazamento atrasado em vez de um limite seguro.

Depois de uma ação HTTP bem-sucedida e novamente depois de uma ação SSH bem-sucedida, faça um processo de sondagem no lado do agente abortar. Mantenha o alvo da falha separado do gateway. Você quer testar se o lado do agente herdou ou registrou material secreto, não se derrubar deliberadamente o portador da credencial expõe seu estado privado.

No macOS, colete o relatório pelo Console ou pelo caminho de coleta de diagnóstico do ambiente de teste e verifique o arquivo sem alterações. A Apple descreve relatórios de falha como registros detalhados do estado da aplicação e recomenda analisar o relatório completo do sistema operacional. A documentação de relatórios de falha também observa que eles contêm informações do processo e do ambiente, como identidade do processo, caminho, processo pai, horários e estado das threads.

A ausência do canário em um relatório de falha do macOS não prova que ele nunca esteve presente na memória. Um relatório padrão não é um despejo completo da memória. Essa limitação não é motivo para ignorar o teste. Ela significa que você deve descrever o resultado corretamente: o relatório não expôs o canário, e o processo do agente não o recebeu pelos outros canais testados.

Verifique também os logs da aplicação e os arquivos de suporte criados perto da falha. A Apple alerta os desenvolvedores para não incluírem informações sensíveis à privacidade nos logs. Trate isso como requisito do seu próprio fixture: se um impressor de exceções registrar um objeto de solicitação, o teste de falha deve falhar mesmo que o relatório do sistema operacional esteja limpo.

Se você executar testes relacionados no Linux mais tarde, acrescente metadados de core dump e saída do journal ao conjunto de artefatos. O manual de systemd-coredump documenta campos que podem armazenar a linha de comando e o ambiente de um processo que falhou. Um conjunto de testes que verifica apenas o arquivo core e ignora seus metadados deixa passar um caminho de vazamento direto.

Verifique bytes, codificações e valores divididos

Um grep recursivo simples é melhor que nada, mas não encontra as formas que aparecem em JSON, URLs, rastreamentos e pacotes binários. Crie um scanner que leia arquivos como bytes e procure várias transformações determinísticas de cada canário.

No mínimo, gere estes alvos para cada canário:

raw bytes
base64 text
URL encoded text
JSON escaped text
hex text
first half and second half separated by one newline

O caso dividido captura wrappers de log que quebram valores longos. Os casos codificados encontram sistemas que serializam dados estruturados antes de gravá-los. Não procure apenas um prefixo do token. Um teste de prefixo pode passar se o token for truncado depois de caracteres suficientes para continuar utilizável e pode falhar por causa de um identificador sem relação.

Um scanner compacto pode informar o caminho do arquivo, o nome da transformação e o deslocamento em bytes sem imprimir o segredo:

import base64
import json
import pathlib
import urllib.parse

secret = bytes.fromhex("73616c6c79706f72745f70726f62655f5837")
needles = {
    "raw": secret,
    "base64": base64.b64encode(secret),
    "url": urllib.parse.quote_from_bytes(secret).encode(),
    "json": json.dumps(secret.decode()).encode(),
    "hex": secret.hex().encode(),
}

for path in pathlib.Path("artifacts").rglob("*"):
    if not path.is_file():
        continue
    data = path.read_bytes()
    for name, needle in needles.items():
        offset = data.find(needle)
        if offset >= 0:
            raise SystemExit(f"secret match: {path} transform={name} offset={offset}")

O código informa deliberadamente um deslocamento, não os bytes correspondentes. Uma falha de teste não deve criar um segundo vazamento na saída da CI. Armazene uma cópia forense rigorosamente controlada apenas se o processo de incidentes exigir isso e mantenha-a fora dos logs normais de build.

Verifique os arquivos depois de descompactá-los em um diretório temporário protegido. Verifique também dados compactados quando for viável, porque uma busca por bytes brutos não encontra um canário dentro de um payload comprimido. Se o cliente de telemetria agrupar eventos, colete o pacote antes que ele deixe a máquina de teste. É inútil descobrir depois que o scanner verificou apenas arquivos locais enquanto um token codificado já havia sido enviado a um coletor externo.

Mantenha uma lista de permissões para rótulos públicos esperados, não para segredos. Se um teste começar a falhar porque um campo inclui o nome da conta de teste, decida se esse nome concede acesso. Não adicione exclusões amplas antes que o scanner fique verde. Toda exclusão é uma brecha que você esquecerá de revisar.

O relatório precisa mostrar ausência e ação

Um bom relatório de teste responde a quatro perguntas sem pedir que o leitor confie na sua interpretação.

Primeiro, qual ação do gateway teve sucesso ou falhou? Mostre o rótulo público da execução, o tipo de ação e a observação do servidor. Segundo, quais artefatos foram coletados? Liste o instantâneo de inicialização, o instantâneo do filho, o pacote de transcrição, a árvore do workspace, as saídas de erro e os artefatos de falha. Terceiro, quais transformações do segredo o scanner procurou? Quarto, alguma leitura do scanner falhou por causa de um problema de permissão, de uma suposição incorreta sobre codificação ou de um arquivo compactado ignorado?

Um artefato ignorado não é aprovação. Marque-o como incompleto e faça o conjunto falhar, a menos que exista uma razão documentada para ele estar fora do limite do agente. Essa regra irrita as pessoas durante a configuração da CI. Ela também evita a situação previsível em que um teste informa sucesso porque não conseguiu abrir silenciosamente o diretório que continha o vazamento.

Mantenha o registro da ação do gateway separado do pacote de artefatos do agente. A auditoria do gateway pode provar que uma ação protegida por credencial ocorreu. O pacote do agente pode provar o que o agente recebeu. Combinar os dois em uma exportação conveniente cria um novo lugar desnecessário para o material sensível circular.

Para verificações de release, torne a condição de aprovação rigorosa:

PASS only when the server confirms the intended action,
all required artifacts were collected,
and no raw or transformed canary appears in agent reachable material.

Depois acrescente controles negativos. Execute um fixture deliberadamente quebrado que passe o canário por uma variável de ambiente ou por uma resposta falsa de depuração. O scanner deve falhar. Um teste que nunca demonstra conseguir capturar um vazamento conhecido é apenas encenação.

Execute o conjunto sempre que alguém alterar a injeção de credenciais, o código de inicialização de processos, o transporte MCP, a formatação de erros, os logs, a coleta de suporte ou o tratamento SSH. Essas mudanças parecem não relacionadas em uma revisão, mas é nelas que as credenciais escapam. Mantenha uma versão menor nos testes comuns de integração e deixe a coleta de falhas e arquivos para execuções agendadas ou de release, se forem caras.

O padrão é simples de declarar: o gateway pode usar um segredo para agir, mas o agente não pode adquirir esse segredo como dado. Se o seu teste observa apenas o que o agente diz, muita coisa fica sem verificação. Faça o agente agir, faça-o falhar, faça-o iniciar um filho, faça-o falhar e verifique o que restou.