numbat – Endpoint visibility cho AI agent trong hệ thống của bạn

Tóm tắt nhanh:
numbat là một công cụ endpoint visibility chuyên cho AI agent, giúp bạn quan sát hoạt động agent trên desktop, CLI, IDE và gateway, phát hiện hành vi rủi ro bằng rule engine tại chỗ, tùy chọn chặn trước hành động (pre-action blocking), và dựng lại timeline forensic từ artifact lưu trữ – tất cả trong một binary duy nhất cho macOS, Linux và Windows.

numbat là một công cụ quan sát và bảo vệ hoạt động AI agent trên endpoint, tập trung vào việc ghi nhận, phân tích và (khi cần) chặn các hành vi nhạy cảm của agent trước khi chúng gây tác động. Thay vì chạy trên một server tập trung, numbat hoạt động local trên từng máy, quan sát các agent thông qua hooks, plugin, OTLP/HTTP logs và artifact phiên làm việc lưu trên disk.

Toàn bộ hoạt động live và at-rest được chuẩn hóa về một event model duy nhất và evaluate bằng cùng một CEL rule engine, giúp bạn có một pipeline detection thống nhất cho mọi loại agent và bề mặt. Đây là mảnh ghép quan trọng nếu bạn đang xây hệ sinh thái AI agent nội bộ (như QM, Codex, Claude Code, OpenClaw,…) và cần một “security/observability layer” chuyên biệt cho chúng.

Những tính năng chính của numbat

numbat tập trung vào ba nhóm chức năng lớn: live monitoring, detection và forensic reconstruction. Cụ thể:

• Live monitoring: quan sát agent thông qua hooks, plugin và OTLP/HTTP log exporters, theo thời gian thực.
• Endpoint-local detection: chạy rule ngay trên endpoint, dùng CEL rule engine, hỗ trợ multi-step sequence rule và custom YAML rule do operator định nghĩa.
• Opt-in blocking: cho phép pre-action blocking qua các hook được hỗ trợ, nhưng trạng thái enforce mặc định là tắt để tránh gây gián đoạn ngoài ý muốn.
• Forensic reconstruction: dựng lại timeline hoạt động từ artifact phiên làm việc được hỗ trợ, kể cả khi trước đó chưa cài numbat, miễn là agent có lưu session artifacts.
• Versioned NDJSON records: mọi event, finding, decision, indicator và scan summary đều ở dạng NDJSON có version, giữ reference nguồn và tuân theo JSON Schema rõ ràng.
• Read-only artifact scanning: scan artifact ở chế độ chỉ đọc, có cơ chế redaction secrets; output mặc định không bao giờ chứa full raw transcript, việc thêm raw evidence vào case bundle là opt-in.
• Inventory & investigation tools: hỗ trợ discovery agent ở chế độ read-only, dựng timeline per-session, và tạo case bundle portable với manifest SHA-256.
• Single-binary distribution: một binary duy nhất cho macOS, Linux, Windows, không cần cgo, phù hợp cho deployment đơn giản trên nhiều hệ điều hành.

Nhờ những tính năng này, numbat giống như một “XDR mini” nhưng chuyên cho AI agent, chạy local và tối ưu cho môi trường dev, security và compliance.

Kiến trúc vận hành và scope của numbat

numbat không thực thi agent hoặc lệnh bên trong artifact; nó chỉ đọc và phân tích dữ liệu được agent ghi lại, đồng thời gửi log ra các sink HTTP đã được cấu hình. Coverage matrix của numbat là nguồn tham chiếu chính, ghi rõ những agent nào được hỗ trợ, bề mặt nào được hook, giới hạn fidelity, deferred store và override root trên từng hệ điều hành.

Trên Windows native, numbat dùng profile và AppData path do vendor định nghĩa; trong WSL, nó dùng home Linux riêng. At-rest reconstruction không phải là disk/memory acquisition và không thể phục hồi hoạt động mà agent chưa bao giờ ghi lại – findings là kết quả match rule, không phải bằng chứng kết luận compromise. Case bundle manifest giúp đảm bảo nội bộ bundle nhất quán; nếu bundle không được ký, nó cũng không thể chứng minh toàn vẹn nguồn hoặc độ đầy đủ dữ liệu.

Chuẩn bị môi trường để cài đặt numbat

Để bắt đầu với numbat, bạn cần một endpoint macOS, Linux hoặc Windows (amd64 hoặc arm64), cùng một môi trường Go hiện đại nếu muốn build từ source. Mọi release đều đi kèm SHA-256 checksum để bạn verify binary tải về.

Các yêu cầu cơ bản:

• Hệ điều hành: macOS, Linux, Windows (amd64/arm64).
• Go: phiên bản 1.26.5 hoặc mới hơn, nếu cài qua go install hoặc build từ source.
• Quyền truy cập file logs, hooks và artifact của agent mà bạn muốn quan sát.
• Quyền cấu hình HTTP sink nếu bạn muốn gửi record ra hệ thống log tập trung (ELK, Loki, Splunk, custom collector,…).

Hướng dẫn cài đặt numbat nhanh

Bạn có hai lựa chọn chính: cài bằng go install hoặc build binary từ source.

Cài bằng go install

Với Go đã được cấu hình, chạy:

go install github.com/perplexityai/numbat/cmd/numbat@latest

Lệnh này sẽ tải source, build và đặt binary numbat vào GOBIN hoặc $GOPATH/bin tùy cấu hình của bạn.

