Uma trilha de auditoria de aprovações pode provar quem aprovou uma ação de agente?

Um registro de aprovação que diz apenas «aprovado» não responde à pergunta que importa depois que um agente toca a produção: quem autorizou qual ação, sob qual autoridade e o que aconteceu depois? Ele registra um momento reconfortante na interface e deixa o investigador deduzir o restante.

Uma trilha de auditoria de aprovações precisa preservar a cadeia que vai do processo do agente à decisão humana, da decisão ao uso de uma credencial e do uso da credencial a uma solicitação HTTP ou a um comando SSH concluído. Se esses dados ficarem em registros separados, sem vínculos duráveis, o revisor pode montar uma história plausível. Mas não pode prová-la.

Essa diferença se torna dolorosa quando a ação funciona, mas ninguém se lembra de tê-la aprovado; quando um agente reinicia no meio de uma tarefa; ou quando alguém pergunta se um clique e uma confirmação com Touch ID tiveram o mesmo significado. Não tiveram. Tratar os dois como equivalentes produz um log que parece completo até a primeira revisão séria.

Um evento de aprovação precisa responder mais do que «sim»

Um evento de aprovação útil informa o que a pessoa aprovou, por que o sistema pediu a aprovação, como a decisão foi tomada e onde termina a autorização. O clique no botão visível é apenas um dos campos desse evento.

Registre estes fatos no momento da decisão:

• Um identificador exclusivo da aprovação e um timestamp do evento com deslocamento de fuso horário.
• O método de aprovação, como click ou touch_id.
• A conta local ou outra identidade conhecida do aprovador, além das evidências usadas para fazer essa atribuição.
• O escopo da autorização: uma sessão ou um único uso de credencial para uma chamada.
• A solicitação que provocou o aviso, identificada por um identificador estável de solicitação ou chamada.

Não registre user=alex apenas porque a máquina tem uma conta chamada Alex. Essa pode ser a melhor atribuição disponível e ainda vale a pena registrá-la, mas chame-a pelo que é: contexto da conta local. Se um aviso biométrico for aceito, registre que uma biometria cadastrada naquele dispositivo autorizou o evento. Essas afirmações são mais fortes do que «alguém chamado Alex aprovou», porque não fingem que o log de auditoria sabe mais do que realmente sabe.

A NIST SP 800-171 Rev. 3 oferece um ponto de partida sensato para o conteúdo da auditoria: timestamps, endereços de origem e destino, identificadores de usuário ou processo, descrições de eventos, controles de acesso aplicáveis e resultados. Ela também observa que registros detalhados podem incluir comandos privilegiados e as identidades individuais por trás de contas compartilhadas. Esse é um bom nível mínimo para ações de agentes, não um projeto completo. Um fluxo de aprovação de agente precisa tratar as relações entre a decisão, a credencial e a chamada como dados de primeira classe.

O erro mais fácil é registrar a aprovação como um atributo da ação final, como approved=true. Isso reduz um evento a um rótulo. Você perde o intervalo entre a solicitação e a decisão, a origem da decisão, o escopo do consentimento e qualquer revogação posterior. Também fica impossível distinguir uma aprovação humana de uma autorização padrão, de uma concessão armazenada em cache ou de uma regra de automação.

A decisão deve ter seu próprio registro, mesmo quando a resposta for não. Um aviso rejeitado pode explicar por que um agente falhou ao fazer uma implantação. Um aviso expirado pode explicar por que o agente tentou novamente. Um cofre bloqueado pode explicar por que o sistema se recusou a fazer qualquer chamada de rede. São eventos materialmente diferentes, e um revisor posterior não deveria ter de deduzir a diferença a partir da ausência de um registro de sucesso.

Cinco identidades mantêm a linha do tempo honesta

Uma linha do tempo completa precisa de cinco identidades separadas. Combiná-las economiza colunas em uma tabela e destrói o significado durante uma investigação.

