Aliases de credenciais para agentes de IA: ações locais mais seguras

Os agentes devem solicitar uma conexão pelo nome, sem receber a credencial que faz essa conexão funcionar. Parece uma pequena escolha de design de API. Na prática, é a diferença entre um agente que pode agir dentro de um limite e um processo de agente que carrega vários segredos reutilizáveis.

Já vi equipes chamarem um segredo de GITHUB_TOKEN, colocá-lo no ambiente de um agente e se parabenizarem porque a interface da ferramenta parecia organizada. O token ainda vai parar na memória do processo, no histórico do shell, na saída de depuração, nos processos filhos e, às vezes, nas próprias anotações de trabalho do agente. Mudar o nome da exposição não reduz a exposição.

Aliases de credenciais para agentes de IA funcionam quando um executor local confiável resolve um nome curto e legível para uma conexão e executa a solicitação autenticada por conta própria. O agente solicita repo-release-prod; o executor injeta a credencial no momento do uso; o agente recebe um código de status, um corpo de resposta filtrado para remover segredos ou a saída do comando. O segredo nunca entra como entrada ou saída do ciclo do agente.

Esse limite precisa ser projetado com mais cuidado do que a maioria das primeiras versões recebe. Um alias pode oferecer um identificador operacional limpo, rotação simples e registros de auditoria úteis. Também pode virar uma etiqueta decorativa sobre uma autoridade ampla e permanente se você não definir o que o nome permite, quem pode invocá-lo e como interrompê-lo.

Um alias nomeia uma autoridade, não uma string oculta

Um alias de credencial útil nomeia uma conexão de serviço com uma finalidade específica. Ele não nomeia um banco de segredos que o agente pode consultar, nem promete que toda solicitação que carrega o alias é aceitável.

Considere payments-prod. Esse nome é vago demais para um agente autônomo. Ele permite ler faturas, emitir reembolsos, editar dados de contas ou baixar relatórios? Um único token bearer pode tecnicamente fazer tudo isso, mas o alias não deve apagar a distinção. Nomes melhores revelam a intenção operacional: payments-invoice-read-prod e payments-refund-review-prod informam ao operador o que ele está prestes a autorizar e tornam o registro de auditoria compreensível seis meses depois.

As pessoas costumam misturar três coisas diferentes:

• Uma referência de segredo identifica o material armazenado, como um caminho de cofre ou ID de segredo.
• Um alias de credencial identifica uma conexão autenticada utilizável.
• Um nome de capacidade identifica uma operação permitida, como publicar uma versão ou ler um log de compilação.

Em uma configuração pequena, esses conceitos podem se relacionar diretamente, mas não devem se tornar a mesma coisa por acidente. Uma referência de segredo pode apontar para um token capaz de chamar muitos endpoints. Uma conexão pode exigir um token e um certificado de cliente. Uma capacidade pode precisar de conexões diferentes em ambientes diferentes. Se você os juntar, rotação, revisão e resposta a incidentes ficam mais difíceis, porque ninguém consegue dizer qual parte mudou.

Prefiro aliases que incluam o serviço de destino, o ambiente e a tarefa, sem indicar o tipo de credencial. artifact-publish-prod é melhor que artifact-api-token-2. O primeiro nome sobrevive a uma migração de um token estático para uma troca de curta duração. O segundo incorpora um detalhe de implementação a cada prompt do agente, chamada de ferramenta, teste e procedimento operacional.

Não permita que os agentes enumerem todos os aliases por padrão. Uma lista de nomes de conexão costuma revelar nomes de serviços internos, ambientes e fluxos privilegiados. Além disso, a enumeração transforma um agente restrito em um agente curioso. Entregue à tarefa o pequeno conjunto de nomes de que ela precisa ou exponha uma ferramenta orientada à operação que escolha a conexão internamente.

Um segredo fora do contexto precisa ficar fora de todos os caminhos

Manter o token fora do prompt principal do modelo é necessário, mas está longe de ser suficiente. Uma credencial escapa quando qualquer componente na árvore de processos acessível ao agente consegue lê-la ou convencer outro componente a imprimi-la.

Considere um design falho bastante comum. Um agente de programação chama um helper local com connection=deploy-prod. O helper consulta um token de API e inicia um cliente de linha de comando com esse token em uma variável de ambiente. O comando falha. Um wrapper de diagnóstico imprime o ambiente em um arquivo de log. O agente tem acesso ao diretório de logs do workspace e lê o token para explicar a falha.

