Gerenciador de segredos para agentes de IA: armazenamento não é controle de ações

Um gerenciador de segredos para agentes de IA é necessário, mas não resolve a parte perigosa: o que acontece depois que um agente pede uma credencial. Se o gerenciador devolver o valor em texto simples ao processo do agente, o segredo já atravessou o limite que você precisava proteger.

Essa distinção parece preciosista até que um agente siga uma instrução contaminada, invoque uma ferramenta inesperada, grave um arquivo de diagnóstico ou entre em contato com o host errado. Um cofre pode manter um token criptografado por anos e desfazer boa parte desse trabalho em uma única chamada de recuperação. Para o trabalho com agentes, o desenho mais seguro mantém a credencial em um executor confiável e permite que o agente solicite uma ação autenticada.

Um cofre protege o armazenamento, não o uso da credencial

Um gerenciador de segredos tradicional responde a uma pergunta de armazenamento: quem pode recuperar este valor? Agentes autônomos criam uma pergunta sobre o uso: este processo pode realizar esta ação específica com esse valor, neste momento e contra este destino?

A maioria das equipes começou com hábitos sensatos. Tirou tokens dos repositórios, criptografou-os em repouso, fez a rotação depois de um commit acidental e os injetou em um ambiente de build. Esses hábitos funcionam bem para a implantação comum de aplicações. Um job de build costuma ter um script fixo, uma duração limitada e um conjunto conhecido de endpoints. O ambiente ainda pode ser amplo demais, mas uma pessoa escreveu os comandos antes do início do job.

Um agente é diferente. Ele gera comandos, escolhe ferramentas, segue o texto de issues, lê arquivos escritos por outras pessoas e pode revisar o próprio plano. Dar a ele DEPLOY_TOKEN em uma variável de ambiente significa que todo subprocesso iniciado por ele pode ler o token. O mesmo vale para um comando de shell que imprime o ambiente, um depurador, um hook de instalação de pacote ou uma ferramenta não confiável escolhida pelo agente porque um documento mandou usá-la.

O gerenciador de segredos não falhou nessa situação. Ele fez exatamente o que foi configurado para fazer: entregou um segredo a uma carga de trabalho autorizada. O modelo de autorização é que era amplo demais para um ator capaz de escolher sua própria próxima operação.

Mantenha estas duas permissões separadas:

• Permissão para identificar uma credencial por uma referência estável.
• Permissão para usar essa credencial em uma ação de saída descrita.

A primeira permissão pode ser segura para um agente. A segunda precisa de restrições compatíveis com a ação. Uma requisição como POST https://deploy.example.internal/releases expressa algo que um revisor pode avaliar. Uma requisição como read production token entrega um ativo cujos usos futuros não podem ser avaliados no momento da recuperação.

Isso também corrige uma afirmação comum, mas pouco útil: «o agente já tem execução de código, então esconder o segredo não muda nada». A execução de código em uma máquina de desenvolvedor já é grave. Um token bearer copiado dessa máquina cria um segundo problema: pode sair dela, sobreviver ao fim da sessão e funcionar em um computador completamente diferente. Mantê-lo fora do processo não elimina todo o risco. Remove uma forma portátil e duradoura de acesso que os atacantes valorizam.

A RFC 6750 deixa isso claro para tokens bearer do OAuth. A definição afirma que qualquer parte que possua um token bearer pode usá-lo. O protocolo não pergunta se essa parte é o agente aprovado, um plugin malicioso ou alguém que encontrou um arquivo de log. Tratar tokens bearer como uma saída comum de ferramenta ignora sua propriedade fundamental.

O acesso de leitura transforma erros de instrução em vazamentos de credenciais

Um agente com acesso a segredos em texto simples pode vazar uma credencial sem tentar exfiltrá-la. O caminho perigoso muitas vezes parece normal até a última etapa.

Imagine um agente encarregado de diagnosticar por que uma API de implantação rejeitou uma versão. Ele lê um documento do repositório que manda coletar um pacote de suporte. O script do pacote executa env, copia arquivos de configuração e arquiva a saída. O agente cria o arquivo fielmente e o anexa a um ticket ou o envia para um sistema de chat. O token nunca apareceu no terminal, mas passou pelo ambiente, pelo arquivo, pelo ticket e por cada sistema de backup ou notificação ligado a esse ticket.

