Os logs de auditoria de agentes precisam falhar de forma fechada sob pressão de disco

Um gateway de agentes que continua agindo depois de não conseguir mais registrar essas ações de forma durável rompeu o próprio limite de segurança. A pressão sobre o disco não é um incômodo de observabilidade. Ela decide se a próxima chamada de API ou o próximo comando SSH deixará evidências que os operadores possam consultar e verificar.

A regra segura é simples: negue novas chamadas que exigem credenciais antes que o gravador de auditoria fique sem espaço. Gere o alerta antes disso. Permita que o trabalho que já atravessou o limite de admissão termine apenas se o gateway ainda conseguir registrar sua conclusão ou falha. Quando os anexos falharem, preserve o texto cifrado que já está no disco e pare de tratar o log como um arquivo conveniente que pode ser limpo depois.

O registro de auditoria precisa fazer parte da autorização

Um gateway não pode tratar o registro de auditoria como «melhor esforço» se sua finalidade é criar um limite controlado por uma pessoa em torno das ações dos agentes. Quando um agente pode solicitar uma chamada HTTP com credenciais ou um comando SSH, o registro dessa solicitação faz parte da decisão de autorização. Se o gateway executa a ação, mas perde o registro, o operador não consegue distinguir depois uma execução legítima de uma execução sem prestação de contas.

É aqui que as equipes costumam misturar duas falhas diferentes:

• O painel ou a tela de atividade não consegue ser atualizado porque um índice derivado está indisponível.
• O log de origem criptografado não consegue aceitar um anexo de evento durável.

A primeira falha é inconveniente. A segunda muda a resposta para a pergunta sobre se o gateway pode realizar uma nova ação externa. Não atribua às duas o mesmo nível de gravidade nem o mesmo caminho de recuperação.

O modelo do Sallyport dá uma forma útil a essa distinção: os diários Sessions e Activity são projetados a partir de um único log de auditoria criptografado e encadeado por hash, em vez de cada um ser uma fonte de verdade separada. Uma projeção pode atrasar ou precisar ser reconstruída. A cadeia criptografada de origem, que não pode ser consultada para escrita, é o registro que precisa permanecer intacto.

Esse arranjo também facilita a definição da regra de admissão. Antes de despachar uma ação, o gateway precisa saber que tem capacidade de armazenamento suficiente e que o gravador está saudável para registrar pelo menos a tentativa. Depois do despacho, ele precisa registrar o resultado. Se a ação tiver um efeito irreversível, como alterar uma configuração remota de produção, o gateway deve registrar um evento de intenção durável antes do despacho e um evento de resultado depois dele.

Não prometa uma cronologia exata que a camada de armazenamento não consegue sustentar. Prometa algo mais forte e útil: toda ação admitida tem um registro durável e ordenado de sua identidade, do contexto de autorização e do resultado final conhecido. Se o gateway não consegue manter essa promessa, não deve admitir outra ação.

Alertas e negação são estados diferentes

Gerar o alerta exatamente no momento em que você nega chamadas garante uma escolha operacional ruim. O operador descobre o problema quando o agente já está bloqueado e precisa decidir sob pressão se deve apagar dados, interromper o trabalho ou enfraquecer a regra de auditoria. Uma política de armazenamento precisa de estados separados, com transições explícitas.

Use quatro estados:

1. Normal: a capacidade livre excede a reserva operacional e uma verificação recente de durabilidade foi bem-sucedida.
2. Atenção: a capacidade caiu abaixo do limite de alerta, mas o gateway ainda tem toda a sua reserva. Novas chamadas continuam, e os operadores recebem um alerta.
3. Restrito: a capacidade caiu abaixo da reserva, ou o gravador detectou uma falha temporária que ainda não ultrapassou o limite de falha crítica. Não admita ações que possam criar registros grandes ou com vários eventos. Permita apenas o trabalho já admitido e continue testando o gravador.
4. Negado: o gateway não consegue anexar um evento de auditoria de forma durável, ou a capacidade restante não cobre o orçamento mínimo de registros. Negue toda nova chamada que exija credenciais.