Ninguém pretendia revelar o segredo. A arquitetura fez isso porque o helper tratou uma variável de ambiente como um canal privado. Ela não é privada para processos filhos, relatórios de falha, diagnósticos ou qualquer comando que consiga inspecionar o próprio ambiente. Colocar credenciais nos argumentos do comando é pior, porque a inspeção de processos e o histórico do shell podem expô-las.

O executor local deve manter a credencial em seu próprio armazenamento protegido, construir a solicitação autenticada na memória e retornar um resultado deliberadamente limitado. Para HTTP, normalmente ele mesmo adiciona o cabeçalho de autorização. Para SSH, ele seleciona a chave privada ou chama um helper capaz de usar a chave sem entregar ao agente o caminho ou o conteúdo do arquivo.

O caminho de resposta merece a mesma atenção. Algumas APIs retornam credenciais durante a criação de tokens, webhooks podem repetir dados de autorização e relatórios de erro podem incluir cabeçalhos da solicitação. O executor precisa de uma política de resposta que remova cabeçalhos conhecidos por carregar segredos e evite refletir a forma como sua própria solicitação foi construída. Isso não é motivo para reescrever silenciosamente dados de negócio. É motivo para decidir quais partes da solicitação e da resposta o agente tem direito de ver.

Um teste limpo é mais útil que um diagrama de arquitetura. Peça ao agente para recuperar o valor do alias, exibir as configurações das ferramentas, provocar um erro de autenticação, inspecionar processos filhos em execução se puder e ler todos os locais de log aos quais tiver acesso. O resultado esperado é sem graça: ele encontra um nome e os resultados das ações, mas nenhum token, senha, chave privada ou solicitação assinada reutilizável.

O escopo da conexão precisa caber na superfície da ação

Um alias só é restrito na medida em que a autoridade por trás dele também é. Um token de administrador perfeitamente oculto continua sendo um token de administrador.

Para serviços HTTP, o escopo começa nas permissões da conta de serviço ou do token. Dê a um agente de lançamentos permissão para criar uma versão e enviar o artefato necessário. Não acrescente administração do repositório, participação na organização, acesso a faturamento ou personificação de usuários só porque isso pode ser útil mais tarde. Essa necessidade futura deve gerar uma nova revisão e, em geral, uma conexão diferente.

As restrições de endpoint pertencem ao executor quando o modelo de autorização do serviço não consegue expressá-las. É aqui que as equipes costumam recorrer a uma linguagem de políticas grande. Ela parece flexível em uma demonstração e vira um problema de manutenção quando um operador precisa prever se uma solicitação desconhecida será aceita. Se precisar restringir endpoints, mantenha as regras visíveis e pequenas: método permitido, host, família de caminhos e credencial esperada. Trate corpos de solicitação incomuns e redirecionamentos como casos que exigem uma decisão consciente, não como exceções acidentais.

O SSH exige a mesma disciplina, embora seus controles pareçam diferentes. Uma chave que abre um shell interativo oferece ao agente uma superfície de ação enorme. Prefira uma conta que execute a tarefa necessária em um diretório limitado ou um comando forçado que aceite a operação exata pretendida. Não presuma que um alias de host em ~/.ssh/config resolva isso. Esse alias escolhe um destino para o cliente, mas não restringe o que acontece depois da autenticação.

O manual do OpenSSH para authorized_keys documenta opções como command=, no-pty, no-port-forwarding e restrict. Elas são ferramentas práticas para conexões de máquina. Também têm riscos específicos: um comando forçado precisa validar seus argumentos, e uma restrição que bloqueia o encaminhamento de portas não torna segura uma conta de shell ampla. Primeiro, leia as permissões efetivas da conta. Depois, use as opções do SSH para reduzir os caminhos de que você não precisa.

Não use um alias para staging e produção só porque o endpoint muda em um parâmetro da URL. Um agente comete erros sob pressão, assim como uma pessoa. Nomes separados permitem definir credenciais, tratamento de aprovação e expectativas de auditoria diferentes. Eles também impedem que uma tarefa de staging adquira autoridade de produção por meio de um erro de substituição de string.

O executor precisa autenticar o chamador antes de aceitar o alias

Um alias de credencial não protege nada se qualquer processo local puder invocá-lo. O executor precisa responder claramente a uma pergunta simples: qual processo solicitou essa ação?

IDs de processo, sozinhos, não são uma identidade. Eles têm vida curta e podem ser reutilizados. O nome do processo é ainda pior, porque outro programa pode usar o mesmo nome. No macOS, a autoridade de assinatura de código oferece ao aprovador informações melhores sobre o executável por trás de uma solicitação, embora não torne a ação solicitada segura por si só. O operador ainda precisa avaliar se esse processo assinado deve receber essa conexão nessa sessão.

