AI エージェント向け改ざん検知 Runtime 記録：ハッシュ連結による完全監査証跡

アーキテクチャと基本概念

AI エージェント（ツールコール、モデル呼出し、データアクセスなど）が行ったすべてのアクションは、追記のみで可能なハッシュ連結されたログの形式で保存されます。

• 改ざん検知機能: 記録が一度も変更されていないことを検証するには、作成者の信頼を要しません。
• 第三者検証可能: 顧客のセキュリティチームや任意の関係者が独立して監査を行うことができます。
• 監査証跡の提示: セキュリティレビューにおいては、説明文ではなく検証可能なレポートへのリンクを提供します。
• 対応の必要性: SOC2 チェックリストや AI 規制に準拠するための、書面での保証を超えたリアルタイム証明が必要とされています。

記録形式はオープンであり、以下のコンポーネントを備えた参考実装（パッケージ）が提供されます：

• recorder

  : 記録機能

• verifier

  : 検証機能

• witness

  : 第三者による指紋保持クライアント

• report server

  : レポート配信サーバー

なぜこのコードを信頼できるのか

エージェント内部へ組み込む際、以下の特性に基づいて信頼性を持たせています。盲目的に採用すべきではありませんが、以下の点は注目すべきです：

• ゼロのランタイム依存関係: 標準ライブラリのみを使用します。インストールは

  pip install halo-record

  の単一パッケージで完了します。
• ネットワーク通信の排除:

  witness

  を除き（オプトイン制）、記録内容や連鎖指紋以外は一切送信しません。データはローカルに留まります。
• 生データの非保存: 入力された引数はハッシュ化され、秘密情報の形式に準拠したサマリーとしてのみ保存されます。完全な生値は一切保存されません。（※防御的対策ですが、完全なる保証ではない点にご注意ください）。
• 小規模かつ監査容易: コード量は Python で約 4,300 行程度。短期間で全文を閲覧可能です。
• Apache-2.0 ライセンス: オープンソースとして利用できます。

60 秒で動作を確認するデモ

エージェントの事前セットアップも不要です。環境構築（

uv

インストール方法

1. uv を使用する場合

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

2. 従来の pip 方式の場合

   pip install halo-record
   halo demo --serve
   

デモの内容

上記コマンドを実行すると、以下のデモ環境が起動します。

• 架空のエージェントベンダーの構築
• 2 つの顧客の設定とチェーン検証
• ゲートされた Runtime レポートの配信
• ブラウザによるオペレーターコンソールの表示

改ざんテスト例: デモで生成された

.jsonl

ご自身のエージェント記録への導入

境界点（エントリーポイント）での 1 行のカット＆ペーストで開始可能です。

Python エージェントへの組み込み

エントリポイントをラップして、各ツールコールを

./audit.jsonl

from halo import trace

# run_my_agent が定義された関数です
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") 

• デフォルトの保存場所:

  log

  引数が省略される場合、

  ~/.halo/my-agent.jsonl

  に保存されます（エージェントごとに個別のチェーンが生成されます）。
• アダプター利用: 既存システムとの連携アダプターも用意されています（詳細は後述）。

レポートの描画と配信

記録されたデータを HTML 形式で表示したり、顧客向けに配信したりします。

# チェーン単体の自己検証レポート生成
halo report audit.jsonl -o report.html

# テナント単位のカスタムアクセス制御付きサーバー起動
halo serve ./records --port 8721

クイックスタート完了: ブラウザで自身のエージェント Runtime レポートが表示されれば準備は整います。JSONL ファイルを取得しても表示されない場合は、Issue をお立ちください。

既存システムとの連携アダプター

ソースタグが付与されたすべての記録により、レポートは証拠の収集方法を明文化します。

from halo import trace

アダプターの概要:

• OpenTelemetry 系: CrewAI、LlamaIndex など、OTel 機能を備えたフレームワークはアダプター経由でチェーンへ接続します。
• TypeScript: Vercel AI SDK および JS エコシステム向けのネイティブアダプター同梱されています。
• カスタム対応: スタックにない場合は Issue をお立ちください（多くのアダプターは約 100 行程度です）。

