Arquivos temporários de ferramentas de agentes: encontre e limpe vestígios secretos

Os arquivos temporários de uma ferramenta de agente merecem o mesmo cuidado que um repositório de código. Um agente de programação pode criar o corpo de uma requisição, executar um comando, repeti-lo com logs detalhados, copiar a saída para um cache e deixar o diretório de trabalho original aparentemente limpo. O material sensível continua na máquina, muitas vezes em locais que ninguém incluiu na revisão.

O erro é imaginar que um segredo só vaza quando o agente o exibe em uma conversa. Na prática, o vazamento mais comum é uma requisição com credenciais copiada para um arquivo temporário para que um auxiliar possa enviá-la, ou um comando com falha registrado em um log porque alguém ativou o modo de depuração na semana anterior. A limpeza importa, mas a prevenção importa mais: não entregue credenciais brutas a um agente quando outro processo puder executar a ação.

As ferramentas de agentes criam cópias fora da árvore de trabalho

Uma execução pode deixar dados em várias camadas mesmo quando o diretório do projeto não contém nenhum vestígio óbvio. A árvore de trabalho é apenas um local de gravação, e os desenvolvedores costumam examiná-la por ser familiar. O agente, seu ambiente de execução, shell, gerenciador de pacotes, editor, terminal e sistema operacional têm seus próprios locais de gravação.

Comece separando três tipos de material. Arquivos de payload contêm o que o agente pretendia enviar, como corpos de requisições JSON, lotes SQL, exportações de prompts, arquivos de patch ou configurações SSH. Arquivos de saída contêm o que o sistema remoto devolveu, como respostas de API, saída de comandos, exportações de banco de dados e páginas de erro. Material de diagnóstico contém as evidências ao redor: argumentos de comandos, detalhes do ambiente, rastreamentos de pilha, novas tentativas e traces.

Os três tipos podem carregar dados sensíveis. Um payload pode incluir um token porque um script o inseriu antes do envio. A saída pode conter um registro de cliente ou um segredo de implantação. O diagnóstico pode capturar ambos na mesma linha, por isso um log de depuração costuma causar mais dano que o próprio comando com falha.

Um inventário útil inclui estes locais:

• O diretório temporário do processo e /private/tmp no macOS.
• Diretórios de suporte de aplicativos, cache e logs em ~/Library.
• Histórico do shell, exportações do buffer do terminal e wrappers de comandos.
• Pastas locais do projeto, como .cache, tmp, logs, .agent e diretórios de fixtures de teste.
• Camadas graváveis de contêineres, montagens vinculadas, espaços de trabalho de CI e artefatos de build enviados.

Não presuma que um agente usa um único diretório previsível. Versões, plugins, ambientes de linguagem e caminhos de erro diferentes fazem escolhas diferentes. Uma ferramenta pode usar o diretório indicado por TMPDIR; um auxiliar chamado por ela pode usar /tmp; uma biblioteca pode criar um cache no projeto atual. A única resposta defensável vem da observação da sua própria execução.

O mesmo vale para a saída de comandos. Um redirecionamento como command > result.txt é evidente. Menos óbvios são logs de multiplexadores de terminal, arquivos de depuração do gerenciador de pacotes, traces de clientes HTTP e arquivos de recuperação do editor criados depois que o agente altera um documento. Se um agente pode chamar várias ferramentas, presuma que cada uma tenha um comportamento independente de retenção até testá-la.

Mapeie os locais reais de gravação antes de tentar limpá-los

Você não consegue limpar corretamente um caminho que foi apenas adivinhado. Execute o agente usando um marcador exclusivo e inofensivo e depois procure esse marcador nos locais onde a execução poderia gravar. Use dados falsos que se pareçam o suficiente com os reais para percorrer os mesmos caminhos de código, mas nunca use um token de produção nesse exercício.

No macOS, comece registrando o diretório temporário herdado pelo shell que inicia o agente:

