halo-record

Registros de runtime à prova de adulteração para agentes de IA: a trilha de auditoria que o fornecedor executa, mas não pode editar.

Cada ação do seu agente (chamadas de ferramentas, chamadas de modelo, acesso a dados, aprovações) torna-se um registro em um log de estrutura anexada e encadeado por hash. Qualquer parte que possua um checkpoint da cadeia pode verificar que os registros anteriores a ele nunca foram alterados, sem precisar confiar em quem os produziu. Quando a equipe de segurança de um cliente pergunta "o que seu agente fez com nossos dados?", você entrega um link em vez de um parágrafo. As revisões de segurança já fazem perguntas sobre IA ao lado do checklist do SOC 2, e hoje uma garantia por escrito ainda é aceita. A aposta por trás deste projeto é que isso não durará por muito tempo.

O formato de registro é aberto e livre para implementar. Este pacote é a implementação de referência: gravador, verificador, cliente de testemunha e servidor de relatório.

Por que você pode confiar neste código

Você está sendo convidado a colocar um gravador dentro do seu agente. Você não deve aceitar isso por fé:

• Zero dependências em tempo de execução. Apenas a biblioteca padrão. pip install halo-record instala exatamente um pacote.
• Sem chamadas de rede, exceto a testemunha (witness), que é opcional e recebe apenas uma contagem de registros e uma impressão digital da cadeia. O conteúdo dos registros nunca sai da sua infraestrutura.
• Entradas brutas nunca entram em um registro. Os argumentos são transformados em hash e armazenados apenas como um resumo com dados ocultados — nunca o valor bruto. A ocultação é de melhor esforço (regex sobre formatos comuns de segredos e PII): trate-a como defesa em profundidade, não como garantia.
• Pequeno o suficiente para auditar. ~4.300 linhas de Python. Leia tudo em uma tarde.
• Apache-2.0.

Demonstração de 60 segundos

Nenhum agente é necessário. Com uv, nada para instalar:

uvx --from halo-record halo demo --serve

ou do jeito clássico:

pip install halo-record
halo demo --serve

Qualquer um dos dois monta um fornecedor fictício de agente de suporte com dois clientes, testemunha as cadeias, serve os Runtime Reports com acesso controlado e abre o console do operador no seu navegador. Então tente o teste de adulteração: exclua uma linha de um dos arquivos .jsonl e recarregue. O relatório detecta.

Grave seu próprio agente

Uma linha na fronteira:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

Sem log=, os registros vão para ~/.halo/my-agent.jsonl (uma cadeia por agente). Ou use o adaptador para o que você já executa (veja a matriz abaixo). Depois renderize o relatório:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

O início rápido termina quando você está olhando o Runtime Report do seu próprio agente em um navegador. Se você obteve um arquivo JSONL e nenhum relatório, algo está errado: abra uma issue.

Conecte-se ao que você já executa

Cada registro carrega uma tag source, então o relatório divulga como cada evidência foi coletada. Registros capturados e ingeridos vivem na mesma cadeia.

Qualquer coisa que emita spans GenAI do OpenTelemetry (CrewAI, LlamaIndex e a maioria dos frameworks de agentes com instrumentação OTel) chega à cadeia por meio do adaptador OTel, e o pacote TypeScript traz adaptadores nativos para o Vercel AI SDK e o ecossistema de agentes JS. Falta um adaptador para a sua stack? Abra uma issue. A maioria dos adaptadores tem cerca de cem linhas.

Grave seu agente de codificação

O Claude Code dispara um hook PostToolUse após cada chamada de ferramenta. Aponte-o para halo hook e cada ação — gravações de arquivos, comandos de shell, chamadas de conector MCP — torna-se um registro em uma cadeia local. Sem mudanças de código; uma entrada de configurações:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

Adicione isso a ~/.claude/settings.json e os registros vão para ~/.halo/audit.jsonl (o caminho pode ser sobrescrito com $HALO_LOG). Ferramentas de orquestração pura que não tocam dados, rede ou estado externo são ignoradas — a cadeia registra ações na fronteira de confiança, não o pensamento. Defina HALO_HASH_ONLY=1 para registrar hashes de conteúdo sem resumos. Defina HALO_AGENT_VERSION (e opcionalmente HALO_AGENT_MODEL) para vincular cada registro à versão do agente que o produziu — quando um auditor perguntar sobre a versão que estava em execução em um determinado período, a exportação responde por coluna em vez de por memória.

Se você precisar que o relatório responda "sob quais regras esta execução aconteceu?", defina HALO_AUTHORITY_FILE como um snapshot JSON da autoridade efetiva para a sessão. Mantenha-o seguro para a privacidade: hashes e refs, não prompts brutos, texto de políticas privadas, segredos ou esquemas completos de ferramentas.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