クロードコード (Claude Code) への適用

Claude Code は各ツールコール後に

PostToolUse

コード変更なしの設定

既存のコーディングスタイルを維持したまま、設定ファイルに以下の JSON を追加するだけで機能します。

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

この設定を

~/.claude/settings.json

~/.halo/audit.jsonl

$HALO_LOG

重要な動作特性:

• 思考過程の除外: データやネットワーク、外部状態を操作しない純粋なオーケストレーションツールはスキップされます。
• 記録対象: 境界点でのアクションのみを記録します（思考プロセスではなく）。
• ハッシュのみモード:

  HALO_HASH_ONLY=1

  を設定すると、サマリーなしにコンテンツハッシュのみを記録できます。

検証とレポート生成

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

任意の Runtime がポストアクションフックをサポートしていれば、同様のコマンドでイベントを読み込んで記録を追加できます（標準入力の JSON 形式）。

完全性と整合性 (Integrity) の仕組み

自己管理チェーン: チェーン内で何らかの変更がなされなかったことを証明できます。

• 不可避: 事後に編集や再順序付けは検知されます。
• 限界: recorder オペレーターによる記録の削除や書き換えに対しては、内部的には完全性を保証できません（信頼できる第三者の介入が必要です）。

完全性証明 (Witness): 信頼できる第三者が定期的にチェーンの指紋（数とヘッダーハッシュのみ）を保持することで、客観的な完全性を証明します。

# ローカルな witness にチェックポイントをアンカー設定
halo anchor audit.jsonl witness.jsonl

# アンカー設定の完全性判定
halo anchor audit.jsonl witness.jsonl --check

• 役割分担: 自己検証は整合性の証明になりますが、顧客への完全性保証には信頼できる

  witness

  の存在が必要です。
• 早期アクセス: ホストされ認知された

  witness

  の導入については、

  bkuan001@gmail.com

  までお問い合わせください。

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

halo-record

• セキュリティ監査 / SOC 2: 検証可能な Runtime レポートで代替可能です（スクリーンショットや文章説明の代わり）。
• AIUC-1 (EU AI Act): エージェント振る舞いの継続的な Runtime 証拠。監査時に再構築するのではなく、リアルタイムで保持されます。
• OWASP GenAI Top 10: 過剰な代理権限や機密情報の漏洩リスクに対する、具体的なエージェント・ツール・データ操作の記録です。
• AARM (CSA): 改ざん検知可能なアクション受領書（R5/R6）を生成します。

  halo-record

  は受領書レイヤーであり、完全な AARM システムには強制ゲートウェイとの連携が必要です。
• EU AI Act: ハイリスク AI システム向けのログ記録および保持義務の満たし。
• ISO 42001 / NIST AI RMF: 管理システム制御の背後にある運用証拠の提供。

重要: これらの出力自体は「認証」を行いますが、評価者に検証可能な証拠を見せるためのものです。

コマンドラインインターフェース (CLI) チュートリアル

• halo verify

  : シーマ＋ハッシュチェーンを検証（失敗時は非ゼロ終了ステータス；CI/CD 親和）。

• halo report

  : チェーンを自己検証可能な HTML レポートとして描画。

• halo serve

  : HTTP プロトコルでテナント別レポートを配信（顧客ごとのアクセス制御付き）。

• halo grant

  : レポート受信者（メールまたはドメイン）を指定。

• halo anchor

  : チェーンヘッダーを witness にアンカーし、

  --check

  で完全性を検証。

• halo demo

  : 完全なベンダーデモのスケルトンを作成（記録 → witness → ゲートレポート）。

• halo sample

  : 有効な例ログを出力。

• halo hash

  : JSON 値の正規化 SHA-256 ハッシュ計算。

• 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.js)

同じ記録フォーマットと witness プロトコルを Node 向けにも提供しています (

halo-record-ts

verifier

ライセンス

Apache-2.0