A primeira é o processo do agente. Registre um identificador do processo ou da execução, o executável ou a autoridade de assinatura de código que o iniciou, o horário de início e o horário de término. A pessoa deve conseguir responder: «Qual programa em execução pediu isso?». O nome de um projeto ou uma conversa não basta. Duas cópias do mesmo agente de programação podem ser executadas ao mesmo tempo, e uma pode ser inofensiva enquanto a outra aponta para um repositório diferente.

A segunda é a sessão. Uma sessão é a relação limitada entre um processo do agente e o gateway. Ela precisa de um identificador próprio porque um processo pode fazer muitas chamadas e porque a autorização de sessão costuma valer para várias chamadas. Quando o processo termina, a sessão deve terminar. Se um novo processo começar depois, ele deve criar uma nova sessão, mesmo que tenha o mesmo executável, a mesma conta local e a mesma descrição de tarefa.

A terceira é o contexto do aprovador. Ele inclui a conta do dispositivo, qualquer usuário autenticado da aplicação e o método de aprovação. Não faça o campo do aprovador carregar fatos que ele não consegue sustentar. local_account=maya, method=touch_id e device_id=... são claros. human=maya afirma mais. Em alguns ambientes essa afirmação é razoável; em outros, uma estação de trabalho compartilhada ou uma área de trabalho desbloqueada a invalida imediatamente.

A quarta é a referência da credencial. Ela identifica a autoridade usada pelo gateway, não o segredo em si. Um ID de credencial opaco e estável, um rótulo legível, o canal e o tipo de credencial normalmente bastam para uma revisão de atividade. Um token bearer não é um campo de auditoria. A impressão digital de uma chave privada SSH também pode se tornar um contexto sensível, então decida se os investigadores precisam dela antes de espalhá-la pelos logs comuns.

A quinta é a operação executada. Para HTTP, isso inclui a identidade resolvida do destino, o método da solicitação, o caminho normalizado, fatos selecionados da solicitação que não sejam secretos, o status da resposta e os horários. Para SSH, inclui a identidade do host, a conta remota, o comando ou um hash do comando aprovado, o status de saída e os horários. O evento precisa dizer o que foi executado, não apenas o que foi solicitado.

Essas identidades formam um grafo, não uma linha simples:

agent_process
  -> session
    -> approval_decision
      -> credential_use
        -> executed_call

Uma tela de atividade pode apresentar esse grafo como uma linha quando a pessoa precisa de rapidez. Ainda assim, mantenha os vínculos subjacentes. A tela serve para quem examina um dia de trabalho. Os identificadores servem para quem precisa explicar uma chamada seis semanas depois.

Um clique e o Touch ID são evidências diferentes

Um clique registra a interação com um controle de aprovação na interface atual. O Touch ID registra uma autorização biométrica bem-sucedida pelo sistema operacional, além da interação que a iniciou. Os dois podem autorizar uma ação. Eles não devem compartilhar um valor vago como approved_manually.

Use um campo de método explícito com um conjunto controlado de valores. Por exemplo:

{
  "approval_id": "apr_01J8K4VY5Q",
  "occurred_at": "2026-07-22T14:18:06.184Z",
  "decision": "approved",
  "method": "touch_id",
  "approver": {
    "local_account": "maya",
    "identity_assurance": "device_account_and_biometric"
  },
  "scope": "credential_use",
  "session_id": "ses_01J8K4TE0M",
  "requested_call_id": "call_01J8K4VPM2"
}

Os nomes exatos dos campos não são sagrados. A separação é. method informa como a aprovação foi concluída. identity_assurance informa o que o sistema pode afirmar com responsabilidade sobre a pessoa. scope informa o que a decisão autorizou. requested_call_id vincula a aprovação a uma solicitação que já existia antes de a pessoa ver o aviso.

Um clique pode ser a escolha certa para uma confirmação com pouco atrito, especialmente quando a pessoa já está acompanhando o trabalho do agente. O Touch ID acrescenta uma etapa local de confirmação mais forte para uma operação sensível, mas não fornece magicamente uma identidade corporativa, um motivo para a decisão ou um aval para todas as chamadas posteriores. Se uma equipe precisa de uma aprovação nominal de funcionário com um provedor de identidade externo, precisa de um fluxo que registre a asserção desse provedor. Não atribua silenciosamente essa garantia a um evento biométrico local.

