bkuan001/halo-recordTrilhas de auditoria à prova de adulteração para agentes de IA: Registros de Runtime encadeados por hash, sem dependências, verificáveis por qualquer pessoa.
Trilhas de auditoria à prova de adulteração para agentes de IA — Runtime Records encadeados por hash, renderizados como um Runtime Report que os seus clientes podem verificar por si mesmos.
Cada ação que a sua instrumentação captura (chamadas de ferramentas, chamadas de modelos, acesso a dados, aprovações) torna-se um Runtime Record num registo apenas de acrescento, encadeado por hash; o Runtime Report é essa cadeia renderizada como uma página HTML que recalcula a cadeia de hash no navegador do leitor e renderiza o que apresenta a partir dos registos que verificou (para uma verificação que não depende do próprio código da página, execute halo verify sobre o JSONL). Qualquer parte que detenha um checkpoint da cadeia pode verificar que os registos até esse checkpoint não foram alterados desde que foi obtido, sem confiar em quem os produziu — esse checkpoint é a peça fulcral: a cadeia por si só é à prova de adulteração contra todos exceto a parte que opera o registador (LIMITS.md §1). Quando a equipa de segurança de um cliente pergunta "o que fez o seu agente com os nossos dados?", você entrega-lhes um link em vez de um parágrafo. As revisões de segurança já fazem perguntas sobre IA ao lado da checklist SOC 2 — e cada vez mais essas perguntas vêm da ISO 42001, dos artigos de conservação de registos do Regulamento Europeu da IA e dos questionários dos próprios clientes. Hoje, uma garantia escrita ainda passa. A aposta por trás deste projeto é que não passará por muito tempo.
Em destaque na Help Net Security (agosto de 2026).
O formato de registo é aberto e livre de implementar. Este pacote é a implementação de referência: registador, verificador, cliente de testemunha e servidor de relatórios.
Está a usar o halo-record, ou a pensar nisso? Diga-me quem é e para quê → Quem está a usar o halo-record?
Estão a pedir-lhe para colocar um registador dentro do seu agente. Não deve aceitar isso pela fé:
pip install halo-record instala exatamente um pacote.halo serve --verify-email (envia um código de uso único e o nome do sujeito do relatório, por SMTP através do servidor que configurar em $HALO_SMTP_HOST, para o endereço que um visualizador do relatório introduzir). Todas estão desativadas a menos que as invoque; nenhum outro conteúdo de registo sai da sua infraestrutura.summaries=False) não guarda resumo algum. A redação é o melhor esforço possível (regex sobre formatos comuns de segredos e PII mais um apanha-tudo por entropia): trate-a como defesa em profundidade, não como garantia. Os campos de resultado que fornecer além de summary são analisados e mascarados com os mesmos padrões, mas não cortados a 200 caracteres (LIMITS §13).O que cada camada prova — a distinção fulcral neste projeto (LIMITS.md §1): uma cadeia que você próprio detém prova que os registos não foram editados, relativamente a uma cabeça que alguém já detém; apenas checkpoints detidos fora do operador provam que nenhum foi removido; e nenhum hash prova que todas as ações foram capturadas.
| Afirmação | Cadeia própria | + Checkpoints externos | + Captura fiável |
|---|---|---|---|
| Detetar edições a um artefacto estabelecido | ✔ | ✔ | ✔ |
| Detetar reescrita de histórico comprometido | — | ✔ | ✔ |
| Detetar checkpoints em falta/atrasados | — | ✔ (cadência acordada) | ✔ |
| Provar que todas as ações foram registadas | — | — | depende do limite de captura |
Veja um antes de instalar: um Runtime Report de exemplo — dados fictícios, cadeia real, e o seu script recalcula a cadeia de hash dos registos incorporados no seu navegador quando o abre.
Não é necessário agente. Com uv, nada a instalar:
uvx --from halo-record halo demo --serve
ou da forma clássica:
pip install halo-record
halo demo --serve
Ou se cria um fornecedor fictício de agente de suporte com dois clientes, testemunha as cadeias (com um arquivo de testemunha local representando uma fora do operador — consulte LIMITS.md §1), serve seus Runtime Reports com acesso restrito e abre o console do operador no seu navegador. Em seguida, tente o teste de adulteração: exclua uma linha de um dos arquivos .jsonl e recarregue. O relatório detecta isso.
Uma linha no limite:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
Um shim de conveniência from halo import ... também é fornecido — mas o nome halo no PyPI pertence a um pacote de spinner de terminal não relacionado, e se esse pacote estiver instalado ele vence o import. halo_record é inequívoco, então os exemplos o utilizam.
Sem log=, os registros vão para ~/.halo/my-agent.jsonl (uma cadeia por agente). O wrapper sela o limite da execução; a evidência vive nos registros por chamada. Capture-os com um adaptador de framework (matriz abaixo) — ou explicitamente, o que também mostra como a delegação se liga:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call: # one sealed record per tool call
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call: # child links to the action that spawned it
call.result = payments.refund(120)
Em seguida, renderize o relatório:
halo report audit.jsonl -o report.html # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721 # all tenants, gated per customer