Planilha de inventário de credenciais para agentes de programação com IA

Agentes de programação com IA não devem receber um monte de credenciais herdadas junto com uma instrução vaga para tomar cuidado. Antes que um agente chame uma API, implante um serviço ou abra uma conexão SSH, alguém precisa manter um registro que informe a que a credencial dá acesso, quem assume a responsabilidade por ela e como a equipe vai desativá-la.

Uma planilha de inventário de credenciais parece trabalho administrativo até que um agente faça vinte chamadas enquanto o operador está longe do teclado. Então ela passa a ser a diferença entre revogar uma capacidade conhecida e desativar metade da organização de engenharia porque ninguém consegue identificar o token. Já vi equipes descobrirem que sua automação de «staging» tinha um token de gravação em produção somente depois que uma alteração automática chegou a um lugar que não deveria alcançar.

O inventário deve descrever autoridade, não sequências secretas

Uma planilha de inventário de credenciais registra autoridade. Ela não registra o token de API, o material privado de SSH, a senha, o código de recuperação nem uma exportação criptografada de qualquer um deles. Se uma planilha consegue autenticar algo, ela se tornou outro repositório de segredos, com controles de acesso mais fracos e um público muito maior.

Essa distinção importa porque as equipes costumam confundir um identificador com uma credencial. Os quatro últimos caracteres de um token de API ajudam o operador a localizar a entrada certa durante a rotação. Eles não informam se o token pode excluir um projeto. A impressão digital de uma chave pública SSH identifica uma identidade. Ela não informa qual conta Unix a chave abre, se permite encaminhamento de portas ou quais hosts confiam nela.

Use uma linha para cada autoridade que possa ser revogada de forma independente. Uma conta de provedor pode precisar de várias linhas: um token de relatórios de produção somente leitura, um token de implantação em staging, um token administrativo de emergência que os agentes não podem usar e um segredo de assinatura de webhook. Combinar tudo em uma linha faz desaparecerem os diferentes riscos e requisitos de rotação.

A mesma regra vale para SSH. Não escreva «Git e servidores» em uma única célula só porque uma chave privada funciona nos dois lugares. Uma identidade de gravação no controle de código-fonte e uma identidade de login em um host têm consequências diferentes. Elas precisam de linhas separadas, mesmo quando foram criadas pela mesma pessoa na mesma tarde.

A NIST SP 800-57 Part 1 trata o gerenciamento de chaves criptográficas como um problema de ciclo de vida: geração, distribuição, armazenamento, uso, substituição e destruição precisam de controle. O documento se concentra em chaves criptográficas, mas sua disciplina se aplica diretamente aqui. Uma lista de credenciais que termina em «criamos um token» não é um inventário. É um lembrete que falha justamente quando a equipe precisa de registros confiáveis.

Dê a cada credencial um responsável definido

Cada linha precisa de um responsável identificado que possa responder «essa autoridade ainda deve existir?». Essa pessoa não precisa administrar o gerenciador de segredos nem escrever a integração do agente. Ela precisa conhecer o sistema afetado o suficiente para aprovar o acesso e assumir suas consequências operacionais.

Evite responsáveis como «plataforma», «equipe de desenvolvimento», «compartilhado» ou o nome de um funcionário inativo. Um grupo pode operar um processo, mas o nome do grupo não informa a um responsável pelo incidente para quem ligar às duas da manhã. Registre um responsável principal e, se necessário, um substituto com autoridade para revogar ou substituir a credencial.

Separe quatro funções que as equipes costumam misturar:

• O responsável pelo sistema decide se o acesso continua apropriado.
• O custodiante da credencial pode criá-la, armazená-la, revogá-la e rotacioná-la.
• O operador do agente inicia ou supervisiona a execução do agente.
• O contato de incidentes cuida de uma falha urgente quando as três primeiras pessoas não estão disponíveis.

Uma pessoa pode exercer várias funções em uma equipe pequena. Ainda assim, a planilha deve nomeá-las separadamente. Quando um token falha durante uma implantação, o custodiante pode corrigir o armazenamento enquanto o responsável pelo sistema decide se uma substituição temporária deve ter o mesmo escopo.

Para uma API de fornecedor, a responsabilidade geralmente pertence à equipe que paga ou administra a conta, não ao desenvolvedor que colou o primeiro token em um arquivo de configuração local. Para acesso SSH, a responsabilidade normalmente pertence ao responsável pelo host ou pela aplicação, não à pessoa que gerou o par de chaves. Parece óbvio, mas credenciais órfãs quase sempre começaram como um atalho razoável tomado por alguém que depois mudou de equipe.