O erro inverso é igualmente ruim: tratar o Touch ID como algo decorativo. Se uma ação exigiu aprovação biométrica e o log reduz o evento a approved=true, o registro não consegue mostrar que o controle mais rigoroso realmente foi executado. A revisão perde uma evidência que poderia separar uma confirmação deliberada de um clique acidental em um aviso amplo de sessão.

Registre tentativas biométricas malsucedidas com cuidado. Uma trilha de auditoria normalmente precisa saber que a ação solicitada não recebeu aprovação, mas raramente precisa de cada falha de autenticação no nível do sistema operacional. Um evento útil é decision=denied_or_cancelled, method=touch_id e um motivo como user_cancelled, quando a plataforma disponibilizar essa distinção. Não transforme um gateway de ações em um coletor de telemetria biométrica.

O consentimento da sessão e o consentimento por chamada têm escopos diferentes

A autorização de sessão concede a um processo de agente delimitado permissão para operar depois que uma pessoa revisa a identidade do processo. A aprovação por chamada concede consentimento para um único uso de credencial e uma única operação. Chamar os dois de «aprovação» sem registrar o escopo torna a linha do tempo posterior enganosa.

Considere um processo de agente iniciado às 09:00. O gateway mostra um cartão de autorização que identifica a autoridade de assinatura do código do processo. Um desenvolvedor clica em aprovar. Às 09:20, o agente faz uma solicitação HTTP com uma credencial cujas configurações não exigem confirmação por chamada. Essa chamada pode ser permitida porque a sessão continua autorizada. A linha do tempo correta mostra dois fatos separados:

1. Às 09:00, o desenvolvedor aprovou a sessão ses_... durante a vida útil daquele processo.
2. Às 09:20, essa sessão usou a credencial cred_... para fazer a chamada call_....

Ela não deve criar uma aprovação fictícia do usuário às 09:20. O desenvolvedor não viu nem aprovou aquela chamada específica. A concessão anterior a abrangia.

Agora altere uma configuração: a credencial exige aprovação a cada uso. Às 09:20, o gateway pergunta novamente e o desenvolvedor aprova com Touch ID. O novo evento precisa apontar para call_..., indicar scope=credential_use e incluir method=touch_id. A aprovação da sessão continua relevante porque explica por que o agente pôde chegar à solicitação da credencial. Ela não substitui a segunda decisão.

Essa distinção importa principalmente quando um agente faz uma chamada inesperada no fim de uma sessão. Se o log disser «aprovado» ao lado dela, o revisor precisa saber se isso significa que alguém aprovou o executável trinta minutos antes ou aprovou aquele uso específico da credencial três segundos antes. Esses fatos têm implicações muito diferentes para o desenho dos avisos, as configurações das credenciais e a resposta a incidentes.

Não resolva a ambiguidade exigindo aprovação para todas as chamadas. Essa recomendação é popular porque parece segura e produz uma quantidade satisfatória de registros. Ela também acostuma as pessoas a aprovar avisos repetitivos sem lê-los, deixando-as sem saber distinguir a única chamada excepcional das rotineiras. Configure a aprovação por chamada para credenciais cujo uso precisa de uma confirmação humana nova. Mantenha a autorização de sessão ativada por padrão para vincular o processo do agente a um limite de aprovação responsável.

Uma revogação também precisa de escopo. Se um operador revogar uma sessão, registre o evento de revogação contra a sessão e o horário em que ela passou a valer. Não substitua a aprovação antiga. Se um usuário desativar ou remover uma credencial, registre essa alteração separadamente. Uma linha do tempo de auditoria deve mostrar por que uma chamada posterior foi negada sem reescrever o passado para fazer a concessão anterior desaparecer.

Os registros de credenciais devem identificar a autoridade sem expô-la

