アップデート一覧に戻る
New releaseSep 9, 2026

halo-record v0.2.42

AIエージェント向けの改ざん防止監査証跡：ハッシュチェーン化されたRuntime Records、依存関係なし、誰でも検証可能

共有

halo-record

改ざん検知可能なAIエージェント向けランタイムレコード: ベンダーが実行するが編集はできない監査証跡。

エージェントが実行するすべてのアクション(ツール呼び出し、モデル呼び出し、データアクセス、承認)は、追記構造のハッシュチェーンログ内の1つのレコードになります。チェーンのチェックポイントを保持する任意の当事者は、その背後にあるレコードが決して改ざんされていないことを、それらを生成した者を信頼することなく検証できます。顧客のセキュリティチームが「あなたのエージェントは当社のデータで何をしたのか?」と尋ねてきたら、長文の代わりにリンクを渡せます。セキュリティレビューではすでにSOC 2チェックリストに並んでAIに関する質問が行われており、現時点では文書による保証がまだ通用しています。このプロジェクトの背後にある賭けは、それが長くは通用しないだろうということです。

レコード形式はオープンで、自由に実装できます。このパッケージはリファレンス実装です: レコーダー、ベリファイア、ウィットネスクライアント、レポートサーバー。

このコードを信頼できる理由

あなたはエージェントの中にレコーダーを組み込むことを求められています。それを盲目的に信じるべきではありません:

  • ランタイム依存関係ゼロ。 標準ライブラリのみ。pip install halo-record は正確に1つのパッケージだけをインストールします。
  • ネットワーク呼び出しなし。ただしウィットネスは例外で、オプトイン制であり、レコード数とチェーンフィンガープリントのみを受信します。レコードの内容があなたのインフラストラクチャの外に出ることはありません。
  • 生の入力がレコードに入ることは決してありません。 引数はハッシュ化され、マスクされたサマリーとしてのみ保存されます — 生の値は決して保存されません。マスク処理はベストエフォートです(一般的なシークレットおよびPII形式に対する正規表現): これは保証ではなく、多層防御として扱ってください。
  • 監査できるほど小さい。 約4,300行のPython。午後ひとつで全て読めます。
  • Apache-2.0。

60秒デモ

エージェントは不要です。uvを使えば、インストールは何もありません:

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

または従来の方法:

pip install halo-record
halo demo --serve

どちらの方法でも、2人の顧客を持つ架空のサポートエージェントベンダーをスキャフォールドし、チェーンをウィットネスし、顧客ごとにアクセス制御されたRuntime Reportを配信し、ブラウザでオペレーターコンソールを開きます。その後、改ざんテストを試してください: .jsonl ファイルの1つから1行を削除してリロードすると、レポートがそれを検出します。

自分のエージェントを記録する

境界に1行:

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

log= を指定しない場合、レコードは ~/.halo/my-agent.jsonl に保存されます(エージェントごとに1つのチェーン)。または、すでに実行しているもの用のアダプターを使用します(下記のマトリックスを参照)。次にレポートをレンダリングします:

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

クイックスタートは、ブラウザで自分のエージェントのRuntime Reportを確認した時点で完了です。JSONLファイルが生成されたのにレポートがなければ、何かが間違っています: issueを開いてください。

すでに実行しているものに接続する

境界でキャプチャ既存のテレメトリから取り込み
ネイティブレコーダー (from halo import trace)OpenTelemetry GenAI スパン
MCPインターセプターLiteLLMコールバック
LangChain / LangGraph コールバックLangfuseエクスポート
OpenAI Agents SDK フック任意のゲートウェイ / リバースプロキシログ
Claude Code / Claude Agent SDK フック

すべてのレコードは source タグを保持するため、レポートは各証拠がどのように収集されたかを開示します。キャプチャされたレコードと取り込まれたレコードは同じチェーンに存在します。