echo "TMPDIR=$TMPDIR"
ls -ld "$TMPDIR" /private/tmp /tmp

O macOS costuma fornecer a cada usuário um diretório abaixo de /var/folders, e /tmp aponta para /private/tmp. O caminho gerado muda e não é uma fronteira de segurança. Registre seu valor em vez de gravá-lo diretamente em um script de limpeza.

Crie um marcador fácil de encontrar e faça o agente executar uma ação representativa que o passe pelo corpo de uma requisição, por um argumento de comando e pela saída do comando. Este exemplo usa deliberadamente uma string que não é secreta:

export AGENT_TRACE_MARKER='TEMP-PAYLOAD-CANARY-9f2a7c'
printf '%s\n' "$AGENT_TRACE_MARKER" > /tmp/agent-canary.txt

Depois da execução, procure nas áreas prováveis do usuário. O grep pode encontrar arquivos binários e erros de permissão, portanto use-o como ferramenta de descoberta, não como prova de que nada existe.

grep -RIl --exclude='*.sqlite*' \
  'TEMP-PAYLOAD-CANARY-9f2a7c' \
  "$TMPDIR" /private/tmp \
  "$HOME/Library/Caches" \
  "$HOME/Library/Logs" \
  "$HOME/Library/Application Support" 2>/dev/null

O resultado deve ser uma lista de caminhos de arquivos. Para cada caminho, responda a quatro perguntas: qual processo o criou, que categoria de conteúdo ele contém, quem pode lê-lo e quando ele desaparece. Se não conseguir relacionar um arquivo a um processo, examine seu horário de modificação e repita o teste com um marcador novo. Não exclua primeiro os arquivos sem explicação. Você pode apagar a pista que indicaria qual componente precisa ser reconfigurado.

Use fs_usage quando um arquivo aparecer somente por um instante. Ele pode mostrar a atividade do sistema de arquivos de um processo enquanto o agente executa:

sudo fs_usage -w -f filesystem | grep -iE 'agent|tmp|cache|log'

Esse comando produz muito ruído. Execute-o por pouco tempo durante um teste, salve os caminhos observados fora de um diretório de projeto compartilhado e encerre-o depois. Um processo que grava e exclui um arquivo em um segundo não aparecerá em uma listagem posterior, mas seu conteúdo pode ter chegado a um backup, observador ou outro coletor de logs.

A construção da requisição é onde as credenciais costumam vazar

O arquivo temporário mais perigoso costuma ser criado antes da chamada de rede. Muitos scripts montam a requisição em um arquivo porque colocar JSON entre aspas no shell é desagradável. O arquivo começa sem risco, até alguém acrescentar um campo Authorization, um cookie ou uma string de conexão completa para fazer a requisição funcionar. Sem querer, ele vira um contêiner duradouro de segredos.

Evite este padrão:

cat > /tmp/request.json <<'EOF'
{"endpoint":"https://api.example.invalid/export","token":"$PRODUCTION_TOKEN"}
EOF

O heredoc com aspas simples acima não expande a variável, o que pode parecer seguro. Uma edição posterior pode mudar o delimitador ou usar outro método de construção. Mais importante, o desenho ainda incentiva colocar uma credencial em um artefato de requisição. Um dump de depuração da requisição concluída a exporá.

Coloque as credenciais na camada de transporte quando o protocolo permitir e garanta que o transporte não registre cabeçalhos. Cabeçalhos HTTP de autorização são preferíveis a um token em uma string de consulta, mas não são automaticamente seguros. Clientes detalhados, configurações de proxy, handlers de exceção e código personalizado de novas tentativas ainda podem registrá-los.

A especificação HTTP Semantics, RFC 9110, afirma que os agentes de usuário não devem enviar uma URI com informações sensíveis em um cabeçalho Referer. O alerta reflete um fato mais amplo: as URLs viajam mais longe do que as pessoas esperam. Elas acabam em logs de acesso, histórico do navegador, comandos de terminal copiados, chamados de suporte e sistemas de análise. Não coloque tokens bearer, URLs assinadas com autoridade ampla, senhas ou strings de conexão de banco de dados em uma URL, a menos que o protocolo não ofereça alternativa e a credencial tenha uma vida útil muito curta.

