Ordenação da atividade de agentes para reconstrução confiável de incidentes

A ordenação da atividade do agente determina se um relatório de incidente explica o que aconteceu ou apenas exibe um amontoado de timestamps. Quando um agente autônomo de programação pode chamar APIs e abrir sessões SSH, os investigadores precisam descobrir qual processo agiu, o que tentou fazer, o que foi concluído e qual resultado o agente recebeu antes de escolher a próxima ação.

Uma lista ordenada por horário não basta. Os relógios sofrem desvios, as solicitações se sobrepõem, as respostas chegam fora de ordem e um timeout pode ocultar uma ação que teve sucesso remotamente. Crie registros que preservem o contexto da sessão, uma ordem local durável e timestamps distintos para cada etapa do ciclo de vida. Caso contrário, o primeiro incidente sério transformará sua trilha de auditoria em uma discussão baseada em suposições.

O horário sozinho não estabelece a ordem das ações

Um timestamp informa quando um relógio observou um evento. Ele não prova que esse evento ocorreu antes de todos os outros eventos com timestamp posterior. A diferença parece acadêmica até que duas chamadas saiam do agente em rápida sucessão, um serviço remoto fique lento e a segunda chamada retorne primeiro. Ordenar por completed_at fornece a ordem das respostas, não a ordem das decisões do agente.

Cada chamada tem vários momentos relevantes. O agente decide chamar uma ferramenta. O gateway aceita a solicitação. Ele autoriza a solicitação. Encaminha o trabalho para um serviço HTTP ou um helper SSH. O lado remoto pode aceitá-lo. Uma resposta retorna. O gateway entrega esse resultado ao agente. Tratar tudo isso como um único evento elimina as evidências necessárias para explicar uma falha.

Mantenha uma call_sequence local e monotonicamente crescente em cada sessão. Atribua-a quando o gateway aceitar uma chamada, antes do início do trabalho de rede. Esse número responde a uma pergunta limitada e útil: «Em que ordem este gateway aceitou chamadas desse processo de agente?» Ele não afirma descrever a ordem da execução remota. Um escopo honesto é melhor que uma afirmação ampla que você não consegue defender.

Use uma segunda sequência durável para o próprio diário de auditoria. Chamadas de sessões diferentes podem se sobrepor, e eventos de autorização, revogação, bloqueio do cofre e verificação precisam estar no mesmo fluxo de evidências. A sequência do diário informa ao investigador a ordem de gravação do registrador. A sequência de chamadas da sessão informa a ordem das intenções em uma execução de agente. Nenhum dos dois campos substitui o outro.

Não use a precisão do timestamp como substituto para números de sequência. Adicionar mais casas decimais apenas registra uma leitura mais precisa do relógio. Isso não resolve um ajuste do relógio nem estabelece uma ordem total entre gravadores concorrentes.

A RFC 3339 define uma representação interoperável útil para timestamps de relógio civil, incluindo um deslocamento UTC explícito. Use sua forma UTC, como 2025-03-08T21:14:03.482Z, em exportações e revisões humanas. A RFC 3339 não promete ordem causal. Essa é a função do seu registrador, e ela exige campos de sequência e limites de evento claros.

Uma sessão identifica o processo que age, não uma tarefa vaga

Uma sessão deve vincular uma execução ordenada ao processo específico do agente que recebeu autorização para agir. Ela deve começar quando esse processo estabelecer uma conexão e terminar quando o processo sair, perder seu canal ou tiver a autorização revogada por um operador. Não defina sessão como «trabalho no chamado 184» ou «a implantação da tarde». Esses rótulos podem ajudar na busca, mas não definem um limite de execução.

O registro da sessão precisa ter informações suficientes para responder às perguntas que os investigadores realmente fazem: qual executável se conectou, quem o assinou, qual usuário local o iniciou, qual transporte o conectou e quando sua autorização começou e terminou. Registre identificadores que o sistema operacional ou a conexão possam atestar. Não deixe o agente gravar suas próprias declarações de identidade nos campos oficiais.

