Registro de auditoria de ações de agentes: um modelo prático para controle

As ações de agentes precisam de registros que descrevam a autoridade, não apenas a atividade. Uma linha como POST /deploy returned 200 não informa ao investigador se o processo certo fez a solicitação, se alguém a autorizou, qual sistema a recebeu ou se uma revogação posterior interrompeu alguma coisa.

A unidade prática é um registro imutável de ação, ligado a eventos de sessão, aprovação e revogação. Mantenha o registro pequeno o bastante para ser pesquisado e verificado, mas específico o bastante para que um engenheiro cansado consiga reconstruir uma chamada contestada sem inventar uma história para preencher os campos ausentes.

Uma entrada de auditoria precisa descrever uma tentativa autorizada

Um registro de auditoria de ação de agente captura um efeito tentado sobre um sistema externo e o contexto de autoridade presente naquele instante. Uma ação pode falhar antes de chegar à rede, falhar durante a entrega, receber uma recusa do destino ou ser concluída com sucesso. Os quatro casos pertencem à trilha de auditoria.

As equipes costumam registrar uma de duas coisas inadequadas. Registram uma transcrição do chat, que descreve a intenção, mas não a execução. Ou registram o tráfego bruto das solicitações, que produz material secreto demais e ainda não mostra a decisão humana que permitiu a chamada. Nenhum dos dois registros responde se um determinado ator tinha autoridade para executar uma determinada operação.

Trate estes elementos como objetos separados:

• Uma sessão identifica um processo de agente em execução e seu ciclo de vida.
• Uma aprovação registra uma decisão humana com escopo definido.
• Uma ação registra uma operação externa solicitada e seu resultado.
• Uma revogação encerra uma sessão ou autorização em um momento preciso.

A distinção tem uma consequência durante um incidente. Se alguém revoga uma sessão às 14:03, você precisa ver todas as ações anteriores às 14:03, todas as ações tentadas depois das 14:03 e a decisão local que negou essas tentativas posteriores. Uma única linha mutável com o rótulo «sessão aprovada: falso» destrói esse histórico.

Não faça o modelo do registro depender de a ação ter sido bem-sucedida. A própria solicitação pode indicar intenção maliciosa, uma falha de configuração ou um agente que entendeu mal a tarefa. As chamadas que falham costumam ser a primeira evidência útil.

O ator é um processo, não um rótulo amigável de agente

Registre o processo que realmente solicitou a ação. O nome do modelo, do workspace ou o apelido do agente pode ajudar uma pessoa a ler um relatório, mas nenhum deles identifica de forma única o executável que mantinha a conexão naquele momento.

Um objeto de ator útil contém um identificador interno de sessão, o ID do processo, o caminho do executável, o horário de inicialização e a autoridade de assinatura de código quando o sistema operacional fornecer essa informação. Inclua o ID e o executável do processo pai quando puder coletá-los de forma confiável. A relação com o processo pai costuma explicar se um terminal iniciou o agente, se uma extensão do editor o criou ou se houve um helper inesperado.

Use uma captura da identidade do processo em vez de tentar resolvê-lo depois. IDs de processo são reutilizados. Caminhos podem mudar. Uma consulta posterior não corrige uma observação que não foi registrada.

{
  "actor": {
    "session_id": "ses_01J8Q1F9K9Z3",
    "pid": 48217,
    "started_at": "2025-02-18T21:14:06Z",
    "executable": "/usr/local/bin/agent-runner",
    "signing_authority": "Developer ID Application: Example Developer",
    "parent_pid": 48091,
    "parent_executable": "/Applications/Terminal.app"
  }
}

O valor de signing_authority deve vir da avaliação de assinatura da plataforma, não de uma string fornecida pelo agente. Um agente pode se chamar claude-code, deploy-helper ou trusted-agent. Um rótulo é apenas decoração, a menos que o sistema operacional o associe a uma identidade executável.

Não transforme a identidade do processo em uma falsa afirmação de autoria. Um binário assinado pode agir mal depois de uma injeção de prompt, de um plugin comprometido ou de uma instrução descuidada. O campo estabelece qual autoridade de código iniciou a solicitação. Ele não certifica que a solicitação foi sensata.

A RFC 5424, especificação do protocolo syslog, separa campos de cabeçalho, como nome da aplicação e ID do processo, dos dados estruturados. Essa separação continua fazendo sentido nos registros de agentes. Coloque a identidade estável e os horários em campos próprios que as máquinas possam consultar. Coloque o contexto variável, como referência de repositório ou tarefa, em um objeto com namespace. Quando tudo vai para uma única string de mensagem, cada investigação posterior vira análise de texto.

Um destino precisa de endereço e significado

Registre para onde a ação foi e qual recurso ou comando ela tentou afetar. São fatos relacionados, mas não intercambiáveis.