O registro de uso da credencial é onde muitas equipes fazem uma troca perigosa: adicionam material secreto para facilitar uma investigação. É um péssimo negócio. Logs são copiados, indexados, exportados e mantidos por mais tempo que o processo que os gerou. Um segredo em um diário de atividade transforma cada leitor do log em portador da credencial.

Dê a cada credencial armazenada um identificador opaco e imutável, como cred_01J8K.... Combine-o com um rótulo que ajude uma pessoa a reconhecer a finalidade, como payments-readonly ou staging-deploy. Registre o canal e o modo de injeção, por exemplo http_bearer, http_custom_header ou ssh_key. Isso dá ao investigador contexto suficiente para fazer a pergunta certa sem copiar a chave para o registro.

Um evento prático de uso de credencial pode ser assim:

{
  "credential_use_id": "use_01J8K4WHD7",
  "occurred_at": "2026-07-22T14:18:06.221Z",
  "credential": {
    "id": "cred_01J7ZB7F8P",
    "label": "inventory-production",
    "channel": "http",
    "injection": "bearer"
  },
  "session_id": "ses_01J8K4TE0M",
  "approval_id": "apr_01J8K4VY5Q",
  "call_id": "call_01J8K4VPM2",
  "secret_exposed_to_agent": false
}

O campo secret_exposed_to_agent pode parecer redundante quando o desenho do gateway garante isso. Mantenha-o se a linha do tempo puder incluir vários caminhos de execução ou migrações. Ele torna essa propriedade de segurança verificável no mesmo registro da ação. Se todos os caminhos compatíveis tiverem a mesma garantia, o campo pode ser implícito no desenho do sistema e documentado uma vez.

Separe a seleção da credencial do uso da credencial. Um agente pode solicitar uma credencial por rótulo, mas nenhuma credencial foi usada até que o gateway inicie a operação de saída. Isso importa para as negativas. Se o Touch ID for cancelado antes de a solicitação sair da máquina, registre uma chamada tentada e um evento de aprovação negada. Não registre um uso bem-sucedido da credencial. Caso contrário, sua contagem de auditoria afirmará que uma credencial de produção foi usada quando isso não aconteceu.

Para SSH, evite tratar um alias de host como a identidade completa do destino. prod-db é legível, mas aliases podem mudar. Registre o destino configurado e as evidências de identidade do host verificadas pelo fluxo de conexão. Se o agente pediu prod-db, mas o destino resolvido foi diferente, essa diferença pertence ao registro de execução. É exatamente o tipo de detalhe que importa depois de uma implantação malsucedida.

A chamada executada é a evidência de que a ação aconteceu

A aprovação prova o consentimento. A seleção da credencial prova a autoridade pretendida. Só um registro de execução informa se o gateway tentou fazer a operação no mundo externo e qual resultado recebeu.

Para chamadas HTTP, registre a operação de forma normalizada. Mantenha o método da solicitação, a origem do destino ou a identidade do serviço, o caminho canônico, nomes selecionados de campos de consulta quando forem úteis, o status da resposta, os timestamps de início e fim e uma referência ao resultado. Decida deliberadamente quais campos de solicitação e resposta são seguros para manter. Cabeçalhos de autorização, cookies, valores com formato de token, corpos completos de solicitação e corpos brutos de resposta não devem chegar a uma linha do tempo geral de atividades.

Um hash da solicitação pode ajudar a provar que o conteúdo aprovado e o conteúdo executado coincidiram, mas somente se você definir exatamente seus dados de entrada. Fazer o hash de um corpo JSON sem normalizar a ordem dos campos cria incompatibilidades falsas. Fazer o hash de um corpo que contém um valor pequeno e previsível ainda pode ajudar um invasor a confirmar tentativas. Use um hash para correlacionar a integridade quando o conteúdo já estiver protegido em outro lugar, não como substituto universal para o tratamento do conteúdo.

