CASAN/docs/casan/CASAN_AGENTIC_CLIENT_SECURITY.md

CASAN Agentic Client — Mô hình bảo mật & giới hạn bypass (Plan-20)

Tài liệu này nêu rõ CASAN đảm bảo gì và không đảm bảo gì khi developer gõ prompt trực tiếp trong một agentic client (Claude Code, Codex, VS Code). Mục tiêu là không dùng từ “bắt buộc tuyệt đối” sai mức: một số tuyến chỉ là guardrail theo project, có thể bị người có quyền sửa cấu hình bypass.

Liên quan: Plan-20 §3 · Spike-20 §9.

1. Certification strength — bốn mức, không gộp

Strength	Ý nghĩa	Cam kết	Bypass
casan_owned	Launcher/SDK/Chat Participant do CASAN điều khiển toàn vòng đời	Mạnh nhất trong local client	Rất khó với người dùng thường
managed_hook	Hook/policy được tổ chức pin, user không tắt được	Guardrail tổ chức	Cần quyền quản trị môi trường
project_hook	Hook commit trong repo, user trust project	Guardrail theo project	Có thể bypass bởi người sửa/tắt config
observed_only	Chỉ telemetry, không đủ admission/tool gate	Không certified	N/A

UI và export H6 không được gộp bốn mức trên thành một nhãn pass. Turn ở observed_only không bao giờ hiển thị certified.

2. Điều kiện tối thiểu để một turn được certified

1. Có admission_id hợp lệ, còn hạn (TTL), gắn đúng project root canonical và session/turn.
2. Mọi side-effect tool trong coverage đã công bố đều qua pre-tool.
3. Enforcement mode = enforce và certification strength ∈ {project_hook, managed_hook, casan_owned}.
4. Không có tín hiệu bypass coverage (ví dụ tool cross-project, tool ngoài coverage).
5. finalize chạy đúng một lần và các control kết thúc không đánh flag.

Nếu bất kỳ điều kiện nào thiếu → turn là non-certified. Bridge fail-closed: khi không quyết định được trong internal timeout → block/deny.

Phân biệt timeout vs gate-unavailable (graceful degradation):

• Timeout (gate tồn tại nhưng không trả lời kịp) → fail-closed: block prompt / deny tool. Coi như có thể có rủi ro.
• Gate không chạy được (ví dụ Windows không có bash/Git Bash) → degrade: turn bị hạ cấp observed_only, không certify, nhưng không chặn developer. Đây là thực tế triển khai, không phải tấn công. CASAN không bao giờ certify âm thầm khi H4/H2 không chạy, và cũng không biến việc thiếu bash thành lý do chặn mọi prompt. Cài Git Bash để bật lại certification.

3. Những gì CASAN KHÔNG hứa

• Không chặn được mọi prompt trong mọi AI extension bên thứ ba.
• Không coi project_hook là security boundary tuyệt đối khi user có quyền sửa/tắt .claude/settings.json hoặc .codex/hooks.json.
• Không gọi model lần hai từ hook để “chạy lại qua CASAN”.
• Không suy diễn token/cost khi client không cấp nguồn tin cậy — số thiếu là null kèm warning, không phải 0.
• Codex tool hooks là guardrail, không phủ 100% hosted/specialized tools; turn dùng tool ngoài coverage bị hạ cấp, không certified.

4. Threat model đã kiểm thử

Suite tests/phase-agentic-bridge-tests.sh (Spike-20 C1–C12 + threat) kiểm:

Mối đe dọa	Phòng thủ	Test
Side-effect không admission	Deny fail-closed	C4
Replay admission hết hạn	TTL check → deny	C5
Dùng lại admission khác project	Project binding → deny + bypass_signal	C5, THREAT bypass
Prompt injection	H4 admission scan → block trước model	C2
Tamper admission_id (path traversal)	Chỉ chấp nhận uuid hex, chặn ..	THREAT tamper
Bridge/hook timeout	Internal timeout ngắn hơn outer → block/deny; ghi H6 failure	C6
Outer hook timeout (fail-open của client)	Side-effect vẫn bị pre-tool deny nếu thiếu admission	C7/C4
Stop loop	finalize idempotent, stop_hook_active guard	C8/C9
Secret/tool output lọt log	Redact + chỉ lưu hash, không lưu raw prompt/output	C11
Cost hiding (bịa số 0)	Missing → null + telemetry_quality	C10
Certified giả ở observe mode	Observe luôn observed_only, không certified	THREAT observe

5. Contract dữ liệu & privacy

• State ở .specify/state/agentic-sessions/, ghi atomic + lock per-turn.
• Không dùng raw prompt làm key; dùng salted hash + turn_id opaque.
• Admission có TTL, project root canonical, và session binding.
• Không ghi secret/credential hoặc toàn bộ tool output vào audit; evidence chỉ giữ bản redact + hash.
• Mỗi record mang schema_version, trace_id, project_id, client, client_version, integration_mode, certification_strength, occurred_at.

6. Khi cần enforcement mạnh

Absolute enforcement cần casan_owned hoặc managed_hook:

• managed_hook: pin hook/policy qua managed environment/MDM/requirements; user không tắt được. Đặt CASAN_AGENTIC_INTEGRATION_MODE=managed_hook qua môi trường quản trị, không commit trong repo.
• casan_owned: dùng launcher/SDK/Chat Participant do CASAN sở hữu toàn bộ vòng đời (ví dụ @casan VS Code Chat Participant — tuyến CASAN-owned, không phải global interceptor cho mọi prompt Copilot).

Plan-20 không quảng bá project_hook như một sandbox tuyệt đối.

7. Rollout & rollback

• Feature flags: CASAN_AGENTIC_BRIDGE_ENABLED, CASAN_AGENTIC_ENFORCEMENT_MODE, CASAN_AGENTIC_CLIENT_ALLOWLIST.
• Bắt đầu observe, sau đó enforce trong pilot; production default chỉ đổi sau exit gate.
• Trace sinh trong observe mode luôn observed_only, không retroactively certified.
• Rollback chỉ tắt adapter; bin/casan-chat và core H1→H7 hiện tại vẫn hoạt động.