Adicione uma data de revisão separada da data de rotação do segredo. Um token pode continuar tecnicamente válido enquanto sua finalidade de negócio desapareceu. A revisão pergunta se o acesso deve existir. A rotação substitui um material que pode ter envelhecido ou escapado. Fazer uma não conclui a outra.

Escreva as ações permitidas como verbos e alvos

«Acesso à produção» não é uma descrição de permissão. É um rótulo de alerta que não oferece nada útil ao operador do agente. A planilha precisa de verbos, recursos de destino e limites que um revisor possa testar.

Escreva as permissões neste formato:

verbo + alvo + limite + ação proibida

Por exemplo:

• GET /v1/projects/acme/builds em staging; nenhuma solicitação ao tenant de produção
• POST de revisões de implantação para o serviço catalog-api; sem rollback ou exclusão
• SSH como deploy no grupo de hosts de build; executar apenas o comando de release aprovado; sem shell interativo
• Criar comentários de issues no repositório alpha; sem merge, exclusão de branches ou alterações de configurações

Isso é mais útil do que um rótulo amplo do provedor, como «gravação». Um agente que pode criar uma revisão de implantação e outro que pode remover uma implantação têm permissão de gravação, mas o raio de impacto não é nem de longe semelhante.

Registre se a ação pretendida é ler, criar, modificar, excluir, executar ou fazer uma alteração administrativa. «Executar» exige atenção especial. Uma chamada de API que inicia um trabalho na nuvem, rotaciona uma credencial de serviço, aciona uma operação de pagamento ou executa um shell remoto pode parecer inofensiva no registro de solicitações e ainda assim causar um resultado caro ou irreversível mais adiante.

Não transforme a planilha em um documento jurídico cheio de linguagem vaga. «Usar somente quando apropriado» e «trabalho normal de implantação» não oferecem nenhum limite. Uma pessoa não consegue aprovar com base neles, e um engenheiro não consegue criar controles a partir deles. Se a ação depende do contexto, declare o contexto: ambiente, repositório, grupo de hosts, conta ou tipo de alteração específicos.

O atalho mais comum é conceder um token de administrador geral e confiar que o prompt do agente evitará chamadas perigosas. Ele é popular porque coloca um protótipo em funcionamento em poucos minutos. Está errado porque prompts não são controles de acesso e chamadas posteriores podem herdar a autoridade ampla sem que a pessoa que escreveu o prompt perceba.

Ambientes precisam de linhas e consequências separadas

Uma credencial de staging e uma credencial de produção nunca devem compartilhar uma linha apenas porque chamam a mesma API. Os responsáveis podem ser os mesmos, mas a conta de destino, a exposição dos dados, a exigência de aprovação e a urgência da revogação geralmente não são.

Trate o ambiente como algo mais do que um rótulo. Registre a conta ou o tenant do provedor, o endpoint ou grupo de hosts, a classificação dos dados e se uma chamada pode atravessar uma fronteira de ambiente. «Prod» é vago demais quando uma organização tem várias contas de produção, regiões ou partições de clientes.

Um campo de ambiente que funcione poderia ser:

production / tenant 4821 / dados de contas de clientes / endpoint api.example.internal

Não coloque um hostname interno real em uma planilha que muitas pessoas possam ler se o próprio hostname for sensível. A ideia é nomear o alvo com precisão suficiente para a equipe autorizada. A política de acesso ao inventário deve corresponder à sensibilidade de seus detalhes operacionais.

Inclua um campo separado para os dados que um agente pode receber na resposta. A permissão para chamar um endpoint e a permissão para visualizar sua resposta são riscos relacionados, mas não idênticos. Uma solicitação de leitura pode retornar código-fonte, dados de contato de clientes, faturas, metadados de acesso ou um segredo inserido em um valor antigo de configuração.

Isso identifica um padrão de falha frequente. Uma equipe cria uma credencial de agente para «diagnósticos somente leitura» em staging. Mais tarde, durante um incidente, um engenheiro aponta o cliente de diagnóstico para produção porque a sintaxe do comando é idêntica. A credencial funciona porque o provedor usou um escopo válido para toda a conta, e o agente retorna dados de clientes em sua transcrição. A linha original da planilha teria exposto o limite ausente se tivesse nomeado o tenant e os dados da resposta, em vez de simplesmente dizer «leitura de diagnóstico».

Quando um provedor não consegue isolar ambientes, não compense isso com documentação otimista. Marque a credencial como válida entre ambientes, aumente seu nível de aprovação e decida se um agente deve usá-la. Às vezes, a resposta honesta é não.

O acesso SSH precisa de mais detalhes que o acesso à API

As credenciais SSH merecem campos próprios porque uma conexão SSH pode carregar vários tipos de autoridade ao mesmo tempo. A conta de login, os hosts aceitos, as restrições de comando, as permissões de encaminhamento e a configuração de encaminhamento do agente mudam o que a conexão pode fazer.