Para SSH, registre a conta remota, a identidade do destino, a representação do comando, o status de saída e os horários de início e fim. Uma linha de comando completa pode conter segredos em atribuições de ambiente, URLs temporárias ou argumentos. Um meio-termo sensato é armazenar um comando renderizado seguro para a revisão rotineira e uma representação completa protegida ou um hash para a investigação. Não diga que um hash é uma evidência legível. Ele informa que dois valores coincidem, mas não informa ao revisor o que o comando fez.

A RFC 5424 separa um timestamp e a identidade da mensagem dos dados estruturados porque os analisadores precisam de campos confiáveis, não de prosa que tenham de interpretar. O formato de timestamp também carrega um deslocamento de fuso horário e permite frações de segundo. Você não precisa emitir syslog, mas a lição de desenho permanece: mantenha tipos de evento e campos de correlação estruturados e reserve o texto humano para explicações.

Use tipos de evento distintos. call.requested, call.dispatched, call.completed e call.failed_before_dispatch dizem mais do que um evento call sobrecarregado, cujo campo de status muda de significado. Os registros extras permitem responder se um timeout de rede ocorreu depois da injeção da credencial, se uma validação local bloqueou primeiro a solicitação e se o serviço remoto retornou uma resposta.

O horário sozinho não estabelece a ordem entre máquinas. Use timestamps UTC com deslocamentos e mantenha um número de sequência monotônico dentro de cada log de auditoria local. Se a API remota retornar seu próprio ID de solicitação, armazene-o como valor de correlação remoto. Isso dá ao investigador uma forma de comparar a linha do tempo local com os registros de um fornecedor sem fingir que os relógios estão perfeitamente sincronizados.

Uma linha do tempo quebrada se esconde em logs comuns de sucesso

Imagine um agente de implantação que recebe aprovação de sessão às 10:02. Ele lê um repositório, prepara uma versão e chama um endpoint de implantação em produção às 10:17. O endpoint aceita a solicitação. Às 10:18, o desenvolvedor percebe que o ambiente errado foi selecionado.

Um log fraco contém isto:

10:02 approved agent
10:17 deployment API call succeeded

Esse log quase não responde a nada. A chamada das 10:17 estava coberta pela aprovação das 10:02? A credencial exigia um segundo aviso? Qual processo fez a chamada? O agente usou a credencial de implantação pretendida ou um token mais amplo? O sistema enviou a solicitação para produção ou um redirecionamento ou erro de configuração a levou até lá? A pessoa clicou em aprovar, usou Touch ID ou nunca viu um aviso específico da ação?

Uma linha do tempo útil seria assim:

10:02:11  session.opened       ses_71  process=proc_44 signer=known_authority
10:02:14  approval.approved    apr_02  method=click scope=session session=ses_71 account=maya
10:17:03  call.requested       call_88 POST deploy.example/release target=production session=ses_71
10:17:04  credential.selected  use_53  credential=cred_prod_deploy call=call_88
10:17:04  call.dispatched      call_88 destination=deploy.example
10:17:06  call.completed       call_88 status=202 remote_request=req_914

Esse registro pode estabelecer que o agente tinha uma autorização de sessão válida, mas não recebeu uma aprovação específica da chamada. Isso não prova que a implantação era desejada. É uma evidência de como o controle funcionou. A equipe pode então decidir se a credencial de produção deve exigir aprovação por chamada, se o aviso precisa exibir o ambiente de destino com mais clareza ou se o agente não deveria ter acesso àquela credencial.

Agora acrescente a confirmação por chamada. A entrada adicional correta não é outra linha genérica approved. Ela deve indicar a chamada aprovada e seu escopo:

10:17:04  approval.approved    apr_03  method=touch_id scope=credential_use
          session=ses_71 call=call_88 credential=cred_prod_deploy account=maya

Se o agente tentar novamente depois de um timeout, dê à nova tentativa um ID de chamada novo. Ele pode reutilizar uma concessão de sessão existente, mas uma regra de credencial por chamada deve criar uma nova exigência de aprovação para a tentativa. Registrar a nova tentativa como se fosse a chamada original cria a falsa impressão de que uma confirmação cobriu duas ações externas.