Isso não é apenas injeção de prompt. A injeção de prompt é uma rota até a ação problemática, mas uma credencial copiada cria seu próprio raio de impacto depois que a instrução original desaparece. Outra pessoa que leia o ticket pode baixá-la. Um scanner automatizado pode indexá-la. Um destinatário pode reutilizá-la muito depois do fim da execução do agente.

A mesma falha aparece de formas mais discretas:

• Um cliente HTTP detalhado imprime um cabeçalho Authorization durante uma nova tentativa.
• Um arquivo de histórico do shell captura um token passado na linha de comando.
• Um fixture de teste registra um cabeçalho de requisição e acaba sendo enviado ao repositório.
• Um processo filho herda uma variável de ambiente de que nunca precisou.
• Um modelo inclui um segredo na explicação porque o segredo apareceu na saída de uma ferramenta.

A resposta mais popular é a redação. A redação ajuda depois de um erro, mas não pode provar que todo caminho de saída, formato de arquivo, rastreamento, subprocesso e serviço remoto tratou o valor corretamente. Ela também falha com formatos de segredo desconhecidos e tokens divididos entre vários campos. Não transforme a redação na principal barreira em torno de credenciais que o agente jamais deveria ter lido.

Uma organização melhor reduz as entradas do agente. O agente envia uma intenção sem material de credencial: método HTTP, URL permitida, corpo da requisição e referência da credencial. Um componente confiável verifica a requisição, adiciona internamente os dados de autenticação, envia a requisição e retorna uma resposta com os cabeçalhos sensíveis removidos.

Esse limite oferece uma resposta melhor para a investigação de incidentes. Se um agente se comportar mal, revogue a sessão ou negue ações posteriores. Se você descobrir uma instrução maliciosa depois da execução, não precisará começar presumindo que toda transcrição, arquivo temporário e artefato remoto agora contém um token de produção.

A execução de ações é uma interface diferente da recuperação de segredos

Um limite de execução deve receber uma operação, não entregar ao agente um valor opaco esperando que ele o use com cuidado. Essa é a distinção que as equipes mais confundem, e errá-la transforma o cofre em uma máquina de fornecer credenciais.

Para HTTP, o agente pode precisar expressar uma requisição como esta:

{
  "credential": "release-api",
  "method": "POST",
  "url": "https://deploy.example.internal/releases",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "version": "2025.03.8",
    "environment": "staging"
  }
}

O executor resolve release-api no cofre protegido, injeta o esquema de autenticação correspondente e faz a requisição. O agente pode receber um resultado com este formato:

{
  "status": 201,
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "release_id": "rel_4821",
    "state": "queued"
  }
}

A resposta não deve incluir o cabeçalho Authorization injetado, uma cópia da credencial ou diagnósticos de transporte que a exponham. Parece óbvio, mas o desenho do limite falha quando desenvolvedores tratam o registro de requisições e respostas como uma parte inofensiva da infraestrutura.

Para SSH, o agente deve enviar um host, uma conta, um comando e talvez uma referência de credencial. O executor usa a chave privada durante a troca de autenticação SSH e retorna a saída padrão, o erro padrão e o status de saída. O agente nunca recebe um bloco PEM nem um socket de agente que possa reutilizar em outro lugar.

Não confunda isso com um proxy geral. Um proxy encaminha tráfego arbitrário e pode inspecioná-lo ou modificá-lo. Um executor de ações tem uma função mais estreita: possui as credenciais, executa operações HTTP e SSH nomeadas, registra a decisão e retorna um resultado limitado. Essa restrição é uma vantagem. Cada recurso que aceita outro protocolo ou introduz um desvio genérico oferece ao agente mais maneiras de transformar autoridade em uma requisição impossível de revisar.

A interface de requisição ainda precisa de disciplina. Uma referência de credencial sozinha não basta. Se release-api puder autenticar em muitos hosts ou aceitar uma URL arbitrária, o agente poderá direcionar uma credencial válida para um endpoint controlado por um atacante ou para um serviço interno menos protegido. Vincule as credenciais ao esquema de autenticação e aos destinos pretendidos. Rejeite truques de URL, como segmentos inesperados de informações do usuário, redirecionamentos para novos hosts ou um host que apenas se pareça com o aprovado.

O executor também precisa decidir o que retorna. Uma resposta completa de API pode conter dados de usuários, tokens de acesso emitidos por um serviço downstream ou detalhes de configuração que não deveriam voltar ao contexto do modelo. Retornar apenas os campos necessários para a próxima operação costuma tornar o agente mais confiável e mais seguro.

