agent-pd: "Sở cảnh sát" giám sát và kiểm tra an toàn cho các tác nhân Claude Code

Trong bối cảnh các tác nhân AI (AI agents) ngày càng được tích hợp sâu vào quy trình phát triển phần mềm, việc giám sát hành vi của chúng trở nên cực kỳ quan trọng. Mới đây, một công cụ mang tên agent-pd đã được giới thiệu trên GitHub, hoạt động như một "sở cảnh sát" dành riêng cho các tác nhân Claude Code, giúp nhà phát triển kiểm soát an toàn và minh bạch hóa mọi hoạt động của AI.

agent-pd là gì?

agent-pd là một công cụ ghi nhật ký (logging-only hook) ghi lại mọi sự kiện công cụ và quyền hạn từ tác nhân chính cũng như các tác nhân con (subagents). Thay vì đóng vai trò là một tường lửa chặn mọi hành động, agent-pd hoạt động theo cơ chế ghi lại và báo cáo (catch-and-report). Nó cung cấp bằng chứng rõ ràng về các vi phạm quy tắc mà không làm gián đoạn luồng làm việc của tác nhân.

License Apache 2.0 Python 3.12+

Các tính năng chính

Hệ thống phát hiện vi phạm (Detectors)

Điểm mạnh nhất của agent-pd là hệ thống sáu bộ phát hiện xác định (deterministic detectors) hoạt động với chi phí token bằng không. Các bộ phát hiện này bao gồm:

• permission_bypass (Nghiêm trọng): Phát hiện các cuộc gọi bị từ chối và quét lệnh Bash hai tầng để tìm các mẫu nguy hiểm như sudo, rm -rf /, hoặc curl | sh.
• out_of_scope (Cao/Nghiêm trọng): Cảnh báo khi tác nhân truy cập file hoặc đường dẫn Bash nằm ngoài phạm vi dự án, hoặc chạm vào các đường dẫn nhạy cảm như ~/.ssh, ~/.aws, /etc/shadow.
• self_permission (Nghiêm trọng): Báo cáo khi bất kỳ tác nhân nào cố gắng ghi vào các tệp cấu hình kiểm soát của chính nó (ví dụ: .claude/settings.json).
• tool_not_allowed (Cao): Phát hiện tác nhân con sử dụng công cụ không nằm trong danh sách cho phép (allowlist).
• redundant (Thấp): Phát hiện các lệnh gọi công cụ trùng lặp chính xác.
• off_task (Xem xét): So sánh các thuật ngữ tìm kiếm với nhiệm vụ của tác nhân để phát hiện việc đi lạc chủ đề (có thể dùng LLM để xác nhận lại).

Giám sát thời gian thực

Công cụ cung cấp lệnh pd watch, biến terminal của bạn thành một "máy nghe cảnh sát" (police scanner). Bạn có thể xem trực tiếp các hành động của tác nhân và các quy tắc đang bị phá vỡ ngay khi chúng xảy ra.

Tests Passing

Tính toàn vẹn của nhật ký kiểm toán

Mọi sự kiện đều được ghi lại trong một tệp nhật ký kiểm toán (audit log) có chuỗi băm (hash-chained). Điều này giúp phát hiện việc can thiệp hoặc cắt xén dữ liệu. Công cụ cũng hỗ trợ tính năng "sink" để chuyển tiếp nhật ký ra khỏi máy chủ (off-host) nhằm đảm bảo tính không thể sửa đổi (append-only).

Cơ chế hoạt động

agent-pd sử dụng một hook đơn giản để ghi lại sự kiện. Hook này được đăng ký toàn cầu trong ~/.claude/settings.json và kích hoạt trên các sự kiện như PostToolUse, PermissionDenied, hoặc SubagentStart.

Quy trình hoạt động bao gồm ba bước chính:

1. SETUP: Cài đặt hook (pd install-hook).
2. CAPTURE: Hook tự động ghi lại mọi cuộc gọi công cụ vào tệp nhật ký .jsonl theo từng phiên làm việc.
3. READ: Sử dụng các lệnh như pd report (phân tích hậu quả) hoặc pd watch (scanner trực tiếp) để đọc và phân tích dữ liệu.

Cài đặt và sử dụng

Bạn có thể dễ dàng cài đặt agent-pd trực tiếp từ PyPI:

pip install agent-pd
pd install-hook

Sau khi cài đặt, bạn chỉ cần sử dụng Claude Code bình thường. Hook sẽ chạy ngầm và ghi lại mọi hoạt động. Để xem báo cáo vi phạm của phiên gần nhất:

pd report

Để xem danh sách tất cả các phiên cùng với thư mục dự án và câu lệnh nhắc đầu tiên:

pd list

Lưu ý về bảo mật

Tác giả nhấn mạnh rằng agent-pd không phải là một sandbox (hộp cát). Nó nâng cao tiêu chuẩn an toàn nhưng không thay thế hoàn toàn các biện pháp cách ly hệ điều hành. Một kẻ tấn công có cùng đặc quyền vẫn có thể lẩn tránh việc phát hiện tĩnh bằng cách sử dụng các kỹ thuật che giấu hoặc gián tiếp (như biến môi trường đa cấp, lệnh base64, v.v.).

Tuy nhiên, đối với hầu hết các trường hợp sử dụng thông thường, agent-pd cung cấp sự minh bạch cần thiết để các nhà phát triển tin tưởng sử dụng các tác nhân AI trong quy trình làm việc của mình mà không lo ngại về các hành vi vô tình hoặc nguy hiểm khó phát hiện.