No caso de HTTP, o destino de rede pode ser api.example.internal, enquanto a operação relevante é POST /v1/releases/{release_id}/promote. Armazene host, porta, protocolo, método HTTP e um modelo de rota. Adicione um identificador do sistema de destino controlado pela equipe, como release-service-prod. O identificador continua válido depois de uma migração de hostname; o hostname ajuda a diagnosticar a solicitação que realmente saiu da máquina.

Para SSH, armazene o alias ou nome do host, a porta, a impressão digital da chave do host ou uma referência à entrada de hosts conhecidos e o rótulo da conta remota quando for seguro mantê-lo. O destino também deve nomear a classe do comando solicitado. restart-worker explica mais do que ssh succeeded, mas revela menos do que um comando shell completo contendo caminhos de clientes e variáveis de ambiente.

Faça a redação antes da persistência, não depois que um analista abrir o log. Strings de consulta de URLs, cabeçalhos de solicitação, argumentos shell e corpos JSON costumam conter tokens. Uma biblioteca de logs que os captura «para depuração» acabará produzindo um arquivo de incidente cheio de credenciais.

Este formato mantém os fatos do destino consultáveis sem copiar todo o conteúdo da solicitação:

{
  "target": {
    "kind": "http",
    "system_id": "release-service-prod",
    "endpoint": {
      "scheme": "https",
      "host": "api.example.internal",
      "port": 443,
      "method": "POST",
      "route_template": "/v1/releases/{release_id}/promote"
    }
  },
  "operation": {
    "name": "promote_release",
    "request_fingerprint": "sha256:8e8c...",
    "request_bytes": 286,
    "redacted_parameters": {
      "environment": "production",
      "release_id": "rel_7b2"
    }
  }
}

A impressão digital só ajuda se você definir a canonização. Ordene os campos dos objetos, remova os campos excluídos pela política de redação, normalize a codificação do texto e então gere o hash dos bytes resultantes. Registre a versão da canonização. Caso contrário, duas solicitações equivalentes podem produzir resumos sem relação, e uma mudança futura no schema pode fazer registros antigos parecerem suspeitos.

Um resumo não substitui a evidência retida quando um regulador, contrato ou processo de incidente exige a solicitação original. Nesse caso, criptografe a evidência separadamente, restrinja o acesso e armazene o resumo do conteúdo no registro da ação. Não coloque o corpo original no diário comum pesquisável apenas porque o armazenamento é barato.

A operação solicitada e o resultado observado precisam de campos diferentes

Uma solicitação do agente expressa uma intenção. O resultado informa o que o gateway observou depois de tentar executar essa intenção. Não misture os dois em um status vago como completed.

Em uma chamada de rede, registre a etapa do transporte em que a execução parou, o status do protocolo quando houver um, um resumo limitado da resposta e o tempo gasto. Para SSH, registre o resultado da conexão, o resultado da autenticação, o código de saída remoto e resumos limitados de saída padrão e de erro. Um destino pode aceitar uma solicitação e executar um trabalho assíncrono depois, portanto uma resposta 202 não significa que a alteração externa ocorreu.

Use um vocabulário de resultados que indique onde a falha aconteceu. Por exemplo:

• denied_vault_locked significa que o limite local de segredos recusou a chamada.
• denied_approval significa que a decisão humana exigida não a autorizou.
• network_error significa que o gateway não conseguiu estabelecer ou manter uma conexão.
• target_rejected significa que o serviço remoto devolveu uma recusa.
• target_accepted significa que o serviço remoto aceitou a solicitação.

Mantenha o erro bruto de transporte fora do campo de status principal. Coloque um código normalizado, como dns_lookup_failed ou tls_validation_failed, ao lado de um diagnóstico curto e redigido. Engenheiros precisam de agregação; quem responde ao incidente precisa de contexto local suficiente para distinguir um certificado expirado de um hostname bloqueado.

Um objeto de resultado completo pode ser assim:

{
  "result": {
    "outcome": "target_accepted",
    "started_at": "2025-02-18T21:19:42.184Z",
    "finished_at": "2025-02-18T21:19:43.021Z",
    "duration_ms": 837,
    "http_status": 202,
    "response_fingerprint": "sha256:2a64...",
    "response_summary": "promotion job accepted",
    "evidence_ref": null
  }
}

Evite chamar target_accepted de sucesso no schema. Essa palavra causa problemas depois. Se o serviço aceita um trabalho e o trabalho falha, o gateway fez exatamente o que deveria, enquanto a operação de negócio não terminou. Um evento posterior de conclusão remota, associado por um ID de trabalho, pode responder a essa outra pergunta.

Os registros de aprovação precisam dizer o que a pessoa aprovou

