AI Guardian

AI Guardian

免責事項：コミュニティが保守するオープンソースプロジェクトです。**Ollama、IGEL、またはAIセキュリティベンダーとの提携、承認、スポンサー関係はありません。**製品名および商標は各所有者に帰属します。MITライセンスです。

管理された エンドポイント上のローカルLLM向けの可観測性とガバナンスを提供します。これにより、ローカルモデルに実際に何が渡されているかを監視・監査し、プロンプトに含めて外部に送信される内容を制御できます。IGEL AI Armorを補完するものです。AI Armorはエンドポイントでローカルモデルを実行できるかどうかを管理し、ai-guardianはモデルが何をしたかを記録するとともに、プロンプトに含める内容（シークレット、PII、ソース、ジェイルブレイク）と、要求を処理できるモデルを制御します。単体で動作し、各ランタイムのREST APIと通信するため、httpxとMCP SDK以外は必要ありません。v0.1では、オプトイン方式のルート経由コンテンツガバナンスに加え、オプトインしていないクライアント向けの透過的なキャプチャプロキシを提供します。

サポート対象のランタイム

1つのツールで複数のローカルランタイムに対応し、config.yamlのruntimeフィールドでターゲットごとに選択します（initウィザードで設定を求められます）。OllamaはネイティブAPIを使用し、他の3つは1つのOpenAI互換トランスポート（/v1/models + /v1/chat/completions）を共有します。

ランタイム	runtime	デフォルトポート	一覧表示／ポリシー	スキャン＋ルート経由ガード	出所情報
Ollama	ollama	11434	✅	✅	ダイジェスト（コンテンツハッシュ — 強力）
llama.cpp（llama-server）	llamacpp	8080	✅	✅	プロパティ — /propsのモデルパス／サイズ → 固定可能なID
LM Studio	lmstudio	1234	✅	✅	IDのみ — より弱く、固定したモデルはunverifiableと報告
vLLM（ローカルの単一ノード）	vllm	8000	✅	✅	IDのみ — より弱く、固定したモデルはunverifiableと報告

許可／拒否モデルポリシー、決定論的なプロンプトスキャナー、ルート経由ガード（guarded_generate／observe_chat）、出所情報のドリフト、およびdoctorは、すべてのランタイムで動作します。モデルのライフサイクル変更（pull／remove／unload）に対応するのはOllamaのみです。OpenAI互換サーバーは起動時にモデルをロードし、ライフサイクル用のエンドポイントを公開しないため、これらの変更要求は明確なメッセージとともに拒否されます。

出所情報に関する正確さ：固定対象にできる情報を公開するのは、Ollama（コンテンツダイジェスト）とllama.cpp（/propsから導出したパス／サイズのID）のみです。LM StudioとvLLMが公開するのはモデルのIDのみであるため、誤ってDRIFTと判定せず、固定されたダイジェストはunverifiableと報告されます。

ここでのvLLMは、ローカルのエンドポイントガードのユースケースです。GPU推論クラスターの操作（自動スケーリング、ドレイン、Ray Serve／Jobs、大規模なモデルのライフサイクル管理）は、系列内の別のツールの対象です — GPUクラスター運用 → inference-aiops。

機能

Ollama には照会可能なプロンプト／応答の履歴が一切保存されません。会話のコンテキストは、リクエストごとにクライアントから渡す必要があります。そのため、ai-guardian は次の 2 つの側面から監視します。

• パッシブなインベントリ／状態の監査 — /api/tags、/api/ps、 /api/show、/api/version を通じて、インストール済みおよび実行中のモデル、 VRAM 上の常駐状況、ライセンス／パラメーター／機能、 来歴ダイジェストを確認します。すべてのモデルに許可／拒否の ポリシー判定が付与されるため、シャドーモデル（未承認モデル）には allowed: false と表示されます。
• オプトイン方式のコンテンツガバナンス — 呼び出し元はプロンプトを ai-guardian 経由で送信します（guarded_generate ／ observe_chat）。テキストを スキャン（シークレット／PII／ソースコード／ジェイルブレイク）し、 ポリシーに照らしてモデルをチェックし、やり取りを独自の使用ログ （~/.ai-guardian/usage.db）に記録してから、初めて Ollama を呼び出します。 リスクレベルが高すぎる場合、またはモデルが許可されていない場合はブロックします。 生のプロンプトは保存されず、記録されるのは長さとマスキング済みの検出結果だけです。