Uma porcentagem sozinha não define nenhum desses estados. Cinco por cento livres em um volume de 4 TB podem ser suficientes. Cinco por cento livres em um volume pequeno podem desaparecer durante uma execução de agente, uma atualização do sistema ou uma rajada de saída detalhada de um comando remoto. As políticas de armazenamento falham quando copiam números de um modelo de monitoramento, em vez de considerar o comportamento real de gravação do gateway.

O limite de alerta compra tempo para o operador. A reserva protege a trilha de evidências. O estado Negado protege a afirmação de que toda ação admitida foi registrada. Cada um tem uma função diferente, portanto não deve usar o mesmo número.

Uma boa transição de estado também evita oscilações. Entre em Atenção quando a capacidade livre cruzar para baixo do limite. Saia desse estado apenas depois que a capacidade subir acima de um limite de recuperação mais alto e o gravador concluir um anexo de teste durável. A mesma histerese se aplica ao estado Restrito. Sem ela, uma execução de agente próxima do limite pode alternar entre chamadas permitidas e negadas por causa de alguns blocos do sistema de arquivos. Isso é confuso e difícil de investigar.

Uma reserva é um orçamento de registros, não uma aposta no espaço livre

Defina a reserva crítica calculando quais registros ainda podem precisar existir depois que você parar de admitir novos trabalhos. O cálculo não precisa de uma precisão falsa. Ele precisa de entradas conservadoras que você consiga explicar durante um incidente.

Comece com estas perguntas:

• Qual é o maior registro de ação admitido, incluindo o conteúdo criptografado, os cabeçalhos retidos pela política, os metadados do resultado e os campos da cadeia de hashes?
• Quantas ações podem estar em andamento no momento em que o gateway entra no estado Restrito?
• Uma ação pode produzir um registro separado de conclusão, tempo limite ou nova tentativa?
• Quais arquivos locais crescem ao lado do log de origem, como metadados de segmentos, índices, arquivos temporários ou relatórios de falha?
• De quanto espaço o sistema operacional e o aplicativo precisam para informar a condição corretamente?

Suponha que um gateway permita 12 ações simultâneas, que cada uma possa exigir um registro de intenção e um de resultado, e que o orçamento conservador para um registro criptografado seja de 128 KiB. Os registros das ações sozinhos consomem 3 MiB. Esse número não é a reserva. Adicione o maior lote esperado de projeção do diário, a sobrecarga de troca de arquivos, um marcador de falha e uma margem de segurança significativa para o comportamento de alocação. Depois, arredonde para cima até chegar a um número fácil de monitorar.

O resultado útil é uma política escrita, não um número mágico:

warning threshold: 2 GiB free on the audit volume
hard reserve:      512 MiB reserved for audit completion and recovery records
admission budget:  256 KiB minimum available per new action
recovery threshold: 3 GiB free plus one durable test append

Esses valores são exemplos, não padrões para todo Mac. Uma máquina de desenvolvimento individual com chamadas de API curtas pode justificar uma reserva menor que uma máquina de compilação compartilhada com agentes autônomos executando trabalhos SSH longos. A política precisa refletir a pior saída plausível que o gateway registra, não o tamanho médio das solicitações em uma semana tranquila.

A documentação atual da Apple sobre APFS destaca um ponto relacionado que costuma passar despercebido quando as equipes criam um alerta baseado em porcentagem: verifique se o espaço necessário para uma determinada operação está disponível, em vez de tentar derivar um total confiável de espaço livre disponível em uma partição. O APFS também usa compartilhamento de espaço, clones e arquivos esparsos. Por isso, o espaço aparente e o espaço imediatamente utilizável nem sempre se comportam como em um disco antigo de tamanho fixo.