Os argumentos do shell exigem o mesmo cuidado. Em sistemas semelhantes ao Unix, outro processo local pode observar argumentos, dependendo das permissões e das configurações da plataforma. Os argumentos também podem parar no histórico do shell se alguém os copiar, no log de um executor de tarefas e no transcript das ferramentas do agente. Variáveis de ambiente reduzem alguns desses caminhos, mas criam outros, incluindo processos filhos herdados e relatórios de diagnóstico. Nenhuma das duas opções é um cofre seguro.

A fronteira mais segura é simples: o agente solicita uma operação informando o destino e as entradas não sensíveis. Um responsável separado pelas credenciais adiciona a autenticação imediatamente antes da chamada. O agente recebe a resposta ou um erro redigido, não a credencial usada para obtê-la.

O Sallyport segue essa fronteira nas ações HTTP e SSH: a credencial permanece em seu cofre criptografado e o agente pede ao aplicativo local que execute a ação. Isso remove o segredo bruto do contexto do agente, mas não torna inofensivos os corpos das respostas ou os arquivos de depuração criados pelo agente. Você ainda precisa controlar o que a ação retorna e onde o agente grava o resultado.

O modo de depuração transforma falhas rotineiras em registros de segredos

O log de depuração é útil para diagnosticar uma integração quebrada. Ele também foi criado para preservar as evidências que o log comum omite. Isso costuma incluir cabeçalhos, corpos completos de requisições e respostas, linhas de comando, configurações derivadas do ambiente, estado das novas tentativas e rastreamentos de pilha.

O erro é deixar uma flag ampla de depuração ativada porque o problema ocorreu uma vez. Sem perceber, a flag se aplica a uma tarefa diferente semanas depois, quando alguém executa uma exportação ou implantação com autoridade real. O arquivo resultante pode ficar em um diretório de cache que ninguém sabe pertencer à ferramenta.

Trate os diagnósticos como uma classe de dados diferente, com uma vida útil curta e explícita. Antes de ativar um trace, decida que pergunta ele precisa responder. Se a dúvida é se o DNS resolve, capture a saída do resolvedor. Se é saber se o servidor rejeita um campo JSON, registre o código de status e um trecho redigido da resposta. O log completo do tráfego deve ser exceção, pois registra material de que você não precisava para resolver o problema.

Faça a redação no componente que grava, não depois. Um job de limpeza que procura Authorization: nos logs não encontrará cabeçalhos personalizados, campos JSON, parâmetros de URL, valores multilinha, blocos em base64 ou conteúdo de resposta com segredos. Depois que um coletor de logs ou serviço de backup copia o arquivo sem redação, limpar o original faz pouco efeito.

Um wrapper de diagnóstico seguro tem uma lista de permissões dos campos que pode gravar. Por exemplo, registre o método HTTP, o host, o caminho sem parâmetros de consulta, o código de status, a duração, a quantidade de bytes da resposta e um identificador da requisição. Não registre todos os cabeçalhos acreditando que mascarará os problemáticos depois. Os formatos das credenciais mudam mais rápido que os scripts de limpeza.

Essa distinção importa em ferramentas que exibem um comando antes de executá-lo. Mostrar um comando não é o mesmo que registrar o ambiente efetivo do comando, e nenhum dos dois equivale a um trace de pacotes. Descubra qual representação a ferramenta salva. Ela pode redigir a exibição no console e ainda deixar um log detalhado intacto.

Teste os caminhos de falha de propósito. Cancele uma requisição no meio. Envie JSON malformado. Provoque uma falha de autenticação com uma credencial sintética. Cause um timeout para exercitar as novas tentativas. Esses caminhos criam arquivos temporários e exceções que chamadas bem-sucedidas talvez não criem. Também são caminhos que um invasor pode provocar para fazer o sistema divulgar mais do que divulga na operação normal.

