Catálogo de ações de agentes de IA: encontre acessos desnecessários

Um catálogo de ações de um agente de IA é a maneira mais rápida de encontrar permissões que ninguém escolheu conscientemente. Ele lista as operações que um agente pode executar fora do próprio espaço de trabalho e obriga a tomar uma decisão sobre cada uma: quem é o responsável, o que acontece se algo der errado e se uma pessoa precisa aprová-la.

A maioria das equipes começa pelo lugar errado. Elas inventariam chaves de API, integrações ou contas de software e então concluem que entendem o acesso. Não entendem. Uma credencial é apenas um contêiner. A decisão de segurança está no nível da operação: «criar uma fatura em rascunho» é muito diferente de «emitir um reembolso», mesmo quando as duas chamadas usam o mesmo token.

Já vi revisões de permissões fracassarem porque a equipe perguntou: «O agente precisa de acesso ao sistema de faturamento?». A pergunta é ampla demais para ser respondida com honestidade. Pergunte se ele precisa ler uma única fatura, criar um rascunho, enviar um reembolso, atualizar dados de pagamento ou exportar a lista de clientes. As respostas geralmente são diferentes. É nessas diferenças que o acesso desnecessário aparece.

Uma lista de integrações esconde as permissões que importam

Um inventário de sistemas mostra onde o agente se conecta. Um catálogo de ações mostra o que ele pode causar. Mantenha os dois, mas não confunda um com o outro.

Considere um agente conectado a um serviço de controle de código-fonte. «Acesso ao repositório» pode incluir ler código, abrir um pull request, alterar a proteção de branches, criar uma chave de implantação, publicar uma versão ou excluir um repositório. Tratar esse conjunto como uma única permissão transforma várias decisões de risco em um sim ou não preguiçoso.

O mesmo erro aparece com SSH. «O agente pode usar SSH no staging» quase não diz nada. Um comando restrito que consulta o status de um serviço tem uma consequência diferente do acesso a um shell em uma conta que pode reiniciar serviços, ler segredos de implantação ou alterar regras de firewall. Catalogue a família de comandos ou o endpoint, não apenas o meio de transporte.

A distinção importa porque a exposição tem três dimensões que as equipes costumam misturar:

• Alcance é a possibilidade de o agente contatar um sistema.
• Autoridade é o que o sistema permite depois do contato.
• Consequência é o que pode acontecer se o agente fizer uma solicitação errada ou manipulada.

Um endpoint interno pode ter baixo alcance e autoridade muito alta. Uma API pública pode ter amplo alcance, mas autoridade limitada. Um desenho de aprovações baseado apenas no fato de um serviço ser «interno» deixará de perceber os dois casos.

A Publicação Especial 800-53 do NIST, no controle AC-6, descreve o privilégio mínimo como a concessão apenas do acesso necessário para realizar as tarefas atribuídas. A frase parece óbvia até ser aplicada a um agente. «Tarefa atribuída» não pode significar «ajudar com engenharia». Precisa significar uma operação com alvo, método, limite e resultado esperado. Se você não consegue escrever isso, não pode afirmar que segue o privilégio mínimo.

Comece com nomes de ações que um revisor consiga entender sem abrir um repositório de código. «POST /v1/issues» é uma evidência útil, mas «criar um issue no rastreador de engenharia» informa ao responsável o que ele está aprovando. Mantenha os dois no registro.

Crie uma linha para cada operação visível externamente

Cada linha do catálogo deve representar a ação mais específica que possa receber uma decisão própria de acesso ou aprovação. Se duas operações puderem ter responsáveis, impactos ou exigências de aprovação diferentes, elas precisam de linhas separadas.

Uma linha prática deve ter detalhes suficientes para um engenheiro implementar o controle e linguagem simples o bastante para o responsável pelo sistema recusá-la. Use estes campos:

Não escreva «vários», «tarefas administrativas», «API completa» ou «conforme necessário» no campo de operação. Essas expressões significam que o catálogo parou antes de o trabalho começar. Divida a entrada até que uma pessoa possa dizer sim ou não sem adivinhar.

Este é um exemplo compacto para um agente de desenvolvimento:

action_id: issue-tracker.create-bug
system: issue tracker, production tenant
operation: Create a bug report in the Engineering project
technical_route: POST /api/projects/engineering/issues
identity: service account agent-issues, scope issues:write
inputs: title, body, labels, repository reference
outputs: issue ID and URL
impact: internal write, reversible by project members
owner: Engineering operations manager
approval: per-session
review_date: 2026-09-30

A expressão «production tenant» pertence a essa linha mesmo que a ação apenas crie chamados. Muitas equipes usam um único tenant de produção de SaaS para informações reais de clientes, funcionários e incidentes. O rótulo do ambiente informa aos revisores qual limite está sendo atravessado.

Evite o problema da falsa precisão. Você não precisa de uma linha separada para cada atualização inofensiva de campo quando destino, responsável, identidade, aprovação e consequência forem realmente idênticos. Mas precisa de linhas separadas quando um campo especial mudar o resultado. «Atualizar o status do incidente» e «alterar o responsável pelo incidente» podem passar pelo mesmo endpoint, mas não devem receber a mesma decisão de aprovação.

Descubra ações seguindo credenciais e fluxos de trabalho

Você não encontrará todo o conjunto de ações lendo o prompt do agente. Prompts descrevem intenção; código, configuração, credenciais e tráfego observado mostram o que o agente realmente pode solicitar.

Comece pelos fluxos de trabalho que as pessoas esperam que o agente execute. Peça aos engenheiros que descrevam as dez últimas tarefas que deram a ele, ou que pretendem dar, usando verbos. «Investigar uma compilação com falha» pode incluir ler logs, consultar um serviço de implantação, abrir um issue, reiniciar um ambiente de teste e publicar uma mensagem. Registre cada limite externo atravessado.

Depois, trabalhe de trás para frente a partir de cada credencial. Inspecione escopos de API, concessões OAuth, funções de contas de serviço, chaves autorizadas de SSH, wrappers de comandos, variáveis de CI e armazenamentos locais de segredos. Uma credencial frequentemente revela operações que ninguém mencionou na discussão do fluxo. Um token de API com escopo de administração de usuários é candidato a uma ação mesmo que a equipe insista que o agente só abre chamados.

Por fim, compare intenção e evidência. Rastros de rede, logs do gateway de API, registros de auditoria de comandos e definições das ferramentas do agente revelam chamadas que o documento do fluxo não registrou. Faça isso primeiro em um ambiente de teste seguro quando possível. Os logs de produção continuam importantes, porque agentes e pessoas tendem a descobrir atalhos sob pressão.

Use esta rotina de coleta em cinco passagens:

1. Liste cada fluxo de trabalho do agente que ultrapassa a tarefa local.
2. Extraia de configuração e código cada chamada de ferramenta, endpoint e padrão de comando de shell.
3. Enumere o que cada credencial permite, incluindo funções herdadas e escopos curinga.
4. Revise os logs recentes de ações em busca de destinos ou verbos ausentes da lista.
5. Reconcilie as diferenças com a pessoa responsável pelo sistema de destino.

É na quarta passagem que aparecem as descobertas desconfortáveis. Você pode encontrar um token antigo com administração ampla de repositórios, uma chave SSH de staging aceita por hosts de produção ou um webhook «interno» capaz de acionar uma versão. Não reduza silenciosamente a entrada para fazê-la caber no plano original. Coloque a operação efetiva no catálogo e faça alguém decidir se ela permanece.

Um teste útil é entregar uma linha a um colega que não criou a integração. Ele deve conseguir explicar o que o agente envia, o que recebe e qual é o pior erro plausível. Se não conseguir, a linha é entulho técnico, não um registro de controle.

O impacto precisa descrever consequências, não uma pontuação genérica de risco

Classifique o impacto pelo que uma ação errada altera, expõe, gasta ou compromete. Uma única avaliação «alto, médio, baixo» falha porque esconde o motivo pelo qual uma ação precisa da atenção humana.

Uso cinco categorias de consequência no catálogo: divulgação, integridade, disponibilidade, compromisso externo e alteração de privilégio. Uma linha pode ter mais de uma. Ler uma exportação de clientes cria uma consequência de divulgação. Excluir uma implantação altera a disponibilidade. Adicionar um administrador altera o privilégio. Enviar um contrato cria um compromisso externo, mesmo que a ação seja tecnicamente reversível.