Para cada linha SSH, registre a impressão digital da chave pública, o local do material privado, a conta de login, o host ou grupo de hosts e o comando exato pretendido. Não copie a chave privada para a planilha. Uma impressão digital SHA256 basta para identificação, e os operadores podem obtê-la localmente.

Execute este comando no arquivo da chave pública:

ssh-keygen -lf ~/.ssh/id_agent_deploy.pub

Um resultado normal tem este formato:

256 SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd agent-deploy (ED25519)

Armazene o valor SHA256: e o comentário somente se o comentário ajudar as pessoas a identificar a função. Comentários não são controles de segurança. Qualquer pessoa pode alterá-los ao copiar uma chave pública.

Para os hosts de destino, examine as restrições em authorized_keys em vez de presumir que uma conta de implantação é limitada apenas porque essa era a intenção. O OpenSSH documenta opções como command=, no-port-forwarding, no-agent-forwarding e no-pty no manual do sshd. Essas restrições podem transformar uma identidade de automação em um executor de comandos limitado. Elas não corrigem uma credencial que faz login como uma conta administrativa sem restrições.

Uma entrada poderia dizer: «login deploy, hosts do grupo de release A, comando forçado /usr/local/bin/release-catalog, sem encaminhamento de portas, sem PTY, sem encaminhamento do agente». Se o acesso precisar de um shell interativo para trabalho de emergência, crie uma identidade separada, operada por uma pessoa. Não reutilize silenciosamente a identidade do agente só porque ela já está disponível.

A verificação do host também pertence ao registro. Anote como a integração do lado do agente verifica a identidade do host, onde ficam as entradas de known_hosts e quem as atualiza depois de uma substituição legítima do host. Desativar a verificação do host para superar uma reconstrução é um convite para enviar uma credencial válida à máquina errada.

Uma planilha útil tem campos que exigem respostas concretas

Copie este modelo para um documento controlado, sistema de tickets ou banco de dados de inventário. Remova as colunas que sua equipe não consegue manter, mas não remova os campos que estabelecem autoridade, escopo e recuperação.

A coluna caminho do agente força uma pergunta útil: como o agente obtém o efeito dessa credencial? «Variável de ambiente no shell de programação» é uma resposta, mas deve causar desconforto porque o processo pode imprimi-la, transmiti-la ou persistir com ela. «O gateway de ações faz a solicitação e retorna a resposta» é um projeto diferente, com um caminho de exposição menor.

O campo método de revogação deve poder ser executado por outra pessoa. «Peça ao Sam» não é um método. «Desative o token nas configurações do projeto do provedor e depois revogue a sessão ativa do agente» é um método. Teste essa instrução quando adicionar a linha, antes que um incidente faça cada página do console parecer desconhecida.

Evite um campo de status que diga apenas ativo ou inativo. Inclua último uso, última revisão e aposentadoria planejada. Uma credencial não utilizada não é inofensiva. Muitas vezes é justamente aquela que ninguém lembra de revogar quando um projeto termina.

Os planos de rotação precisam incluir substituição e comprovação

A rotação só termina quando a credencial antiga é desativada e a substituta conclui uma ação pretendida pelo caminho real do agente. Criar um novo token, adicioná-lo ao armazenamento e prometer revisar o token antigo depois deixa as duas identidades ativas. Isso dobra o trabalho durante um incidente.

Um plano de rotação deve declarar cinco fatos operacionais:

1. O evento que causa a rotação, como expiração programada, saída de um funcionário, suspeita de exposição ou mudança de escopo.
2. A pessoa que cria a substituta e a pessoa que aprova a autoridade alterada.
3. O local onde o novo material é armazenado sem chegar ao agente.
4. A ação de teste restrita que comprova que a substituta funciona.
5. O momento exato em que o material antigo é revogado e a evidência é registrada.

Use um teste restrito. Para uma credencial HTTP, chame um endpoint inofensivo que exija o escopo pretendido e confirme o status e o formato de resposta esperados. Para SSH, execute o comando forçado de status da implantação contra o grupo de hosts aprovado, em vez de testar com um login de shell geral.

Um registro de teste pode ser tão simples quanto este:

Credential ID: api-catalog-deploy-prod-01
Replacement ID suffix: ...7KQ2
Test: POST /deployments/validate for catalog-api revision 8f3c
Expected: HTTP 200 with validation status accepted
Old credential revoked: provider audit event recorded
Reviewer: production service owner