Para um gravador de auditoria, isso significa que a verificação de admissão deve perguntar: «Posso arcar com segurança com este orçamento de registros agora?». Ela não deve perguntar: «A barra de menus ainda mostra algum espaço livre?».

Uma falha de anexo precisa mudar imediatamente o comportamento do gateway

Trate uma falha de anexo como uma transição de estado, não como uma linha em um log de depuração seguida de outra tentativa. Uma nova tentativa pode fazer sentido para uma interrupção temporária. Ela não pode servir como autorização para continuar enviando chamadas sem registro.

Imagine uma sequência plausível de falha. O volume de auditoria caiu abaixo da reserva porque uma ferramenta local de desenvolvimento criou um cache grande. Um agente solicita ao gateway uma ação de implantação via HTTP. O gateway grava o evento de intenção, despacha a solicitação, recebe uma resposta bem-sucedida e depois não consegue anexar o evento de conclusão porque o sistema de arquivos retorna um erro de falta de espaço.

Nesse momento, o gateway sabe três coisas: admitiu a ação, o sistema externo pode ter sido alterado e seu registro normal de conclusão está ausente. O comportamento correto é preservar o evento de intenção durável, registrar um marcador de falha se algum canal seguro ainda estiver disponível, interromper novas chamadas e mostrar ao operador o identificador da ação e a falha de armazenamento. Ele não deve repetir a solicitação silenciosamente. Uma nova tentativa poderia duplicar o efeito remoto.

Agora considere uma sequência pior. O próprio anexo da intenção falha antes do despacho. O gateway precisa negar a ação. Ele não tem uma base durável para afirmar que a ação foi solicitada, aprovada ou executada. Isso pode frustrar alguém quando uma compilação está esperando, mas a alternativa é uma lacuna de auditoria que ninguém consegue reconstruir com segurança.

A mesma regra se aplica às falhas detectadas durante a sincronização. O manual fsync da Apple diz que fsync move dados e atributos modificados em direção ao armazenamento permanente e que uma operação de E/S enfileirada pode fazer fsync falhar com erros associados à leitura ou à gravação. O manual também alerta que uma descarga comum não garante, por si só, a ordenação física na mídia durante uma perda de energia. Por isso, o software precisa definir seu próprio limite de durabilidade, em vez de equiparar um anexo em memória a um evento confirmado.

Use um classificador pequeno de falhas:

append or sync succeeds                 -> action may proceed or complete normally
append fails before dispatch             -> deny the action
append fails after dispatch              -> deny new actions, preserve intent, raise incident
sync reports I/O failure                 -> deny new actions, preserve files, investigate storage health
space check below admission budget       -> deny this new action before dispatch

Não exclua segmentos antigos para fazer a gravação atual funcionar. Isso transforma um incidente de capacidade em destruição de evidências.

O gravador precisa de um limite de confirmação durável

Um gravador que simplesmente anexa bytes a um arquivo aberto ainda não resolveu o problema da auditoria. Ele precisa de um limite que informe ao restante do gateway quando um evento passou a fazer parte da cadeia durável.

Mantenha esse limite pequeno e explícito. Um padrão possível usa arquivos de segmento somente para anexação, cada evento contendo o hash do evento anterior, e um pequeno manifesto de segmento. A codificação exata pode variar. A ordem das operações não deve variar.

1. Serialize the next encrypted event with sequence number N and previous hash H(N-1).
2. Append the complete event frame to the active segment.
3. Sync the segment file and check the result.
4. Update the manifest with the new high-water sequence and segment hash.
5. Sync the manifest and check the result.
6. Only now mark event N as committed to the dispatcher.

O manifesto importa porque a recuperação precisa responder à pergunta «quais quadros completos de eventos contam?». Um quadro parcial no final do arquivo depois de uma falha ou de um disco cheio não é um evento confirmado apenas porque alguns de seus bytes chegaram ao segmento. O tamanho do quadro, os dados de autenticação, o número de sequência e o maior número de sequência confirmado no manifesto permitem que a recuperação rejeite a ambiguidade em vez de adivinhar.