A exclusão no macOS exige contenção, não destruição mágica

No armazenamento moderno do macOS, exclusão segura não significa sobrescrever repetidamente um nome de arquivo. Nivelamento de desgaste de SSD, comportamento copy-on-write, snapshots, sincronização na nuvem e backups fazem com que o software não possa prometer que uma sobrescrita atingiu todos os vestígios físicos. O velho hábito de executar um utilitário de destruição segura cria uma sensação de conclusão sem tratar das cópias que realmente importam.

Use a exclusão para remover arquivos ativos e acessíveis. Use contenção para limitar onde o material sensível pode existir desde o início. Use criptografia e altere as credenciais quando suspeitar de exposição.

Para um diretório temporário específico do agente, crie-o com permissões restritas antes da execução e remova-o depois:

run_dir="$(mktemp -d "${TMPDIR%/}/agent-run.XXXXXX")" || exit 1
chmod 700 "$run_dir"
trap 'rm -rf "$run_dir"' EXIT HUP INT TERM
export TMPDIR="$run_dir"

# launch the agent from this same shell
# agent-command

Isso dá à execução uma área temporária conhecida e garante sua remoção nos caminhos normais de saída. Não obriga todas as dependências a respeitar TMPDIR nem remove conteúdo copiado para outro diretório. Por isso a descoberta vem primeiro.

