universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-TW/core/guides/security-guide.md

@@ -0,0 +1,494 @@
+---
+source: core/guides/security-guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Security Guide
+
+> **語言**: [English](../../../../core/guides/security-guide.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-29
+**相關標準**: [Security Standards](../security-standards.md)
+
+---
+
+## Purpose
+
+本指南提供軟體安全的詳細說明、漏洞範例與教學內容。若需要可立即執行的檢查清單、必要演算法與強制標頭，請參閱 [Security Standards](../security-standards.md)。
+
+---
+
+## Table of Contents
+
+1. [Security Principles Explained](#security-principles-explained)
+2. [OWASP Top 10 Detailed Analysis](#owasp-top-10-detailed-analysis)
+3. [Authentication Deep Dive](#authentication-deep-dive)
+4. [Authorization Patterns](#authorization-patterns)
+5. [Input Validation Strategies](#input-validation-strategies)
+6. [Cryptography Explained](#cryptography-explained)
+7. [Secure Coding Patterns](#secure-coding-patterns)
+8. [Security Testing Methods](#security-testing-methods)
+9. [Secrets Management Practices](#secrets-management-practices)
+10. [Security Logging Best Practices](#security-logging-best-practices)
+11. [Incident Response Process](#incident-response-process)
+12. [References](#references)
+
+---
+
+## Security Principles Explained
+
+### Defense in Depth
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Defense in Depth Model                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Layer 1: Perimeter Security                                   │
+│   ├── Firewall, WAF, DDoS protection                           │
+│   └── Network segmentation                                      │
+│                                                                 │
+│   Layer 2: Application Security                                 │
+│   ├── Input validation, output encoding                        │
+│   ├── Authentication, authorization                            │
+│   └── Secure session management                                │
+│                                                                 │
+│   Layer 3: Data Security                                        │
+│   ├── Encryption at rest and in transit                        │
+│   ├── Data masking, tokenization                               │
+│   └── Access controls                                          │
+│                                                                 │
+│   Layer 4: Monitoring & Response                                │
+│   ├── Security logging, SIEM                                   │
+│   ├── Intrusion detection                                      │
+│   └── Incident response                                        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+關鍵洞見在於：沒有任何單一的安全控制是完美的。透過分層佈防，即使攻擊者突破了某一層，仍會面臨更多障礙。
+
+---
+
+## OWASP Top 10 Detailed Analysis
+
+### A01:2021 – Broken Access Control
+
+**為何位居第一**：存取控制失效從第 5 名躍升至第 1 名，原因在於應用程式越來越依賴複雜的權限系統，而這類系統極易設定錯誤。
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│             Broken Access Control Prevention                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Vulnerabilities:                                              │
+│   ├── IDOR (Insecure Direct Object Reference)                  │
+│   ├── Missing function-level access control                    │
+│   ├── Privilege escalation                                     │
+│   └── CORS misconfiguration                                    │
+│                                                                 │
+│   Prevention:                                                   │
+│   ├── Deny by default, explicit allow list                     │
+│   ├── Server-side access control (never trust client)          │
+│   ├── Validate object ownership on every request               │
+│   ├── Log access control failures, alert on anomalies          │
+│   └── Rate limit APIs to prevent enumeration                   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**IDOR 防護範例**：
+```typescript
+// ❌ Bad: Direct object reference without ownership check
+app.get('/api/orders/:orderId', (req, res) => {
+  const order = db.orders.findById(req.params.orderId);
+  res.json(order);
+});
+
+// ✅ Good: Validate ownership
+app.get('/api/orders/:orderId', authenticate, (req, res) => {
+  const order = db.orders.findById(req.params.orderId);
+  if (!order || order.userId !== req.user.id) {
+    return res.status(404).json({ error: 'Order not found' });
+  }
+  res.json(order);
+});
+```
+
+### A03:2021 – Injection
+
+**SQL Injection 防護**：
+```typescript
+// ❌ Bad: String concatenation (vulnerable to SQL injection)
+const query = `SELECT * FROM users WHERE id = '${userId}'`;
+
+// ✅ Good: Parameterized query
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
+
+// ✅ Good: ORM with proper escaping
+const user = await User.findOne({ where: { id: userId } });
+```
+
+**Command Injection 防護**：
+```typescript
+// ❌ Bad: Direct shell execution with user input is dangerous
+// Never pass unvalidated user input to shell commands
+
+// ✅ Good: Use library APIs with validated input
+import sharp from 'sharp';
+if (!/^[a-zA-Z0-9_-]+$/.test(filename)) {
+  throw new Error('Invalid filename');
+}
+await sharp(`${filename}.png`).toFile('output.jpg');
+
+// ✅ Good: Use execFile with argument array (no shell)
+import { execFile } from 'child_process';
+execFile('convert', [validatedInput, 'output.jpg']);
+```
+
+### A10:2021 – Server-Side Request Forgery (SSRF)
+
+```typescript
+// ❌ Bad: Unvalidated URL from user input
+const response = await fetch(userProvidedUrl);
+
+// ✅ Good: Allowlist validation
+const ALLOWED_HOSTS = ['api.trusted.com', 'cdn.trusted.com'];
+const url = new URL(userProvidedUrl);
+if (!ALLOWED_HOSTS.includes(url.hostname)) {
+  throw new Error('URL not allowed');
+}
+// Also: Block internal IPs (127.0.0.1, 10.x.x.x, 192.168.x.x, etc.)
+```
+
+---
+
+## Authentication Deep Dive
+
+### Password Storage Explained
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Password Hashing Standards                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   ✅ Recommended Algorithms (in order):                         │
+│   1. Argon2id (winner of PHC, memory-hard)                     │
+│   2. bcrypt (cost factor ≥ 12)                                 │
+│   3. scrypt (N=2^17, r=8, p=1)                                 │
+│                                                                 │
+│   ❌ Never Use:                                                 │
+│   - MD5, SHA1, SHA256 (without salt/iteration)                 │
+│   - Plain text storage                                         │
+│   - Reversible encryption for passwords                        │
+│                                                                 │
+│   Configuration Example (Argon2id):                            │
+│   - Memory: 64 MB                                              │
+│   - Iterations: 3                                              │
+│   - Parallelism: 4                                             │
+│   - Salt: 16 bytes (random per password)                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**為何採用這些演算法？** 它們的設計目的就是要在計算上耗費高昂的成本，使得暴力破解攻擊變得不切實際。Argon2id 屬於 memory-hard（記憶體密集）演算法，意味著攻擊者難以利用 GPU 輕易地平行化攻擊。
+
+### JWT Best Practices
+
+```typescript
+// ✅ JWT Configuration
+const jwtConfig = {
+  algorithm: 'RS256',        // Use asymmetric for distributed systems
+  expiresIn: '15m',          // Short-lived access tokens
+  issuer: 'your-app.com',
+  audience: 'your-app.com',
+};
+
+// ✅ Validation checklist:
+// - Verify signature with correct algorithm
+// - Check exp, iat, nbf claims
+// - Validate iss and aud claims
+// - Use allowlist for algorithms (prevent "none" attack)
+
+// ❌ Never:
+// - Store sensitive data in JWT payload
+// - Use symmetric keys for multi-party systems
+// - Set expiresIn > 1 hour for access tokens
+```
+
+---
+
+## Authorization Patterns
+
+### RBAC Model Example
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    RBAC Model Example                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   Roles:                                                        │
+│   ├── admin        → All permissions                           │
+│   ├── manager      → Read, Write, Delete (own team)            │
+│   ├── editor       → Read, Write                               │
+│   └── viewer       → Read only                                 │
+│                                                                 │
+│   Permissions:                                                  │
+│   ├── resource:read                                            │
+│   ├── resource:write                                           │
+│   ├── resource:delete                                          │
+│   └── resource:admin                                           │
+│                                                                 │
+│   Assignment:                                                   │
+│   User → Role → Permissions                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### ABAC for Complex Policies
+
+當 RBAC 不足以應付需求時（複雜的政策）：
+
+```typescript
+// ABAC Policy Example
+const policy = {
+  effect: 'allow',
+  action: 'document:edit',
+  conditions: {
+    'user.department': { equals: 'resource.department' },
+    'user.clearanceLevel': { greaterThanOrEqual: 'resource.sensitivityLevel' },
+    'time.hour': { between: [9, 17] },
+  },
+};
+```
+
+---
+
+## Input Validation Strategies
+
+### Validation Layers
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Input Validation Layers                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   1. Client-side (UX only, not security)                        │
+│      └── Immediate feedback, reduce server load                 │
+│                                                                 │
+│   2. API Gateway / Edge                                         │
+│      └── Rate limiting, basic format validation                 │
+│                                                                 │
+│   3. Application Layer (PRIMARY)                                │
+│      ├── Type validation (schema validation)                   │
+│      ├── Business rule validation                              │
+│      └── Sanitization                                          │
+│                                                                 │
+│   4. Database Layer                                             │
+│      └── Constraints, triggers (last line of defense)          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**關鍵洞見**：用戶端驗證僅用於提升使用者體驗。所有安全驗證都必須在伺服器端進行。
+
+---
+
+## Cryptography Explained
+
+### Key Management Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Key Management Lifecycle                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   1. Generation                                                 │
+│      ├── Use cryptographically secure RNG                      │
+│      ├── Generate in secure environment (HSM, KMS)             │
+│      └── Never generate client-side                            │
+│                                                                 │
+│   2. Storage                                                    │
+│      ├── Use KMS (AWS KMS, HashiCorp Vault, Azure Key Vault)   │
+│      ├── Never store in code or version control                │
+│      └── Encrypt keys at rest with master key                  │
+│                                                                 │
+│   3. Distribution                                               │
+│      ├── Use secure channels only                              │
+│      └── Implement key wrapping                                │
+│                                                                 │
+│   4. Rotation                                                   │
+│      ├── Define rotation schedule (90 days typical)            │
+│      ├── Support graceful rotation (multiple active keys)      │
+│      └── Automate rotation where possible                      │
+│                                                                 │
+│   5. Revocation & Destruction                                   │
+│      ├── Immediate revocation on compromise                    │
+│      └── Secure deletion (memory wipe, crypto-shredding)       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Secure Coding Patterns
+
+### Error Handling
+
+```typescript
+// ❌ Bad: Exposes internal details
+catch (error) {
+  res.status(500).json({ error: error.message, stack: error.stack });
+}
+
+// ✅ Good: Generic message, log details internally
+catch (error) {
+  logger.error('Database error', { error, requestId: req.id });
+  res.status(500).json({
+    error: 'An internal error occurred',
+    requestId: req.id
+  });
+}
+```
+
+**為什麼？** 錯誤訊息可能洩漏以下資訊：
+- 資料庫結構（SQL 錯誤）
+- 檔案系統路徑（堆疊追蹤）
+- 函式庫版本（有助於鎖定已知漏洞發動攻擊）
+
+---
+
+## Security Testing Methods
+
+### CI/CD Security Integration
+
+```yaml
+# Example: GitHub Actions Security Pipeline
+name: Security Checks
+
+on: [push, pull_request]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Dependency vulnerability check
+      - name: npm audit
+        run: npm audit --audit-level=high
+
+      # SAST
+      - name: Run Semgrep
+        uses: returntocorp/semgrep-action@v1
+        with:
+          config: p/owasp-top-ten
+
+      # Secrets scanning
+      - name: GitLeaks
+        uses: gitleaks/gitleaks-action@v2
+
+      # Container scanning
+      - name: Trivy
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          severity: 'CRITICAL,HIGH'
+```
+
+---
+
+## Security Logging Best Practices
+
+### What to Log
+
+| 類別 | 事件 |
+|----------|--------|
+| **Authentication** | 登入成功／失敗、登出、MFA 事件 |
+| **Authorization** | 拒絕存取、權限提升嘗試 |
+| **Data Access** | 敏感資料存取、大量匯出 |
+| **Admin Actions** | 使用者建立、權限變更 |
+| **Security Events** | 輸入驗證失敗、觸及速率限制 |
+
+### Log Format
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "SECURITY",
+  "event_type": "authentication_failure",
+  "user_id": "usr_12345",
+  "ip_address": "203.0.113.50",
+  "user_agent": "Mozilla/5.0...",
+  "request_id": "req_abc123",
+  "details": {
+    "reason": "invalid_password",
+    "attempt_count": 3
+  }
+}
+```
+
+---
+
+## Incident Response Process
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                 Security Incident Response                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   1. IDENTIFY                                                   │
+│      ├── Detect and confirm the incident                       │
+│      ├── Determine scope and impact                            │
+│      └── Assign severity level                                 │
+│                                                                 │
+│   2. CONTAIN                                                    │
+│      ├── Isolate affected systems                              │
+│      ├── Preserve evidence                                     │
+│      └── Prevent further damage                                │
+│                                                                 │
+│   3. ERADICATE                                                  │
+│      ├── Remove threat actor access                            │
+│      ├── Patch vulnerabilities                                 │
+│      └── Reset compromised credentials                         │
+│                                                                 │
+│   4. RECOVER                                                    │
+│      ├── Restore systems from clean backups                    │
+│      ├── Verify system integrity                               │
+│      └── Monitor for reoccurrence                              │
+│                                                                 │
+│   5. LESSONS LEARNED                                            │
+│      ├── Document timeline and actions                         │
+│      ├── Identify root cause                                   │
+│      └── Update security controls                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## References
+
+### Standards
+- [OWASP Top 10 (2021)](https://owasp.org/Top10/)
+- [OWASP ASVS v4.0](https://owasp.org/www-project-application-security-verification-standard/)
+- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)
+- [NIST SP 800-53 Rev 5](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final)
+- [CWE/SANS Top 25](https://cwe.mitre.org/top25/)
+
+### Books
+- OWASP - "OWASP Testing Guide v4"
+- Adam Shostack - "Threat Modeling: Designing for Security" (2014)
+- Dafydd Stuttard - "The Web Application Hacker's Handbook" (2011)
+
+---
+
+## License
+
+本指南以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
+
+**來源**: [core/guides/security-guide.md](../../../../core/guides/security-guide.md)

package/bundled/locales/zh-TW/core/iac-design-principles.md

@@ -0,0 +1,90 @@
+---
+source: ../../../core/iac-design-principles.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: 6cf9c75621e0
+status: current
+---
+
+# 基礎設施即程式碼設計原則
+
+> **Language**: [English](../../../core/iac-design-principles.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/iac-design-principles.ai.yaml`
+> **規格**: XSPEC-065（cross-project/specs/XSPEC-065-uds-infrastructure-pack.md）
+
+## 概觀
+
+本標準定義基礎設施即程式碼（IaC）撰寫的四項基礎原則：**可重現、不可變、冪等、
+版本化**。涵蓋狀態管理要求（含鎖定的遠端狀態）、漂移偵測類別，以及 CI/CD 整合。
+設計目標為確保基礎設施變更可追溯、可逆，並可重複套用而無非預期副作用。
+
+本標準屬於 **IaC 標準包**（XSPEC-065），並作為 `container-image-standards` 與
+`secret-management-standards` 所立基的工具無關基礎（映像與機密後端本身即是版本化、
+可重現的基礎設施）。
+
+> **範圍**：本標準定義*撰寫原則*、*狀態管理*規則與*漂移處理分類*。特定 IaC 工具
+> （Terraform／Pulumi／CloudFormation）與後端屬採用者的選擇，不在本標準範圍內。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | IaC 四原則（可重現、不可變、冪等、版本化） | MUST |
+| REQ-002 | 狀態管理（遠端後端、鎖定、加密、VCS 不存本地狀態） | MUST |
+| REQ-003 | 漂移偵測（PR 上執行 plan；三類分類） | MUST |
+
+### REQ-001 — IaC 四原則
+
+所有基礎設施定義 MUST 遵循四項基礎原則：(1) **可重現**——在相同輸入與狀態下，套用
+IaC 產生相同的基礎設施；(2) **不可變**——基礎設施變更以取代資源的方式套用，而非
+就地變更；blue/green 或滾動取代模式優於就地變更；(3) **冪等**——多次套用相同 IaC
+設定產生相同結果，無錯誤或非預期副作用；(4) **版本化**——所有 IaC 定義儲存於版本
+控制並具備有意義的 commit message；不在 VCS 流程外進行任何基礎設施變更。
+
+### REQ-002 — 狀態管理
+
+IaC 狀態 MUST 儲存於啟用鎖定的遠端後端，以防止並行修改。本地狀態檔 MUST NOT 提交
+至版本控制或用於 CI/CD 管線。建議後端：Terraform Cloud／S3+DynamoDB（Terraform）、
+Pulumi Service／S3（Pulumi）、CloudFormation 原生 stack 狀態。狀態存取 MUST 透過 IAM
+或同等機制限制為獲授權主體。狀態靜態加密為 REQUIRED。
+
+### REQ-003 — 漂移偵測
+
+團隊 MUST 在每個 pull request 於 CI 執行 `plan`（或同等）以偵測設定漂移。漂移結果
+MUST 分類為三類之一並據以處理：(1) **rollback-to-code**——實際基礎設施因手動變更而
+偏離程式碼；於下次 apply 將實際還原以符合程式碼；(2) **update-code-from-actual**——
+實際反映尚未編碼的有意變更；更新 IaC 以符合，然後 apply；(3) **manual-reconcile**——
+漂移需人為判斷（例如資料 volume 變更）；以文件化決策上呈基礎設施負責人。漂移報告
+SHOULD 依排定節奏（例如每日）發布至團隊頻道。
+
+## 反模式
+
+- 將本地狀態檔（`terraform.tfstate`）提交至版本控制。
+- 套用可變的就地變更（例如以 sed patch 執行中的 VM）而非取代資源。
+- 進行手動 console 變更而未更新對應的 IaC 定義。
+- 不使用遠端鎖定，允許並行 apply 而損毀狀態。
+- pin 至 `latest` provider 或 module 版本，破壞可重現性。
+
+## 與既有標準的整合
+
+- **`container-image-standards`**——容器映像是依相同原則產生的版本化、可重現產物。
+- **`secret-management-standards`**——機密後端（Vault／KMS）作為具遠端狀態、受存取
+  控制的基礎設施管理。
+- **`deployment-standards` / `cd-deployment-strategies`**——不可變取代（REQ-001）
+  支撐 blue/green 與滾動部署模式。
+- **`no-cicd-deployment`**——即使無 CI/CD 平台，四原則與狀態管理規則仍適用於腳本化
+  的基礎設施變更。
+
+## 相關規格
+
+- XSPEC-065 — UDS 基礎設施（IaC）標準包（本標準來源）
+- DEC-043 — UDS 覆蓋完整性路線圖（Wave 4 範圍）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~003：IaC 四原則、狀態管理、漂移偵測（XSPEC-065） |