Não resolva isso reescrevendo um arquivo JSON no mesmo lugar. Parece fácil até que o sistema de arquivos tenha espaço para o novo arquivo, mas não para a renomeação, ou até que uma falha deixe um índice antigo ao lado de um segmento mais novo. Segmentos somente para anexação e um manifesto pequeno tornam o comportamento diante de falhas mais fácil de entender e de verificar offline.

Há uma segunda distinção importante: a criptografia protege o conteúdo dos eventos, enquanto a cadeia de hashes protege a continuidade ordenada. Nenhuma dessas propriedades significa que um anexo foi durável. O gravador precisa estabelecer a durabilidade primeiro. Depois, o verificador pode confirmar que a sequência preservada não foi alterada.

O sp audit verify do Sallyport pode verificar offline sua cadeia de hashes criptografada sobre o texto cifrado, sem uma chave do cofre. Essa verificação é útil depois de um incidente de armazenamento, porque o operador pode conferir as evidências preservadas antes de desbloquear o cofre ou retomar o trabalho dos agentes.

Execute o teste em um volume de auditoria descartável

Um teste de pressão de disco deve comprovar o comportamento em cada transição de estado, não apenas mostrar que uma gravação acaba falhando. Use uma imagem de disco ou um volume de teste isolado, configure somente uma instância de não produção do gateway para armazenar os dados de auditoria ali e remova tudo depois do exercício. Não preencha o volume normal do Mac. O teste deve causar problemas em um ambiente descartável, não colocar em risco a máquina que guarda seu código-fonte e suas credenciais.

No macOS, crie e monte uma imagem de disco APFS pequena para o teste:

hdiutil create -size 2g -fs APFS -volname AuditDrill /tmp/audit-drill.dmg
hdiutil attach /tmp/audit-drill.dmg
df -h /Volumes/AuditDrill

O caminho exato de montagem pode mudar se já existir um volume com esse nome. Confirme-o com df antes de alterar qualquer configuração de teste. O formato esperado da saída deve identificar um sistema de arquivos montado e mostrar aproximadamente 2 GiB de capacidade:

Filesystem        Size   Used  Avail Capacity  Mounted on
/dev/diskXsY      2.0G   ...   ...     ...%    /Volumes/AuditDrill

Aponte o armazenamento de auditoria da instância de teste para esse caminho montado. Gere primeiro algumas ações conhecidas e bem-sucedidas. Registre seus identificadores de ação e execute o verificador da cadeia. Essa linha de base é importante porque uma falha de verificação posterior pode vir da configuração, não da pressão sobre o disco.

Depois, consuma espaço apenas dentro da imagem de disco montada:

dd if=/dev/zero of=/Volumes/AuditDrill/fill.bin bs=1048576

O dd para quando o volume não consegue alocar mais blocos. Ele é propositalmente direto. Não use um comando de arquivo esparso para este teste, porque um arquivo esparso pode parecer grande sem consumir os blocos necessários para disparar a condição que você precisa testar.

Execute o teste em etapas, em vez de correr diretamente até o espaço zero:

1. Preencha até o limite de Atenção ser acionado. Confirme que novas ações pequenas ainda funcionam e que o alerta do operador aparece uma vez.
2. Preencha até a reserva crítica ser acionada. Confirme que o gateway nega novas ações de acordo com seu orçamento de admissão.
3. Se o desenho do teste permitir, admita uma ação controlada imediatamente antes do estado Restrito e observe se o evento final é registrado com sucesso.
4. Preencha até que um anexo ou uma sincronização realmente falhe. Confirme que o gateway entra no estado Negado e expõe o motivo da falha.
5. Pare o processo, remonte a imagem se necessário e verifique a cadeia criptografada antes de excluir o arquivo de preenchimento.

O objetivo não é admirar um erro ENOSPC. O objetivo é responder se o gateway falha no momento correto, se seus diários contam a verdade depois disso e se o operador tem evidências suficientes para agir sem adivinhar.