A integridade da auditoria exige uma afirmação separada

Um log de auditoria pode ser completo o suficiente para explicar uma sequência e ainda ser fácil de alterar. Ele pode ser apenas de acréscimo na intenção e, mesmo assim, permitir que um administrador ou malware com acesso local remova as linhas inconvenientes. Trate conteúdo e integridade como propriedades separadas.

Um diário encadeado por hash vincula cada registro ao anterior por meio de um resumo criptográfico. Se você alterar um registro antigo, a cadeia posterior deixará de ser verificada. Isso é útil porque uma tela de atividade exportada pode ser comparada ao diário subjacente, em vez de ser aceita por confiança. Isso não prova que o sistema original registrou todos os eventos, que um gravador comprometido não criou registros falsos ou que uma aprovação válida foi uma boa decisão. São afirmações diferentes, que exigem controles diferentes.

Verifique na fronteira onde as evidências saem do sistema. Um investigador deve poder usar o fluxo de registros criptografados, executar uma verificação de integridade offline e descobrir se a sequência está intacta sem expor credenciais apenas para validar a cadeia. O resultado da verificação deve identificar o intervalo examinado, o estado da cadeia e a primeira sequência com falha, caso a verificação falhe.

O Sallyport projeta seus diários Sessions e Activity a partir de um único log de auditoria criptografado, encadeado por hash e protegido contra escrita, e sp audit verify pode verificar a cadeia offline sobre o texto cifrado sem uma chave do cofre. Essa organização importa porque a decisão da sessão e a operação individual continuam sendo visões da mesma evidência, não histórias editáveis de forma independente.

Não use a verificação de integridade como motivo para guardar dados demais para sempre. Retenção, controle de acesso e redação continuam importantes. Um log perfeitamente preservado e cheio de segredos é um incidente à espera de uma consulta conveniente. Defina quem pode inspecionar os registros brutos, quem pode exportá-los, por quanto tempo eles ficam disponíveis e quais campos são seguros nas visões rotineiras.

Construa a linha do tempo em torno das relações e teste os casos difíceis

Uma revisão de esquema deve começar com uma pergunta direta: um investigador pode partir de qualquer ação executada e voltar até a aprovação sem precisar adivinhar? Se não puder, acrescente o identificador que falta antes de aperfeiçoar a tela de atividade.

Execute uma pequena matriz de testes na implementação. Você não precisa de uma simulação grande. Precisa de casos que revelem erros de escopo e ordenação:

• Inicie um processo novo do agente, aprove a sessão com um clique e faça uma chamada de baixo risco.
• Use uma credencial que exige aprovação por chamada, autorize-a com Touch ID e confirme que a chamada aponta para essa aprovação.
• Cancele o aviso biométrico e confirme que nenhum registro bem-sucedido de uso da credencial aparece.
• Encerre o processo do agente, inicie-o novamente e verifique que o novo processo não consegue herdar a concessão da sessão antiga.
• Force uma falha remota depois do envio e verifique se a linha do tempo distingue o envio da conclusão.

Inspecione o resultado nas duas direções. Comece pela aprovação e liste todas as ações que dependeram dela. Depois comece pela chamada executada e siga o processo, a sessão, a decisão e a credencial. A primeira visão encontra concessões mais amplas ou duradouras do que o esperado. A segunda encontra chamadas com evidências quebradas ou ambíguas.

Mantenha a linguagem da interface tão precisa quanto o modelo de dados. «Sessão aprovada por clique» é claro. «Credencial de implantação em produção aprovada com Touch ID para esta chamada» é claro. «Aprovado» é uma palavra decorativa de status que pede ao leitor que invente os detalhes mais importantes.

Na primeira vez que alguém perguntar quem aprovou uma ação de agente, não entregue uma captura de tela com um selo verde. Entregue uma linha do tempo que mostre o processo, o método da decisão, o escopo, a autoridade da credencial, a chamada exata e o resultado. Qualquer coisa menos pode ser conveniente durante uma demonstração. Não será suficiente quando a ação realmente importar.