SSH precisa de controle de comandos, não apenas de proteção da chave privada

Esconder uma chave privada SSH ajuda, mas não torna seguros comandos remotos arbitrários. A autenticação informa a um servidor quem se conectou. Ela não limita o que essa conta pode fazer depois que o shell começa.

A RFC 4252 descreve a autenticação SSH por chave pública como uma assinatura sobre os dados da troca. A chave privada permanece privada durante essa troca, e por isso muitas pessoas consideram o SSH mais seguro que um token de API colocado em uma variável de ambiente. Isso é verdade em um sentido restrito: o cliente prova que possui a chave, em vez de enviá-la pela rede. Ainda assim, um processo que pode pedir a um agente SSH que assine pode obter acesso a sistemas que confiam nessa chave.

O encaminhamento do agente SSH merece uma avaliação direta. Ele permite que um servidor remoto use seu agente de autenticação local durante a conexão. O servidor remoto não recebe o arquivo da chave privada, mas pode pedir assinaturas pelo socket encaminhado. Isso só é aceitável quando você confia nessa máquina remota com a capacidade prática de se autenticar como você enquanto o canal de encaminhamento existir. Não é um limite adequado para um agente autônomo capaz de escolher onde se conectar e qual comando de configuração executar.

Uma interface de ações SSH mais segura nomeia explicitamente o destino e o comando. Ela deve registrar ambos, porque ssh deploy@host "./deploy staging" e ssh deploy@host "cat /etc/shadow" têm o mesmo evento de autenticação, mas consequências muito diferentes.

As restrições no lado remoto continuam necessárias. Use contas separadas para funções separadas. Dê a uma conta de implantação acesso aos diretórios de implantação, em vez de acesso administrativo. Quando o servidor oferecer suporte, configure comandos forçados ou wrappers de comandos restritos para credenciais de automação. Evite uma chave pessoal compartilhada de administrador para tarefas do agente só porque ela já está presente em uma estação de trabalho.

Uma requisição SSH prática pode ser tão pequena quanto esta:

{
  "credential": "staging-deployer",
  "host": "staging-runner.internal",
  "user": "deploy",
  "command": "./release apply 2025.03.8",
  "timeout_seconds": 120
}

Essa requisição dá ao revisor algo concreto para aprovar. Também fornece algo concreto para auditar depois. Se o agente precisar de um shell interativo, pare e pergunte por quê. Shells interativos são úteis para pessoas que reparam um sistema. São um padrão ruim para agentes porque transformam uma ação limitada em uma sessão aberta, na qual cada comando posterior herda a mesma autoridade.

A verificação do host também importa. Um executor deve usar a verificação de hosts conhecidos, em vez de aceitar qualquer chave apresentada porque um modelo foi instruído a se conectar. Se o agente puder desativar a verificação do host, um atacante da rede poderá receber comandos, observar a saída e talvez capturar dados enviados pelo agente depois do login.

A aprovação deve identificar o processo e o escopo da ação

Um botão de aprovação humana é fraco se informa apenas que «um agente» solicitou acesso. Você precisa saber qual processo local fez a solicitação, qual autoridade assinada o iniciou e se a aprovação vale para esta execução ou para todas as execuções futuras.

As confirmações por chamada parecem mais seguras, por isso as equipes costumam começar com elas. Depois o agente faz uma longa sequência de leituras inofensivas, verificações de status e chamadas seguintes. A pessoa que observa recebe uma parede de diálogos quase idênticos e começa a aprovar por ritmo. Essa reação é compreensível e destrói o controle pretendido.

A aprovação por sessão funciona melhor para o trabalho comum quando vincula uma aprovação à vida útil de um único processo de agente. A pessoa aprova uma execução específica depois de ver sua identidade. O agente pode concluir a sequência esperada até sair. Um novo processo recebe uma nova decisão. Isso limita o efeito de um processo reiniciado ou substituído que por acaso use o mesmo diretório do projeto.

Reserve a aprovação por chamada para credenciais cujo uso tenha uma consequência irreversível ou cara. Credenciais de lançamento em produção, tokens para excluir contas ou uma identidade SSH que alcance sistemas sensíveis entram nessa categoria. Chamadas de status somente leitura normalmente não entram.

O escopo da aprovação deve responder a quatro perguntas em linguagem simples:

1. Qual autoridade de assinatura de código ou executável iniciou esta requisição?
2. Qual referência de credencial será usada?
3. Qual destino ou host receberá a ação?
4. A decisão expira quando este processo termina ou esta chamada exige sua própria confirmação?

Evite uma linguagem de políticas, a menos que você tenha uma equipe para mantê-la e testes que comprovem seu efeito. Mecanismos de políticas atraem engenheiros porque prometem uma resposta precisa para cada situação. Na prática, um conjunto de regras vira um programa de autorização não documentado, e as equipes concedem uma exceção ampla quando ele impede o trabalho. Um conjunto pequeno e visível de barreiras é mais fácil de inspecionar e mais difícil de enfraquecer acidentalmente.

O Sallyport usa uma sequência fixa de decisões: um cofre bloqueado nega todas as ações, um novo processo de agente exige autorização de sessão por padrão e credenciais selecionadas podem exigir aprovação a cada uso. O modelo permanece intencionalmente pequeno porque o limite de credenciais de um agente deve tornar o estado da aprovação evidente, em vez de obrigar administradores a depurar uma sintaxe de autorização.

Um registro de auditoria deve esclarecer a situação depois da execução

Você precisa de duas visões da atividade do agente: uma para a execução e outra para cada chamada que usa credenciais. Um registro de sessão responde quem executou o agente e quando sua autoridade terminou. Um registro de ação responde qual destino, método ou comando, referência de credencial, decisão e resultado ocorreram.

As equipes costumam registrar apenas uma transcrição do terminal. Isso não basta. Uma transcrição registra o que o agente imprimiu, não necessariamente o que um executor enviou. Ela pode omitir chamadas em segundo plano, conter uma saída alterada ou revelar segredos se o agente tiver acesso a eles. Por outro lado, um log bruto de pacotes ou requisições pode registrar dados sensíveis demais para ser mantido com segurança.

Registre o ponto de decisão, não cada byte. Para HTTP, capture método normalizado, host, caminho, referência da credencial, status da resposta, horário, identidade da sessão e resultado da aprovação. Registre um resumo limitado ou um digest do corpo da requisição quando precisar de correlação sem reter dados de clientes. Para SSH, capture o host verificado, o usuário remoto, o comando, o status de saída e os mesmos campos de sessão e aprovação.

Um registro deve permitir responder: «Qual processo autorizado usou a credencial de implantação para executar qual operação, e uma pessoa aprovou esse uso?» Se não puder, talvez ajude na depuração, mas ajudará pouco depois de um incidente.

A evidência contra adulteração aumenta o valor desse registro. Um arquivo de log simples na mesma máquina pode ser editado por um processo com acesso local suficiente. Uma cadeia de hashes vincula cada evento ao anterior, portanto remover ou reescrever um registro antigo interrompe a verificação dos registros seguintes. A criptografia protege o conteúdo, enquanto o encadeamento fornece evidência de que a sequência foi alterada.

O Sallyport projeta os diários de sessões e de ações a partir de um registro de auditoria criptografado e encadeado por hashes, e sp audit verify pode verificar a cadeia offline sobre o texto cifrado sem uma chave do cofre. Essa separação importa durante uma investigação: um revisor pode testar a integridade dos logs sem obter acesso às credenciais ou ao conteúdo das requisições mantidos pelo cofre.

Uma cadeia não torna magicamente confiável um endpoint comprometido. Um atacante que controla a aplicação em execução ainda pode tentar ações antes que você reaja, e alguém com controle antes da gravação de uma entrada pode afetar o que será registrado. A cadeia oferece evidência forte sobre o histórico armazenado. Combine-a com revogação rápida, armazenamento local protegido e logs do lado remoto se precisar de um relato mais completo do evento.

A falha começa quando o agente recebe uma saída conveniente

Os desenhos mais perigosos costumam começar com uma exceção razoável. Alguém diz que o gateway é restritivo demais para uma integração, então o agente recebe um comando de shell genérico com um token no ambiente. Ou uma ferramenta de implantação precisa de SSH, e a equipe ativa o encaminhamento em vez de definir a ação SSH específica. Ou um engenheiro adiciona um endpoint de depuração que retorna cabeçalhos porque isso facilita os testes.

Cada exceção resolve um problema local e reabre a recuperação de segredos com outro nome.

