niuniu/lijiaoqiao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb3c503152efcdcb351864f538de5d1e57c981a2
lijiaoqiao/docs/compliance_capability_package_design_v1_2026-04-02.md

972 lines
34 KiB
Markdown
Raw Normal View History

feat(P1/P2): 完成TDD开发及P1/P2设计文档 ## 设计文档 - multi_role_permission_design: 多角色权限设计 (CONDITIONAL GO) - audit_log_enhancement_design: 审计日志增强 (CONDITIONAL GO) - routing_strategy_template_design: 路由策略模板 (CONDITIONAL GO) - sso_saml_technical_research: SSO/SAML调研 (CONDITIONAL GO) - compliance_capability_package_design: 合规能力包设计 (CONDITIONAL GO) ## TDD开发成果 - IAM模块: supply-api/internal/iam/ (111个测试) - 审计日志模块: supply-api/internal/audit/ (40+测试) - 路由策略模块: gateway/internal/router/ (33+测试) - 合规能力包: gateway/internal/compliance/ + scripts/ci/compliance/ ## 规范文档 - parallel_agent_output_quality_standards: 并行Agent产出质量规范 - project_experience_summary: 项目经验总结 (v2) - 2026-04-02-p1-p2-tdd-execution-plan: TDD执行计划 ## 评审报告 - 5个CONDITIONAL GO设计文档评审报告 - fix_verification_report: 修复验证报告 - full_verification_report: 全面质量验证报告 - tdd_module_quality_verification: TDD模块质量验证 - tdd_execution_summary: TDD执行总结 依据: Superpowers执行框架 + TDD规范
2026-04-02 23:35:53 +08:00
# P2 合规能力包详细设计
> 本文档为 P2 阶段合规能力包的增强设计，基于 `tos_compliance_engine_design_v1_2026-03-18.md` 的 S4 合规引擎架构，扩展以满足 M-013~M-017 指标的自动化合规检查与报告需求。
---
## 1. 概述与背景
### 1.1 目的
P2 合规能力包旨在扩展现有 ToS 合规引擎的能力，实现：
1. **合规规则库扩展**：支持 M-013~M-016 指标的规则化定义与执行
2. **自动化合规检查**：将合规检查嵌入 CI/CD 流水线，实时检测违规事件
3. **合规报告生成**：自动生成符合 M-017 要求的依赖兼容审计四件套报告
### 1.2 指标映射
| 指标ID | 指标名称 | 目标值 | 阻断阈值 | P2 能力要求 |
|--------|----------|--------|----------|-------------|
| M-013 | supplier_credential_exposure_events | 0 | >0 即 P0 | 凭证泄露检测规则 + 实时告警 |
| M-014 | platform_credential_ingress_coverage_pct | 100% | <100% 即阻断 | 入站凭证校验 + 覆盖率统计 |
| M-015 | direct_supplier_call_by_consumer_events | 0 | >0 即 P0 | 直连检测规则 + 阻断机制 |
| M-016 | query_key_external_reject_rate_pct | 100% | <100% 即阻断 | 外部 query key 拒绝规则 |
| M-017 | dependency_compatibility_audit | PASS | FAIL 即阻断 | SBOM + 锁文件 diff + 兼容矩阵 + 风险登记册 |
### 1.3 与现有设计的关系
```
tos_compliance_engine_design_v1_2026-03-18.md (S4 设计)
│
▼
┌─────────────────────────────────────────────┐
│ P2 合规能力包扩展 │
├─────────────────────────────────────────────┤
│ 1. 合规规则库扩展（M-013~M-016 指标规则化） │
│ 2. 自动化合规检查（CI 流水线集成） │
│ 3. 合规报告生成（M-017 四件套） │
└─────────────────────────────────────────────┘
```
---
## 2. 合规规则库扩展
### 2.1 M-013 凭证泄露检测规则
#### 2.1.1 规则定义
> **重要**：所有事件命名遵循 `audit_log_enhancement_design_v1_2026-04-02.md` 规范，格式为 `{Category}-{SubCategory}[-{Detail}]`，以确保与审计日志系统兼容。
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-EXPOSE-RESPONSE | 响应包含 `sk-`、`ak-`、`api_key` 等可复用凭证片段 | block + alert | P0 |
| R02 | CRED-EXPOSE-LOG | 日志输出包含完整凭证格式 | block + alert | P0 |
| R03 | CRED-EXPOSE-EXPORT | 导出功能返回可还原凭证 | block + alert | P0 |
| R04 | CRED-EXPOSE-WEBHOOK | 回调请求携带供应商凭证 | block + alert | P0 |
> **注**：原 `C013-R01~R04` 格式已废弃，统一使用 `CRED-EXPOSE-*` 格式与审计日志对齐。
#### 2.1.2 规则配置示例
```yaml
# compliance/rules/m013_credential_exposure.yaml
rules:
- id: "CRED-EXPOSE-RESPONSE"
name: "响应体凭证泄露检测"
description: "检测 API 响应中是否包含可复用的供应商凭证片段"
severity: "P0"
matchers:
- type: "regex_match"
pattern: "(sk-|ak-|api_key|secret|token).*[a-zA-Z0-9]{20,}"
target: "response_body"
scope: "all"
action:
primary: "block"
secondary: "alert"
notification:
channels: ["slack", "email"]
template: "credential_exposure_alert"
audit:
log_level: "critical"
retention_days: 1825 # 5年
# 审计日志事件名称（与 audit_log_enhancement_design_v1_2026-04-02.md 对齐）
event_name: "CRED-EXPOSE-RESPONSE"
event_category: "CRED"
event_sub_category: "EXPOSE"
```
#### 2.1.3 检测算法
```
凭证泄露检测算法 (CRED-EXPOSE-D01)
输入: HTTP 响应体内容
输出: 泄露检测结果 {is_leaked: bool, matches: []Match}
步骤:
1. 预编译凭证正则模式库
2. 对响应体进行多模式并行匹配
3. 过滤误报 (测试数据、示例数据)
4. 若匹配, 提取匹配片段并脱敏后记录审计日志
- 审计事件名称: CRED-EXPOSE-RESPONSE
- 事件分类: CRED
- 事件子分类: EXPOSE
5. 触发阻断或告警流程
```
### 2.2 M-014 入站凭证覆盖率规则
#### 2.2.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-INGRESS-PLATFORM | 请求头不包含 `Authorization: Bearer ptk_*` | block + alert | P0 |
| R02 | CRED-INGRESS-FORMAT | 平台凭证格式不符合规范 | block + alert | P1 |
| R03 | CRED-INGRESS-EXPIRED | 平台凭证已过期或被吊销 | block | P0 |
> **注**：原 `C014-R01~R03` 格式已废弃，统一使用 `CRED-INGRESS-*` 格式与审计日志对齐。
#### 2.2.2 覆盖率统计
```yaml
# compliance/rules/m014_ingress_coverage.yaml
coverage_tracking:
metric: "platform_credential_ingress_coverage_pct"
calculation: "(使用有效平台凭证的请求数 / 总请求数) * 100"
target: 100
blocking_threshold: 100
window: "rolling_1h"
aggregation: "percentile"
```
### 2.3 M-015 直连检测规则
#### 2.3.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-DIRECT-SUPPLIER | 请求目标为已知供应商 IP/域名 | block + alert | P0 |
| R02 | CRED-DIRECT-API | 请求路径匹配 `*/v1/chat/completions` 等上游端点 | block | P0 |
| R03 | CRED-DIRECT-UNAUTH | 调用未经审批的供应商 | block + alert | P0 |
> **注**：原 `C015-R01~R03` 格式已废弃，统一使用 `CRED-DIRECT-*` 格式与审计日志对齐。
#### 2.3.2 检测方法
M-015 直连检测通过以下多层检测机制实现：
| 检测方法 | 描述 | 检测点 |
|----------|------|--------|
| **蜜罐检测** | 在 API Gateway 层部署蜜罐端点，检测是否有直接访问上游 API 的请求 | API Gateway |
| **网络流量分析** | 监控出站连接，识别绕过平台代理的直接连接 | 出网防火墙 |
| **API 日志分析** | 分析请求日志，检测异常的上游 API 调用模式 | 审计中间件 |
| **DNS 解析监控** | 监控 DNS 解析，检测是否有应用直接解析供应商域名 | 网络层 |
| **代理层检测** | 检查请求是否经过平台代理层，未经过则标记为直连 | 负载均衡器 |
> **检测流程**：蜜罐触发 -> 网络流量分析 -> API 日志复核 -> 确认直连事件
#### 2.3.2 供应商白名单配置
```yaml
# compliance/config/allowed_suppliers.yaml
allowed_suppliers:
direct_access:
# 禁止直连，全部通过平台代理
enabled: false
approved_providers:
- name: "openai"
base_urls:
- "api.openai.com"
- "api.openai.azure.com"
requires_approval: true
- name: "anthropic"
base_urls:
- "api.anthropic.com"
requires_approval: true
- name: "minimax"
base_urls:
- "api.minimax.chat"
requires_approval: false
```
### 2.4 M-016 外部 Query Key 拒绝规则
#### 2.4.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | AUTH-QUERY-KEY | 来自外部的 query key 请求进入平台北向入口 | reject (403) | P0 |
| R02 | AUTH-QUERY-INJECT | 请求参数包含 `key=`、`api_key=`、`token=` 等外部 key | reject (403) | P0 |
| R03 | AUTH-QUERY-AUDIT | 内部处理 query key 时记录全量审计 | alert | P1 |
> **注**：原 `C016-R01~R03` 格式已废弃，统一使用 `AUTH-QUERY-*` 格式与审计日志对齐。
#### 2.4.2 拒绝模式配置
```yaml
# compliance/rules/m016_query_key_reject.yaml
query_key_rejection:
enabled: true
default_action: "reject"
patterns:
# 拒绝所有包含以下模式的外部请求
reject_patterns:
- "key=.*"
- "api_key=.*"
- "token=.*"
- "bearer=.*"
- "authorization=.*"
# 允许内部白名单模式
allow_patterns:
- "^internal-.*"
- "^platform-.*"
response:
status_code: 403
message: "External query keys are not allowed"
include_request_id: true
```
---
## 3. 自动化合规检查
### 3.1 架构设计
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 自动化合规检查系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ 合规规则引擎 │───▶│ 实时检测器 │───▶│ 告警发送器 │ │
│ │ (Rule Engine) │ │ (Real-time) │ │ (Notifier) │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 合规指标存储层 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ M-013 │ │ M-014 │ │ M-015 │ │ M-016 │ │ │
│ │ │ 泄露事件 │ │ 入站覆盖 │ │ 直连事件 │ │ 拒绝率 │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CI/CD 流水线集成 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ Pre-Commit │ │ Build │ │ Deploy │ │ Monitor │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 3.2 规则执行引擎
#### 3.2.1 核心组件
| 组件 | 职责 | 性能要求 |
|------|------|----------|
| **规则编译器** | 将 YAML 规则编译为可执行格式 | 启动时编译，不影响运行时 |
| **规则匹配器** | 根据请求上下文匹配适用规则 | P95 < 2ms |
| **策略执行器** | 执行 block/alert/reject 动作 | P95 < 1ms |
| **审计记录器** | 记录所有合规决策 | 异步，不阻塞主流程 |
#### 3.2.2 规则执行流程
```
规则执行流程 (CMP-FLOW-01)
1. 请求进入合规检查拦截点
│
▼
2. 提取请求上下文
- 请求头 (Authorization, X-Request-Id)
- 请求路径
- 请求参数
- 源 IP
│
▼
3. 并行匹配所有启用规则
│
▼
4. 聚合匹配结果
- 若存在 P0 匹配 → 立即阻断
- 若存在 P1 匹配 → 告警 + 继续
- 若仅 P2/P3 匹配 → 记录但不阻断
│
▼
5. 执行动作
- block: 返回错误响应
- alert: 发送告警通知
- reject: 返回 403
│
▼
6. 记录审计日志
- 规则 ID
- 匹配结果
- 执行动作
- 时间戳
```
### 3.3 CI/CD 流水线集成
#### 3.3.1 集成点
| 阶段 | 检查项 | 阻断条件 | 超时时间 |
|------|--------|----------|----------|
| **Pre-Commit** | 本地凭证泄露扫描 | M-013 > 0 | 30s |
| **Build** | 依赖兼容审计 (M-017) | 四件套任一 FAIL | 120s |
| **Deploy-Staging** | M-013~M-016 实时检测 | 任一 P0 | N/A (实时) |
| **Deploy-Production** | M-013~M-016 实时检测 | 任一 P0 | N/A (实时) |
| **Monitor** | 7x24 指标监控 | 阈值突破 | N/A |
#### 3.3.2 CI 脚本集成
```bash
# compliance/ci/compliance_gate.sh
#!/bin/bash
# 合规门禁 CI 脚本
set -e
# 使用环境变量或相对路径，避免硬编码
COMPLIANCE_BASE="${COMPLIANCE_BASE:-$(cd "$(dirname "$0")/.." && pwd)}"
RULES_DIR="${COMPLIANCE_BASE}/rules"
REPORTS_DIR="${COMPLIANCE_BASE}/reports"
# M-013: 凭证泄露扫描
echo "[COMPLIANCE] Running M-013 credential exposure scan..."
if ! bash "${COMPLIANCE_BASE}/ci/m013_credential_scan.sh"; then
echo "[COMPLIANCE] M-013 FAILED: Credential exposure detected"
exit 1
fi
# M-014: 入站覆盖率检查
echo "[COMPLIANCE] Running M-014 ingress coverage check..."
if ! bash "${COMPLIANCE_BASE}/ci/m014_ingress_coverage.sh"; then
echo "[COMPLIANCE] M-014 FAILED: Ingress coverage below 100%"
exit 1
fi
# M-015: 直连检测
echo "[COMPLIANCE] Running M-015 direct access check..."
if ! bash "${COMPLIANCE_BASE}/ci/m015_direct_access_check.sh"; then
echo "[COMPLIANCE] M-015 FAILED: Direct supplier access detected"
exit 1
fi
# M-016: Query Key 拒绝率
echo "[COMPLIANCE] Running M-016 query key rejection check..."
if ! bash "${COMPLIANCE_BASE}/ci/m016_query_key_reject.sh"; then
echo "[COMPLIANCE] M-016 FAILED: Query key rejection rate below 100%"
exit 1
fi
# M-017: 依赖兼容审计
echo "[COMPLIANCE] Running M-017 dependency audit..."
if ! bash "${COMPLIANCE_BASE}/ci/m017_dependency_audit.sh"; then
echo "[COMPLIANCE] M-017 FAILED: Dependency compatibility issue"
exit 1
fi
echo "[COMPLIANCE] All checks PASSED"
```
> **注意**：以下 CI 脚本处于**待实现**状态，依赖于 `compliance/` 目录的创建：
> - `m013_credential_scan.sh` - 待实现
> - `m014_ingress_coverage.sh` - 待实现
> - `m015_direct_access_check.sh` - 待实现
> - `m016_query_key_reject.sh` - 待实现
> - `m017_dependency_audit.sh` - 待实现
### 3.4 实时监控
#### 3.4.1 监控指标
| 指标 | 描述 | 告警阈值 |
|------|------|----------|
| m013_exposure_events_total | 凭证泄露事件总数 | > 0 |
| m014_ingress_coverage_pct | 入站凭证覆盖率 | < 100 |
| m015_direct_access_events_total | 直连事件总数 | > 0 |
| m016_query_key_reject_rate_pct | query key 拒绝率 | < 100 |
| compliance_rules_triggered_total | 规则触发总数 | N/A |
#### 3.4.2 告警规则
```yaml
# compliance/monitoring/alerts.yaml
alerts:
- name: "m013_credential_exposure_p0"
condition: "m013_exposure_events_total > 0"
severity: "P0"
channels: ["slack_critical", "pagerduty", "email"]
message: "P0: Credential exposure event detected"
- name: "m014_ingress_coverage_degraded"
condition: "m014_ingress_coverage_pct < 100"
severity: "P0"
channels: ["slack_critical", "pagerduty"]
message: "P0: Platform credential ingress coverage below 100%"
- name: "m015_direct_access_detected"
condition: "m015_direct_access_events_total > 0"
severity: "P0"
channels: ["slack_critical", "pagerduty", "email"]
message: "P0: Direct supplier access detected"
- name: "m016_reject_rate_degraded"
condition: "m016_query_key_reject_rate_pct < 100"
severity: "P1"
channels: ["slack", "email"]
message: "P1: Query key rejection rate below 100%"
```
---
## 4. 合规报告生成
### 4.1 M-017 依赖兼容审计四件套
根据 `supply_gate_command_playbook_v1_2026-03-25.md` 第7章要求，M-017 需生成以下四件套：
| 报告 | 文件名模式 | 内容要求 |
|------|------------|----------|
| **SBOM** | `sbom_{date}.spdx.json` | 软件物料清单，SPDX 2.3 格式 |
| **锁文件 Diff** | `lockfile_diff_{date}.md` | 依赖版本变更对比 |
| **兼容矩阵** | `compat_matrix_{date}.md` | 组件版本兼容性矩阵 |
| **风险登记册** | `risk_register_{date}.md` | 发现的安全与合规风险 |
### 4.2 四件套生成流程
```
依赖兼容审计流程 (M017-FLOW-01)
1. 执行时间: 每日 00:00 UTC (CI Build 阶段自动触发)
│
▼
2. SBOM 生成
- 使用 syft/spdx-syft 生成项目 SPDX 2.3 SBOM
- 覆盖语言: Go (go.mod), Node (package.json), Python (requirements.txt)
│
▼
3. 锁文件 Diff 生成
- 对比当前 lock 文件与 baseline
- 提取新增/升级/降级/删除依赖
- 变更影响评估
│
▼
4. 兼容矩阵生成
- 读取兼容矩阵模板
- 填充当前版本信息
- 标注已知不兼容项
│
▼
5. 风险登记册生成
- 汇总 CVSS >= 7.0 的漏洞
- 汇总许可证合规风险
- 汇总过期依赖风险
│
▼
6. 报告输出
- 生成日期标注的报告文件
- 更新趋势数据库
- 发送摘要邮件
```
### 4.3 四件套详细规格
#### 4.3.1 SBOM (软件物料清单)
```json
{
"spdxVersion": "SPDX-2.3",
"dataLicense": "CC0-1.0",
"SPDXID": "SPDXRef-DOCUMENT",
"name": "llm-gateway",
"documentNamespace": "https://llm-gateway.example.com/spdx/2026-04-02",
"creationInfo": {
"created": "2026-04-02T00:00:00Z",
"creators": ["Tool: syft-0.100.0"]
},
"packages": [
{
"SPDXID": "SPDXRef-Package-go-github-com-openai",
"name": "github.com/openai/openai-go",
"versionInfo": "v0.2.0",
"supplier": "Organization: OpenAI",
"downloadLocation": "https://github.com/openai/openai-go",
"licenseConcluded": "Apache-2.0"
}
]
}
```
#### 4.3.2 锁文件 Diff
```markdown
# Lockfile Diff Report - 2026-04-02
## Summary
| 变更类型 | 数量 |
|----------|------|
| 新增依赖 | 3 |
| 升级依赖 | 7 |
| 降级依赖 | 0 |
| 删除依赖 | 1 |
## New Dependencies
| 名称 | 版本 | 用途 | 风险评估 |
|------|------|------|----------|
| github.com/acme/newpkg | v1.2.0 | 新功能 | LOW |
## Upgraded Dependencies
| 名称 | 旧版本 | 新版本 | 风险评估 |
|------|--------|--------|----------|
| github.com/acme/existing | v1.0.0 | v1.1.0 | LOW |
## Deleted Dependencies
| 名称 | 旧版本 | 原因 |
|------|--------|------|
| github.com/acme/unused | v0.9.0 | 功能下线 |
## Breaking Changes
None detected.
```
#### 4.3.3 兼容矩阵
```markdown
# Dependency Compatibility Matrix - 2026-04-02
## Go Dependencies
| 组件 | 版本 | Go 1.21 | Go 1.22 | Go 1.23 |
|------|------|----------|----------|----------|
| github.com/acme/pkg | v1.2.0 | PASS | PASS | PASS |
## Known Incompatibilities
None detected.
```
#### 4.3.4 风险登记册
```markdown
# Risk Register - 2026-04-02
## Summary
| 风险级别 | 数量 |
|----------|------|
| CRITICAL | 0 |
| HIGH | 1 |
| MEDIUM | 2 |
| LOW | 5 |
## High Risk Items
| ID | 描述 | CVSS | 组件 | 修复建议 |
|----|------|------|------|----------|
| RISK-001 | CVE-2024-XXXXX | 8.1 | github.com/acme/vuln-pkg | 升级到 v1.3.0 |
## Medium Risk Items
| ID | 描述 | CVSS | 组件 | 修复建议 |
|----|------|------|------|----------|
| RISK-002 | License: GPL-3.0 conflict | N/A | github.com/acme/gpl-pkg | 评估许可证合规 |
## Mitigation Status
| ID | 状态 | 负责人 | 截止日期 |
|----|------|--------|----------|
| RISK-001 | IN_PROGRESS | @security | 2026-04-05 |
```
### 4.4 自动化报告生成脚本
```bash
#!/bin/bash
# compliance/reports/m017_dependency_audit.sh
#!/usr/bin/env bash
set -e
REPORT_DATE="${1:-$(date +%Y-%m-%d)}"
# 使用环境变量或相对路径，避免硬编码
REPORT_DIR="${COMPLIANCE_REPORT_DIR:-${PROJECT_ROOT}/reports/dependency}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
mkdir -p "${REPORT_DIR}"
echo "[M017] Starting dependency audit for ${REPORT_DATE}"
# 1. Generate SBOM
echo "[M017] Generating SBOM..."
if command -v syft >/dev/null 2>&1; then
syft "${PROJECT_ROOT}" -o spdx-json > "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json"
# 验证 SBOM 包含有效包
if ! grep -q '"packages"' "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json" || \
[ "$(grep -c '"SPDXRef' "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json" || echo 0)" -eq 0 ]; then
echo "[M017] FAIL: syft generated invalid SBOM (no packages found)"
exit 1
fi
echo "[M017] SBOM generated successfully with syft"
else
echo "[M017] ERROR: syft is required but not found. Please install syft first."
echo "[M017] See: https://github.com/anchore/syft#installation"
exit 1
fi
# 2. Generate Lockfile Diff
echo "[M017] Generating lockfile diff..."
LOCKFILE_DIFF_SCRIPT="${PROJECT_ROOT}/scripts/ci/lockfile_diff.sh"
if [ -x "$LOCKFILE_DIFF_SCRIPT" ]; then
bash "$LOCKFILE_DIFF_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/lockfile_diff_${REPORT_DATE}.md"
else
echo "[M017] ERROR: lockfile_diff.sh not found or not executable at $LOCKFILE_DIFF_SCRIPT"
exit 1
fi
# 3. Generate Compatibility Matrix
echo "[M017] Generating compatibility matrix..."
COMPAT_MATRIX_SCRIPT="${PROJECT_ROOT}/scripts/ci/compat_matrix.sh"
if [ -x "$COMPAT_MATRIX_SCRIPT" ]; then
bash "$COMPAT_MATRIX_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/compat_matrix_${REPORT_DATE}.md"
else
echo "[M017] ERROR: compat_matrix.sh not found or not executable at $COMPAT_MATRIX_SCRIPT"
exit 1
fi
# 4. Generate Risk Register
echo "[M017] Generating risk register..."
RISK_REGISTER_SCRIPT="${PROJECT_ROOT}/scripts/ci/risk_register.sh"
if [ -x "$RISK_REGISTER_SCRIPT" ]; then
bash "$RISK_REGISTER_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/risk_register_${REPORT_DATE}.md"
else
echo "[M017] ERROR: risk_register.sh not found or not executable at $RISK_REGISTER_SCRIPT"
exit 1
fi
# 5. Validate all artifacts exist
echo "[M017] Validating artifacts..."
ARTIFACTS=(
"sbom_${REPORT_DATE}.spdx.json"
"lockfile_diff_${REPORT_DATE}.md"
"compat_matrix_${REPORT_DATE}.md"
"risk_register_${REPORT_DATE}.md"
)
ALL_PASS=true
for artifact in "${ARTIFACTS[@]}"; do
if [ -f "${REPORT_DIR}/${artifact}" ] && [ -s "${REPORT_DIR}/${artifact}" ]; then
echo "[M017] ${artifact}: OK"
else
echo "[M017] ${artifact}: MISSING OR EMPTY"
ALL_PASS=false
fi
done
# 6. Generate summary
if [ "$ALL_PASS" = true ]; then
echo "[M017] PASS: All 4 artifacts generated successfully"
exit 0
else
echo "[M017] FAIL: One or more artifacts missing"
exit 1
fi
```
### 4.5 四件套生成脚本详细设计
> **重要**：以下脚本均为**待实现**状态，需要在 P2-CMP-006 阶段完成开发。
#### 4.5.1 Lockfile Diff 生成脚本
```bash
#!/bin/bash
# scripts/ci/lockfile_diff.sh
# 功能：生成依赖版本变更对比报告
# 输入：REPORT_DATE (可选，默认为昨天)
# 输出：lockfile_diff_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Lockfile Diff Report - ${REPORT_DATE}"
# 获取当前 lockfile
LOCKFILE="${PROJECT_ROOT}/go.sum"
BASELINE_DIR="${PROJECT_ROOT}/.compliance/baseline"
# 对比逻辑
echo "## Summary"
echo "| 变更类型 | 数量 |"
echo "|----------|------|"
echo "| 新增依赖 | TBD |"
echo "| 升级依赖 | TBD |"
echo "| 降级依赖 | TBD |"
echo "| 删除依赖 | TBD |"
# 待实现：实际的对比逻辑
```
#### 4.5.2 兼容矩阵生成脚本
```bash
#!/bin/bash
# scripts/ci/compat_matrix.sh
# 功能：生成组件版本兼容性矩阵
# 输入：REPORT_DATE (可选)
# 输出：compat_matrix_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Dependency Compatibility Matrix - ${REPORT_DATE}"
# 读取 Go 版本信息
GO_VERSION=$(go version 2>/dev/null | grep -oP 'go\d+\.\d+' || echo "unknown")
echo "## Go Dependencies (${GO_VERSION})"
echo "| 组件 | 版本 | 兼容性 |"
echo "|------|------|--------|"
echo "| TBD | TBD | TBD |"
# 待实现：实际的兼容性检查逻辑
```
#### 4.5.3 风险登记册生成脚本
```bash
#!/bin/bash
# scripts/ci/risk_register.sh
# 功能：生成安全与合规风险登记册
# 输入：REPORT_DATE (可选)
# 输出：risk_register_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Risk Register - ${REPORT_DATE}"
echo "## Summary"
echo "| 风险级别 | 数量 |"
echo "|----------|------|"
echo "| CRITICAL | 0 |"
echo "| HIGH | 0 |"
echo "| MEDIUM | 0 |"
echo "| LOW | 0 |"
echo "## High Risk Items"
echo "| ID | 描述 | CVSS | 组件 | 修复建议 |"
echo "|----|------|------|------|----------|"
echo "| - | 无高风险项 | - | - | - |"
# 待实现：实际的漏洞扫描和风险评估逻辑
# 建议集成：grype (漏洞扫描)、license-check (许可证检查)
```
---
## 5. 与现有安全机制联动
### 5.1 联动矩阵
| 源机制 | 目标机制 | 联动方式 | 触发条件 |
|--------|----------|----------|----------|
| ToS 合规引擎 | 告警系统 | 事件推送 | 违规事件触发 |
| Token Runtime | 合规规则引擎 | 凭证验证 | Token 校验时 |
| Rate Limit | 合规规则引擎 | 流量检测 | 限流触发时 |
| Audit Middleware | 合规报告 | 日志聚合 | 审计事件写入 |
| Secret Scanner | 合规规则引擎 | 凭证检测 | 扫描结果输出 |
### 5.2 联动设计
#### 5.2.1 告警系统联动
```
合规事件 ──┬──▶ 告警通道 (Slack/PagerDuty/Email)
│
└──▶ 事件存储 (审计数据库)
│
└──▶ 趋势分析 ──▶ M-013~M-016 指标更新
```
#### 5.2.2 Token Runtime 联动
```
Token 校验请求
│
├──▶ CRED-INGRESS-PLATFORM: 验证平台凭证存在
│
├──▶ CRED-INGRESS-FORMAT: 验证凭证格式
│
└──▶ CRED-INGRESS-EXPIRED: 验证凭证状态 (通过 Token Runtime)
```
#### 5.2.3 Audit Middleware 联动
```
HTTP 请求
│
├──▶ Audit Middleware (记录请求)
│
├──▶ 合规规则引擎 (执行检查)
│ │
│ ├──▶ CRED-EXPOSE-* 凭证泄露检测
│ │
│ └──▶ CRED-DIRECT-* 直连检测
│
└──▶ 合规报告生成 (聚合日志)
```
---
## 6. 目录结构
```
compliance/ # [待创建] 合规能力包根目录
├── rules/ # 合规规则定义
│ ├── m013_credential_exposure.yaml
│ ├── m014_ingress_coverage.yaml
│ ├── m015_direct_access.yaml
│ └── m016_query_key_reject.yaml
│
├── config/ # 合规配置
│ ├── allowed_suppliers.yaml
│ ├── alert_channels.yaml
│ └── rule_sets.yaml
│
├── engine/ # 合规规则引擎
│ ├── compiler.go # 规则编译器
│ ├── matcher.go # 规则匹配器
│ ├── executor.go # 策略执行器
│ └── audit.go # 审计记录器
│
├── reports/ # 合规报告 (M-017)
│ ├── m017_dependency_audit.sh # [待实现] 四件套生成脚本
│ └── templates/ # 报告模板
│
├── ci/ # CI 集成
│ ├── compliance_gate.sh # 合规门禁主脚本
│ ├── m013_credential_scan.sh # [待实现]
│ ├── m014_ingress_coverage.sh # [待实现]
│ ├── m015_direct_access_check.sh # [待实现]
│ ├── m016_query_key_reject.sh # [待实现]
│ └── m017_dependency_audit.sh # [待实现]
│
├── monitoring/ # 监控配置
│ ├── alerts.yaml # 告警规则
│ └── dashboards/ # 监控面板
│
└── docs/ # 文档
├── compliance_capability_package_design_v1_2026-04-02.md
└── compliance_rules_reference.md
scripts/ci/ # [已存在] 现有 CI 脚本目录
├── lockfile_diff.sh # [待实现] Lockfile Diff 生成
├── compat_matrix.sh # [待实现] 兼容矩阵生成
└── risk_register.sh # [待实现] 风险登记册生成
```
---
## 7. 实施计划
### 7.1 P2 阶段任务分解
> **工期修正说明**：根据评审意见，原设计工期（26d）低估了CI脚本实现工作量。实际工作量需要 **35-40d**，主要原因是：
> 1. 所有 CI 脚本（m013~m017）均需新实现
> 2. M-017 四件套生成脚本需要独立开发
> 3. 与现有审计日志系统的集成需要额外协调
| 任务ID | 任务名称 | 依赖 | 设计工期 | 修正工期 | 交付物 |
|--------|----------|------|---------|---------|--------|
| P2-CMP-001 | 合规规则引擎核心开发 | - | 5d | 6d | engine/*.go |
| P2-CMP-002 | M-013 凭证泄露规则实现 | P2-CMP-001 | 3d | 4d | rules/m013_*.yaml + ci/m013_*.sh |
| P2-CMP-003 | M-014 入站覆盖规则实现 | P2-CMP-001 | 2d | 3d | rules/m014_*.yaml + ci/m014_*.sh |
| P2-CMP-004 | M-015 直连检测规则实现 | P2-CMP-001 | 2d | 4d | rules/m015_*.yaml + ci/m015_*.sh + 蜜罐配置 |
| P2-CMP-005 | M-016 Query Key 拒绝规则实现 | P2-CMP-001 | 2d | 3d | rules/m016_*.yaml + ci/m016_*.sh |
| P2-CMP-006 | M-017 依赖审计四件套 | - | 3d | 6d | 四件套生成脚本 + 模板 |
| P2-CMP-007 | CI 流水线集成 | P2-CMP-002~006 | 2d | 5d | ci/compliance_gate.sh |
| P2-CMP-008 | 监控告警配置 | P2-CMP-001 | 2d | 3d | monitoring/alerts.yaml |
| P2-CMP-009 | 安全机制联动实现 | P2-CMP-001 | 3d | 4d | 联动代码 |
| P2-CMP-010 | 端到端测试与验证 | P2-CMP-007 | 2d | 4d | 测试报告 |
| **总计** | | | **26d** | **38d** | |
### 7.2 里程碑
| 里程碑 | 完成条件 | 设计日期 | 修正日期 |
|--------|----------|----------|----------|
| **M1: 规则引擎完成** | P2-CMP-001 通过单元测试 | 2026-04-07 | 2026-04-08 |
| **M2: 四大规则就绪** | P2-CMP-002~005 在 staging 通过 | 2026-04-11 | 2026-04-15 |
| **M3: CI 集成完成** | P2-CMP-007 合规门禁在 CI 通过 | 2026-04-13 | 2026-04-20 |
| **M4: 监控告警就绪** | P2-CMP-008 告警通道验证通过 | 2026-04-15 | 2026-04-22 |
| **M5: P2 交付完成** | E2E 测试通过 + 文档完备 | 2026-04-17 | 2026-04-26 |
---
## 8. 验收标准
### 8.1 M-013~M-016 验收
| 指标 | 验收条件 | 测试方法 |
|------|----------|----------|
| M-013 | 凭证泄露事件 = 0 | 自动化扫描 + 渗透测试 |
| M-014 | 入站覆盖率 = 100% | 日志分析覆盖率 |
| M-015 | 直连事件 = 0 | 蜜罐检测 + 日志分析 |
| M-016 | 拒绝率 = 100% | 外部 query key 构造测试 |
### 8.2 M-017 验收
| 报告 | 验收条件 |
|------|----------|
| SBOM | SPDX 2.3 格式有效, 包含所有直接依赖 |
| Lockfile Diff | 变更条目完整, 影响评估准确 |
| 兼容矩阵 | 版本对应关系正确 |
| 风险登记册 | CVSS >= 7.0 漏洞已收录 |
### 8.3 集成验收
| 场景 | 验收条件 |
|------|----------|
| CI 流水线 | 合规门禁在 build 阶段可执行 |
| 告警通道 | 告警可实时送达 (延迟 < 30s) |
| 报告生成 | 四件套在 CI 中自动生成 |
| 规则热更新 | 规则变更无需重启服务 |
---
## 9. 附录
### 9.1 参考文档
- `docs/tos_compliance_engine_design_v1_2026-03-18.md` - ToS 合规引擎设计
- `docs/llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md` - M-013~M-016 指标定义
- `docs/supply_gate_command_playbook_v1_2026-03-25.md` - M-017 依赖审计要求
### 9.2 术语表
| 术语 | 定义 |
|------|------|
| SBOM | Software Bill of Materials, 软件物料清单 |
| SPDX | Software Package Data Exchange, 软件包数据交换标准 |
| CVSS | Common Vulnerability Scoring System, 通用漏洞评分系统 |
| ToS | Terms of Service, 服务条款 |
| CI | Continuous Integration, 持续集成 |
---
**文档状态**: 已修订
**版本**: v1.1
**日期**: 2026-04-02
**关联任务**: P2 合规能力包设计
**修订说明**:
- 统一事件命名格式与 audit_log_enhancement_design_v1_2026-04-02.md 对齐
- 修复硬编码路径问题，改为环境变量或相对路径
- 补充 M-015 直连检测方法（蜜罐、网络流量分析等）
- 修复 syft 缺失时生成无效 SBOM 问题（改为必需检查）
- 补充 M-017 四件套生成脚本详细设计（待实现状态）
- 修正实施工期从 26d 到 38d
Reference in New Issue Copy Permalink