Chamadas de descoberta versus chamadas de mutação para agentes de IA mais seguros

Um agente que pode inspecionar amplamente um sistema e alterá-lo sem critério tem uma autoridade mal definida. A separação útil é simples: permita que o agente descubra o suficiente para montar um plano fundamentado e, depois, estabeleça um limite claro para operações que criam, modificam, acionam ou excluem estado.

Essa separação parece óbvia até você encontrar uma API real. Um endpoint supostamente somente leitura atualiza um cache. Uma prévia aloca um trabalho remoto. Um endpoint de atualização aceita um filtro vazio e altera todos os registros. Um comando SSH parece inofensivo, até que uma expansão do shell transforme um caminho restrito em um caminho amplo. Nomes de métodos e boas intenções não protegem uma conta de produção.

Já vi equipes resolverem isso colocando uma pessoa diante de cada chamada. Isso protege a conta por uma tarde e faz com que todos aprendam a aprovar sem ler até sexta-feira. O design melhor dá espaço para os agentes inspecionarem, torna as mudanças de estado evidentes e aplica o maior atrito onde uma ação errada produz um resultado irreversível ou caro.

A descoberta precisa de um formato de permissão diferente

As chamadas de descoberta devem responder a perguntas sobre o estado atual sem alterá-lo, enquanto as chamadas de mutação tentam criar, editar, executar ou remover algo. A distinção importa porque um agente não consegue planejar com segurança a partir de suposições desatualizadas, mas também não deve receber um direito permanente de agir apenas porque precisa de contexto.

Um agente de programação que investiga uma falha de implantação pode precisar listar serviços, buscar eventos recentes, comparar uma revisão de configuração, consultar o status do repositório e ler uma ocorrência remota. Essas solicitações reduzem a incerteza. Se você exigir aprovação para cada uma, o operador verá uma sequência de prompts pequenos, com pouco contexto para avaliar. Enquanto espera, o agente também perde o fio da investigação.

Mais tarde, esse mesmo agente pode reiniciar uma carga de trabalho, fazer merge de um pull request, alternar uma credencial, fechar uma ocorrência ou excluir um objeto. Cada operação altera o mundo fora da janela de contexto do agente. O operador deve ver o destino e o efeito propostos antes de autorizá-los.

Isso não equivale a conceder uma função ampla de «somente leitura» e considerar o problema resolvido. A descoberta pode expor material sensível. Também pode gerar custos, consumir limites de uso ou ativar comportamentos em um serviço mal projetado. A separação controla ações, não declara que a inspeção é inofensiva.

Uma classificação útil pergunta o que o sistema remoto consegue observar depois que a solicitação termina:

1. Uma chamada de descoberta retorna informações e não deixa nenhuma mudança relevante no estado comercial, operacional ou de cobrança.
2. Uma chamada de mutação cria, atualiza, exclui, executa, publica, envia ou altera de alguma forma um estado visível externamente.
3. Uma chamada ambígua deve ser tratada como mutação até que alguém prove o contrário.

A terceira categoria merece mais atenção do que costuma receber. Se ninguém consegue explicar os efeitos colaterais de um endpoint com base no contrato e em um teste controlado, não o coloque no conjunto de descoberta sem supervisão só porque o nome parece inofensivo.

Os verbos HTTP são uma pista, não uma decisão de permissão

Os nomes dos métodos HTTP ajudam a classificar chamadas, mas não substituem a revisão do endpoint. A RFC 9110 define GET, HEAD, OPTIONS e TRACE como métodos «seguros», isto é, métodos em que o cliente não solicita uma mudança de estado. A RFC também alerta que o servidor ainda pode registrar solicitações, cobrar uma conta ou produzir outros efeitos incidentais.

Essa distinção é fácil de ignorar. A segurança HTTP descreve a semântica pretendida da solicitação, não uma promessa criptográfica de que a implementação não fez nada. A RFC 9110 atribui ao proprietário do recurso a responsabilidade de evitar ações inseguras quando os usuários seguem as convenções de métodos seguros. Seu agente não consegue impor essa promessa se o serviço a viola.

Trate estas regras como pontos de partida, não como decisões finais:

1. GET e HEAD normalmente pertencem ao conjunto candidato à descoberta. Revise primeiro os parâmetros de consulta e a documentação do endpoint.
2. POST, PUT, PATCH e DELETE pertencem ao conjunto de mutações, a menos que um endpoint específico tenha um comportamento de leitura documentado e testado.
3. OPTIONS pode inspecionar os recursos do servidor, mas algumas plataformas incluem detalhes específicos da conta que ainda precisam de controle de escopo.
4. Um teste de webhook, uma prévia de tarefa, uma exportação de relatório ou um endpoint de busca pode usar POST e ainda assim ser observacional. Verifique o comportamento em vez de liberar todo POST.