Percorra uma configuração conhecida. Um agente de programação tem um token de serviço no ambiente para poder executar um comando de lançamento. O agente lê um comentário de pull request que pede uma investigação sobre uma versão que falhou. Um script auxiliar no repositório chama um comando de diagnóstico. Esse comando exporta variáveis de ambiente para um arquivo de suporte. O agente envia o arquivo a um sistema de issues de terceiros porque o comentário pediu a abertura de um ticket.

Nenhum atacante precisou conhecer o valor do token antecipadamente. Bastou influenciar um texto que o agente tratou como instrução e apontá-lo para um caminho de ferramenta que expunha o estado herdado. Revogar a sessão do agente depois da descoberta não retira o arquivo. Fazer a rotação do token se torna obrigatório, e a equipe precisa identificar todos os lugares por onde o arquivo passou.

Um executor controlado muda essa sequência. O script auxiliar ainda pode ser executado, e o agente ainda pode consultar o status da versão por meio de uma ação de API aprovada. Mas ele não consegue ler o token do ambiente, porque o token nunca foi colocado ali. Se o script tentar fazer uma nova chamada com credencial, o executor a registra e aplica a decisão de sessão ou de chamada. O arquivo de suporte tem menos informações valiosas para roubar.

Não conceda uma saída de emergência apenas porque um agente afirma precisar de uma ferramenta para concluir uma tarefa. Peça a menor operação de que a ferramenta precisa. Se ela precisar chamar um endpoint de API, exponha essa operação. Se precisar de um comando de implantação, exponha esse comando. Se a necessidade for realmente ampla, trate a solicitação como autoridade ampla e exija que uma pessoa use um fluxo separado e deliberado.

Construa o limite em torno das ações que importam

Comece pelas credenciais cuja perda exigiria uma rotação emergencial ou permitiria uma mudança significativa em produção. Você não precisa mover todos os tokens de desenvolvimento no primeiro dia. Um limite parcial ao redor das credenciais mais perigosas é melhor que uma migração completa que ninguém termina.

Primeiro, faça um inventário de como os agentes obtêm autoridade hoje. Pesquise scripts de inicialização dos agentes, configurações do shell, arquivos de transferência do CI, configurações de ferramentas, arquivos .env locais e wrappers de comandos. Marque cada lugar que entrega a um agente um token, senha, chave privada, sessão de nuvem ou socket de autenticação encaminhado. Esse inventário muitas vezes revela que o agente tem mais autoridade por meio das configurações herdadas do desenvolvedor do que qualquer pessoa pretendia.

Depois, substitua a entrega em texto simples por solicitações de ações. Defina referências de credenciais por finalidade, não por pessoa nem por um rótulo de ambiente vago. staging-deployer explica mais que shared-key-2. Crie referências separadas quando dois usos precisarem de requisitos de aprovação ou destinos diferentes.

Para cada referência, decida o seguinte antes de automatizá-la:

• Quais hosts, métodos e caminhos HTTP, ou quais hosts, usuários e comandos SSH, fazem parte da sua função?
• Um novo processo de agente precisa de aprovação explícita antes de poder usá-la?
• Cada uso precisa de confirmação porque a ação é destrutiva ou difícil de reverter?
• Quais campos do resultado o agente precisa receber para continuar o trabalho?
• Quais registros permitirão explicar a ação mais tarde sem reter material secreto?

Teste os caminhos de rejeição com o mesmo cuidado dedicado ao caminho esperado. Execute um processo de agente sem aprovação e confirme que ele não pode agir. Tente um nome de host parecido, um redirecionamento para outro host, um comando fora do caminho esperado de implantação e uma tentativa de imprimir a referência da credencial como se ela fosse um valor. Confirme que uma sessão revogada não pode continuar fazendo requisições.

Teste também o lado humano. Se as aprovações chegarem com tanta frequência que você pare de lê-las, os escopos estão errados. Se um diálogo não puder informar qual processo fez a solicitação, a identidade do processo é fraca demais. Se o agente não conseguir concluir o trabalho normal sem pedir repetidamente uma saída genérica, a interface de ações precisa de outra operação cuidadosamente limitada, não de um despejo de segredos.

O padrão de sucesso é simples: um agente consegue realizar o trabalho aprovado, mas uma transcrição, subprocesso, plugin ou instrução contaminada não consegue transformar esse trabalho na posse de uma credencial reutilizável. Construa em direção a esse padrão antes que a próxima implantação urgente faça uma exceção conveniente parecer inofensiva.