Um registro de aprovação precisa de uma decisão, um escopo, um objeto e horários. «Usuário aprovou o agente» diz pouco. Os revisores ficam sem saber se a pessoa autorizou uma chamada de API, uma credencial específica, uma sessão ou todas as sessões futuras de um processo com nome parecido.

Uma aprovação de sessão normalmente permite chamadas de um processo identificado até que ele seja encerrado ou alguém o revogue. Uma aprovação por chamada se aplica a um único uso de uma credencial ou operação. Registre o escopo diretamente, porque os dois controles produzem riscos muito diferentes.

{
  "approval": {
    "approval_id": "apr_01J8Q1P4Y5D6",
    "decision": "approved",
    "scope": "session",
    "subject_session_id": "ses_01J8Q1F9K9Z3",
    "approved_at": "2025-02-18T21:14:11Z",
    "expires_at": "2025-02-18T22:02:53Z",
    "approver_presence": "local_user_confirmation"
  }
}

Não afirme mais certeza do que sua interface consegue oferecer. Se a aplicação recebe um evento de confirmação local, registre esse fato. Não registre o nome de uma pessoa, a conta do provedor de identidade ou o método biométrico, a menos que o sistema realmente autentique e mantenha essa associação sob uma política documentada. Detalhes de identidade inventados criam uma falsa sensação de segurança e obrigações de privacidade.

Armazene a aprovação que governou uma ação como um identificador no registro da ação. Armazene também a decisão de autorização ocorrida imediatamente antes da execução. Isso parece repetitivo até que você investigue um caso de timing: pode existir uma aprovação antiga da sessão, mas uma exigência por chamada pode negar a ação. A ação precisa dos dois fatos.

A fadiga de aprovações é um defeito de design, não um motivo para omitir evidências de aprovação. Se uma pessoa precisa aprovar cada solicitação inofensiva, ela aprovará sem ler. Reserve a confirmação por chamada para credenciais ou operações cujo uso indevido exige atenção direta e faça o registro explicar por que o gateway solicitou a aprovação.

A revogação é um evento com horário de corte

A revogação encerra a autoridade dali em diante. Ela não apaga uma sessão, recolhe uma solicitação já entregue nem altera a decisão de aprovação que existia cinco minutos antes.

Registre o alvo da revogação, o tipo de iniciador, o horário observado e o resultado da aplicação. Se o gateway consegue encerrar ou bloquear uma sessão ativa, registre se fez isso. Se uma ação já atravessou o limite da rede, diga que a revogação não pode recuperá-la. Engenheiros precisam desse fato desagradável durante a resposta, não de um rótulo revoked reconfortante, mas falso.

Considere esta sequência de falha:

1. Um processo de agente recebe aprovação de sessão às 09:00 e envia uma alteração de produção às 09:17.
2. O operador percebe um destino inesperado e revoga a sessão às 09:18:04.
3. O destino responde à solicitação das 09:17 às 09:18:07 porque já havia colocado o trabalho em fila.
4. O agente tenta outra chamada às 09:18:09, e o gateway a nega.

Um bom diário preserva os quatro eventos. A ação das 09:17 estava autorizada quando começou. A resposta depois da revogação pertence à ação anterior. A tentativa negada prova que a revogação passou a valer para o trabalho posterior. Se você marcar todas as ações anteriores como «revogadas», perde a sequência que explica a exposição real.

Use um número de sequência monotônico além do horário do relógio. Relógios podem variar, usuários podem alterar a hora local e eventos podem compartilhar a mesma resolução de timestamp. Um número de sequência estabelece a ordem em que o diário aceitou os registros. Se você opera em vários hosts, preserve a sequência local de cada host e use IDs de correlação em vez de fingir que relógios de parede estabelecem uma ordem global perfeita.

A evidência de adulteração depende de disciplina de apenas anexar

Uma cadeia de hashes torna mais difícil editar registros sem ser detectado, pois inclui o resumo do registro anterior em cada novo registro. Ela não transforma um arquivo de log comum em prova de que todos os eventos esperados existem. Alguém que controle o escritor e o início armazenado da cadeia pode excluir um sufixo, iniciar uma nova cadeia ou impedir que os registros cheguem ao armazenamento persistente.

Essa limitação não torna as cadeias de hashes inúteis. Elas respondem a uma pergunta mais específica e útil: esses registros mudaram, desapareceram do meio ou chegaram em outra ordem depois que o sistema os gravou? Mantenha explícitos os campos da cadeia.

{
  "journal": {
    "sequence": 1842,
    "recorded_at": "2025-02-18T21:19:43.024Z",
    "previous_hash": "sha256:68b1...",
    "record_hash": "sha256:93f4...",
    "hash_format": "canonical-json-v1"
  }
}

