sys-analysis-design/.claude/skills/sa-2-architecture/templates/security-architecture.md

# SEC — Security Architecture & Threat Model — <PROJECT>

| | |
|---|---|
| **Version** | 1.0 |
| **Date** | YYYY-MM-DD |
| **Author** | <SA> (skill sa-2-architecture) |
| **Status** | 🟡 Draft |
| **Approved by** | **Security: —** · Tech Lead: — |
| **Source** | SAD_… v1.0 · DAT_… v1.0 · RBAC_… của BA · chính sách bảo mật … |
| **Scope** | |
| **Confidence** | 🟡 |

## Change Log

| Version | Date | Người sửa | Thay đổi | ADR |
|---|---|---|---|---|
| 1.0 | | | Bản đầu | — |

> 🔴 **Security có quyền phủ quyết AG2.** Tài liệu này phải được làm **cùng** người của
> Security, không phải trình cho họ xem lúc cuối. Phát hiện muộn nhất và đau nhất luôn đến từ đây.

---

## 1. Ranh giới tin cậy

*Nơi dữ liệu đi từ vùng ít tin cậy sang vùng tin cậy hơn. Mỗi ranh giới phải có kiểm tra đầu vào.*

<!-- archify: architecture · diagrams/SEC_ranh-gioi-tin-cay.architecture.json -->
```mermaid
flowchart LR
```

| # | Ranh giới | Từ vùng | Sang vùng | Kiểm tra gì tại đây | `CMP` chịu trách nhiệm |
|---|---|---|---|---|---|
| 1 | Internet → hệ thống | không tin cậy | | xác thực, giới hạn tốc độ, kích thước payload, kiểm tra định dạng | |
| 2 | Service → CSDL | | | | |

## 2. Xác thực

| | Quyết định | `ADR` |
|---|---|---|
| **Cơ chế** | session / JWT / OAuth2 + OIDC / mTLS | |
| **Nơi giữ trạng thái** | server-side / stateless token | |
| **Thời hạn access token** | | |
| **Refresh token** | có/không · thời hạn · xoay vòng không | |
| **Cách thu hồi ngay lập tức** | *(bắt buộc trả lời — token stateless thu hồi bằng gì)* | |
| **Đa yếu tố (MFA)** | với vai trò nào | |
| **Nơi ký/xác minh chữ ký** | khoá ở đâu, xoay bao lâu một lần | |

🔴 **JWT stateless không thu hồi được ngay** trừ khi có danh sách chặn. Nhân viên nghỉ việc
lúc 9h mà token còn hiệu lực tới 10h là rủi ro thật — quyết định ở đây, không để dev tự xử lý.

## 3. Phân quyền

| | Quyết định | `ADR` |
|---|---|---|
| **Mô hình** | RBAC / ABAC / kết hợp | |
| **Chỗ ra quyết định** | gateway / từng service / thư viện chung | |
| **Nguồn sự thật của vai trò** | | |
| **Ràng buộc dữ liệu (row-level)** | có/không · cơ chế | |

🔴 **Phân quyền ở gateway không đủ khi có ràng buộc dữ liệu.** "Chỉ xem cửa hàng mình phụ
trách" là điều kiện trên dữ liệu — gateway không biết. Phải quyết ở service, và phải nhất quán.

### 3.1 Map `RBAC` của bộ BA xuống quyền kỹ thuật

| `ROLE-nn` (BA) | Vai trò kỹ thuật | Quyền trên `IF-nnn` | Ràng buộc dữ liệu | Ai gán vai trò này |
|---|---|---|---|---|
| `ROLE-01` | | `IF-001` đọc | 🔶 chỉ cửa hàng phụ trách | |

Mỗi `ROLE-nn` trong `RBAC` của BA phải có đúng một dòng ở đây. Thiếu ⇒ chặn AG2.

### 3.2 Phân tách nhiệm vụ (SoD)

*Cho các hành động phê duyệt / chốt sổ / chuyển tiền.*

| Hành động | Người thực hiện không được đồng thời là | Cơ chế cưỡng chế |
|---|---|---|

## 4. Threat model — STRIDE

*Làm cho mỗi luồng nhạy cảm: đăng nhập, thanh toán, dữ liệu cá nhân, thao tác quản trị, xuất dữ liệu.*

