109 lines
6.1 KiB
Markdown
109 lines
6.1 KiB
Markdown
# 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](../plans/CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) ·
|
||
[Spike-20 §9](../spikes/CASAN_SPIKE_20_AGENTIC_CLIENT_HOOKS.md).
|
||
|
||
## 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; Core H1→H7 đã pin theo project vẫn hoạt động.
|