Build static binary từ repo

Nếu bạn clone repo numbat và muốn build static binary:

Trên macOS hoặc Linux:

CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat

Trên Windows (PowerShell):

$env:CGO_ENABLED = "0"
go build -trimpath -o numbat.exe ./cmd/numbat

Thiết lập CGO_ENABLED=0 để đảm bảo binary không phụ thuộc cgo, dễ triển khai trên nhiều host.

Inventory và scan: Bắt đầu ở chế độ chỉ đọc

Trước khi cài hooks live-capture, bạn nên chạy inventory và scan ở chế độ read-only để xem numbat nhìn thấy những agent nào. Các lệnh cơ bản:

# liệt kê các agent được phát hiện
numbat agents

# scan toàn bộ agent được parser hỗ trợ
numbat scan

# chỉ scan Codex
numbat scan --agent codex

Các lệnh này không cài hook, không thay đổi cấu hình agent – rất phù hợp để “thăm dò” trước khi rollout chính thức.

Monitor và enforce: Cài live capture cho agent

Khi đã sẵn sàng live monitoring, bạn cài hook cho agent được hỗ trợ live-capture (ví dụ Codex). Hooks khởi đầu ở chế độ monitor-only; flag --emit all cho phép ghi đầy đủ events, findings, indicators và enforcement decision vào file NDJSON:

numbat hook install --agent codex --emit all
numbat hook status --agent codex

Output mặc định được ghi vào ~/.numbat/records.ndjson, nơi bạn có thể stream hoặc ingest vào hệ thống log của mình.

Lưu ý về “hook trust”: mỗi agent có yêu cầu trust khác nhau; với Codex, bạn cần review definition hiện tại của hook trong /hooks (CLI) hoặc Settings > Hooks (app), đặc biệt sau khi có thay đổi như thêm --enforce. Hooks cài với --managed thường được trust theo policy của agent; hook status chỉ verify cấu hình, không verify execution hay delivery.

Bật chế độ enforce với rules YAML tùy biến

Mặc định, mọi rule ship kèm numbat đều là monitor-only; điều này tránh việc blocking ngoài ý muốn trong giai đoạn đầu triển khai. Để bật enforcement cho một detection cụ thể, operator cần:

1. Copy YAML rule ship kèm numbat vào thư mục policy riêng (ví dụ ./numbat-policy).
2. Giữ nguyên id của rule, thêm trường enforce: true và tăng version.
3. Validate và cài đặt policy cho hook pre-action tương ứng.

Ví dụ:

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

Sau bước này, nếu rule match trong pre-action hook, numbat có thể đưa ra quyết định deny cho hành vi đó, dựa trên semantics của từng agent.

Ví dụ output: Event, finding và enforcement

Để hình dung cách numbat biểu diễn dữ liệu, README cung cấp ba ví dụ output:

• Hook event: một callback before_tool_call từ OpenClaw trở thành network event có đầy đủ context (hostname, OS, user, project path, URL truy cập đến metadata cloud), và match rule cloud-metadata high severity.
• Sequence finding: replay hai callback của Claude Code (đọc file secret, sau đó upload) tạo ra finding với severity: high, có tham chiếu hai event, command redacted và các tag MITRE ATT&CK như attack.t1048, attack.t1552, attack.t1567.
• Enforcement decision: một pre-action create_file của Codex vào authorized_keys match rule persistence.ssh_authorized_keys, numbat đưa ra decision: "deny" với mode: "enforce" và link đến finding liên quan.

Các JSON này đều tuân theo schema versioned (schema_version: "0.2.0"), giúp bạn dễ validate và ingest vào hệ thống phân tích hoặc SIEM.

Tổng quan lệnh CLI quan trọng

numbat tổ chức các lệnh CLI theo nhóm chức năng:

• Inventory và investigation: agents, scan, timeline.
• Live capture: hook install, hook status, hook uninstall, collect.
• Record delivery: ship.
• Rule development: rules check, rules list, rules test.
• Case bundles: case build, case verify.

Bạn có thể chạy numbat --help để xem toàn bộ danh sách lệnh, hoặc numbat help <command> để xem flags chi tiết. Các ác lệnh như scan, collect, hook EVENT, hook install, rules check|list|test nhận flag --rules-dir DIR (có thể lặp lại) để thêm rules của operator hoặc thay thế rule embedded theo id; flag --no-builtin-rules cho phép dùng catalog chỉ có rule của operator.

Tài liệu tham khảo và security model

Repo numbat cung cấp bộ tài liệu khá đầy đủ:

• Agent coverage: chi tiết artifact, live capture, enforcement, và known gaps cho từng agent.
• CLI reference: giải thích commands, flags, record, sink và exit code.
• Live capture: hướng dẫn setup hooks và OTLP.
• Deployment: mô tả install scope, trust, rollout theo fleet, và cách gửi output.
• Enforcement: giải thích semantics của blocking và behavior khi enforcement thất bại.
• Rules: format rule custom, field CEL, cách test và sequence.
• Built-in rules: danh sách detection ship sẵn.
• Record schemas: JSON Schema cho wire format hiện tại.

Về security, numbat nhấn mạnh rằng record có thể giữ context nhạy cảm của endpoint và agent ngay cả sau khi redaction. SECURITY.md mô tả threat model và cách báo cáo lỗ hổng riêng tư.