Teste as janelas de tempo difíceis, não apenas um volume cheio

Um teste superficial preenche o volume, observa uma negação, libera espaço e declara sucesso. Isso deixa de fora as janelas de tempo que criam lacunas na auditoria.

Teste uma ação cujo efeito externo termine rapidamente enquanto o registro de conclusão da auditoria é atrasado. O alvo controlado pode ser um endpoint HTTP de teste que retorne um identificador de solicitação único. Inicie a ação enquanto ainda houver espaço para o evento de intenção e depois consuma o espaço restante do volume de teste antes que o gateway confirme o evento de resultado. O resultado esperado não precisa ser um status limpo de sucesso ou falha. O gateway pode precisar informar que o estado final da ação externa exige reconciliação.

Esse é um resultado honesto. O gateway deve mostrar o registro de intenção durável, o identificador da solicitação remota se tiver recebido um e a falha de armazenamento local. Ele deve negar chamadas posteriores. O operador pode consultar o alvo de teste e decidir se a ação remota foi bem-sucedida. O que o gateway não pode fazer é transformar a incerteza em uma segunda solicitação.

Teste também uma falha enquanto o gateway troca um segmento de auditoria. A troca consome metadados e pode envolver um novo arquivo, uma atualização de diretório e uma atualização do manifesto. Um projeto que sobrevive a um anexo comum, mas falha durante a troca, não resolveu a pressão de armazenamento.

Teste o comportamento após a reinicialização. Depois de uma falha de anexo, feche à força apenas a instância de teste descartável e inicie-a novamente com o volume ainda cheio. Ela deve permanecer em uma condição segura de negação, em vez de presumir que um processo novo significa armazenamento saudável. Libere uma quantidade medida de espaço, inicie-a novamente e confirme que ela verifica a última sequência confirmada antes de abrir um novo segmento.

Por fim, injete uma falha de permissão ou de E/S se o seu ambiente de testes permitir. A falta de capacidade e um erro de E/S exigem a mesma resposta imediata de admissão quando bloqueiam gravações duráveis de auditoria, mas a investigação é diferente. Liberar espaço pode resolver ENOSPC. Isso não resolve um volume defeituoso, um erro do sistema de arquivos ou um dispositivo de armazenamento desconectado.

Preserve o texto cifrado antes de tentar um reparo

Quando uma gravação de auditoria falha, as pessoas costumam recorrer à limpeza porque querem desbloquear o agente. Esse reflexo transforma um incidente recuperável em um incidente contestado. Preserve primeiro, repare depois.

Congele o diretório de auditoria afetado. Não compacte segmentos, regenere o manifesto, trunque o último arquivo, troque o material criptográfico nem repita uma ação apenas para fazer a tela de atividade parecer completa. Se o dispositivo de armazenamento parecer instável, copie o diretório com um método que informe erros de leitura e trabalhe a partir da cópia. O original pode ser a única evidência de quais registros chegaram ao armazenamento.

Sua lista de preservação deve responder a cinco perguntas:

• Qual segmento de auditoria e qual manifesto estavam ativos quando a primeira gravação falhou?
• Qual foi a última sequência aceita pelo verificador?
• Quais ações admitidas têm um registro de intenção sem um registro de resultado?
• Quais sistemas externos podem confirmar essas ações de forma independente?
• Algum processo modificou o diretório de auditoria depois da falha?

Um resultado de verificação da cadeia é uma evidência, não uma instrução de reparo. Se a verificação parar na sequência 8.412, preserve esse fato. Não trunque automaticamente um quadro parcial posterior, a menos que seu procedimento de recuperação documentado defina essa ação e o artefato original tenha sido retido. Um quadro criptografado parcial pode ser esperado depois de uma falha, mas também pode revelar um erro no gravador. Você precisa dos bytes originais para distinguir uma coisa da outra.

