# 镜像漏洞修复任务需求规格说明书

## 目录
1. [需求背景与描述](#1-需求背景与描述)
2. [功能需求清单](#2-功能需求清单)
3. [技术约束与依赖条件](#3-技术约束与依赖条件)
4. [验收标准 (Acceptance Criteria)](#4-验收标准-acceptance-criteria)
5. [实施步骤](#5-实施步骤)
6. [测试要求](#6-测试要求)
7. [交付物说明](#7-交付物说明)
8. [待确认事项与风险](#8-待确认事项与风险)

---

## 1. 需求背景与描述
针对 `/Users/ray/workplace/project_data/migu/security/scan_all_*.html` 路径报告中识别出的“maas”相关镜像漏洞，提供可落地的修复方案、自动化验证脚本及结构化交付文档，确保镜像安全水平达到生产发布标准。

## 2. 功能需求清单
- **漏洞筛选与定位**：筛选所有名称包含“maas”的镜像，记录 CVE 编号、组件坐标（GAV）、漏洞等级、CVSS 得分及容器内物理路径。
- **修复方案制定**：
    - 优先方案：升级至官方安全版本。
    - 备选方案：通过 `<exclusions>` 排除依赖并替换为 Patched 版本。
    - 缓解方案：针对底层无法移除的依赖，提供 JVM 参数级缓解措施（如 Log4j2 lookup 禁用）。
- **配置自动化生成**：
    - 为每个镜像生成独立的 POM 片段，遵循 `${v.artifactId}` 命名规则。
    - 提供 Dockerfile 修改建议（针对 OS 级漏洞）。
- **一键验证自动化**：提供 Shell 脚本，支持自动编译、依赖对比及安全工具重新扫描。
- **结构化归档**：在 `/Users/ray/workplace/project_data/migu/security/` 下按镜像名称创建独立子目录，分类保存报告、配置及验证脚本。

## 3. 技术约束与依赖条件
- **运行环境**：支持 Linux/MacOS 系统的 Shell 环境。
- **开发工具**：依赖 Maven 3.x，需具备私有仓库访问权限。
    - **重要配置**：为避免路径解析问题，Maven 的 `settings.xml` 文件中的 `<localRepository>` 标签必须配置为绝对路径，例如 `<localRepository>/Users/your_user/path/to/repository</localRepository>`，不支持 `~/` 写法。
- **安全工具**：验证环节建议本地安装 Trivy 。
- **兼容性**：升级版本必须保持与现有 Spring Boot 3.x / Spring Cloud 框架的兼容性。

## 4. 验收标准 (Acceptance Criteria)
- **安全红线**：修复后 低危 及以上级别的 CVE 数量降为 0。
- **功能完备**：所有包含漏洞的“maas”镜像均需配备独立的修复报告和验证脚本。
- **性能红线**：镜像层大小增量 < 5%，应用启动时间增量 < 10%。
- **质量保障**：单元测试通过率 100%，关键业务接口回归测试通过率 100%。

## 5. 实施步骤
1. **分析阶段**：深度解析 HTML 报告，识别 Java 组件与系统库漏洞。
2. **调研阶段**：检索 Maven 中央仓库，确定安全版本及版本间兼容性变更点。
3. **编写阶段**：生成 `maas-vulnerability-fix-pom-snippets.xml` 及 Markdown 报告。
4. **归档阶段**：执行目录创建与文件迁移命令。
5. **验证阶段**：运行 `verify-maas-fix.sh`，对比修复前后的依赖树差异。

## 6. 测试要求
- **静态分析**：使用完整的 Maven 命令 `/Users/ray/software/maven/bin/mvn -s /Users/ray/software/maven/conf/settings.xml dependency:tree` 强制检查传递依赖是否已被正确覆盖，以确保加载正确的配置文件。
- **安全扫描**：使用安全工具对打包后的 Jar/镜像进行二次扫描，确认漏洞“清零”。
- **兼容性测试**：重点测试升级组件涉及的核心 API，防止 ClassNotFound/NoSuchMethod 异常。
- **性能监控**：记录并对比修复前后容器冷启动耗时。

## 7. 交付物说明
- **根目录文件**：`requirements.md` (本需求文档)。
- **镜像专属子目录** (`/{image_name}/`)：
    - `maas-{image_name}-vulnerability-details.md`：**（必须前置提供）** 详细的漏洞清单文件。要求在提供任何修复方案之前，先将完整的漏洞信息（包含组件、来源、版本、CVE）和出现次数统计，以此文件的形式交付。
    - `maas-{image_name}-fix-report.md`：按镜像维度的详细漏洞修复报告。
    - `maas-vulnerability-fix-pom-snippets.xml`：可直接复制的 Maven 配置片段。
    - `verify-maas-fix.sh`：本地一键化修复验证脚本。

## 8. 待确认事项与风险
- **私有依赖**：部分 `com.maas` 自有组件是否存在漏洞，需研发内部评估。
- **基础镜像**：是否允许在 Dockerfile 中通过 `apk upgrade` 批量升级，需安全合规组确认。