Acrescente dois modificadores: reversibilidade e raio de impacto. Reversibilidade pergunta se uma pessoa competente consegue desfazer a ação sem perda ou confusão. Raio de impacto pergunta se um erro afeta um rascunho, um projeto, muitos usuários ou todo um ambiente.

Isso produz decisões que as pessoas conseguem defender. «Excluir uma branch temporária de teste» pode ser uma alteração de integridade reversível e limitada. «Rotacionar as credenciais do banco de dados de produção» pode preservar a segurança, mas também afetar a disponibilidade de muitos serviços. As duas são ações de escrita. Elas pertencem a categorias de aprovação diferentes.

Não deixe que «a API oferece desfazer» resolva a questão da reversibilidade. Um reembolso pode ser revertido no ledger enquanto o cliente já recebeu um e-mail confuso. Um pacote publicado pode ser retirado enquanto sistemas downstream já o baixaram. Uma conta excluída pode ser restaurada enquanto seu antigo proprietário fica sem acesso durante um incidente. Considere a consequência operacional, não apenas a operação no banco de dados.

Os dados retornados por uma ação merecem a mesma atenção que os dados enviados. Uma consulta de status aparentemente inofensiva que retorna todas as variáveis de ambiente, transcrições de suporte ou chaves privadas é uma ação de divulgação. As equipes costumam se concentrar demais na capacidade de escrita do agente porque escrever parece uma atividade. Um agente capaz de ler todos os segredos e depois chamar um endpoint externo já tem acesso suficiente para causar um incidente grave.

Mantenha a linguagem de impacto concreta. Troque «alto impacto» por «pode alterar a autorização de produção de todos os membros do workspace» ou «pode transmitir identificadores de clientes a uma API de terceiros». A primeira descrição informa ao responsável o que decidir. O rótulo sozinho não informa.

A responsabilidade deve ficar com quem pode dizer não

Toda ação precisa de um responsável identificado que possa negá-la, reduzi-la ou removê-la. Essa pessoa é responsável pela decisão de permissão, não por todo resultado operacional produzido pelo agente.

O melhor responsável normalmente pertence ao sistema de destino ou assume a consequência comercial. Um líder de engenharia pode ser responsável pelas ações de implantação em produção. O financeiro é responsável pelo envio de reembolsos. A equipe de segurança pode definir condições para a administração de acesso, mas não deve virar a responsável padrão por cada linha apenas por ser a equipe de segurança.

A responsabilidade compartilhada é onde os catálogos se deterioram. «Segurança e engenharia» faz cada grupo presumir que o outro revisará a entrada. Registre uma única pessoa responsável e liste as equipes consultadas nas notas, se necessário. Se alguém mudar de cargo ou equipe, transfira as linhas do catálogo como parte da transição.

Os responsáveis precisam de um pacote de decisão que caiba em uma tela. Mostre a operação, o sistema, a identidade efetiva, os dados envolvidos, a consequência, a aprovação proposta e um breve motivo para o agente precisar dela. Não entregue uma lista bruta de escopos OAuth e chame isso de governança.

O responsável deve responder a quatro perguntas:

• O agente precisa desse resultado ou o fluxo apenas o considera conveniente?
• Um endpoint, função, conta, alvo ou comando mais restrito pode produzir o resultado?
• Que erro criaria uma consequência inaceitável?
• Quem deve aprovar o uso e quando essa decisão deve expirar?

A primeira costuma ser a pergunta desconfortável. As equipes frequentemente concedem uma operação ampla porque isso elimina uma conversa futura. Isso não é um requisito. É uma revisão de acesso adiada, acompanhada de uma credencial.

Torne a responsabilidade visível no caminho de execução. Se ninguém consegue identificar o responsável durante um incidente, o catálogo não cumpriu seu papel. Um responsável identificado também torna a revisão periódica viável, pois ela pode fazer uma pergunta direta: «Você ainda autoriza a ação X para este agente e esta identidade?»

A aprovação deve corresponder ao momento do compromisso

A aprovação é útil quando aparece antes do ponto em que o agente causa uma consequência e quando o revisor consegue entender o que está permitindo. Um botão que diz «permitir uso da ferramenta» depois que o agente agrupou dez operações sem relação é teatro de segurança.