Esse é outro motivo para manter o log de origem separado do diário voltado ao usuário. Um diário pode mostrar linhas incompletas até que a projeção seja retomada. Isso é aceitável se ele informar ao operador que está se atualizando. A reconstrução ou ocultação de telas derivadas nunca deve reescrever as evidências de origem apenas para deixar uma tela mais organizada.

Os alertas precisam informar qual decisão o gateway tomou

«Disco quase cheio» é um alerta fraco para um gateway de ações. Ele informa uma condição da máquina, mas não diz se a atividade dos agentes continua permitida, se as evidências de auditoria estão em risco ou o que mudou desde a notificação anterior.

Emita um alerta quando o gateway entrar nos estados Atenção, Restrito e Negado, e também quando a recuperação for verificada. Inclua os campos que permitem ao operador agir:

state: denied
reason: audit append failed with ENOSPC
audit path: /configured/audit/path
free bytes observed: 41,943,040
hard reserve: 536,870,912
last committed sequence: 8412
unresolved admitted actions: 1
new credentialed calls: denied
existing action handling: completion record could not be committed
first failure time: 2026-07-22T14:37:18Z

Não coloque segredos, corpos de solicitações ou credenciais nesse alerta. O alerta precisa de identificadores que possam ser associados às evidências criptografadas, não de uma segunda cópia de dados sensíveis espalhada pelos sistemas de notificação.

Evite enviar uma página a cada amostra de pouco espaço. Envie-a quando entrar nos estados Restrito ou Negado e depois apenas se a condição persistir ou piorar. Um alerta ruidoso na transição de Normal para Atenção pode virar um chamado ou uma notificação local visível. A transição para Negado é um incidente operacional, porque o gateway interrompeu intencionalmente novas ações externas.

O alerta também deve informar se o gateway está protegendo os registros já admitidos. Esse detalhe muda a resposta. Se houver espaço para concluir os registros em andamento, os operadores podem deixar essas execuções terminarem enquanto liberam espaço. Se um anexo já falhou depois do despacho, os operadores precisam investigar as ações não resolvidas antes de retomar a automação.

A recuperação precisa provar que o gravador voltou a funcionar

Liberar espaço é necessário, mas não prova que o gravador de auditoria pode voltar com segurança ao estado Normal. Um procedimento de recuperação deve fazer o gateway conquistar essa transição.

Primeiro, preserve os artefatos do incidente e registre o que liberou o espaço. Excluir um cache de compilação que não tem relação com o caso é diferente de excluir arquivos de auditoria, e o registro do incidente deve dizer qual das duas coisas aconteceu. Depois, verifique a cadeia preservada offline. Se a verificação falhar, mantenha o gateway no estado Negado e investigue as evidências antes de permitir novas ações.

Em seguida, execute um anexo de recuperação limitado. O gateway deve gravar um evento de recuperação que identifique o estado Negado anterior, anexá-lo a um segmento de recuperação novo ou documentado, sincronizá-lo, atualizar seu manifesto e verificar a sequência resultante. Ele não deve retomar silenciosamente no meio do segmento que falhou.

Só depois que esse anexo for bem-sucedido o gateway deve reconstruir ou atualizar seus diários derivados. O trabalho do diário pode falhar de forma independente. Se isso acontecer, mantenha as evidências de origem e informe que a tela está incompleta. Não negue que uma ação ocorreu apenas porque uma linha de atividade ainda não apareceu.

Depois, aplique o limite de recuperação. Se você configurou Atenção em 2 GiB, uma reserva crítica de 512 MiB e recuperação em 3 GiB, não reabra chamadas com 600 MiB apenas porque o gravador conseguiu fazer um anexo. O limite mais alto evita uma recaída imediata e dá ao operador tempo para encontrar a origem da pressão.

Um teste de pressão de armazenamento vale a pena quando muda uma decisão concreta: o ponto exato em que seu gateway deixa de autorizar novos trabalhos. Escreva esse ponto, teste-o em um volume descartável e trate cada anexo que falhar como uma evidência a preservar, não como lixo a remover.