OpenTelemetry GenAIスパンを出力するもの(CrewAI、LlamaIndex、およびOTel計装を備えたほとんどのエージェントフレームワーク)は、OTelアダプターを通じてチェーンに取り込まれます。TypeScriptパッケージ には、Vercel AI SDKおよびJSエージェントエコシステム向けのネイティブアダプターが同梱されています。お使いのスタック向けのアダプターがありませんか? issueを開いてください。ほとんどのアダプターは約100行です。

コーディングエージェントを記録する

Claude Codeは、すべてのツール呼び出しの後に PostToolUse フックを発火します。それを halo hook に向けると、各アクション(ファイル書き込み、シェルコマンド、MCPコネクタ呼び出し)がローカルチェーンのレコードになります。コード変更は不要で、設定エントリを1つ追加するだけです:

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

これを ~/.claude/settings.json に追加すると、レコードは ~/.halo/audit.jsonl に保存されます($HALO_LOG で上書き可能)。データ、ネットワーク、外部状態に一切触れない純粋なオーケストレーションツールはスキップされます — チェーンは思考ではなく、信頼境界のアクションを記録します。HALO_HASH_ONLY=1 を設定すると、サマリーなしでコンテンツハッシュを記録します。HALO_AGENT_VERSION(および必要に応じて HALO_AGENT_MODEL)を設定すると、すべてのレコードをそれを生成したエージェントビルドにバインドできます — 監査人が特定の期間に実行されていたバージョンを尋ねたとき、エクスポートは記憶ではなく列で回答します。

レポートに「この実行はどのようなルールの下で行われたのか?」に回答させる必要がある場合は、HALO_AUTHORITY_FILE をセッションの実効オーソリティのJSONスナップショットに設定します。プライバシーに配慮してください: ハッシュと参照のみで、生のプロンプト、社内ポリシーテキスト、シークレット、完全なツールスキーマは含めません。