O problema inverso também é comum. Às vezes, desenvolvedores ligam um link ou uma rota GET a uma ação porque é conveniente. Uma URL como /reports/monthly?refresh=true pode reconstruir um cache caro de relatórios. Um endpoint GET com ?send=true pode entregar uma notificação. Um agente que segue uma descrição de API usará o que recebe. Não espere que o modelo perceba que o projetista do servidor ignorou a semântica HTTP.

Leia na documentação do endpoint palavras como «cria», «inicia», «atualiza», «gera», «envia», «registra», «sincroniza» e «cobra». Esses verbos devem tirar a chamada da descoberta, mesmo quando a rota usa GET. Depois, teste o endpoint em uma conta descartável e compare o estado antes e depois, incluindo filas de tarefas, notificações, contadores de uso e registros de auditoria.

A resposta HTTP também ajuda a classificar a solicitação. Uma resposta que retorna um identificador de tarefa, um identificador de operação ou a URL de um novo recurso geralmente indica que o serviço remoto iniciou um trabalho. Um status 200 prova apenas que o servidor processou a solicitação. Não prova que ela foi observacional.

Defina recursos e efeitos antes de criar listas de permissão

Uma lista de caminhos permitidos é simplista demais quando ignora o recurso e o efeito por trás de cada caminho. Crie um inventário pequeno de ações que diga o que um agente pode inspecionar, o que pode propor e o que nunca deve fazer sem uma decisão humana direta.

Use um registro como este para cada ação externa. Os nomes não importam. As evidências importam.

Action: repository pull request list
Channel: HTTP
Target pattern: GET /repos/{owner}/{repo}/pulls
Class: discovery
Data returned: title, status, branch names, review metadata
Side-effect evidence: API reference defines this endpoint as a list operation
Scope limit: named repositories only
Review date: 2025-02-14

Action: repository merge pull request
Channel: HTTP
Target pattern: PUT /repos/{owner}/{repo}/pulls/{number}/merge
Class: mutation
Effect: changes merge state and source history
Required control: explicit approval for each call

O inventário força uma decisão que as equipes costumam deixar vaga: o agente tem permissão para conhecer este recurso ou para alterá-lo? São concessões diferentes. Um sistema de tickets pode permitir a descoberta do título e do status de uma ocorrência, mas negar o conteúdo dos comentários porque eles contêm dados de clientes. Uma conta de nuvem pode permitir a listagem de uma carga de trabalho com escopo restrito, mas negar acesso a identidades e registros de cobrança de toda a conta.

Mantenha o escopo no registro da ação. GET /projects não é uma descrição útil de permissão se a credencial puder listar todos os projetos já criados pela empresa. Uma descrição melhor nomeia a organização, o repositório, o namespace, a conta ou o caminho de que o agente precisa. Se o serviço upstream não puder restringir a credencial dessa forma, imponha uma lista de destinos permitidos no gateway de ações ou não torne essa descoberta automática.

Não preencha essa lista apenas a partir de arquivos Swagger. As descrições de API costumam identificar o método e os parâmetros, mas omitem as consequências operacionais. Combine a documentação com uma conta de teste, um registro de auditoria do serviço e um responsável pelo sistema remoto. O objetivo é formular uma afirmação explícita que alguém possa revisar quando a API mudar.

Uma solicitação de leitura ainda pode causar danos ao sistema

O acesso de leitura tem um raio de impacto e merece limites próprios. Um agente autorizado a inspecionar todos os repositórios, nomes de segredos, notas de incidentes, registros de clientes e eventos de implantação recebe contexto suficiente para causar danos se um invasor controlar o processo do agente ou suas instruções.

A recomendação popular é «comece com acesso somente leitura». Ela é popular porque parece cautelosa e combina com nomes conhecidos de funções de IAM. Está errada quando substitui a reflexão sobre classificação de dados por uma função ampla de leitura. A descoberta ampla costuma produzir a maior exposição de informações do design.

Separe duas perguntas:

• A solicitação pode alterar o estado remoto?
• A resposta pode revelar informações que o agente não deveria receber?

Uma solicitação só deve receber tratamento de descoberta depois de passar pela primeira pergunta. Ela só deve receber permissão depois de passar pela segunda. Não reduza esses testes a um único rótulo.