Não defina cronogramas de rotação que sua equipe não consegue cumprir. Um intervalo curto com exceções repetidas ensina as pessoas a tratar o inventário como ficção. Use a expiração do provedor quando disponível, estabeleça gatilhos baseados em eventos e programe uma frequência de revisão compatível com o risco. O acesso de gravação em produção, o acesso amplo de leitura a dados sensíveis e o acesso SSH a hosts compartilhados merecem mais atenção do que um token descartável de staging sem dados sensíveis na resposta.

Se houver suspeita de exposição, revogue primeiro quando o serviço puder suportar isso. As equipes perdem tempo tentando provar se um token vazado foi copiado do buffer do terminal, do log de CI, da transcrição do prompt ou do histórico local. Raramente é preciso ter essa prova antes de interromper a credencial. Preserve os logs, substitua a credencial e depois investigue o caminho.

A aprovação do agente deve acompanhar a consequência da chamada

Uma execução de agente tem um ciclo de vida que scripts comuns muitas vezes não têm: alguém pode iniciá-la, deixá-la trabalhando, voltar mais tarde e descobrir que ela fez várias chamadas externas. Por isso, a planilha deve declarar quando a autorização humana se aplica, não apenas quem é responsável pela credencial.

A aprovação por sessão funciona para uma execução contida, com um processo de agente local confiável e identificado, e consequências baixas ou moderadas. Ela confirma que esse processo pode usar as autoridades listadas enquanto estiver ativo. Isso não significa que toda chamada futura mereça passagem livre.

Exija aprovação a cada uso para operações que possam publicar, implantar, alterar dados de produção, alcançar respostas de alta sensibilidade ou criar um novo compromisso externo. Um clique adicional custa menos do que explicar uma ação inesperada a um cliente ou à equipe financeira. Use uma credencial separada para ações com outro nível de aprovação quando o provedor permitir.

A aprovação não substitui o escopo. Uma pessoa pode aprovar a ação errada porque a descrição da solicitação era vaga, porque a ação chegou durante um incidente ou porque o agente fez várias chamadas semelhantes em rápida sequência. Mantenha as permissões restritas primeiro e use a aprovação para cobrir o risco residual que o escopo não consegue expressar.

O Sallyport mantém credenciais de API e SSH em um cofre criptografado no Mac e pode exigir autorização para um novo processo de agente ou para cada uso de uma credencial selecionada, enquanto o agente recebe resultados, não os segredos.

Uma boa planilha associa cada linha de alta consequência às evidências de auditoria esperadas após o uso. Registre o identificador da sessão ou o local do diário da execução, o registro de atividade de cada chamada, o alvo, o horário, o resultado e, quando aplicável, a pessoa que aprovou. Se as evidências não conseguirem informar qual credencial foi usada para qual resultado, a integração do agente é opaca demais para a autoridade concedida.

Os registros de auditoria resolvem discussões depois de uma execução problemática

O inventário é um trabalho preventivo. Os registros de auditoria respondem a uma pergunta diferente depois que um agente se comporta de forma inesperada: o que ele realmente tentou fazer, o que deu certo e qual autoridade tornou isso possível? Não misture essas funções. Uma planilha mantida com cuidado não consegue provar que uma chamada aconteceu, e um log não consegue provar que uma permissão era justificável.

Faça um exercício de incidente com base em uma linha do inventário. Peça a um operador para localizar o responsável, revogar a credencial, interromper o acesso atual do agente, identificar a última chamada bem-sucedida e verificar se a trilha de auditoria não foi alterada. Meça a confusão, não o tempo decorrido. Se as pessoas não conseguirem nomear a conta de destino ou distinguir o token antigo da substituta, corrija os campos da planilha.

A evidência contra adulteração importa quando várias pessoas podem consultar ou exportar logs. Um banco de dados simples, somente de acréscimo, pode ser alterado por um administrador com acesso suficiente e depois apresentado como histórico. Um log encadeado por hashes torna alterações não autorizadas detectáveis quando a cadeia é verificada contra a sequência armazenada. Ele não torna a solicitação original sensata nem impede uma pessoa autorizada de fazer uma chamada ruim. Esses são controles separados.

Mantenha a decisão sobre retenção da auditoria junto ao registro do inventário, especialmente quando as respostas podem conter dados sensíveis. Um registro de atividade deve preservar contexto suficiente para a investigação sem reter casualmente payloads completos de clientes para sempre. Armazene metadados da solicitação e o status do resultado sempre que possível; reserve a captura da resposta completa para casos em que ela seja realmente necessária e permitida.

A primeira linha de credencial que você deve preencher é aquela que um agente pode usar hoje para fazer uma alteração em produção. Nomeie o alvo com precisão, torne o verbo permitido concreto, escreva a instrução de revogação para que outra pessoa possa segui-la e teste o caminho de substituição. Se essa linha contém suposições, o restante do inventário é apenas decoração.