Essa separação importa quando alguém copia uma configuração de ferramenta para outro processo. A solicitação de ação pode dizer que pretende operar em um repositório específico. O gateway deve registrar a identidade do processo que observou. Durante um incidente, a segunda declaração tem mais peso.

Um registro de sessão prático pode conter:

{
  "event_id": "01JNRQ2Q9Y9J0R3E5P8F7K2X4M",
  "journal_sequence": 8124,
  "event_type": "session.opened",
  "occurred_at": "2025-03-08T21:14:02.901Z",
  "session_id": "sess_7f31c4",
  "process": {
    "pid": 48102,
    "code_signing_authority": "observed signing authority",
    "local_user": "developer account"
  }
}

O agente deve receber um identificador opaco de sessão, não a autoridade para escolher o identificador ou alterar seus metadados. Ele ainda pode anexar seu próprio rótulo de execução, caminho do repositório ou referência da tarefa em um campo separado de contexto declarado. Marque esses valores como fornecidos pelo agente. O rótulo pode explicar a intenção, mas nunca deve substituir fatos observados sobre o processo.

A autorização por sessão oferece um segundo benefício investigativo. Ela registra uma decisão humana vinculada a uma execução de processo delimitada. Se essa execução fizer depois uma chamada prejudicial, os revisores poderão ver o evento de autorização que a precedeu e o evento de fechamento ou revogação que a encerrou. Uma aprovação aplicada silenciosamente a processos posteriores cria uma lacuna que nenhum volume de logs de chamadas consegue reparar.

Uma chamada precisa de um ciclo de vida, não de uma única linha de conclusão

Um registro útil de chamada preserva o ciclo de vida de uma tentativa. Ele não junta uma solicitação tentada, um despacho de rede, um resultado remoto e o resultado visível ao agente em um único campo vago de «sucesso» ou «falha».

Comece com um call_id imutável e a próxima call_sequence da sessão. Registre um evento de aceitação antes de entrar em contato com o mundo externo. Se uma política ou aprovação bloquear a solicitação, o evento de aceitação e o evento de negação ainda serão importantes. Eles mostram a intenção e o comportamento do controle sem fingir que a ação externa ocorreu.

Para uma ação HTTP permitida, capture estes limites de evento separados:

1. call.accepted registra a solicitação ordenada no gateway.
2. call.authorized ou call.denied registra a decisão de controle.
3. call.dispatched registra que o gateway entregou a solicitação ao cliente de rede.
4. call.result_received registra o resultado do transporte ou a resposta remota.
5. call.result_returned registra o resultado entregue de volta ao agente.

Os nomes podem variar, mas a semântica não deve variar. Um resultado recebido nem sempre é um resultado retornado. O gateway pode redigir uma resposta, rejeitar dados malformados, perder a conexão do agente ou encontrar uma falha interna ao preparar o resultado. Os investigadores precisam enxergar essa lacuna.

Mantenha request_started_at, dispatched_at, result_received_at e result_returned_at quando esses momentos ocorrerem. Use null para um momento que não aconteceu. Não invente um horário de término quando um processo cair. Registre um evento posterior de recuperação informando que o registrador encontrou uma chamada inacabada.

Este exemplo mostra o formato de uma solicitação concluída sem expor um bearer token ou o corpo completo da resposta:

{
  "event_id": "01JNRQ3M8W7P0Q4R6S9T1V2X3Y",
  "journal_sequence": 8131,
  "event_type": "call.result_received",
  "occurred_at": "2025-03-08T21:14:05.841Z",
  "session_id": "sess_7f31c4",
  "call_id": "call_00017",
  "call_sequence": 17,
  "channel": "http",
  "target": "api.internal.example/v1/releases",
  "method": "POST",
  "dispatch_event_id": "01JNRQ3G2A...",
  "outcome": {
    "transport": "response",
    "http_status": 201,
    "response_digest": "sha256:..."
  }
}

