---
name: springboot-security
description: Spring Boot 安全性最佳實踐，涵蓋身份驗證/授權、輸入驗證、CSRF、秘密資訊管理、安全性標頭、速率限制及依賴項安全性。
---

# Spring Boot 安全性審核 (Spring Boot Security Review)

在添加驗證、處理輸入、建立端點或處理秘密資訊時，請遵循本技能。

## 何時啟用

- 實作身份驗證（JWT、OAuth2、Session）。
- 實作授權（使用 `@PreAuthorize` 或基於角色的存取控制 RBAC）。
- 驗證使用者輸入（Bean Validation）。
- 配置 CORS、CSRF 與安全標頭 (Security Headers)。
- 管理秘密資訊（Secrets 管理）。
- 實作速率限制（Rate Limiting）與防止暴力破解。
- 掃描依賴項中的 CVE 漏洞。

## 身份驗證與授權

### 身份驗證 (Authentication)
- 優先使用無狀態的 **JWT** 或帶有撤銷清單的 **Opaque Tokens**。
- 對於 Session 應使用 `httpOnly`, `Secure`, `SameSite=Strict` 的 Cookies。
- 透過 `OncePerRequestFilter` 驗證權杖。

### 授權 (Authorization)
- 開啟方法級別安全性：`@EnableMethodSecurity`。
- 使用 `@PreAuthorize("hasRole('ADMIN')")` 進行權限控管。
- **預設拒絕**：僅開放必要的 Scopes。

## 輸入驗證與防止注入

### 輸入驗證
- 在 Controller 使用 Bean Validation 標註 `@Valid`。
- 在 DTO 上定義約束條件：`@NotBlank`, `@Email`, `@Size`。
- **防止 XSS**：渲染前清理任何 HTML 內容。

### SQL 注入防範
- 使用 Spring Data JPA Repository。
- 原生查詢務必使用 `:param` 綁定，**嚴禁**字串拼接。

## 密碼安全性

- 務必使用 **BCrypt** 或 **Argon2** 對密碼進行雜湊處理，絕不儲存明文。
- 使用 `PasswordEncoder` 實例進行處理。

## 其他防禦機制

- **CSRF 護衛**：對於純 API (Bearer Token) 可停用 CSRF；對於具備 Browser Session 的應用則必須啟用並處理 Token 傳輸。
- **秘密資訊管理**：金鑰/帳密嚴禁寫死在代碼或 `application.yml` 中，應透過環境變數或 Vault 載入。
- **安全性標頭**：配置 CSP, Frame-Options, XSS Protection 等標頭。
- **CORS 配置**：在安全過濾器層級配置，並嚴格限制 `allowedOrigins`，**生產環境不得使用 `*`**。
- **依賴項安全**：定期運行 `npm audit` 或 OWASP 工具，並在 CI 流程中攔截已知 CVE 的佈署。

## 釋出前安全性檢查清單

- [ ] 權杖 (Token) 是否有正確驗證與過期機制？
- [ ] 所有敏感路徑是否均有授與檢查 (Authorization Guards)？
- [ ] 是否所有輸入內容都經過驗證與清理？
- [ ] 查詢是否排除字串拼接 SQL？
- [ ] 是否已將秘密資訊移至外部配置（並確認沒被提交到 Git）？
- [ ] 已正確配置安全標頭、CORS 與速率限制。
- [ ] 紀錄檔中是否確保無洩露任何敏感個資 (PII)？

---

**核心原則**：預設拒絕、全面驗證、最小權限原則，並優先透過框架配置實現安全性。