{
  "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

スナップショットは、アクションレコードと同じハッシュチェーンに封入されます。良いデフォルトは、開始時に1つのセッションレベルのスナップショットを取得し、さらにルール、Skills、フック、MCPツールレジストリ、またはコンパクションポリシーが変更されたときに新しいスナップショットを取得することです。長時間のセッションを軽量に保つため、同じ authority.snapshot_id を持つ連続レコードは、最初の完全なスナップショットの後にコンパクト化されます: 以降のレコードは {"snapshot_id": "...", "same_as_previous": true} のみを保持します。ポインターはハッシュチェーンに残りますが、かさばる refs/omissions/stale-if ブロックは各アクションで繰り返されません。その後はいつもの流れです:

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

アクション後フックを公開する任意のエージェントランタイムが同じコマンドに供給できます — フックはstdinで1つのイベントをJSONとして読み取り、1つのレコードを追記します。

整合性と完全性(この部分を読んでください)

各レイヤーが何を証明するかを正確に理解してください — これらは異なる主張であり、その違いこそが要点だからです:

自己保持チェーンは、確立されたヘッドに対する整合性を証明します: 誰かがすでに保持しているチェーンヘッドが与えられれば、その背後にあるレコードへの編集、並べ替え、削除はすべて検出可能になります。単独では — オペレーター外部の誰もヘッドを見る前に — チェーンは履歴ではなく内部整合性を証明します: オペレーターはレコードを削除して再シールでき、新しいファイルは検証に合格します。チェーンが履歴的にコミットされるのは、そのヘッドがオペレーターの管理を離れた瞬間です。

それがウィットネスです: オペレーターの外部にいて、チェーンの定期的なフィンガープリント(カウントとヘッドハッシュのみ、それ以外は何もない)を保持する当事者です。チェックポイントにより、コミット済み履歴の書き換えが検出可能になり、チェックポイントの欠落自体が可視イベントになります:

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

もう1つの境界を明確に述べます: チェーンもウィットネスも、すべての実世界のアクションがレコーダーを通過したことを証明するものではありません。それはキャプチャ完全性 — スタック内でレコーダーがどこに位置するか(ネイティブ計装、フック、ゲートウェイ取り込み)の特性であり、ハッシュの特性ではありません。レコードが source タグを保持するのは、まさにこの理由です。

主張自己保持チェーン+ 外部チェックポイント+ 信頼できるキャプチャ
確立されたアーティファクトへの編集を検出✔✔✔
コミット済み履歴の書き換えを検出—✔✔
欠落/遅延チェックポイントを検出—✔ (合意された間隔)✔
すべてのアクションが記録されたことを証明——キャプチャ境界に依存

誰でもウィットネスを実行できます。自分で実行するウィットネスはあなた自身に対して履歴をコミットします。顧客に対してコミットするには、顧客が信頼する理由を持つウィットネスが必要です。プロトコルはどちらの場合もオープンです。

このプロジェクトの持続方法は、ホスト型で認知されたウィットネスです。早期アクセス: [email protected]。

コンプライアンススタックにおける位置付け

halo-recordはエビデンスレイヤーであり、認証ではありません。これは、評価フレームワークがさまざまな言葉で求め続けているアーティファクトを生成します:

  • セキュリティ質問票とSOC 2レビュー: スクリーンショットや文章の代わりに、検証可能なRuntime ReportでAI関連セクションに回答します。
  • AIUC-1: この標準の説明責任(Accountability)コントロールが要求する、改ざん検知可能なロギング(E015.4)と、認可イベントを含む完全な実行チェーンレコード(E015.2)を生成します — 監査時に再構築するのではなく、継続的なランタイムエビデンスです。
  • OWASP (GenAI Security Project): OWASP Top 10 for Agentic Applications 2026およびLLM Top 10におけるエージェント行動リスク(ゴールハイジャック、ツール誤用、アイデンティティおよび特権の悪用)の背後にあるランタイムエビデンス — エージェントが実際に何を、どのツールとデータで行ったかとして記録されます。
  • AARM (CSA): AARMが指定する改ざん検知可能なアクションレシート(R5/R6)を生成します — チェーン化され、独立してウィットネスされます。halo-recordはレシートレイヤーです。完全なAARMシステムのためには、執行ゲートウェイと組み合わせてください。AARM.md を参照してください。
  • Agentic Trust Controls: ATCのエビデンスコントロールの背後にあるランタイムレコード — 改ざん検知可能なアクションロギング(RBM-03)とオーソリティ証明(AID-05)を1つのチェーンレコードにまとめ、さらにその両方の上にウィットネスレイヤーを備えます。ATC.md を参照してください。
  • EU AI法: 高リスクAIシステムに対するロギングおよび記録保存の義務。
  • ISO 42001 / NIST AI RMF: マネジメントシステムコントロールの背後にある運用エビデンス。

これらはいずれも単独では何も認証しません。評価者に検証可能なものを提供します。境界 — halo-recordが意図的に行わないこと、およびレビュアーに尋ねられたときに何を言うべきか — は 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

整合性モデル

レコードのハッシュを計算するには: integrity.hash を除いたレコードを取り、integrity.prev_hash を前のレコードのハッシュに設定します。RFC 8785(JSON Canonicalization Scheme)で正規化し、そのバイトをSHA-256でハッシュします。最初のレコードの prev_hash は64個のゼロです。検証はすべてのハッシュを再計算し、すべてのリンクをチェックします。シークレットは不要です。それが要点です。

ベリファイアに気づかれずにチェーンを改ざんできると思いますか? 試行と結果はこちら。

全フィールドリファレンス: halo-record.schema.json。

TypeScript

同じレコーダーがNode用に提供されています: halo-record-ts。同じチェーン形式、同じウィットネスプロトコルです。どちらの言語で書かれたレコードも、どちらのベリファイアでも検証できます。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します — 基本ルールは CONTRIBUTING.md を参照してください(短く言うと: テスト必須、小さなPR、スキーマ変更は先に議論)。

ライセンス

Apache-2.0

もっと読む

カテゴリ

フォレンジックサプライチェーンセキュリティインシデントレスポンスAIセキュリティ