Os resumos criptográficos da solicitação e da resposta permitem comparar evidências retidas sem colocar segredos ou payloads sensíveis grandes nas mãos de todos os leitores do diário. Um resumo não torna um segredo seguro para registro. Valores com pouca entropia, identificadores previsíveis e tokens curtos continuam sendo adivinháveis. Exclua credenciais no momento da captura e depois decida quais trechos de payload seu processo de incidentes realmente precisa.

Novas tentativas e timeouts criam a ambiguidade mais difícil

Um timeout significa que você não sabe se o lado remoto agiu. Não significa que o lado remoto não fez nada. As equipes erram repetidamente nesse ponto porque os logs da aplicação costumam tratar o timeout como um erro simples, enquanto a nova tentativa passa a substituir a primeira tentativa.

Considere um agente que cria uma versão por meio de uma solicitação HTTP. A chamada 41 recebe um timeout de solicitação depois do despacho. O agente lê essa falha e envia a chamada 42, uma nova tentativa. Mais tarde, o serviço remoto processa as duas solicitações. Se seu diário substituir a chamada 41 por um status final de «repetida», os investigadores verão uma solicitação bem-sucedida e perderão a ação duplicada.

Dê a cada tentativa de rede seu próprio call_id e sua própria call_sequence. Adicione retry_of quando uma tentativa seguir diretamente uma tentativa anterior. Preserve a causa visível ao agente para a nova tentativa, como timeout, conexão redefinida ou status recebido que permite nova tentativa. Essa relação permite rastrear a cadeia sem achatá-la.

Uma sequência completa pode ser assim:

sequence 41  accepted       21:14:11.024Z  create release, request r_8d2
sequence 41  dispatched     21:14:11.027Z
sequence 41  result_received 21:14:41.031Z timeout
sequence 41  result_returned 21:14:41.034Z timeout returned to agent
sequence 42  accepted       21:14:42.112Z  retry_of call_00041, request r_8d2
sequence 42  dispatched     21:14:42.115Z
sequence 42  result_received 21:14:42.490Z HTTP 201
sequence 42  result_returned 21:14:42.493Z HTTP 201 returned to agent

A referência repetida da solicitação só é útil se a API remota oferecer um mecanismo de idempotência ou outro identificador estável de operação. Se o serviço aceitar uma chave de idempotência, gere e registre uma chave não secreta que permaneça constante entre as tentativas de uma mesma operação pretendida. Se não aceitar, registre que o risco da nova tentativa continua sem solução. Não afirme que há idempotência apenas porque o payload parece semelhante.

O SSH acrescenta outro problema. Um comando pode ser executado remotamente e a conexão pode falhar antes que o cliente receba a saída ou o código de saída. Registre o despacho do comando, a identidade da conexão, a referência do host e o estado de término observado. Rotule um comando SSH interrompido como «resultado desconhecido», não como «falhou». Um comando posterior que verifique o estado remoto pode reduzir a incerteza, mas não reescreve o resultado original.

Não transforme todas as falhas em eventos terminais. Uma negação de autorização é terminal para aquela chamada porque nenhum despacho externo ocorreu. Uma falha local de DNS pode ser terminal para a tentativa. Um timeout depois que os bytes deixaram a máquina tem resultado externo desconhecido. Essas categorias levam a decisões diferentes durante o incidente.

Registre dois tipos de horário e explique seus limites

O horário civil torna uma linha do tempo legível entre sistemas. O tempo monotônico mede o tempo decorrido sem as alterações causadas pela sincronização de horário da rede ou por um ajuste manual do relógio. Colete os dois quando o sistema operacional fornecer essas medições e declare o significado de cada um no seu esquema.