利用可能になりました（ai-guardian proxy serve）：オプトインしていない クライアントからのトラフィックにも、同じスキャン、モデルポリシー、記録を適用する 透過的なキャプチャプロキシです。ランタイムの代わりにプロキシを接続先として指定します。 リクエストを検査し、レスポンスは変更せずにストリーミングします。 また、これは強制の境界ではなく、すべての通信が通過する中継点です。 ランタイムの実ポートに引き続きアクセスできるクライアントは、プロキシを完全に バイパスできます。proxy_guidance はコマンドとこの注意点を返します。 CLI は起動のたびにこれを表示します。

主な機能

• 決定論的なオフラインプロンプトスキャナー — I/O もネットワークも使用しないため、 完全にオフラインでテストできます。シークレット （AWS AKIA、秘密鍵ブロック、GitHub ／ Slack ／ OpenAI ／ Google のトークン、JWT、 api_key=… 形式の代入、高エントロピーのフォールバック）、 PII（メールアドレス、米国の SSN、Luhn チェック付きのクレジットカード）、 ソースコード／設定ファイルの漏えいに関するヒューリスティック、 ジェイルブレイク／プロンプトインジェクションのシグネチャを検出し、 重み付けされたリスクレベル（low ／ medium ／ high ／ critical。critical があれば 常に最優先）に集約します。検出結果はマスキングされ、検出したシークレットを スキャナーが再出力することはありません。
• モデルの許可／拒否ポリシー（シェルの glob パターン）により、シャドーモデル／ 未承認モデルを allowed: false として検出できます。さらに、来歴ダイジェストを ピン留めして、ダイジェストが変化したモデル（再プル済み／改ざん済み）に フラグを付けます。
• 経由型ガード — guarded_generate ／ observe_chat でスキャン、ポリシー判定、 記録を行い、許可された場合にのみ実行します。リスクレベルが block_threshold（既定値は high）以上の場合、またはモデルが許可されていない 場合はブロックします。
• 同梱のガバナンス用ハーネス — 監査ログ、トークン／暴走予算ガード、 リスク段階の説明、取り消しトークンの記録をパッケージに含みます （外部依存関係はありません）。
• 高度なセルフテスト対応 — API 部分には無料でローカル実行できる Ollama を使用します。 スキャナー、ポリシー、リスクレベルは決定論的なオフラインロジックです。

このツールが判断すること、しないこと

ローカル LLM のオブザーバビリティと運用を、読み取りも書き込みも正確に実行し、そのすべてを記録します。モデル環境への書き込みを許可するかどうかは判断しません。それはエージェントの判断、または実行時に使用するホストとアカウントの権限によります。アカウントが管理できないランタイム、たとえばユーザーがモデルストアを変更できない Ollama デーモンや、エージェントが読み取り専用でアクセスするエンドポイントを指定すれば、実際に権限を管理する場所であるランタイムで書き込みが失敗します。最も簡単なのは、接続するエージェントにスキャン／監視ツールだけを渡すことです。

そのため、ハーネスには読み取り専用スイッチも、拒否ルールファイルも、設定が必要な承認ゲートもありません。（コンテンツガバナンスは別の製品レベルの機能として維持されます。モデルの許可／拒否ポリシーと guarded_generate のブロックしきい値は、引き続きモデルに実行を求める内容をスキャンし、ゲートします。）ハーネスが保証するのは、何も記録されずに実行されることがないという点です。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.ai-guardian/audit.db に監査レコードとして記録され、破壊的な書き込みについては、変更前の状態を記録し、元に戻す手段がある場合はその逆操作も記録します。