Gere o hash do registro canônico completo, excluindo apenas o próprio record_hash. Não gere o hash de uma representação formatada cuja quantidade de espaços, ordem dos campos ou formato dos timestamps mude entre versões. Versione o formato canônico e mantenha o verificador para cada formato emitido.

A publicação especial 800-92 do NIST, Guide to Computer Security Log Management, trata a geração, o armazenamento, a análise e a retenção de logs como responsabilidades separadas. Essa distinção corrige um erro frequente: as equipes adicionam um hash às entradas e consideram o trabalho concluído. Você ainda precisa de armazenamento persistente, controles de acesso ao escritor, uma decisão de retenção, verificação regular e um procedimento de investigação para uma checagem que falhou.

O Sallyport projeta seus diários Sessions e Activity a partir de um único log de auditoria criptografado, encadeado por hashes e sem possibilidade de leitura pelo escritor. O comando sp audit verify verifica a cadeia offline sobre o texto cifrado sem exigir uma chave do cofre. Esse design separa a capacidade de um leitor verificar a integridade do diário da capacidade de usar credenciais.

Um único ID de correlação torna o registro útil sob pressão

Dê a cada ação solicitada um ID de ação antes que o gateway avalie a autorização. Leve-o pela decisão local, pela tentativa de rede, pelo tratamento da resposta e por qualquer callback posterior de conclusão remota. Quando um engenheiro encontrar uma implantação contestada, ele deve pesquisar um único identificador e recuperar a linha do tempo completa.

Use IDs relacionados para relacionamentos diferentes. A ação aponta para sua sessão, aprovação, referência de credencial, destino e sequência do diário. Uma referência a tarefa ou conversa pode apontar da ação para o contexto do agente, mas não transforme a transcrição da conversa na fonte de verdade. O texto do prompt muda, pode conter material privado e muitas vezes não descreve exatamente a solicitação que acabou sendo feita.

Um registro completo e compacto pode usar este formato:

{
  "schema_version": "1.0",
  "action_id": "act_01J8Q2ABR8M7",
  "event_type": "action.completed",
  "actor": {"session_id": "ses_01J8Q1F9K9Z3", "pid": 48217},
  "target": {"kind": "http", "system_id": "release-service-prod"},
  "operation": {"name": "promote_release", "request_fingerprint": "sha256:8e8c..."},
  "authorization": {"vault": "unlocked", "approval_id": "apr_01J8Q1P4Y5D6", "decision": "approved"},
  "result": {"outcome": "target_accepted", "http_status": 202},
  "journal": {"sequence": 1842, "previous_hash": "sha256:68b1..."}
}

Não use o ID de correlação como token de autorização. Gere-o de forma independente, faça-o imprevisível quando chamadores externos puderem observá-lo e nunca aceite a posse do ID como permissão para ler uma ação ou emitir uma chamada posterior.

A retenção precisa preservar evidências sem criar um segundo cofre de segredos

Os dados de auditoria acumulam material privado mesmo quando você faz uma redação rigorosa. Nomes de destinos podem revelar clientes, parâmetros de rota podem revelar projetos internos, resumos de respostas podem expor o estado de contas e caminhos de processos podem revelar hábitos de desenvolvedores. Decida quem pode pesquisar os registros, quem pode exportá-los e por quanto tempo cada categoria ficará disponível.

Mantenha os metadados pesquisáveis das ações separados de qualquer evidência criptografada de solicitação ou resposta. Aplique uma retenção mais curta à evidência detalhada quando a necessidade de investigação terminar. Preserve hashes e registros de vinculação por tempo suficiente para provar que os resumos restantes ainda correspondem ao que o sistema registrou.

Teste o modelo com uma pergunta real de uma revisão de incidente: «Qual processo assinado solicitou acesso a este destino de produção, sob qual aprovação, e alguma tentativa continuou depois da revogação?» Se uma consulta exigir que um analista una mensagens não estruturadas, examine logs de depuração do cliente ou pergunte ao agente do que ele se lembra, o modelo está incompleto.

A escada fixa de decisões do Sallyport cria limites claros para esse modelo de registro: o bloqueio do cofre, a autorização da sessão e a aprovação da credencial por chamada produzem cada um um fato de autorização distinto. Mantenha esses fatos separados no seu próprio design de auditoria. O registro deve mostrar onde a autoridade parou, em vez de esconder toda negação sob um código de falha genérico.

Crie o schema antes que os agentes recebam credenciais amplas. Adaptar depois de um incidente a identidade do ator, o escopo da aprovação e a ordem da revogação significa reconstruir a autoridade a partir de lacunas. É um trabalho lento, e normalmente termina com alguém dizendo «achamos» quando o registro deveria dizer exatamente o que aconteceu.