A autorização por sessão funciona bem para agentes que fazem muitas chamadas relacionadas. A primeira solicitação de um novo processo de agente apresenta a identidade do chamador e a execução solicitada. A aprovação vale para esse processo até que ele seja encerrado. Assim, não é preciso pedir que uma pessoa aprove uma sequência rotineira de pequenas chamadas, preservando ao mesmo tempo um limite entre execuções distintas.

Alguns aliases merecem uma decisão a cada uso. Implantação em produção, operações destrutivas de API e acesso a dados de clientes são candidatos razoáveis. A tela de aprovação deve mostrar o alias, o destino, a operação e a identidade do chamador em linguagem simples. Pedir às pessoas que aprovem um evento opaco é treiná-las a clicar sem ler.

A RFC 6749 faz uma separação útil que os criadores de ferramentas para agentes devem preservar: o servidor de autorização emite tokens de acesso e o servidor de recursos os aceita. O agente não precisa ser nenhum dos dois. Em um design com executor local, o executor pode ser o componente que mantém ou obtém a credencial e envia a solicitação autenticada. O agente continua sendo um solicitante de uma ação descrita de forma restrita. Essa separação é mais limpa do que tratar o agente como um cliente OAuth genérico apenas porque ele pode fazer chamadas HTTP.

Isso não significa que todo agente precise de aprovação interativa. Um worker de compilação controlado pode ter uma conexão limitada e pré-aprovada. A questão é saber se você consegue identificar o chamador e se a autoridade corresponde à tarefa atribuída. Se nenhuma das duas respostas for sólida, o alias apenas escondeu uma elevação de privilégio local atrás de uma interface mais amigável.

A rotação deve trocar o material sem quebrar o nome

O benefício operacional dos aliases aparece durante a rotação. Você substitui o token ou a chave SSH por trás de artifact-publish-prod; o agente continua solicitando o mesmo nome de conexão; nenhum prompt, arquivo-fonte ou configuração do agente precisa receber o novo segredo.

Isso não significa que um alias deva durar para sempre. Mantenha o nome estável apenas enquanto seu significado continuar estável. Se um token passar de acesso somente leitura para acesso de escrita, o nome antigo agora engana. Se a responsabilidade mudar de equipe, a expectativa de aprovação antiga pode deixar de fazer sentido. Se uma credencial passar de um tenant de teste para um tenant de produção, crie um novo alias, mesmo que a API seja idêntica.

A sequência de rotação deve comprovar os dois lados da mudança:

1. Adicione a credencial substituta ao alias existente e faça uma chamada de verificação com escopo limitado pelo executor.
2. Revogue ou desative o material antigo no provedor do serviço e repita a ação esperada do agente.
3. Inspecione o registro de auditoria em busca de novas tentativas malsucedidas ou chamadores inesperados, porque processos antigos costumam aparecer depois de uma rotação.
4. Remova arquivos de credenciais copiados, configurações antigas de ambiente e scripts de emergência que contornavam o executor.

É nesse último item que as rotações costumam falhar na prática. Alguém cria um token temporário para manter uma versão em andamento, deixa-o em uma variável de CI ou em um script local e se esquece dele. O caminho organizado do alias é rotacionado corretamente, enquanto o desvio abandonado continua funcionando. A rotação só termina quando você encontra e fecha o caminho alternativo.

A OWASP Secrets Management Cheat Sheet recomenda rotacionar segredos e aplicar o princípio do menor privilégio. As duas recomendações estão certas, mas geralmente são apresentadas como higiene de armazenamento. Para agentes, a rotação também protege a camada de instruções. Um alias estável significa que o contexto do modelo não contém um segredo que muda e não precisa de uma tarefa de atualização que poderia aparecer em transcrições, mensagens de commit ou saídas de ferramentas.

Os registros de auditoria devem descrever decisões sem registrar segredos

Os logs devem permitir responder quem solicitou uma ação, qual conexão foi solicitada, o que o executor fez e se houve aprovação. Eles nunca devem se tornar uma cópia conveniente do cofre de credenciais.

Um registro de evento prático inclui data e hora, identificador da sessão, identidade do chamador, alias, canal, destino, método ou classe de comando, decisão de autorização e classe do resultado. Em uma chamada HTTP, registrar POST /releases geralmente basta para explicar a ação. Registrar o cabeçalho completo de Authorization nunca é útil e cria um grave problema de limpeza. Para SSH, registre o alias do host, a conta remota ou classe de comando e o status de saída, não a impressão digital de uma chave privada se ela revelar detalhes sensíveis do inventário.