Use três estados de aprovação no catálogo. «Nenhuma» significa que a ação pode prosseguir depois que o agente obtiver a autoridade da sessão. «Por sessão» significa que uma pessoa aprova um processo específico do agente antes que ele possa chamar qualquer ação autorizada. «Por chamada» significa que uma pessoa revisa cada uso da ação.

A aprovação por sessão serve para ações restritas e rotineiras com consequências moderadas, como ler o status de uma compilação ou criar issues internos em rascunho. Ela confirma que o processo pretendido do agente está ativo e permite que ele conclua o trabalho comum sem obrigar alguém a clicar repetidamente em prompts.

A aprovação por chamada serve para ações que criam um compromisso ou atravessam um limite difícil. Use-a para alterar o acesso de produção, excluir registros relevantes, acionar implantações que afetam clientes, enviar mensagens para fora da empresa, lidar com dinheiro e exportar conjuntos de dados sensíveis. Exigir que uma pessoa examine cada solicitação é uma fricção adequada nesses casos.

O registro de aprovação precisa de contexto. No mínimo, mostre a identidade do processo que chama, a operação, o destino, o ambiente-alvo e os parâmetros importantes. «O agente solicita POST» obriga o revisor a reconstruir a ação sob pressão. «Reiniciar o serviço de pagamentos em produção, solicitado pelo processo assinado X» oferece uma decisão que ele consegue tomar.

Não use prompts de aprovação para compensar uma permissão que não deveria existir. Um prompt por chamada para «executar um comando de shell arbitrário em produção» ainda deixa o revisor aprovando repetidamente um cheque em branco. Substitua a capacidade ampla de shell por comandos restritos ou operações separadas e aprove-as quando necessário.

O gateway de ações é importante aqui porque pode manter as credenciais longe do agente e colocar a decisão humana perto da execução. O Sallyport usa uma sequência fixa de decisões: um cofre bloqueado nega todas as ações, um novo processo de agente recebe autorização por sessão por padrão e determinadas chaves podem exigir aprovação a cada uso.

Essa estrutura evita um erro comum: inventar uma linguagem extensa de regras antes de catalogar bem as ações para escrever regras seguras. Políticas complexas parecem maduras em um documento de projeto e se tornam impossíveis de revisar quando chegam as exceções. Comece com operações claras, identidades restritas e aprovações alinhadas ao impacto.

Um catálogo expõe o caminho da falha antes de a produção fazê-lo

Um catálogo mostra seu valor quando detecta uma cadeia de escolhas comuns que parece aceitável isoladamente. Considere um agente de programação solicitado a investigar por que um fluxo de pedidos falhou.

Um engenheiro entrega a ele um token de serviço porque o token pode ler logs. O mesmo token também pode consultar a API de pedidos. O agente encontra um pedido malformado e recebe a instrução de «limpar os dados de teste». Ele chama um endpoint de exclusão no tenant de produção porque a integração não diferenciava claramente os nomes dos tenants. O endpoint aceita a solicitação. Mais tarde, uma pessoa percebe que o pedido era real, mas restaurá-lo exige reconciliação entre os sistemas de pagamentos, estoque e suporte ao cliente.

Cada afirmação isolada parecia inofensiva: ler logs, consultar pedidos, remover dados de teste. O catálogo de ações teria dividido a cadeia em linhas:

A descoberta útil não é «agentes cometem erros». Pessoas cometem essa mesma cadeia de erros quando os limites de acesso são vagos. Agentes executam mais rápido, tentam novamente com mais facilidade e podem seguir uma instrução que parece razoável localmente sem perceber o contexto comercial que uma pessoa inferiria.

Escreva os caminhos de falha nas notas das linhas de alta consequência. Use um formato simples: gatilho, alvo ou interpretação errada, ação executada, efeito imediato e esforço de recuperação. Isso torna as decisões de aprovação menos abstratas e dá aos revisores um motivo para rejeitar o acesso amplo.

Um catálogo também detecta combinações perigosas. Ler notas de incidentes pode ser aceitável. Publicar em uma página pública de status pode ser aceitável com revisão. Permitir que um único agente faça as duas coisas sem um limite de conteúdo pode expor detalhes internos do incidente. Revise as combinações em que uma ação fornece uma entrada sensível e outra envia dados para fora da organização.

Torne o catálogo aplicável e prove que ele corresponde à realidade

