lijiaoqiao/docs/compliance_capability_package_design_v1_2026-04-02.md

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 规则配置示例

# 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 覆盖率统计

# 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 供应商白名单配置

# 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 拒绝模式配置

# 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 脚本集成

# 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 告警规则

# 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 (软件物料清单)

{
  "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

# 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 兼容矩阵

# 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 风险登记册

# 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 自动化报告生成脚本

#!/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 生成脚本

#!/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 兼容矩阵生成脚本

#!/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 风险登记册生成脚本

#!/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