Mantenha o registro da sessão separado do registro de cada ação. Uma sessão informa quando uma execução do agente começou, qual processo local a possuía e se ela foi revogada. Os registros individuais informam o que aconteceu durante essa execução. Se você juntar tudo em um único fluxo de atividade vago, revogar uma execução suspeita e encontrar suas ações demorará mais do que deveria.

A evidência de adulteração muda a qualidade de uma trilha de auditoria. Um arquivo somente de acréscimo é fácil de editar para quem consegue alterar o arquivo. Uma cadeia de hashes torna modificações posteriores detectáveis, porque cada entrada incorpora o resumo da entrada anterior. Ela não impede a exclusão nem prova que um executor malicioso registrou conteúdo verdadeiro. Mas torna muito mais difícil apresentar uma reescrita silenciosa como histórico.

Um comando de verificação útil tem um contrato intencionalmente simples:

$ sp audit verify
verified 184 records
chain: valid
first record: 2025-04-03T09:14:22Z
last record:  2025-04-03T16:48:01Z

A quantidade exata e os horários serão diferentes. O importante é que a verificação leia o fluxo de registros criptografado armazenado, confira a cadeia e informe a posição inválida quando alguém alterar um registro. A verificação offline sobre o texto cifrado é especialmente útil porque um investigador pode conferir a continuidade sem abrir o cofre ou expor os detalhes armazenados das ações.

Não confunda evidência de adulteração com monitoramento. Ainda é preciso examinar atividades suspeitas, preservar cópias quando um incidente começa e decidir quem tem autoridade para revogar sessões. A criptografia pode informar que uma sequência de registros mudou. Ela não pode dizer que delete-production-data era uma solicitação sensata.

A fadiga de aprovações indica um design ruim de aliases

Se uma pessoa precisa aprovar cada ação inofensiva, ela aprovará sem ler. Isso não é um problema das pessoas. É um sistema que se recusa a distinguir autoridade rotineira de autoridade com consequências.

Use aprovação por sessão para uma execução de agente limitada, cujas conexões permitidas tenham risco operacional comum. A aprovação deve identificar a autoridade de assinatura de código do processo, porque um rótulo como agent diz muito pouco. Se o processo for encerrado, exija outra aprovação para o próximo processo. Isso contém melhor uma invocação de ferramenta copiada do que uma aprovação única válida indefinidamente.

Use aprovação por chamada para aliases em que cada invocação mereça análise. O executor deve tornar o evento de decisão claro o suficiente para que uma pessoa o rejeite rapidamente. Use payments-refund-review-prod para enviar uma solicitação de reembolso do pedido 4821 é acionável. A chamada da ferramenta exige aprovação é design preguiçoso.

O Sallyport usa uma sequência fixa de decisões por esse motivo: um cofre bloqueado nega toda ação, um novo processo de agente exige autorização de sessão por padrão e credenciais individuais podem exigir aprovação a cada uso. Isso evita uma linguagem de políticas, porque operadores locais não deveriam precisar depurar um interpretador de autorização antes de conseguir parar um agente.

Não transforme cada confirmação em um debate com o agente. Uma aprovação é um ponto de controle, não um prompt conversacional. Rejeite a ação, revogue a sessão se a execução tiver saído do rumo e inspecione os registros anteriores. Se uma tarefa precisar de aprovações excepcionais frequentes, revise seu limite ou crie uma conexão mais restrita, com autoridade compatível com o trabalho recorrente.

Aliases não corrigem injeção de prompt nem um design ruim de tarefas

O isolamento de credenciais limita o dano causado pelo roubo de segredos. Ele não decide se um agente deve chamar uma API, enviar um arquivo ou executar um comando remoto.

Uma injeção de prompt escondida em uma issue do repositório pode instruir um agente a publicar uma versão, exfiltrar um relatório por um endpoint permitido ou usar uma conexão SSH para um comando que esteja dentro da autoridade ampla de uma conta. O alias cumpriu seu papel se o invasor nunca obteve o token. Ainda assim, o agente pode executar uma ação permitida e prejudicial.

Por isso um alias amplo é perigoso mesmo quando o segredo nunca vaza. cloud-admin-prod dá espaço demais a uma instrução injetada. artifact-publish-prod, combinado com uma conta de serviço restrita e um destino esperado, oferece menos espaço. Ainda é preciso limitar os arquivos que o agente pode ler, separar conteúdo não confiável das instruções de ação e exigir aprovação para ações cujas consequências ultrapassem a tarefa.