Para recursos sensíveis, retorne apenas os campos de que o agente precisa. Um diagnóstico de implantação pode precisar da fase do pod, do digest da imagem e das mensagens de eventos recentes. Não precisa dos valores de ambiente nem de um objeto de configuração completo. Um agente de triagem de ocorrências pode precisar de etiquetas e horários, não de todos os comentários privados. Se a API não permitir selecionar campos, coloque uma ação intermediária restrita diante dela ou mantenha a operação sob aprovação.

A paginação também precisa de atenção. Um endpoint de listagem pode parecer limitado em um teste ideal e se tornar uma rota de extração ilimitada de dados quando o agente segue cursores. Limite o tamanho da página e o total de páginas quando o canal permitir. Registre esse limite no inventário de ações. Limites de uso protegem o provedor, mas não definem um limite adequado de informações para seu agente.

Endpoints de busca precisam do mesmo tratamento. Uma busca de texto completo no código-fonte ou nos registros de suporte pode revelar mais que uma consulta direta a um objeto, e o texto do prompt pode influenciar a consulta. Restrinja as coleções pesquisáveis e a sintaxe das consultas. Não passe expressões de busca criadas pelo agente diretamente a um backend poderoso só porque a solicitação usa GET.

As credenciais devem impor a separação sempre que possível

O lugar mais seguro para distinguir inspeção de ação é o modelo de autorização do serviço remoto. Use uma credencial que possa ler os recursos aprovados para descoberta e outra, separada, que possa executar as mutações delimitadas exigidas pelo fluxo.

Essa estrutura limita uma falha simples, mas desagradável: um agente malicioso ou confuso encontra um endpoint de mutação que você esqueceu de negar. Se a credencial de descoberta não puder escrever, a chamada ao endpoint falha, mesmo que sua camada de ações o classifique incorretamente. Isso é uma defesa por controles independentes, não um motivo para tratar o inventário de ações com descuido.

Alguns serviços facilitam isso com escopos, funções, permissões de projeto ou identidades de máquina separadas. Outros expõem apenas um token pessoal amplo. Quando o provedor oferece somente a segunda opção, use o menor limite de conta e projeto disponível e imponha endpoints e padrões de destino específicos no gateway. Nunca dê a um agente autônomo a credencial pessoal de um administrador só porque ela já está disponível.

Uma configuração limpa costuma ter três classes de credenciais:

1. Uma credencial de descoberta com acesso exato aos recursos que o agente pode inspecionar.
2. Uma credencial de mutação para escritas delimitadas que ainda exigem uma decisão de aprovação.
3. Uma credencial de emergência que os agentes nunca usam e que os humanos recuperam somente por meio de um processo de incidentes.

Não permita que uma credencial de mutação responda a chamadas de descoberta por padrão. Isso parece inofensivo porque o endpoint é somente leitura, mas dificulta revisões futuras. Um log que diz que uma credencial poderosa consultou um recurso não informa se o agente precisava dessa autoridade. Mantenha a identidade significativa.

Sallyport mantém credenciais de API e SSH em seu cofre criptografado e executa a ação externa por conta própria. Assim, um agente MCP recebe o resultado, não o segredo. Esse design torna prático expor uma rota de descoberta restrita sem colocar um bearer token ou material SSH privado no contexto do agente.

A aprovação deve descrever a mudança, não punir toda solicitação

A aprovação por chamada funciona quando o revisor consegue ver um efeito concreto e tomar uma decisão rápida. Ela falha quando o sistema pede consentimento após cada consulta inofensiva, porque a pessoa aprende que o prompt não contém nenhuma decisão que valha a pena tomar.

Use a autorização da sessão para estabelecer qual processo de agente pode usar o conjunto de descoberta. Depois, exija aprovação individual para ações de mutação e mostre a solicitação em termos que uma pessoa consiga avaliar. «POST /v1/jobs» é um texto ruim para aprovação. «Iniciar uma exportação de dados do projeto northwind para o bucket de arquivo, com estimativa de 30 dias» dá ao revisor algo que ele pode verificar.

O cartão de aprovação deve incluir o destino, a operação, os parâmetros relevantes e a identidade da credencial. Não esconda o destino em um corpo JSON extenso. Se uma ação afetar mais de um recurso, mostre a quantidade e uma amostra compacta. Quando a quantidade exceder a faixa normal esperada, exija que o operador abra o conjunto completo antes da aprovação.

Uma carga de solicitação para uma atualização delimitada poderia ser assim:

{
  "action": "update_issue",
  "target": {
    "repository": "payments-api",
    "issue": 1842
  },
  "changes": {
    "labels_add": ["needs-review"],
    "assignee": "release-manager"
  },
  "reason": "The release checklist is complete."
}

O agente pode preparar essa solicitação depois de uma descoberta sem restrições dentro do escopo permitido. A pessoa deve aprovar a mudança, não reconstruir toda a investigação do agente. Preserve o motivo porque ele torna a revisão posterior menos especulativa, mas não confie nele como controle de segurança. Um agente pode produzir uma frase plausível para um destino incorreto.

Evite políticas de aprovação baseadas apenas na intenção expressa em linguagem natural. «Aprovar mudanças de implantação» parece razoável até que um agente classifique a exclusão de um banco de dados como mudança de implantação. Vincule a aprovação a uma classe de operação, a um escopo de destino e a uma credencial. O texto ajuda as pessoas a entender a solicitação. Limites de ações tipadas impedem incompatibilidades.

Exclusão e execução externa precisam de uma classe própria

Exclusões, mudanças de permissão, rotação de credenciais, operações financeiras e chamadas que acionam sistemas externos devem receber um tratamento mais rigoroso que atualizações comuns. Elas podem remover caminhos de recuperação, alterar quem tem acesso, gerar custos ou causar trabalho fora do sistema em que o agente começou.

Não esconda exclusões dentro da categoria geral de mutações. Um patch que corrige a etiqueta de uma ocorrência geralmente pode ser revertido com facilidade. Uma chamada de exclusão pode remover anexos, registros filhos, histórico ou um ambiente nomeado. A API pode colocar uma limpeza assíncrona na fila depois de retornar sucesso, o que significa que o operador nem sempre consegue reverter o erro com uma única solicitação compensatória.

Exija um controle distinto por chamada para ações como:

1. Excluir, eliminar permanentemente, arquivar quando o arquivamento alterar a disponibilidade e remover em massa.
2. Alterar permissões, associações, funções, segredos, credenciais e políticas de acesso.
3. Fazer implantação, reiniciar, escalar, migrar e executar comandos remotos.
4. Enviar e-mails, publicar mensagens, abrir tickets externos e iniciar tarefas pagas.

Antes de a aprovação chegar a uma pessoa, obrigue o agente a resolver os identificadores em uma prévia. Uma solicitação de exclusão contra records?filter=status=inactive deve mostrar a quantidade exata, o filtro e nomes representativos. Melhor ainda, faça o agente buscar primeiro os identificadores candidatos e enviar uma lista que o gateway compare com a solicitação de execução. Isso não elimina condições de corrida, mas captura o erro mais comum: um filtro que significa algo diferente do que o agente supôs.

A confirmação com prazo limitado também é sensata. Se um operador aprovou uma solicitação destrutiva há uma hora, o agente não deve usar essa aprovação depois que o estado ao redor mudou. Vincule a aprovação a um corpo de solicitação ou a um resumo imutável específico, não a uma categoria ampla como «excluir acessos hoje».

SSH exige classificação no nível do comando

SSH é mais difícil de classificar que uma API bem projetada porque uma linha de comando pode combinar inspeção e mutação, chamar um shell, seguir aliases ou alterar o comportamento conforme o ambiente remoto. Não é seguro considerar um host inteiro somente leitura porque o agente pretende executar um comando de leitura.

Comece com comandos e argumentos explícitos. git status --short, git log -n 20 --oneline e kubectl get pods -n staging são ações de descoberta plausíveis quando você restringe o diretório de trabalho, o contexto do cluster e o namespace. git push, kubectl apply, kubectl delete, rm, instalações de pacotes e reinícios de serviços pertencem às classes de mutação ou execução destrutiva.

Rejeite a composição de shell na descoberta sem supervisão. Este é o tipo de comando que parece uma solicitação de listagem, mas devolve o controle ao shell:

find "$WORKDIR" -maxdepth 2 -type f -name '*.log' -print; $EXTRA_COMMAND

Mesmo que o agente forneça um EXTRA_COMMAND vazio nos testes, um valor posterior poderá executar qualquer coisa permitida pela identidade SSH. Não aprove uma gramática de comandos que contenha ;, &&, ||, substituição de comandos, redirecionamentos, expansão de curingas sobre caminhos não controlados ou uma chamada de interpretador, a menos que a própria ação seja revisada como execução.

Use argumentos estruturados. Um gateway pode aceitar uma ação chamada list_recent_logs, validar um diretório fixo e um limite numérico e então construir o comando remoto por conta própria. O agente nunca deve enviar uma string de shell quando uma ação tipada resolver o problema.