Para cada evento do diário, registre um valor UTC de occurred_at no formato RFC 3339. Para eventos dentro de uma sessão ativa, registre também monotonic_ns, medido a partir da origem de relógio monotônico escolhida pelo processo. Não compare leituras monotônicas de máquinas diferentes sem estabelecer explicitamente uma referência compartilhada. Elas são medições locais.

Uma correção do relógio pode produzir registros confusos como este:

journal 901  wall 21:19:07.900Z  monotonic 5562019921  call accepted
journal 902  wall 21:18:58.104Z  monotonic 5562026310  call dispatched

O relógio civil retrocedeu. A sequência do diário e o valor monotônico ainda mostram que o despacho ocorreu depois da aceitação. A exportação deve manter os timestamps originais, sem ordená-los e reescrevê-los silenciosamente. Adicione um evento do registrador quando o sistema operacional informar uma alteração relevante do horário, se você puder observá-la. Esse evento dá aos revisores uma explicação para a discrepância.

A NIST Special Publication 800-92, Guide to Computer Security Log Management, recomenda que as organizações sincronizem os relógios e definam os requisitos dos dados de log antes de um incidente. A recomendação está correta, mas relógios sincronizados sozinhos não fornecem a ordem dentro de uma execução de agente. A sincronização melhora a correlação com uma API remota, um serviço de CI ou logs do host. Sua sequência local ainda estabelece a ordem do registrador.

Timestamps remotos merecem campos próprios. Um cabeçalho HTTP Date, um ID de solicitação do provedor e um horário de evento gerado pelo servidor são declarações externas. Preserve a origem e o valor exato. Não os copie para occurred_at nem os use para renumerar seu diário local. Um timestamp remoto pode ajudar a reconciliar sistemas mais tarde, mas pode refletir uma fila, outro relógio ou o momento de geração da resposta.

Os campos de duração também precisam de uma definição precisa. gateway_duration_ms pode significar o tempo entre a aceitação e o retorno do resultado. network_duration_ms pode significar o tempo entre o despacho e o recebimento do resultado. Escreva a definição ao lado do esquema. Caso contrário, um relatório que diga que uma chamada levou 30 segundos não conseguirá informar se o atraso ocorreu antes do despacho, no serviço remoto ou depois do retorno da resposta.

O gravador de auditoria deve escolher a ordem antes de publicar os resultados

Não é possível reconstruir a ordem se trabalhadores concorrentes gravarem registros sempre que terminarem. Dê ao gravador de auditoria um único caminho de anexação que atribua uma sequência de diário, capture o horário do evento, vincule o registro anterior e confirme o registro antes que o sistema informe ao agente que uma alteração de estado com significado externo ocorreu.

Isso não exige um único bloqueio enorme envolvendo toda a atividade de rede. As chamadas podem ser executadas em paralelo. O registrador precisa apenas de um ponto estreito de confirmação serializada. Quando um trabalhador chega a um limite de evento, ele envia um evento a esse gravador. O gravador atribui a próxima sequência durável do diário. A ordem resultante reflete a ordem de confirmação, que você deve nomear corretamente na documentação e nas exportações.

O padrão de falha é conhecido. O trabalhador A aceita a chamada 17 e inicia uma solicitação lenta. O trabalhador B aceita a chamada 18 e termina rapidamente. Se os trabalhadores anexarem apenas seus registros de conclusão, o diário começará com o sucesso da chamada 18. O investigador não conseguirá saber se a chamada 17 estava em andamento, nunca foi enviada ou foi omitida. Os eventos de aceitação e despacho da chamada 17 fecham essa lacuna.

O encadeamento de hashes acrescenta evidência de adulteração à sequência confirmada. Cada entrada contém o resumo da entrada confirmada anterior e um resumo do próprio conteúdo canônico. A canonização importa. Os mesmos dados precisam produzir os mesmos bytes antes do cálculo do hash. Especifique a ordem dos campos, a codificação UTF-8, a representação dos timestamps, o tratamento de valores nulos e os formatos numéricos. «Nós calculamos o hash do JSON» não é uma especificação, porque a ordem comum dos objetos JSON não é uma propriedade de segurança.

