From 571f5d8cc385a1bda31547fb94ec02e7651c765a Mon Sep 17 00:00:00 2001 From: thanhnv Date: Sun, 5 Jul 2026 12:48:32 +0900 Subject: [PATCH] docs(arch): add projectable visual architecture page (casan-architecture.html) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Self-contained, full-screen-projectable HTML visualizing the base → competition → now journey: OLED-glass design, 3-milestone timeline, 7 harness bento cards (color-coded H1–H7 with each file's role), 5 upgrade-track tables (Track A / C-MVP / Evidence / H5+ / H6+) with gap-closed columns, honest-maturity panel + one-line flow diagram. UTF-8 standalone doc (opens directly in a browser), IntersectionObserver scroll reveals, custom cubic-bezier motion, mobile fallback. Verified rendering in preview. Cross-linked from both architecture md files. Adds .claude/launch.json (static server for local preview of optimize-docs). Co-Authored-By: Claude Fable 5 --- .claude/launch.json | 11 + optimize-docs/CASAN_ARCHITECTURE_AFTER.md | 2 + optimize-docs/CASAN_ARCHITECTURE_BEFORE.md | 2 + optimize-docs/casan-architecture.html | 438 +++++++++++++++++++++ 4 files changed, 453 insertions(+) create mode 100644 .claude/launch.json create mode 100644 optimize-docs/casan-architecture.html diff --git a/.claude/launch.json b/.claude/launch.json new file mode 100644 index 0000000..4842242 --- /dev/null +++ b/.claude/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.0.1", + "configurations": [ + { + "name": "casan-docs", + "runtimeExecutable": "python3", + "runtimeArgs": ["-m", "http.server", "8791", "--directory", "optimize-docs"], + "port": 8791 + } + ] +} diff --git a/optimize-docs/CASAN_ARCHITECTURE_AFTER.md b/optimize-docs/CASAN_ARCHITECTURE_AFTER.md index 135e859..c8eeaea 100644 --- a/optimize-docs/CASAN_ARCHITECTURE_AFTER.md +++ b/optimize-docs/CASAN_ARCHITECTURE_AFTER.md @@ -3,6 +3,8 @@ > **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"**. +> +> 🖥️ **Bản trình chiếu trực quan:** `casan-architecture.html` — mở full-screen bằng trình duyệt khi thuyết trình. --- diff --git a/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md b/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md index 622a14f..56d2bba 100644 --- a/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md +++ b/optimize-docs/CASAN_ARCHITECTURE_BEFORE.md @@ -2,6 +2,8 @@ > **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. +> +> 🖥️ **Bản trình chiếu trực quan (mở full-screen khi thuyết trình):** `casan-architecture.html` — mở trực tiếp bằng trình duyệt, có cả 3 mốc + 7 harness + 5 nhóm nâng cấp trên một trang. --- diff --git a/optimize-docs/casan-architecture.html b/optimize-docs/casan-architecture.html new file mode 100644 index 0000000..62a98b0 --- /dev/null +++ b/optimize-docs/casan-architecture.html @@ -0,0 +1,438 @@ + + + + + +CASAN — Kiến trúc before → after + + +
+
+ + +
+
CASAN · Kiến trúc bảo mật AI
+

Từ bộ khung trống
đến 7 lớp phòng thủ

+

Hành trình before → after của thư mục .specify/scripts: khởi đầu chỉ có 5 file spec-kit vô hại, đến hệ 60 script chặn tấn công thật — mỗi tuyên bố có một cuộc tấn công chứng minh.

+ +
+
Script
5 → 37 → 60
+
Kiểm thử đối kháng
79 → 175 0 lỗi
+
H4 · H5 · H6
3.0 → 4.0/ 5
+
Lớp yếu nhất
76 → 79 → 80
+
+
+ + +
+
3 mốc
+

Ba mốc, một mạch tiến hoá

+
+
+
Mốc 0 · Base

Spec-kit vanilla

+
5 file
+

Chỉ biết sinh khung dự án. Không chặn, không ghi vết, không đo chi phí.

+ Điểm xuất phát +
+
+
Mốc 1 · Lúc mang đi thi

Đủ 7 harness

+
37 script
+

Hiện thực đủ 7 lớp bảo vệ. Chặn được tấn công trên sân khấu — mức demo/PoC.

+ H4/H5/H6 ~3.0 / 5 +
+
+
Mốc 2 · Sau khi thi

Cứng hoá production

+
60 script
+

+23 script vá đường lọt "sát production". Chứng minh bằng tấn công, trung thực chỗ chưa tới.

+ CASAN Level 4 · không lớp nào < 80 +
+
+
+ + +
+
Mốc 0 → Mốc 1
+
+

Base gốc: 5 file "chỉ sinh khung"

+

Đây là toàn bộ .specify/scripts/bash của spec-kit vanilla — chưa một dòng nào về an toàn.

+
+
+
check-prerequisites

Kiểm tra công cụ/điều kiện trước khi chạy

+
common

Hàm dùng chung (đường dẫn, tiện ích)

+
create-new-feature

Dựng khung một feature theo đặc tả

+
setup-plan

Dựng khung kế hoạch triển khai

+
update-agent-context

Cập nhật ngữ cảnh cho agent

+
+
+ + +
+
Mốc 1 · lúc thi
+
+

+32 script → đủ 7 lớp phòng thủ

+

Mỗi harness là một lớp bảo vệ. Mỗi file là một mảnh của lớp đó.

+
+
+ +
+
H1

Context

Ngữ cảnh
+
    +
  • context-validatekiểm tra pipeline-context hợp lệ
    • +
  • casan-logghi log theo cấp độ
    • +
+
+ +
+
H2

Tool

Công cụ
+
    +
  • tool-registry-gateleast-privilege + rate-limit + idempotency
    • +
  • validate-tool-inputkiểm input theo JSON schema
    • +
  • tool-execchạy tool có timeout cứng
    • +
  • tool-audit-libghi nhật ký mọi lần gọi tool
    • +
  • verify-tool-auditxác minh chuỗi nhật ký tool
    • +
+
+ +
+
H3

Evaluation

Đánh giá / model
+
    +
  • model-routerđịnh tuyến model theo vai trò
    • +
  • model-callgọi model local + cloud
    • +
  • model-fallbackmodel A hỏng → chuyển B
    • +
+
+ +
+
H4

Security

Bảo mật đầu vào / đầu ra
+
    +
  • security-checkquét injection / secret / PII hai chiều
    • +
  • artifact-scanchặn injection gián tiếp giấu trong tài liệu
    • +
  • security-gatecổng bảo mật tổng hợp
    • +
  • pii-maskche thông tin cá nhân
    • +
+
+ +
+
H5

Governance

Quản trị & nhật ký
+
    +
  • governance-checktách quyền (SoD), duyệt, least-privilege
    • +
  • verify-audit-chainxác minh hash-chain (sửa 1 ký tự là gãy)
    • +
  • sign-audit-headký số HEAD chuỗi audit
    • +
  • sign-policy-bundleký gói chính sách trung tâm
    • +
  • secrets-scanquét secret lỡ commit
    • +
  • circuit-breaker-checkno-bypass + cầu dao model
    • +
  • vault-kmský qua Vault Transit (KMS)
    • +
+
+ +
+
H6

AgentOps

Vận hành & chi phí
+
    +
  • agent-metricsđo chi phí / độ trễ / token + cảnh báo
    • +
  • cost-spike-detectphát hiện vọt chi phí
    • +
  • drift-detectmodel đổi hành vi theo thời gian
    • +
  • hallucination-scanquét tín hiệu bịa đặt
    • +
  • import-provider-telemetrynhập số dùng thật
    • +
  • provider-cost-lookuptra chi phí thật theo bước
    • +
  • business-kpi-reportbáo cáo KPI nghiệp vụ
    • +
+
+ +
+
H7

Orchestration

Điều phối
+
    +
  • casan-harnesswrapper chạy 1 bước qua đủ harness
    • +
  • rollback-managerrollback thật khi bước lỗi
    • +
  • verify-harness-reusechứng minh harness tái dùng đa dự án
    • +
+
+
+
+ + +
+
Mốc 1 → Mốc 2 · sau khi thi
+
+

+23 script → cứng hoá cho chạy thật

+

Năm nhóm nâng cấp. Không xoá gì của bản thi — chỉ bồi thêm lớp và vá từng đường lọt.

+
+ + +
+
Track A

Vá khe hở bộ lọc cũ

+

Bịt các kỹ thuật né tránh nâng cao mà bộ lọc thi bỏ sót; làm telemetry không sửa được.

+
+
File mớiTác dụngĐường lọt nó vá
+
unicode-normalize.pyChuẩn hoá NFKC + gấp homoglyph + bóc zero-width + fullwidthChữ "ignore" viết bằng ký tự Cyrillic giả
+
decode-suspicious.pyGiải base64/hex đoạn khả nghi rồi quét lạiPayload giấu trong mã hoá
+
tool-output-scan.shQuét injection trong OUTPUT của tool trước khi tái nhập contextKết quả tool nhiễm độc quay lại model
+
telemetry-integrity.shRàng chi phí vào manifest ký — sửa 1 token là MISMATCHSửa lén sổ chi phí
+
benign-fp-report.shCorpus 95 câu hợp lệ (Anh/Việt/Nhật) + ngân sách FPSiết chặt mà bắt nhầm người thật
+
+

File cũ được nâng: security-check thêm strict fail-closed (model chết → CHẶN) · cost-spike-detect thêm trần tuyệt đối + ngân sách tích luỹ + cold-start.

+
+ + +
+
Track C-MVP

Kiểm soát ngoài 3 harness lõi

+

Bảo mật thật không chỉ lọc prompt — còn ở hành động, chuỗi cung ứng, rò rỉ dữ liệu, cô lập chạy.

+
+
File mớiTác dụngĐường lọt nó vá
+
action-gate.shCanh theo hành động: ghi .env, rm -rf, curl|bash, cài depTool "hợp lệ" nhưng làm việc phá hoại
+
supply-chain-gate.shTyposquat / postinstall / denylist + gói mới phải duyệtAI tự kéo thư viện độc
+
supply-chain-scan.pyQuét khác biệt manifest dependencybổ trợ cho gate trên
+
data-exfil-guard.shChặn secret → cloud; che PII → nhật kýTuồn dữ liệu ra ngoài
+
sandbox-run.shChính sách tĩnh (ssh/egress/forkbomb) + ulimitCode sinh ra làm bậy (⚠ scaffold)
+
+
+ + +
+
Evidence Pack

"Vì sao tin output này?"

+
+
File mớiTác dụngKết quả
+
evidence-pack.shLệnh pack / verify-pack gói bằng chứnggói 12 file ký số
+
evidence-pack-build.pyDựng gói + manifest hash + ký HEADanchor = signed
+
evidence-pack-verify.pyXác minh tamper-evidentSửa 1 byte → VÔ HIỆU; certified chỉ khi đủ cổng
+
+
+ + +
+
H5+

Quản trị lên hạng

76 → 80
+

Vá 3 đường lọt lớn nhất: duyệt tin bằng biến môi trường · khoá ký nằm local · nhật ký xoá được.

+
+
File mớiTác dụngĐường lọt nó vá
+
approval-sign.shReviewer ký số vào đúng request để duyệtKhai "người duyệt = X" là qua
+
approval-verify.shXác minh chữ ký + vai trò; chống giả / sai vai / replay / tự duyệtnhư trên
+
audit-ship.shShip HEAD audit ra sổ ngoài append-only (WORM)Xoá nhật ký để phi tang
+
worm-ledger.pySổ ngoài chỉ-ghi-thêm, móc xích hashnhư trên
+
verify-audit-gap.shPhát hiện rollback + giả mạo sổAUDIT_GAP / LEDGER_TAMPERED
+
+

File cũ được nâng: vault-kms thêm rotate (xoay khoá) + non-exportable (chìa không rời két).

+
+ + +
+
H6+

Vận hành lên hạng

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 — cộng kỹ thuật né cầu dao.

+
+
File mớiTác dụngĐường lọt nó vá
+
alert-dispatch.shGửi cảnh báo live ra webhook + dedup + dead-letter + gửi lạiSự cố chỉ ghi file, 3h sáng không ai biết
+
provider-usage-fetch.shKéo usage từ API nhà cung cấp + kiểm định dạng + fail-loudthiếu nguồn chi phí "ground truth"
+
telemetry-reconcile.shĐối soát số ở máy vs nhà cung cấpKhai gian chi phí để giấu hành động lén
+
dashboard-serve.shServe dashboard qua HTTP + /healthz stale-awareBảng tĩnh không biết khi telemetry chết lặng
+
dashboard-server.pyHTTP server: fresh → 200, số liệu cũ → 503 stalenhư trên
+
+

File cũ được nâng: circuit-breaker-check thêm cầu dao theo tỷ lệ hỏng trong khoảng (chống né bằng xen kẽ thành công).

+
+
+ + +
+
+

Trung thực về chỗ chưa tớiCASAN Level 4 · chứng minh bằng tấn công

+

Đây là mức production nội bộ, mỗi tuyên bố có tấn công thật đứng sau — chưa phải production hoàn chỉnh. Sức mạnh nằm ở phòng thủ nhiều tầng + trung thực, không phải "viên đạn bạc". Các hạng mục production còn để ngỏ:

+
+ 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 (container/nsjail) + Dashboard triển khai chính thức + kênh alert managed + Billing-API thật (cần khoá) + Phát hiện đa ngôn ngữ (VI/JA) +
+
+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 · Level 4 (H4/H5/H6 ~4.0/5, không lớp nào < 80) +
+
+
+ +
CASAN — Context-Aware Secure Agent Native · kiến trúc before → after · 175 kiểm thử · 0 lỗi
+ +
+
+ + + +