アップデート一覧に戻る
New releaseJul 15, 2026

halo-record v0.2.8

AIエージェントのための改ざん防止ランタイム証拠：ハッシュチェーンされたランタイムレコード、依存関係なし、誰でも検証可能。

共有

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人の顧客を持つ）をスキャフォールディングし、チェーンをウィットネスし、ゲート付きのランタイムレポートを提供し、ブラウザでオペレーターコンソールを開きます。次に改ざんテストを試してください：.jsonl ファイルの1行を削除して再読み込みします。レポートがそれを検出します。

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

境界に1行追加:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # エントリポイントをラップ; すべてのツール呼び出しを ./audit.jsonl に記録

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

halo report audit.jsonl -o report.html    # 1つのチェーン -> 自己検証HTML
halo serve ./records --port 8721          # すべてのテナント、顧客ごとにゲート

クイックスタートは、ブラウザで自身のエージェントのランタイムレポートを見ている時点で終了です。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つのセッションレベルのスナップショット、ルール、スキル、フック、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

ポストアクションフックを公開する任意のエージェントランタイムは、同じコマンドにフィードできます。フックは1つのイベントをJSONとして標準入力から読み取り、1つのレコードを追加します。

完全性 vs. 完全性（この部分を読んでください）

各層が何を証明するかを正確に理解してください。なぜなら、それらは異なる主張であり、その違いが重要なポイントだからです:

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

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

halo anchor audit.jsonl witness.jsonl           # ローカルウィットネスにチェックポイントを固定
halo anchor audit.jsonl witness.jsonl --check   # それに対する完全性の判定

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

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

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

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

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

halo-recordは証拠レイヤーであり、認定ではありません。評価フレームワークがさまざまな言葉で求め続けている成果物を生成します:

  • セキュリティ質問票およびSOC 2レビュー: スクリーンショットや散文の代わりに検証可能なランタイムレポートでAIセクションに回答します。
  • AIUC-1: 標準のアカウンタビリティコントロールが求める、改ざん防止ログ（E015.4）および承認イベントを含む完全実行チェーンレコード（E015.2）を生成します—監査時に再構築するのではなく、継続的なランタイム証拠を提供します。
  • OWASP（GenAI Security Project）: OWASP Agentic Applications Top 10 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 Act: 高リスクAIシステムのログ記録および記録保存義務。
  • ISO 42001 / NIST AI RMF: マネジメントシステムコントロールの運用証拠。

これらは単独では何も認定しません。評価者に検証可能な何かを提供します。境界—halo-recordが意図的に行わないこと、およびレビュアーから尋ねられたときに何を言うべきか—は LIMITS.md に文書化されています。

CLI

halo verify   スキーマ + ハッシュチェーンを検証（失敗時は非ゼロ終了; CIフレンドリー）
halo report   チェーンを自己検証HTMLランタイムレポートとしてレンダリング
              （--from/--to: レビュー期間のみをカバーする日付範囲レポート）
halo serve    テナントごとのレポートをHTTPで提供、顧客ごとにアクセススコープ
halo grant    レポート受信者（メールアドレスまたはドメイン）を指定
halo anchor   チェーンヘッドをウィットネス、または--checkで完全性確認
halo demo     フルベンダーデモ（記録 -> ウィットネス -> ゲート付きレポート）をスキャフォールディング
halo export   日付範囲の証拠エクスポート: CSV + チェーンヘッドにリンクされたマニフェスト
halo sample   有効なサンプルログを出力
halo hash     JSON値の正規SHA256を計算
halo hook     Claude Code PostToolUseフック

完全性モデル

レコードのハッシュを計算するには: 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セキュリティ