Uma entrada conceitual pode usar estes campos:

{
  "journal_sequence": 8131,
  "event_id": "01JNRQ3M8W7P0Q4R6S9T1V2X3Y",
  "previous_hash": "sha256:9c7d...",
  "record_hash": "sha256:04b1...",
  "payload": {"event_type": "call.result_received"}
}

Uma cadeia válida informa que as entradas retidas estão conectadas sem uma alteração não detectada, desde que o verificador tenha a âncora esperada da cadeia. Ela não prova completude se um invasor controlar o registrador e puder impedir a gravação de um registro. Não trate o encadeamento de hashes como mágica. Ele torna a alteração visível, mas não consegue registrar um evento que o registrador nunca observou.

O Sallyport projeta seus diários Sessions e Activity a partir de um único log de auditoria criptografado e encadeado por hash. O comando sp audit verify verifica a cadeia offline sobre o texto cifrado, sem exigir uma chave do cofre. Esse design mantém a visão da sessão e a visão de cada chamada vinculadas a uma única fonte ordenada, em vez de pedir aos investigadores que reconciliem dois logs separados.

Crie uma linha do tempo que preserve a incerteza

Uma linha do tempo de incidente deve mostrar separadamente fatos, observações e resultados não resolvidos. Uma narrativa bem acabada que transforma desconhecidos em verbos categóricos pode parecer útil durante uma revisão tensa, mas cria um registro falso que evidências posteriores podem contradizer.

Suponha que um processo de agente tenha recebido aprovação às 09:00:00. Ele emitiu um comando SSH às 09:03:14. O cliente perdeu a conexão às 09:03:16. Às 09:03:18, o agente usou HTTP para consultar o sistema de destino e encontrou uma configuração alterada. Essas evidências sustentam várias explicações: o comando SSH foi concluído, outro agente alterou o estado ou uma tarefa enfileirada anteriormente produziu efeito. A linha do tempo precisa declarar qual conclusão as evidências sustentam e qual não sustentam.

Use este formato nas notas do incidente:

Evite escrever «o comando SSH alterou a configuração» sem evidência direta que vincule o comando ao efeito remoto. Registros de auditoria remotos, um ID exclusivo de operação ou uma resposta contendo um ID durável de solicitação no servidor podem fornecer essa ligação. Um timestamp próximo não fornece.

Os investigadores também precisam saber o que o agente viu quando tomou decisões posteriores. Por isso result_returned merece seu próprio evento. Se a resposta remota chegou, mas o agente se desconectou antes de recebê-la, uma ação posterior do agente não veio depois dessa resposta. Se a resposta chegou ao agente, ela pode explicar um ramo perigoso do comportamento.

Apresente uma faixa de sessão e uma faixa de chamadas na visão do incidente. A faixa de sessão mostra eventos de abertura, aprovação, revogação, bloqueio e fechamento. A faixa de chamadas mostra eventos de aceitação, autorização, despacho e resultado. Uma lista simples continua disponível para verificação, mas as duas visões respondem a perguntas diferentes sem misturá-las.

O tratamento de segredos precisa resistir à revisão do incidente

As trilhas de auditoria costumam falhar no momento em que se tornam mais úteis, porque alguém quer registrar cabeçalhos completos, ambientes de shell e corpos de resposta «só para esta investigação». Essa decisão pode transformar um incidente contido com um agente em uma exposição de credenciais.

Capture a identidade da ação sem material secreto. Para HTTP, registre o método, o host e o caminho normalizados, a referência da credencial ou o rótulo da chave, nomes seguros de cabeçalhos, resumo da solicitação, status da resposta, ID da solicitação do provedor quando disponível e um resumo de resposta escolhido com cuidado. Nunca registre um cabeçalho de autorização, uma chave de API bruta, uma chave privada ou um despejo completo do ambiente. Exclua credenciais no momento da captura e decida depois quais fragmentos do payload são realmente necessários para o processo de incidentes.