O mesmo princípio vale para ferramentas com verbos de leitura. kubectl get pode expor dados secretos se o recurso e o namespace forem amplos. git show pode revelar uma credencial que foi incluída por engano. Crie permissões de comando com base no executável, subcomando, argumentos, diretório de trabalho e identidade remota. O verbo, sozinho, informa muito pouco.

Os registros de auditoria devem mostrar que o limite foi respeitado

Uma trilha de auditoria deve permitir que um revisor responda quem fez a chamada, qual rota de credencial a ação usou, qual destino alcançou, se uma pessoa a aprovou e o que o sistema remoto retornou. Se a trilha registra apenas «agente invocou ferramenta», ela não prova que o acesso de descoberta permaneceu separado da autoridade de mutação.

Registre ações tentadas e concluídas. Uma solicitação de exclusão negada é importante. Ela pode indicar que o agente não entendeu seu escopo, que uma injeção de prompt tentou direcioná-lo ou que alguém está testando o limite. Registre o motivo da negação sem gravar segredos ou corpos de resposta sensíveis em um log com acesso mais amplo que o sistema original.

Para cada ação, capture pelo menos estes campos em um registro à prova de adulteração:

• Identidade do processo do agente e identificador da sessão.
• Classe da ação: descoberta, mutação, destrutiva ou execução externa.
• Identidade do destino, método da solicitação ou formato do comando e uma representação segura dos parâmetros.
• Evento de aprovação, incluindo a pessoa que aprovou quando isso era necessário.
• Resultado, status remoto, referência do resultado e horários.

Uma cadeia de hashes ajuda a detectar alterações no log, mas não torna útil um evento vago. Armazene um registro canônico da ação antes da execução e vincule o registro da resposta a ele. Se o registro disser apenas POST /jobs, um revisor ainda não saberá se o agente iniciou um relatório inofensivo ou uma exportação cara.

O Sallyport reúne os diários de sessões e chamadas em um único log de auditoria criptografado e encadeado por hashes. O comando sp audit verify verifica a cadeia offline sem precisar de acesso ao cofre. A verificação só é útil quando a taxonomia de ações torna o evento inteligível, portanto mantenha a classificação próxima do caminho de execução, em vez de adicionar rótulos mais tarde em uma camada de relatórios.

Teste o limite com falhas, não apenas com caminhos ideais

Uma separação de permissões conquista confiança quando bloqueia solicitações ruins que você consegue prever. Trate cada ação de descoberta como um contrato testável e execute casos negativos sempre que a API, o wrapper de comandos ou o fluxo do agente mudar.

Para uma rota HTTP de descoberta, teste um destino permitido, um destino proibido vizinho, um método não aceito, uma solicitação de página grande demais e uma consulta que tente atravessar o limite de um tenant ou projeto. Espere negações específicas. Um erro genérico do servidor é uma evidência fraca, porque pode se tornar sucesso depois de uma pequena mudança de código.

Para uma rota de mutação, teste se uma solicitação válida pausa para aprovação, se a alteração de qualquer campo relevante invalida a aprovação e se um segundo processo de agente não herda a permissão de sessão do primeiro. Para exclusões, teste seletores vazios, seletores semelhantes a curingas, listas maiores que o esperado e destinos que desapareceram entre a prévia e a execução.

Mantenha um rastreamento completo para cada classe de ação. Um bom rastreamento é curto o bastante para um revisor ler e concreto o bastante para revelar uma incompatibilidade:

09:14:03  discovery  GET /projects/acme/services?limit=20  allowed
09:14:05  discovery  GET /projects/acme/services/api-7/events  allowed
09:14:11  mutation   POST /projects/acme/services/api-7/restart  approval required
09:14:32  mutation   POST /projects/acme/services/api-7/restart  approved by operator
09:14:34  mutation   result: accepted, operation=op_481

Se a terceira linha disser GET /services/api-7?action=restart, seu modelo de classificação já encontrou um defeito. Corrija o contrato da ação ou mantenha essa rota sob controle de mutação. Não crie uma exceção porque o endpoint é inconveniente.

Comece pelas ações externas que seus agentes já executam. Marque cada uma pelo efeito, verifique seu comportamento real, restrinja o destino e teste os casos de negação. Quando o agente pedir algo novo, exija uma classificação explícita antes que a ação chegue à produção. Essa pequena pausa custa menos que tentar explicar uma mudança não revisada depois do fato.