### 4.1 Luồng: <tên>

| ID | Loại (STRIDE) | Mối đe doạ | Thành phần bị nhắm | Mức | Biện pháp | **Cách kiểm chứng biện pháp có hiệu lực** | `FIT`/`QAS` |
|---|---|---|---|---|---|---|---|
| `THR-01` | Spoofing | | | 🔴 | | pentest / kiểm thử tự động / review thủ công định kỳ | |
| `THR-02` | Tampering | | | | | | |
| `THR-03` | Repudiation | | | | audit log ghi … | | |
| `THR-04` | Information disclosure | | | | | | |
| `THR-05` | Denial of service | | | | giới hạn tốc độ … | | |
| `THR-06` | Elevation of privilege | | | | | | |

🔴 **Cột "cách kiểm chứng" không được để trống.** Biện pháp không kiểm chứng được là biện pháp
tồn tại trên giấy — đúng theo quy tắc `D8`.

### 4.2 Mối đe doạ đã chấp nhận

| `THR` | Vì sao chấp nhận | Ai ký · ngày | Dấu hiệu cảnh báo | Kế hoạch nếu xảy ra |
|---|---|---|---|---|

## 5. Bảo vệ dữ liệu

| | Quyết định |
|---|---|
| Mã hoá in-transit | TLS … · nội bộ có mã hoá không |
| Mã hoá at-rest | cấp nào (đĩa / CSDL / trường) · khoá quản lý ở đâu |
| Trường nào mã hoá ở mức trường | *(tham chiếu `DAT` §5)* |
| Che dữ liệu khi hiển thị / khi log | quy tắc cụ thể |
| Dữ liệu ở môi trường non-prod | ẩn danh hoá / dữ liệu sinh / **cấm dùng dữ liệu thật** |

🔴 **Dữ liệu production trên môi trường dev là vi phạm phổ biến nhất và dễ tránh nhất.** Chốt
rõ ở đây và cưỡng chế bằng `FIT`.

## 6. Quản lý secret

| | Quyết định |
|---|---|
| Nơi lưu | |
| Cách ứng dụng lấy | |
| Xoay khoá: tần suất, tự động hay thủ công | |
| **Cấm tuyệt đối** | secret trong mã nguồn, trong biến môi trường ghi vào log, trong ảnh container |
| Cách phát hiện rò rỉ | quét mã nguồn: … · `FIT-nn` |

## 7. Audit log

| Hành động phải ghi | Ghi những trường gì | Ai đọc được | Giữ bao lâu | Chống sửa bằng cách nào |
|---|---|---|---|---|
| Đăng nhập / thất bại | | | | |
| Thay đổi quyền | | | | |
| Truy cập dữ liệu nhạy cảm | | | | |
| Phê duyệt / chốt sổ | | | | |

🔴 **Audit log mà người bị audit sửa được thì không phải audit log.** Ghi rõ cơ chế chống sửa
(append-only, tài khoản riêng, hệ thống tách biệt).

## 8. Tuân thủ

| Yêu cầu | Nguồn | Cách đáp ứng | Bằng chứng cho kiểm toán | Ai xác nhận |
|---|---|---|---|---|
| | GDPR / PCI-DSS / K-ISMS / nội bộ | | | |

## 9. Phụ thuộc & chuỗi cung ứng

| | Quyết định |
|---|---|
| Quét lỗ hổng thư viện | công cụ · tần suất · ngưỡng chặn build |
| Quét ảnh container | |
| Chính sách vá lỗ hổng nghiêm trọng | trong bao lâu |
| Ai duyệt thư viện mới | |

## 10. Giả định & Ngoài phạm vi

**Giả định:**

| ID | Giả định | Cách xác minh | Nếu sai |
|---|---|---|---|

**Ngoài phạm vi:**

- *(ví dụ: không chống được kẻ tấn công có quyền quản trị hạ tầng — rủi ro này do quy trình
  nhân sự và kiểm soát truy cập cloud xử lý, không do kiến trúc ứng dụng)*

## 11. Open Questions

| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì | Hệ quả nếu trả lời ngược |
|---|---|---|---|---|---|