Outro design fraco expõe uma ferramenta genérica http_request junto com um parâmetro de alias. O agente pode então apontar uma credencial poderosa para caminhos arbitrários, hosts depois de redirecionamentos ou endpoints que o operador nunca considerou. Uma ferramenta específica, como create_release, tem menos flexibilidade, mas isso costuma ser uma vantagem de segurança. A generalidade não é neutra quando um agente segue texto não confiável.

Trate cada alias como a resposta a uma frase que você consegue escrever: «Este processo identificado pode executar esta classe de ação neste destino, com este tratamento de aprovação». Se você não consegue escrever a frase sem palavras como «qualquer coisa» ou «conforme necessário», a conexão precisa de mais design antes de ser entregue a um agente.

Um executor local deve ser simples e fácil de inspecionar

O executor tem mais privilégios que o agente, por isso deve fazer menos que ele. Precisa de armazenamento criptografado de credenciais, um pequeno conjunto de canais de ação, identificação do chamador, tratamento de decisões e registro de auditoria. Não precisa se tornar um gateway de acesso remoto, um proxy para qualquer finalidade ou uma linguagem de regras personalizada com centenas de exceções.

Em uma configuração de desenvolvimento local, um aplicativo na barra de menus pode tornar visíveis o estado do cofre e as aprovações pendentes sem acrescentar um serviço em segundo plano que os operadores esqueçam que existe. Isso não elimina a necessidade de engenharia cuidadosa. Apenas concentra a operação sensível em um lugar capaz de bloquear, negar solicitações e manter seus próprios registros.

O Sallyport mantém chaves de API e SSH em um cofre local criptografado e executa ações HTTP e SSH em nome de agentes compatíveis com MCP, em vez de passar credenciais para o contexto do agente. Seu shim sp mcp fornece ao agente uma conexão stdio normal, enquanto o aplicativo continua sendo o executor.

A facilidade de inspeção significa que um operador consegue responder a perguntas básicas sem ler o código-fonte durante um incidente: o cofre está bloqueado? Qual execução está ativa? Qual conexão ela solicitou? Posso revogar essa execução? A sequência registrada foi alterada? Se a resposta exigir juntar logs de cinco componentes diferentes, o sistema pode ser engenhoso, mas não é administrável às duas da manhã.

Mantenha o protocolo da ferramenta restrito. Retorne resultados estruturados de sucesso e erro. Evite mensagens de erro que incluam objetos internos da solicitação ou caminhos do armazenamento de segredos. Torne o cancelamento explícito para que o usuário possa interromper uma ação longa sem encerrar trabalhos não relacionados. Essas escolhas parecem comuns. Elas fazem a diferença entre um limite que você consegue operar e um limite que apenas espera estar presente.

Teste o limite como um invasor capaz de escrever prompts

Uma demonstração do caminho feliz prova apenas que o alias é resolvido. Antes de confiar no design, teste as formas pelas quais um agente ou plugin comprometido tentaria transformar um nome de conexão em acesso mais amplo.

Comece com um alias apontando para uma conta de serviço de não produção. Execute uma tarefa do agente que faça a chamada pretendida e depois dê a ele instruções adversariais para inspecionar esquemas de ferramentas, solicitar despejos de configuração, provocar solicitações malformadas, seguir redirecionamentos, iniciar comandos filhos e ler logs acessíveis. Revise tanto a transcrição visível quanto os registros do executor. Procure material secreto, destinos inesperados e chamadas que contornem o limite de ação pretendido.

Depois, teste as falhas deliberadamente. Bloqueie o cofre durante uma solicitação. Revogue a sessão antes da segunda chamada. Faça a rotação da credencial subjacente. Altere um registro de auditoria em uma cópia e execute a verificação. Cada falha esperada deve ser clara para o operador e pouco útil para um invasor. «Acesso negado porque o cofre está bloqueado» é aceitável. Um stack trace contendo um registro do cofre ou o valor de um cabeçalho não é.

Por fim, teste o caso operacional incômodo: uma execução do agente está fazendo um trabalho legítimo quando seu comportamento se torna suspeito. O operador consegue identificar a execução, revogá-la imediatamente, determinar quais chamadas já tiveram sucesso e verificar que a sequência de registros não foi editada? Se essas ações exigirem uma caça ao tesouro por terminais e painéis de nuvem, corrija isso antes de acrescentar mais aliases.

Uma conexão nomeada é uma interface pequena com grandes consequências. Faça com que seu nome seja honesto, sua autoridade seja restrita, seu chamador seja identificável e seus registros sejam úteis. Depois, permita que o agente solicite ações sem jamais entregar a ele um segredo que valha a pena roubar.