O snapshot é selado na mesma cadeia de hash que os registros de ação. Um bom padrão é um snapshot no nível da sessão no início, além de um novo snapshot quando regras, Skills, hooks, registros de ferramentas MCP ou a política de compactação mudarem. Para manter sessões longas enxutas, registros consecutivos com o mesmo authority.snapshot_id são compactados após o primeiro snapshot completo: registros posteriores mantêm apenas {"snapshot_id": "...", "same_as_previous": true}. O ponteiro permanece encadeado por hash, mas o bloco volumoso de refs/omissions/stale-if não é repetido em cada ação. Então, o de sempre:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

Qualquer runtime de agente que exponha um hook pós-ação pode alimentar o mesmo comando — o hook lê um evento como JSON no stdin e acrescenta um registro.

Integridade vs. completude (leia esta parte)

Seja preciso sobre o que cada camada prova — porque são afirmações diferentes, e as diferenças são o ponto:

Uma cadeia mantida por conta própria prova integridade relativa a um head estabelecido: dado um head de cadeia que alguém já possui, qualquer edição, reordenação ou exclusão nos registros anteriores a ele torna-se detectável. Por si só — antes que qualquer pessoa fora do operador tenha visto um head — uma cadeia prova consistência interna, não histórico: um operador poderia descartar um registro e re-selar, e o novo arquivo seria verificado. A cadeia torna-se historicamente comprometida no momento em que seu head sai do controle do operador.

Essa é a testemunha: uma parte fora do operador que mantém impressões digitais periódicas da cadeia (uma contagem e um hash do head, nada mais). Checkpoints tornam detectável a reescrita do histórico comprometido, e um checkpoint perdido é em si um evento visível:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

Mais uma fronteira, dita claramente: nem a cadeia nem a testemunha provam que toda ação do mundo real passou pelo gravador. Isso é completude de captura — uma propriedade de onde o gravador se posiciona na stack (instrumentação nativa, hooks, ingestão por gateway), não de qualquer hash. Os registros carregam uma tag source exatamente por esse motivo.

Qualquer pessoa pode executar uma testemunha. Uma testemunha que você mesmo executa compromete o histórico com você; comprometê-lo com seu cliente exige uma testemunha que ele tenha motivos para confiar. O protocolo é aberto de qualquer forma.

Uma testemunha hospedada e reconhecida é como este projeto se sustentará. Acesso antecipado: [email protected].

Onde isso se encaixa em uma stack de conformidade

halo-record é uma camada de evidência, não uma certificação. Ele produz o artefato que os frameworks de avaliação não param de pedir em outras palavras:

• Questionários de segurança e revisões SOC 2: responda às seções de IA com um Runtime Report verificável em vez de capturas de tela e prosa.
• AIUC-1: produz o log à prova de adulteração (E015.4) e os registros de cadeia de execução completa com eventos de autorização (E015.2) que os controles de Accountability do padrão exigem — evidência contínua de runtime, não reconstruída no momento da auditoria.
• OWASP (GenAI Security Project): a evidência de runtime por trás dos riscos de comportamento de agentes no OWASP Top 10 for Agentic Applications 2026 e no LLM Top 10 — sequestro de objetivo, uso indevido de ferramentas, abuso de identidade e privilégios — registrada como o que o agente realmente fez, com quais ferramentas e dados.
• AARM (CSA): produz o recibo de ação à prova de adulteração que a AARM especifica (R5/R6) — encadeado e testemunhado de forma independente. halo-record é a camada de recibos; combine-o com um gateway de enforcement para um sistema AARM completo. Veja AARM.md.
• Agentic Trust Controls: os registros de runtime por trás dos controles de evidência da ATC — registro de ações à prova de adulteração (RBM-03) e atestado de autoridade (AID-05) em um único registro encadeado, com a camada de testemunha além de ambos. Veja ATC.md.
• EU AI Act: obrigações de registro e manutenção de logs para sistemas de IA de alto risco.
• ISO 42001 / NIST AI RMF: a evidência operacional por trás dos controles de sistemas de gestão.

Nada disso certifica qualquer coisa por si só. Dá ao seu avaliador algo verificável para examinar. As fronteiras — o que o halo-record deliberadamente não faz e o que dizer quando um revisor perguntar — estão documentadas em LIMITS.md.

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

Modelo de integridade

Para calcular o hash de um registro: pegue o registro excluindo integrity.hash, com integrity.prev_hash definido como o hash do registro anterior; canonicalize com RFC 8785 (JSON Canonicalization Scheme); aplique SHA-256 aos bytes. O prev_hash do primeiro registro é 64 zeros. A verificação recalcula cada hash e verifica cada link. Nenhum segredo é necessário; esse é o ponto.

Acha que consegue adulterar uma cadeia sem que o verificador perceba? Tentativas e resultados estão aqui.

Referência completa de campos: halo-record.schema.json.

TypeScript

O mesmo gravador é fornecido para Node: halo-record-ts. Mesmo formato de cadeia, mesmo protocolo de testemunha. Registros escritos em qualquer uma das linguagens são verificados com qualquer um dos verificadores.

Contribuindo

Issues, discussões e pull requests são bem-vindos — veja CONTRIBUTING.md para as regras básicas (versão curta: testes obrigatórios, PRs pequenos, mudanças de schema são discutidas primeiro).

Licença

Apache-2.0