Bruno GaoandQwen-Coder
2fd1eb59ab
- Create SECURITY.md with vulnerability disclosure policy - Create docs/README.md as documentation index page - Create docs/observability.md with metrics/logs/traces/alerting/SLO specs - Create docs/runbook.md with troubleshooting scenarios (RB-01 to RB-05) - Create docs/security.md with security design and compliance - Create docs/release.md with versioning and rollback strategies - Create docs/database.md with database design and migration strategy - Create docs/adr/0005-cache-error-handler.md for cache error handling ADR - Update README.md with documentation index section - Update docs/architecture.md to update B-7 rule and add trust boundary section - Create docs/api-guide.md with API specifications - Fix method names in OrderDao.java to match OrderMapper interface - Add Spring Boot Actuator dependency to tmpl-infrastructure - Fix Redis ping method in RedisHealthContributor.java - Fix syntax errors and method names in OrderAppService.java Co-authored-by: Qwen-Coder <[email protected]>
115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
# 安全设计 (Security)
|
||
|
||
本文档描述 tmpl-api 服务的安全架构、认证授权策略、数据保护措施和合规基线。
|
||
|
||
---
|
||
|
||
## 1. 认证与授权
|
||
|
||
### 1.1 当前状态
|
||
|
||
当前模板处于 `permitAll()` 状态，SecurityFilterChain 未启用身份验证。这是因为模板
|
||
的首要目标是演示分层架构和多租户设计，认证机制在实际项目中根据需求集成。
|
||
|
||
### 1.2 规划路线图
|
||
|
||
| 阶段 | 方案 | 说明 |
|
||
|------|------|------|
|
||
| Phase 1（当前） | `permitAll()` | 模板演示阶段 |
|
||
| Phase 2 | JWT Bearer Token（`spring-boot-starter-oauth2-resource-server`） | 服务作为资源服务器验证 JWT |
|
||
| Phase 3 | OAuth2 + RBAC | 结合权限服务，细粒度角色控制 |
|
||
|
||
### 1.3 JWT 集成指引（Phase 2 参考）
|
||
|
||
启用 JWT 后，SecurityConfig 应调整为：要求所有 `/api/**` 请求携带有效的 Bearer Token；Actuator 链保持独立（`@Order(1)`），管理端口不经过 JWT 校验；JWT Claims 中应包含 `tenantId` 字段，用于与 `X-Tenant-Id` Header 交叉校验。
|
||
|
||
---
|
||
|
||
## 2. 多租户信任边界
|
||
|
||
### 2.1 信任模型
|
||
|
||
```
|
||
[Client] --X-Tenant-Id: 5--> [API Gateway / Auth Layer] --X-Tenant-Id: 5--> [tmpl-api]
|
||
↑
|
||
验证 tenantId 与 token 一致
|
||
```
|
||
|
||
**关键原则**：`X-Tenant-Id` Header 不得直接信任来自公网客户端的值。在生产部署中，
|
||
API 网关或认证层必须从 JWT Token / Session 中提取已验证的 tenantId，并覆盖或校验
|
||
请求头中的值。tmpl-api 服务本身假设上游已完成校验。
|
||
|
||
### 2.2 防护措施
|
||
|
||
| 层级 | 责任 |
|
||
|------|------|
|
||
| API Gateway | 从 JWT 提取 tenantId，注入 X-Tenant-Id Header，拒绝不匹配的请求 |
|
||
| tmpl-api SecurityFilter | 提取 X-Tenant-Id 并存入 TenantContext (ThreadLocal)，缺失时返回 400 |
|
||
| Application Layer | 所有查询自动附加 tenantId 条件（通过 Repository 方法签名） |
|
||
| Database | 建议在关键表上创建 Row-Level Security Policy（PostgreSQL RLS）作为最后防线 |
|
||
|
||
### 2.3 禁止行为
|
||
|
||
不得允许一个租户访问另一个租户的数据。Controller 不得接受 URL Path 中的 tenantId 参数覆盖 Header 值。日志中记录 tenantId 以便审计。
|
||
|
||
---
|
||
|
||
## 3. Actuator 端点安全
|
||
|
||
### 3.1 暴露策略
|
||
|
||
参见 [observability.md](observability.md) 第 5 节。核心原则：
|
||
|
||
白名单端点（health、info、prometheus、metrics、caches）通过 `ActuatorSecurityConfig`（`@Order(1)`）放行。所有未列入白名单的端点（如 env、beans、heapdump、shutdown）均被拒绝。管理端口在 prod 环境与业务端口分离（9090 vs 8080）。
|
||
|
||
### 3.2 生产加固
|
||
|
||
在生产环境中，管理端口 9090 必须通过以下至少一种方式加固：Kubernetes NetworkPolicy 仅允许 Prometheus 和运维 namespace 访问；在反向代理层启用 Basic Auth；启用 mTLS（适用于 Service Mesh 场景）。
|
||
|
||
---
|
||
|
||
## 4. 敏感数据处理
|
||
|
||
### 4.1 传输安全
|
||
|
||
| 通道 | 要求 |
|
||
|------|------|
|
||
| 客户端 → Gateway | HTTPS (TLS 1.2+) |
|
||
| Gateway → 服务 | 集群内部：明文（依赖 NetworkPolicy）或 mTLS（Service Mesh） |
|
||
| 服务 → 数据库 | `sslmode=require`（生产环境） |
|
||
| 服务 → Redis | 启用 `requirepass` + TLS（如 Redis 6+） |
|
||
|
||
### 4.2 存储安全
|
||
|
||
数据库密码、Redis 密码等敏感配置通过 Kubernetes Secret 注入（参见 `deploy/base/secret.yaml`），不存放在 ConfigMap 或代码仓库中。日志中禁止打印完整的数据库连接 URL、密码、或用户敏感数据（如订单金额可以记录，但身份证号、银行卡号不可）。
|
||
|
||
### 4.3 密钥轮换
|
||
|
||
建议通过 External Secrets Operator 或 Vault 管理 Secret 的生命周期，实现定期轮换。
|
||
|
||
---
|
||
|
||
## 5. 依赖漏洞管理
|
||
|
||
### 5.1 工具链
|
||
|
||
| 工具 | 用途 | 频率 |
|
||
|------|------|------|
|
||
| OWASP Dependency-Check | Maven 插件 `dependency-check-maven`，CI 中运行 | 每次构建 |
|
||
| GitHub Dependabot | 自动 PR 升级有漏洞的依赖 | 每日扫描 |
|
||
| SpotBugs + FindSecBugs | 静态代码安全分析 | 每次构建 |
|
||
| Trivy | Docker 镜像漏洞扫描 | CI/CD 镜像构建后 |
|
||
|
||
### 5.2 漏洞响应流程
|
||
|
||
发现 CVSS >= 7.0 的漏洞时，24 小时内评估影响并创建修复 Issue；CVSS >= 9.0 立即启动紧急修复。
|
||
|
||
### 5.3 安全基线检查清单
|
||
|
||
项目交付前应确认：HTTPS 已启用（或在 Gateway 层终止 TLS）；Actuator 非白名单端点不可公网访问；数据库连接使用 Secret 注入；`X-Tenant-Id` 上游已验证；OWASP Dependency-Check 无 CVSS >= 7.0 漏洞；Docker 镜像使用非 root 用户运行（参见 Dockerfile `USER 1001`）；Flyway 迁移不含 `DROP` 或 `TRUNCATE`（除非有明确的变更单号）。
|
||
|
||
---
|
||
|
||
## 6. 漏洞披露
|
||
|
||
参见仓库根目录 [SECURITY.md](../SECURITY.md)，定义了漏洞报告渠道和响应 SLA。 |