各ツールには risk_level が宣言されており、テストによって [READ]／[WRITE] のドキュメント上のタグとの整合性が保たれ、説明用の段階として監査レコードにも記録されます。これにより、レビュー担当者はレコードが高リスクの削除だったことをすぐに確認できます。これはラベルであり、ゲートではありません。

より小型のローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが適用するガードレール（そのため、プロンプトの予算を使ってそれらを繰り返す必要はありません）と、残りの内容に使えるすぐに利用可能なシステムプロンプトを記載しています。

機能マトリックス（MCP ツール 21 種類）

読み取り（11）

ツール	リスク	返される内容
list_models	低	インストール済みモデルと、それぞれの許可／拒否判定（shadow → allowed:false）
running_models	低	読み込み済みモデル：VRAM 使用量と常駐期限
model_details	低	1 つのモデルのライセンス／パラメーター／機能
server_status	低	Ollama の到達可能性とバージョン
vram_usage	低	読み込み済みモデルが使用している VRAM の合計。予算超過を警告
policy_view	低	現在の許可／拒否ポリシーと来歴ダイジェストのピン
model_provenance	低	インストール済みモデルの各ダイジェストとピンとの比較。不一致を警告
scan_prompt	低	テキストのみのスキャン → 検出結果と重み付けされたリスク帯（モデル呼び出しなし）
usage_events	低	観測された使用状況ログを検索
anomaly_report	低	シャドーモデル、ダイジェストの不一致、高リスクおよびブロックされたプロンプトの集計
proxy_guidance	低	proxy serve コマンドとクライアント側の変更、およびプロキシは強制適用境界ではなく、チョークポイントであるという明示的な注意事項。書き込みや起動は行いません

書き込み（8）

ツール	リスク	取り消し／安全性
pull_model	中	ポリシーに違反する場合は拒否
remove_model	高	ドライラン＋取り消し（再プル）
unload_model	中	VRAM から解放（keep_alive:0）
set_model_allowlist	中	取り消し → 以前の許可リストに戻す
set_model_denylist	中	取り消し → 以前の拒否リストに戻す
pin_model_digest	中	モデルに期待される来歴ダイジェストをピン留め
guarded_generate	中	経由処理のガード：スキャン＋ポリシーゲート＋記録＋許可された場合に実行
observe_chat	中	/api/chat メッセージに対して同様に処理

取り消し（2）

ツール	リスク	動作
undo_list	低	記録された取り消しトークンを一覧表示
undo_apply	中	記録された逆操作記述子を再実行

リスク帯によるゲーティング：プロンプトのリスク帯が >= block_threshold（既定値は high）の場合、またはモデルが許可されていない場合、guarded_generate／observe_chat はブロックします。ブロックされた呼び出しが Ollama に到達することはなく、使用状況ログにブロックとして記録されます。

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントはスキルと MCP サーバーの両方を利用できます。

/plugin marketplace add AIops-tools/marketplace
/plugin install ai-guardian@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されるため、監査ログの各行を、その行を書き込んだコードまで追跡できます。認証情報は引き続き ai-guardian init で設定します。詳しくは以下を参照してください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて利用できます。

openclaw plugins install clawhub:@zw008/ai-guardian
openclaw skills info ai-guardian          # expect: Visible to model: yes

インストール後、OpenClaw ゲートウェイを再起動してプラグインを読み込んでください。MCP サーバーは uv で取得され、このリリースの正確なバージョンに固定されるため、uvx が PATH 上にある必要があります。uvx がない場合もスキルはインストールされますが、Visible to model: no と報告されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロンの MCP サーバーとして

uv tool install ai-guardian-aiops          # or: pipx install ai-guardian-aiops
ai-guardian doctor                   # Ollama reachability + policy summary (works zero-config)
ai-guardian overview                 # models installed/running, shadow count, usage stats
ai-guardian model list               # installed models with allow/deny verdicts
ai-guardian guard scan "my key is AKIAIOSFODNN7EXAMPLE"   # deterministic scan → risk band