Para SSH, registre uma referência do host, a referência da conta se a política permitir, uma representação normalizada do comando, o resumo do comando, o status da conexão e o status de saída quando recebido. Os próprios comandos podem conter segredos. Se seu fluxo permitir texto de shell arbitrário, use um armazenamento de evidências protegido para uma revisão limitada e autorizada, ou registre apenas uma forma redigida junto com um resumo. Não finja que um diário de comandos é inofensivo só porque não contém senhas.

O Sallyport mantém as credenciais de API e SSH em seu cofre criptografado e executa a ação externa sem passar essas credenciais ao agente. Isso elimina um motivo comum para que a transcrição e os logs de um agente se transformem em um despejo de segredos, mas o destino, o corpo da solicitação, os argumentos do comando e a resposta ainda podem ser sensíveis.

Controle o acesso aos registros brutos separadamente da verificação. Um respondente pode precisar executar uma verificação da cadeia sem permissão para ler detalhes criptografados das chamadas. Um revisor de segurança pode precisar dos metadados da sessão e do destino, mas não do conteúdo dos payloads. Essa separação reduz a dependência de copiar um diário inteiro para chats, chamados ou planilhas.

Ao exportar evidências, inclua a versão do esquema, o horário da exportação, o intervalo de sequências do diário, o resultado da verificação e as regras de redação usadas. Mantenha o diário protegido original sob seus controles normais. Uma exportação é uma cópia de trabalho, não um substituto da evidência de origem.

Teste o registro com uma execução deliberadamente confusa

Uma demonstração do caminho feliz quase não prova nada sobre reconstrução de incidentes. Teste as condições que tornam a ordenação ambígua: chamadas concorrentes, respostas atrasadas, alterações do relógio, saídas de processo, negações, revogações e um timeout seguido de uma nova tentativa.

Faça um exercício controlado com dois destinos externos permitidos. Faça a primeira chamada esperar antes de retornar. Inicie uma segunda chamada depois que a primeira for despachada. Interrompa uma terceira chamada depois do despacho. Em seguida, revogue a sessão e verifique se as chamadas posteriores recebem uma negação. Exporte o diário e entregue-o a um colega que não tenha criado o cenário.

Peça a esse revisor que responda a cinco perguntas usando apenas a exportação:

• Qual processo recebeu a autorização e quando essa autorização terminou?
• Em que ordem o gateway aceitou as chamadas nessa sessão?
• Quais chamadas chegaram ao limite de despacho?
• Qual resultado o agente recebeu antes de cada chamada posterior?
• Quais resultados continuam desconhecidos, em vez de serem considerados falhos ou bem-sucedidos?

Se ele precisar perguntar o significado de um campo, corrija o esquema ou a documentação da exportação. Se concluir que houve um efeito remoto a partir de um timeout, corrija os rótulos de resultado. Se não conseguir distinguir uma nova tentativa de uma operação nova, adicione a relação e o identificador da operação.

Guarde os artefatos do exercício. Eles se tornam testes de regressão quando você altera uma biblioteca cliente, introduz concorrência, ajusta a retenção ou adiciona um novo canal. Bugs de ordenação costumam surgir em refatorações aparentemente inofensivas, porque os desenvolvedores se concentram em saber se as ações ainda funcionam, enquanto o caminho das evidências muda silenciosamente seu momento de confirmação.

O incidente não vai esperar um design de logging mais limpo. Atribua uma sequência de sessão na aceitação da chamada, confirme os eventos do ciclo de vida por meio de um único gravador ordenado, preserve tanto o horário civil quanto o tempo monotônico e deixe os resultados desconhecidos continuarem desconhecidos. Essas escolhas dão aos investigadores uma sequência que eles podem defender, em vez de uma linha do tempo que precisam justificar.