Evite rm -rf /tmp/* e comandos amplos semelhantes. Eles podem interromper outros processos, excluir material necessário para uma investigação e criar a falsa impressão de que /tmp era o único local a examinar. Exclua apenas diretórios criados pelo seu launcher e nomes que o código de limpeza consiga provar que pertencem a ele.

Se um segredo pode ter escapado, altere ou revogue-o antes de iniciar uma longa campanha de limpeza. Um token de API ativo copiado para um log desconhecido é uma via de acesso atual. O nome do arquivo é menos urgente que a autoridade concedida pelo token. Depois, procure cópias em ferramentas de backup, discos compartilhados, artefatos de CI, agregadores de logs e sistemas de busca de endpoints. Excluir o original sem tratar das cópias mantém a exposição.

O armazenamento local criptografado reduz o risco de perda do dispositivo, mas não protege contra outro processo executado pela mesma conta de usuário desbloqueada. As permissões de arquivo continuam importantes. O modo 700 de um diretório diz que outras contas locais não devem navegá-lo. Isso não impede um processo do agente que já executa como você, nem um cliente de sincronização que você autorizou a ler seu diretório pessoal.

Uma fronteira de credenciais elimina os payloads mais perigosos

A limpeza tem um limite. Se o agente recebe um token de produção em um prompt, variável de ambiente, arquivo de configuração ou saída de comando, ele pode colocá-lo em qualquer arquivo que consiga gravar. É possível reduzir as consequências, mas não tornar essa arquitetura segura apenas com uma boa arrumação.

Mantenha a posse dos segredos fora do processo do agente. O agente deve expressar uma intenção como «enviar esta requisição de implantação para este endpoint aprovado» ou «executar este comando SSH usando esta conexão nomeada». Um responsável local pelas credenciais deve decidir se autoriza a ação, inserir a credencial, executá-la e registrar o resultado. Se não precisa do token, o agente nunca precisa receber um token fictício.

Isso também torna menos vaga a revisão dos arquivos temporários. Você pode examinar os diretórios temporários do agente em busca de entradas do usuário, código gerado e dados retornados. Não precisa presumir que cada arquivo pode conter todos os segredos de produção disponíveis ao agente.

Um modelo fixo de aprovação tem uma vantagem operacional sobre uma pilha de regras personalizadas. As pessoas conseguem explicá-lo durante um incidente. O Sallyport mantém o cofre bloqueado até que a autenticação local o abra, pede autorização quando um novo processo de agente age pela primeira vez e pode exigir aprovação para cada uso de credenciais selecionadas. Isso controla a autoridade de forma clara, em vez de tentar adivinhar se um comando gerado parece suspeito.

Não confunda autorização de ação com minimização de dados. Uma chamada aprovada pode retornar um corpo de resposta sensível, e o agente pode gravá-lo em um arquivo do projeto, cache ou transcript. Projete respostas com o menor resultado útil. Se uma tarefa precisa apenas do identificador e do status da implantação, não retorne um documento de configuração inteiro. Se a API oferece filtragem no servidor, use-a.

O SSH merece atenção especial porque a saída de comandos remotos não tem limites definidos. Um comando que lê um arquivo de configuração, exibe variáveis de ambiente após um erro ou executa um utilitário de implantação detalhado pode enviar segredos de volta ao agente. Trate a saída SSH como dados que precisam de destino, período de retenção e regra de revisão. A credencial pode estar protegida enquanto a saída retornada continua perigosa.

Dê a cada execução um responsável, um diretório e uma expiração

Uma política de limpeza funciona quando associa os arquivos a uma execução específica. Um script noturno genérico não sabe se um diretório temporário pertence a um processo ativo, a um job com falha que merece investigação ou a outro aplicativo. Um launcher de agente sabe.

Use um identificador de execução no nome do diretório temporário, registre o horário de início e mantenha, fora dele, um pequeno manifesto com apenas metadados não sensíveis. O manifesto deve indicar qual diretório o launcher criou, qual processo é responsável por ele, quando deve expirar e se a execução terminou. Não coloque argumentos de comandos, corpos de requisições ou valores de ambiente nesse manifesto.

Um ciclo de vida prático tem quatro ações:

1. Crie um diretório temporário privado antes de iniciar o agente.
2. Defina as variáveis de ambiente de caminhos temporários para o agente e os auxiliares que você controla.
3. Remova o diretório na saída normal e marque o manifesto como concluído.
4. Faça um job agendado sinalizar diretórios abandonados que ultrapassem um limite definido para revisão humana.

O job agendado deve sinalizar, e não apagar automaticamente, diretórios de execuções incompletas. Um processo ainda pode estar gravando. Uma implantação com falha pode exigir evidências. Depois que uma pessoa confirmar que o diretório foi abandonado e não é necessário para um incidente, remova-o usando a mesma regra de propriedade.

Não coloque o diretório temporário dentro de um repositório. A busca do projeto, os comandos de status do controle de versão, a indexação da IDE, os observadores de arquivos e os clientes de backup prestam atenção aos repositórios. Um diretório irmão em um local temporário controlado pelo usuário costuma ser mais fácil de excluir das ferramentas de desenvolvimento e de destruir como uma unidade.

Tenha cuidado com a limpeza automática iniciada pelo próprio agente. Um agente que pode escolher caminhos arbitrários de limpeza pode excluir arquivos-fonte ou evidências. O launcher deve construir o caminho, mantê-lo em seu próprio estado e excluir apenas caminhos que correspondam ao padrão de nomes gerado por ele, depois de canonicalizá-los. A interpolação do shell já causa acidentes suficientes sem acrescentar geração autônoma de texto ao processo.

O objetivo não é não reter nada. Você precisa de evidências operacionais suficientes para responder qual execução fez uma requisição e se ela foi bem-sucedida. Mantenha esse registro separado dos payloads brutos e da saída completa, com campos deliberadamente simples.

Logs e backups precisam de uma decisão de retenção

Um arquivo temporário se torna um registro retido no momento em que outro sistema o copia. Software de backup, pastas de sincronização na nuvem, ferramentas de proteção de endpoint, relatórios de falha, envio de artefatos de CI e logging centralizado podem prolongar sua vida. O caminho original pode desaparecer enquanto a cópia útil permanece em outro lugar.

Liste todos os processos que podem ler os diretórios usados pelas execuções do agente. Em uma máquina de desenvolvimento, isso costuma incluir cliente de backup, indexador do editor, interface de controle de código, gravador de terminal e scanner de malware. Algumas cópias são desejáveis. O ponto é escolhê-las e definir sua retenção, em vez de descobri-las depois que um token aparece em um arquivo de restauração.

Mantenha a saída bruta de diagnóstico fora de diretórios sincronizados automaticamente. Isso inclui pastas da área de trabalho, pastas compartilhadas de projetos e qualquer workspace que um cliente de CI empacote como artefato. Se uma ferramenta precisar produzir uma resposta grande para revisão, armazene-a em um diretório privado com permissões restritas, defina uma expiração e exclua-o da sincronização rotineira quando suas ferramentas permitirem.

Um registro de auditoria encadeado por hashes é diferente de um dump de depuração. Um registro de auditoria deve responder quem solicitou uma ação, quando ela ocorreu e qual categoria de resultado foi obtida, sem duplicar segredos. O Sallyport projeta os diários Sessions e Activity a partir de um log de auditoria criptografado, e sp audit verify pode verificar a cadeia de hashes offline sem uma chave do cofre. Assim, é possível manter evidências da atividade do agente sem tratar todo payload bruto como requisito de auditoria.

A retenção precisa cobrir exceções. Durante um incidente, não deixe que o temporizador normal de limpeza destrua as evidências necessárias para entender o ocorrido. Restrinja o acesso, preserve deliberadamente os arquivos relevantes e documente sua localização. Depois, altere as credenciais afetadas e remova o material preservado quando o processo do incidente não precisar mais dele. A retenção de incidentes não é motivo para despejar toda a saída comum do agente em armazenamento permanente.

Examine também os backups depois de mudar a política. Excluir um novo diretório temporário só afeta execuções futuras de backup. Snapshots existentes podem ainda conter material antigo até que o prazo de retenção do provedor expire. Registre esse fato na resposta à exposição, em vez de fingir que um comando rm reescreveu a história.

Teste a limpeza como um invasor local curioso

Uma política de limpeza que nunca enfrentou um teste de busca é uma promessa, não um controle. Teste-a usando um canário falso que se pareça com as strings que você teme perder e depois inspecione a máquina como se outro processo local quisesse encontrá-lo.

Execute primeiro o teste em condições normais. Coloque o canário em um arquivo de entrada, em um campo de requisição e em uma saída de comando simulada. Execute o agente até o fim, aguarde o hook de limpeza e procure no local temporário, caches, logs, diretório do projeto, histórico do shell e diretórios de suporte prováveis. Registre cada ocorrência e explique-a.

Depois, teste os casos incômodos. Force uma falha do processo. Cancele-o durante uma requisição de rede. Ative o modo de log mais detalhado compatível com a ferramenta. Execute-o a partir de uma IDE, não de um terminal. Use um contêiner com uma montagem vinculada ao host. Cada variação pode encaminhar a saída para um local diferente.

Pesquise pelo marcador, não pelo nome do arquivo. Um payload copiado pode receber um nome aleatório, entrar em um banco SQLite ou ser compactado em um arquivo. Se um binário ou banco de dados contiver o canário, identifique quem o gravou e decida se precisa de configuração, exclusão, redação ou de uma fronteira de execução diferente.

Mantenha um pequeno registro de teste com a versão do agente, a versão do sistema operacional, os plugins ativados, os comandos exercitados, os caminhos encontrados e o resultado da limpeza. Atualize-o quando adicionar uma ferramenta capaz de executar comandos ou enviar requisições. É um trabalho simples, mas detecta regressões que uma revisão do código-fonte voltada à segurança pode não encontrar.

Faça hoje o primeiro teste com um marcador inofensivo. Se ele aparecer em um local inesperado, corrija o componente que grava antes de criar um script de exclusão mais elaborado. O arquivo temporário mais seguro é aquele que nunca recebeu uma credencial ou uma resposta sensível.