コマンド名とパッケージ名は異なります。 CLI、スキル、このリポジトリの名前はいずれも ai-guardian です。PyPI ディストリビューションは、ai-guardian がすでに使われていたため、ai-guardian-aiops です。以下のどちらの表記も正しく、意図されたものです。ai-guardian-aiops をインストールしてから、ai-guardian を実行してください。

MCP 経由でガードを通してプロンプトをルーティングします（スキャン + ポリシーゲート + 記録 + 許可された場合に実行）。

guarded_generate(model="llama3.2:3b", prompt="…", block_threshold="high")

MCP サーバー（stdio）として実行します。全 21 ツールを利用でき、CLI はその一部を簡単に使えるようにしたものです。

export AI_GUARDIAN_AIOPS_MASTER_PASSWORD=...   # only if a target has a stored token
ai-guardian mcp                                # or: ai-guardian-mcp

そのパスワードの保存先：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能であり、シェルの履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使用するか、必要な 1 つのコマンドの実行中のみ、シークレットマネージャーから値を注入することをおすすめします。

ガバナンス

MCP と CLI のすべての操作は、同梱の @governed_tool ハーネスを通ります。このハーネスは記録を行いますが、許可は行いません（上記を参照）。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、およびオペレーターが指定した承認者や理由）は、~/.ai-guardian/audit.db に記録されます（AI_GUARDIAN_AIOPS_HOME で保存先を変更できます）。これは、観測されたローカル LLM の使用状況を保持する ~/.ai-guardian/usage.db とは別です。
• 暴走防止ガード — 認可ゲートではなく、安全対策です。同じ呼び出しが短時間に繰り返されるとサーキットブレーカーが作動し、停止したエージェントが無制限に呼び出しや時間を消費するのを防ぎます。AI_GUARDIAN_RUNAWAY_MAX=0 で無効化できます。任意で、AI_GUARDIAN_MAX_TOOL_CALLS / AI_GUARDIAN_MAX_TOOL_SECONDS に上限を設定できます。
• 取り消し記録 — 元に戻せる書き込みでは、取得した変更前の状態から作成した逆操作記述子を記録します。
• リスクティア — risk_level から導出される監査ログ上の説明用ラベルです。何も制限しません。

対応範囲と制限事項

• 対象範囲：エンドポイント上のローカル LLM — Ollama と、OpenAI 互換の llama.cpp / LM Studio / ローカル単一ノード vLLM。単一エンドポイントのローカル LLM の可観測性とコンテンツガバナンスに対応します。GPU 推論クラスターの運用は対象外です（→ inference-aiops）。
• v0.1 = パッシブなインベントリ／状態監査 およびオプトインのルート経由コンテンツガバナンス。他のクライアントのトラフィックを対象とする透過的なキャプチャープロキシは v0.2 のロードマップであり、v0.1 には含まれません。
• IGEL AI Armor との相互運用性は、現時点では文書上の位置付け（相互補完的な役割）にとどまり、連携機能は組み込まれていません。
• 検証状況 — スキャナー、ポリシー、リスクバンドは純粋な決定論的オフラインロジックであり、テストスイートでもそのように実行されます。Ollama の基本的なルート経由機能（実際の生成 + ポリシーによる拒否 + 取り消しの記録）は、2026-07-13 に稼働中の Ollama 0.24.0 を相手に検証済みです。その他の Ollama 機能と OpenAI 互換の方言（llama.cpp / LM Studio / ローカル vLLM）は、まだモック応答による検証のみです。稼働環境での確認には ai-guardian doctor が最も手軽です。どの項目が検証済みかについては、docs/VERIFICATION.md を参照してください。

必要な機能がありませんか？

パッシブキャプチャプロキシ、別のスキャナーシグネチャ、より充実したポリシーモデル、または AI Armor フックをお求めですか？ イシューまたは PR を作成してください。フィードバックや貢献を歓迎します。