From bb1dc8ad9f825c27faa5a050b6d83d31cd34698a Mon Sep 17 00:00:00 2001 From: thanhnv Date: Sun, 5 Jul 2026 12:21:28 +0900 Subject: [PATCH] docs(arch): add before/after architecture files vs the vanilla spec-kit base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two companion docs tracing the .specify/scripts evolution from the 5-file spec-kit scaffold shown in the file tree: - CASAN_ARCHITECTURE_BEFORE.md — state brought to the competition (freeze fbcef96): base 5 → 37 scripts implementing all 7 harnesses, each file's purpose grouped by H1–H7, + the 8 competition test suites. Honest maturity: demo/PoC (~3.0/5). - CASAN_ARCHITECTURE_AFTER.md — the feat/plan07-track-a-hardening upgrades: 37 → 60 scripts (+23) grouped by Track A / Track C-MVP / Evidence Pack / H5+ / H6+, each new file's purpose + the gap it closes, notes on in-place modifications (strict fail-closed, cost caps, KMS rotate, window breaker), + the 6 new test suites (+96 checks). Honest maturity: Level 4 proven by attack (~4.0/5), not full production. File counts verified against git (ls-tree fbcef96 vs HEAD). Co-Authored-By: Claude Fable 5 --- optimize-docs/CASAN_ARCHITECTURE_AFTER.md | 117 +++++++++++++++++++++ optimize-docs/CASAN_ARCHITECTURE_BEFORE.md | 112 ++++++++++++++++++++ 2 files changed, 229 insertions(+) create mode 100644 optimize-docs/CASAN_ARCHITECTURE_AFTER.md create mode 100644 optimize-docs/CASAN_ARCHITECTURE_BEFORE.md diff --git a/optimize-docs/CASAN_ARCHITECTURE_AFTER.md b/optimize-docs/CASAN_ARCHITECTURE_AFTER.md new file mode 100644 index 0000000..135e859 --- /dev/null +++ b/optimize-docs/CASAN_ARCHITECTURE_AFTER.md @@ -0,0 +1,117 @@ +# CASAN — Kiến trúc BEFORE → AFTER (Mốc 2: sau khi thi) + +> **File này = phần nâng cấp SAU khi thi** — nhánh `feat/plan07-track-a-hardening`. +> Điểm xuất phát là trạng thái ở `CASAN_ARCHITECTURE_BEFORE.md` (**37 script, mức demo/PoC**). +> Mục tiêu nâng cấp: từ "chặn được trên sân khấu" → **"đủ chững chạc để chạy thật, chứng minh bằng tấn công"**. + +--- + +## 0. Nhắc lại điểm xuất phát + +| Mốc | Số script bash | Số test | Mức trưởng thành | +|---|:--:|:--:|---| +| Base vanilla (ảnh) | 5 | 0 | chỉ sinh khung dự án | +| **Lúc mang đi thi** (`fbcef96`) | **37** | 8 | demo/PoC tốt (H4/H5/H6 ~3.0/5) | +| **Sau khi thi** (HEAD) | **60** (+23) | 14 (+6) | production nội bộ, chứng minh bằng tấn công (H4/H5/H6 ~4.0/5) | + +**Thêm 23 script + 6 bộ test.** Không xoá gì của bản thi — chỉ **bồi thêm lớp** và **vá đường lọt**. Chia làm 5 nhóm. + +--- + +## 1. Track A — Vá khe hở bộ lọc cũ (rủi ro thấp) + +Bịt các kỹ thuật **né tránh nâng cao** mà bộ lọc thi bỏ sót, và làm telemetry **không sửa được**. + +| File MỚI | Tác dụng | Đường lọt nó vá | +|---|---|---| +| `unicode-normalize.py` | Chuẩn hoá Unicode (NFKC) + gấp **ký tự giả (homoglyph)** + bóc **ký tự tàng hình (zero-width)** + gấp **chữ toàn phần** | Chữ "ignore" viết bằng ký tự Cyrillic giả né được regex | +| `decode-suspicious.py` | **Giải base64/hex** đoạn khả nghi rồi **quét lại** | Payload độc giấu trong mã hoá | +| `tool-output-scan.sh` | Quét injection trong **OUTPUT của tool** trước khi nó quay lại ngữ cảnh AI | Kết quả tool bị nhiễm độc rồi "tái nhập" vào model | +| `telemetry-integrity.sh` | Ràng số liệu chi phí vào **manifest ký số** — sửa 1 token là **MISMATCH** | Sửa lén sổ chi phí | +| `benign-fp-report.sh` | Corpus **95 câu hợp lệ (Anh/Việt/Nhật)** + ngân sách **dương-tính-giả** | Siết chặt mà **bắt nhầm** người dùng thật | + +> *Ghi chú:* `security-check.sh` được nâng thêm **strict fail-closed** (model chết → CHẶN) và `cost-spike-detect.sh` thêm **trần tuyệt đối + ngân sách tích luỹ + cold-start** — đây là **sửa file cũ**, không phải file mới. + +--- + +## 2. Track C-MVP — Kiểm soát NGOÀI 3 harness lõi + +Bảo mật thật không chỉ nằm ở lọc prompt — còn ở **hành động**, **chuỗi cung ứng**, **rò rỉ dữ liệu**, **cô lập chạy**. + +| File MỚI | Tác dụng | Đường lọt nó vá | +|---|---|---| +| `action-gate.sh` | Canh theo **hành động**: ghi `.env`/khoá, `rm -rf`, `curl\|bash`, cài dep → chặn/hỏi duyệt | Tool "hợp lệ" nhưng làm việc phá hoại | +| `supply-chain-gate.sh` | Cổng chuỗi cung ứng: **typosquat / postinstall / danh sách đen** + bắt gói mới phải duyệt | AI tự kéo thư viện độc | +| `supply-chain-scan.py` | Quét khác biệt manifest dependency | (bổ trợ cho gate trên) | +| `data-exfil-guard.sh` | Chặn **secret → cloud**; **che PII → nhật ký** | Tuồn dữ liệu ra ngoài | +| `sandbox-run.sh` | Sandbox **scaffold**: chính sách tĩnh (chặn `~/.ssh`, egress, fork-bomb) + `ulimit`/timeout | Code sinh ra làm bậy — *(⚠️ chưa cô lập kernel)* | + +--- + +## 3. Evidence Pack (Plan-09) — "Vì sao tin output này?" + +| File MỚI | Tác dụng | +|---|---| +| `evidence-pack.sh` | Lệnh `pack` / `verify-pack` — đóng gói & xác minh gói bằng chứng | +| `evidence-pack-build.py` | Dựng gói **12 file chuẩn** + manifest hash + ký HEAD | +| `evidence-pack-verify.py` | Xác minh **tamper-evident**: sửa 1 byte → gói **VÔ HIỆU**; certified chỉ khi đủ cổng | + +--- + +## 4. H5+ — Quản trị lên hạng (nâng lớp yếu nhất: 76 → 80) + +Vá 3 đường lọt lớn nhất của quản trị: **duyệt tin bằng biến môi trường · khoá ký nằm local · nhật ký xoá được.** + +| File MỚI | Tác dụng | Đường lọt nó vá | +|---|---|---| +| `approval-sign.sh` | Reviewer **ký số** vào đúng request để duyệt | Khai "người duyệt = X" là qua | +| `approval-verify.sh` | Xác minh **chữ ký + vai trò** reviewer; chống giả chữ ký / sai vai / dùng lại (replay) / tự duyệt | như trên | +| `audit-ship.sh` | Ship HEAD audit ra **sổ ngoài append-only (WORM)** | Xoá nhật ký ở máy để phi tang | +| `worm-ledger.py` | Sổ ngoài **chỉ-ghi-thêm, móc xích hash** | như trên | +| `verify-audit-gap.sh` | Đối chiếu → phát hiện **rollback (`AUDIT_GAP_DETECTED`)** + **giả mạo sổ (`AUDIT_LEDGER_TAMPERED`)** | như trên | + +> *Ghi chú:* `vault-kms.sh` được nâng thêm **rotate (xoay khoá)** + **assert-nonexportable (chìa không rời két)** — sửa file cũ. + +--- + +## 5. H6+ — Vận hành lên hạng (nâng lớp yếu nhất kế: 79 → 80) + +Vá 3 gap của chính báo cáo chấm điểm (**alerting chỉ ghi file · telemetry nhập tay · dashboard tĩnh**) + kỹ thuật né cầu dao (V15). + +| File MỚI | Tác dụng | Đường lọt nó vá | +|---|---|---| +| `alert-dispatch.sh` | Gửi cảnh báo **live ra webhook** + gộp trùng (dedup) + **hàng chờ (dead-letter)** + gửi lại | Sự cố chỉ ghi vào file, 3h sáng không ai biết | +| `provider-usage-fetch.sh` | Kéo **usage từ API nhà cung cấp** + kiểm định dạng all-or-nothing + fail-loud | Không có nguồn chi phí "ground truth" | +| `telemetry-reconcile.sh` | **Đối soát** số ở máy vs số nhà cung cấp → khai thiếu = `TELEMETRY_DISCREPANCY` | Khai gian chi phí để giấu hành động lén | +| `dashboard-serve.sh` | Serve dashboard **qua HTTP** + `/healthz` **stale-aware** | Bảng tĩnh không biết khi telemetry chết lặng | +| `dashboard-server.py` | HTTP server: fresh → 200 ok, số liệu cũ → **503 stale** | như trên | + +> *Ghi chú:* `circuit-breaker-check.sh` được nâng thêm **cầu dao theo tỷ lệ hỏng trong khoảng (sliding-window)** — chống né bằng xen kẽ thành công. Sửa file cũ. + +--- + +## 6. Test thêm sau khi thi (6 bộ · +96 kiểm thử) + +| Bộ test MỚI | Số | Kiểm cái gì | +|---|:--:|---| +| `phase1-track-a-tests.sh` | 25 | Track A (chuẩn hoá Unicode, base64, fail-closed, telemetry ký, FP=0) | +| `phase2-track-c-tests.sh` | 29 | Track C-MVP (action-gate, supply-chain, exfil, sandbox) | +| `phase3-evidence-pack-tests.sh` | 7 | Gói bằng chứng (tamper 1 byte → vô hiệu, certified gate) | +| `phase-h5-approval-tests.sh` | 8 | Approval-identity (ký + vai trò + chống replay/tự-duyệt) | +| `phase-h5-infra-tests.sh` | 7 | KMS (rotate/non-exportable, live-aware) + WORM | +| `phase-h6-agentops-tests.sh` | 20 | Alerting live + provider-API + dashboard hosted + window breaker | + +--- + +## 7. Tóm tắt Mốc 2 (một dòng) + +> **37 script "chặn được demo" → 60 script "đủ chững chạc chạy thật".** Ba lớp H4/H5/H6 từ ~3.0/5 lên ~4.0/5; **lớp yếu nhất nhích 76 → 79 → 80 — không còn lớp nào dưới chuẩn**. Tổng **175 kiểm thử đối kháng, 0 lỗi**. +> +> **Trung thực (đã ghi rõ trong `CASAN_HARDENING_STATUS.md`):** đây là mức **CASAN Level 4 — chứng minh bằng tấn công**, **chưa phải production hoàn chỉnh**. Còn cần: hệ danh tính doanh nghiệp (IdP/OIDC live), kho WORM thật (S3 Object Lock), KMS mặc định + HSM, cô lập kernel thật, dashboard triển khai chính thức + kênh alert managed, billing-API thật. Sức mạnh là **phòng thủ nhiều tầng + trung thực**, không phải "viên đạn bạc". + +### Sơ đồ số một dòng +``` +Base 5 file (spec-kit) + └─(+32 script, +8 test) → LÚC THI: 37 script · ~79 test · demo/PoC (H4/H5/H6 ~3.0/5) + └─(+23 script, +6 test) → SAU THI: 60 script · 175 test · production nội bộ (H4/H5/H6 ~4.0/5, không lớp nào <80) +``` diff --git a/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md b/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md new file mode 100644 index 0000000..622a14f --- /dev/null +++ b/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md @@ -0,0 +1,112 @@ +# CASAN — Kiến trúc BEFORE → AFTER (Mốc 1: lúc mang đi thi) + +> **File này = trạng thái "mang đi thi"** — commit freeze `fbcef96`, **trước** nhánh `feat/plan07-track-a-hardening`. +> So sánh với **base gốc** (bộ khung spec-kit vanilla trong ảnh). File tiếp theo (`CASAN_ARCHITECTURE_AFTER.md`) kể tiếp phần nâng cấp sau khi thi. + +--- + +## 0. Base gốc = bộ khung "spec-kit" vanilla (như ảnh) + +Thư mục `.specify/scripts/bash/` ban đầu **chỉ có 5 file** — đây là khung tạo-đặc-tả tiêu chuẩn, **chưa có một dòng nào về an toàn / harness**: + +| File base | Tác dụng | Thuộc về | +|---|---|---| +| `check-prerequisites.sh` | Kiểm tra công cụ/điều kiện trước khi chạy quy trình | spec-kit | +| `common.sh` | Hàm dùng chung (đường dẫn, tiện ích) | spec-kit | +| `create-new-feature.sh` | Dựng khung một feature mới theo đặc tả | spec-kit | +| `setup-plan.sh` | Dựng khung kế hoạch triển khai | spec-kit | +| `update-agent-context.sh` | Cập nhật ngữ cảnh cho agent | spec-kit | + +*(Kèm `init-options.json`, `templates/`, `memory/`.)* → **Base chỉ biết "sinh khung dự án", không biết chặn tấn công, không ghi vết, không đo chi phí.** + +--- + +## 1. Sau cải tiến (lúc thi): từ 5 → **37 script** + 8 bộ test + +**Đã thêm 32 script CASAN** trên nền 5 file base, hiện thực **đủ 7 harness** (7 lớp bảo vệ) + các công cụ ký số/telemetry. Bảng dưới nhóm theo từng harness — **mỗi file là một mảnh của một lớp bảo vệ**. + +### 🟦 H1 — Context (ngữ cảnh) +| File | Tác dụng | +|---|---| +| `context-validate.sh` | Kiểm tra `pipeline-context` hợp lệ — sub-agent lấy đường dẫn spec/artifact từ context, khỏi đoán | +| `casan-log.sh` | Ghi log theo cấp độ (debug/info…) cho toàn pipeline | + +### 🟦 H2 — Tool (công cụ) +| File | Tác dụng | +|---|---| +| `tool-registry-gate.sh` | Đăng ký tool + **least-privilege** (agent chỉ gọi tool được phép) + **rate-limit** + **idempotency** (chống gọi lặp) | +| `validate-tool-input.sh` | Kiểm tra input gọi tool theo **JSON schema** — sai định dạng thì loại | +| `tool-exec.sh` | Chạy tool có **timeout cứng** — công cụ chạy loạn bị cắt giờ | +| `tool-audit-lib.sh` | Thư viện ghi **nhật ký mọi lần gọi tool** (hash-chain + ký) | +| `verify-tool-audit.sh` | Xác minh chuỗi nhật ký tool-calls còn nguyên vẹn | + +### 🟦 H3 — Evaluation (đánh giá / model) +| File | Tác dụng | +|---|---| +| `model-router.sh` | Định tuyến model theo **vai trò** (classify / judge / generate) | +| `model-call.py` | Gọi model — **local (Ollama)** + đường **cloud (OpenAI/Anthropic)** | +| `model-fallback.sh` | Model A hỏng → tự chuyển sang model B | + +### 🟥 H4 — Security (bảo mật) +| File | Tác dụng | +|---|---| +| `security-check.sh` | Quét **injection / secret / PII** ở **cả đầu vào lẫn đầu ra** | +| `artifact-scan.sh` | Quét **injection gián tiếp** giấu trong tài liệu **trước khi** vào ngữ cảnh AI | +| `security-gate.sh` | Cổng bảo mật tổng hợp — chạy loạt kiểm tra, ra một phán quyết chung | +| `pii-mask.py` | Che thông tin cá nhân (dùng chung bởi các control bảo mật) | + +### 🟧 H5 — Governance (quản trị & nhật ký) +| File | Tác dụng | +|---|---| +| `governance-check.sh` | **Tách quyền (SoD)**, duyệt việc nhạy cảm, least-privilege | +| `verify-audit-chain.sh` | Xác minh **hash-chain** sổ kiểm toán — sửa 1 ký tự là gãy | +| `sign-audit-head.sh` | **Ký số HEAD** chuỗi audit (qua KMS hoặc khoá local) | +| `sign-policy-bundle.sh` | Ký gói **chính sách trung tâm** (dùng chung nhiều dự án) | +| `secrets-scan.sh` | Quét **secret lỡ commit** vào mã nguồn | +| `circuit-breaker-check.sh` | Quét **no-bypass** (không cho lách kiểm tra) + cầu dao ngắt khi model hỏng liên tiếp | +| `vault-kms.sh` | Ký qua **Vault Transit (KMS)** — chìa khoá nằm trong két | + +### 🟨 H6 — AgentOps (vận hành & chi phí) +| File | Tác dụng | +|---|---| +| `agent-metrics.sh` | Đo **chi phí / độ trễ / token** mỗi bước + phát cảnh báo | +| `cost-spike-detect.sh` | Phát hiện **vọt chi phí** (bước tốn gấp N lần) | +| `drift-detect.sh` | Phát hiện **model đổi hành vi** theo thời gian | +| `hallucination-scan.py` | Quét **tín hiệu bịa đặt** trong output | +| `import-provider-telemetry.sh` | Nhập **số dùng thật** từ nhà cung cấp model | +| `provider-cost-lookup.py` | Tra chi phí thật theo từng bước | +| `business-kpi-report.sh` | Báo cáo **KPI nghiệp vụ** (cycle-time, rework…) | + +### 🟩 H7 — Orchestration (điều phối) +| File | Tác dụng | +|---|---| +| `casan-harness.sh` | **Wrapper** chạy một bước qua **đủ các lớp harness** một mạch | +| `rollback-manager.sh` | **Rollback thật** khi một bước lỗi | +| `verify-harness-reuse.sh` | Chứng minh bộ harness **tái dùng được** cho nhiều dự án | + +*(Kèm `guideH4-H5-H6.md` — ghi chú hướng dẫn.)* + +--- + +## 2. Test lúc mang đi thi (8 bộ) + +| Bộ test | Vai trò | +|---|---| +| `run-casan4-harness-tests.sh` | **35** kiểm thử happy-path + bằng chứng Level-5 | +| `adversarial-harness-tests.sh` | **44** đòn đối kháng (battery gốc) | +| `phase3-model-router-tests.sh` | Kiểm thử định tuyến model | +| `phase3-redteam-metrics.sh` | Đo **recall** red-team (model vs regex) | +| `phase3-judge-gate-tests.sh` | Cổng LLM-judge nhiều tầng | +| `generate-agentops-dashboard.py` | Sinh bảng theo dõi AgentOps (tĩnh) | +| `generate-casan-demo-context.py` | Sinh ngữ cảnh demo | +| `run-casan-harness-tests.ps1` | Bản PowerShell (Windows) | + +--- + +## 3. Tóm tắt Mốc 1 (một dòng) + +> **Base vanilla 5 file "chỉ sinh khung dự án"** → **CASAN lúc thi 37 script hiện thực đủ 7 lớp bảo vệ** (chặn injection, ghi vết ký số, đo chi phí, điều phối + rollback) — **chứng minh bằng ~79 kiểm thử đối kháng**. +> +> **Trạng thái công tâm lúc thi:** đây là mức **demo/PoC tốt** — chặn được tấn công trên sân khấu. Ba lớp H4/H5/H6 khi đó mới ~3.0/5, còn nhiều đường lọt "sát production" chưa vá (né tránh nâng cao, quản trị khoá, xoá nhật ký, alerting thật…). +> +> 👉 Những đường lọt đó chính là nội dung **`CASAN_ARCHITECTURE_AFTER.md`** — phần nâng cấp `feat/plan07-track-a-hardening` sau khi thi.