Um catálogo que vive apenas em uma planilha vira uma lista de desejos de permissões. Conecte cada linha aprovada a um limite técnico: uma credencial separada, um escopo de API restrito, uma lista de destinos permitidos, um comando SSH limitado ou uma configuração de aprovação.

Use os IDs das ações na configuração e nos logs. Isso fornece um teste simples: toda ação externa observada deve corresponder a um ID do catálogo, e todo ID ativo do catálogo deve corresponder a um ponto de aplicação atual. Investigue os dois tipos de divergência. Uma ação observada sem linha é acesso oculto. Uma linha sem aplicação pode ser um plano antigo ou um caminho sem controle.

Para chamadas HTTP, verifique método, host, padrão do caminho, ambiente-alvo e escopo da credencial. Para SSH, verifique conta, grupo de hosts, restrições de comando e se o auxiliar pode receber argumentos arbitrários. «O acesso SSH foi aprovado» não é uma afirmação aplicável tecnicamente.

Por exemplo, esta entrada afirma que o agente só pode consultar o status de uma implantação:

Action ID: deploy.status.read
Host: deploy.internal.example
Command: deployment-status --service <approved-service>
Identity: agent-deploy-read
Approval: per-session

Esta implementação contradiz a afirmação:

command="/usr/local/bin/deployment-status $SSH_ORIGINAL_COMMAND" ssh-ed25519 AAAA... agent

O wrapper passa um comando original arbitrário como argumento. Se deployment-status chamar um shell ou aceitar uma opção não validada, o limite do catálogo é fictício. Um desenho mais seguro associa um nome de serviço aprovado a um comando fixo e rejeita qualquer outra entrada. Teste deliberadamente o caminho de rejeição.

case "$1" in
  checkout) exec /usr/local/bin/deployment-status --service checkout ;;
  search) exec /usr/local/bin/deployment-status --service search ;;
  *) echo "service not permitted" >&2; exit 1 ;;
esac

Não copie esse trecho cegamente para uma configuração de authorized-keys. Ele ilustra a propriedade necessária: o agente escolhe entre ações definidas, não entre comandos arbitrários. Seu ambiente ainda precisa de validação de entradas, restrições de conta e testes feitos por alguém que entenda o comportamento do comando.

Como evidência da ação, registre um teste que prove os dois lados do limite. Um teste positivo prova que a chamada aprovada funciona. Um teste negativo prova que uma chamada proibida próxima falha. As equipes costumam guardar apenas o teste positivo, e é por isso que credenciais amplas sobrevivem silenciosamente.

O Sallyport registra sessões de agentes e chamadas individuais em um único log de auditoria criptografado e encadeado por hash. O comando sp audit verify pode verificar essa cadeia offline sobre o texto cifrado, sem acesso à chave do cofre. Essa evidência ajuda a comparar o catálogo com o comportamento real, mas não substitui a decisão de remover uma ação desnecessária.

Revise o acesso quando o trabalho mudar, não depois de uma surpresa trimestral

Revise o catálogo quando adicionar uma ferramenta, alterar o fluxo de um agente, emitir ou rotacionar uma credencial, trocar o responsável por um sistema ou descobrir um quase incidente. Esses eventos alteram o acesso efetivo. Esperar por uma revisão no calendário permite que suposições antigas persistam enquanto as integrações se acumulam.

Defina uma data de revisão para cada linha mesmo assim. Operações de alta consequência merecem um intervalo menor que leituras internas inofensivas. A revisão não deve perguntar se a planilha ainda existe. Deve perguntar se o agente ainda precisa dessa operação exata, se a identidade continua restrita, se o responsável ainda está correto e se o uso observado justifica mantê-la.

Remova ações não utilizadas com firmeza. As equipes resistem porque temem que o agente precise da permissão no futuro. Se isso acontecer, adicione-a novamente pela mesma decisão de responsável e aprovação. Conceder outra vez uma operação conhecida exige menos esforço do que limpar uma ação que nunca deveria ter sobrevivido.

O primeiro catálogo útil não precisa ter cobertura perfeita. Escolha um agente, liste todas as operações externas que ele pode executar hoje e obrigue um responsável a decidir sobre cada linha. Você encontrará acessos que existem porque ninguém havia precisado nomeá-los. Esse é o acesso que vale a pena remover antes que seja usado no pior momento possível.