镜像安全扫描与 SBOM：Trivy、Grype、Clair 与 CI 安全门禁

扫描流水线：
  解包镜像层 → 识别操作系统/语言包管理器 → 生成 SBOM（包清单）
  → 匹配 CVE 数据库（按包名+版本）→ 输出漏洞报告

关键依赖：
  - 层数据：镜像层解包（overlayfs 层 → 文件树）
  - 包解析器：apk/dpkg/rpm、pip/npm/maven/golang
  - 漏洞库：OSV、NVD、厂商数据库（红帽、Debian、Alpine）

扫描盲区：
  - distroless/scratch：无包管理器，扫描器无从识别（不代表无漏洞）
  - 静态编译二进制：无包元数据，需 SBOM 显式声明
  - 语言运行时自带依赖：如 .NET self-contained，需运行时级 SBOM
结论：扫描工具 + 显式 SBOM 结合，才能覆盖"无包管理器"场景

# 扫描镜像全部漏洞
trivy image --severity HIGH,CRITICAL registry.example.com/app:v1
# 指定输出格式（json / sarif / table）
trivy image -f json -o report.json registry.example.com/app:v1
# 只扫配置/密钥（不扫漏洞）
trivy config --severity CRITICAL Dockerfile
trivy fs --skip-files '*.min.js' .

# 更新漏洞库（默认启动时自动下载到缓存）
trivy image --update-cache registry.example.com/app:v1
# 完全离线：预先导出漏洞库
trivy image --download-db-only
# 用离线库扫描
trivy image --skip-db-update --offline-scan registry.example.com/app:v1

# 忽略特定 CVE（写 .trivyignore）
# CVE-2024-0001
# reason: 该漏洞仅影响非生产路径

trivy image --ignorefile .trivyignore registry.example.com/app:v1
# 退出码语义：0=无漏洞或全忽略，1=有漏洞（可接入 CI 门禁）

# Syft 生成 SBOM，Grype 基于 SBOM 扫漏洞（同团队工具链）
syft registry.example.com/app:v1 -o spdx-json > sbom.spdx.json
grype sbom:sbom.spdx.json -o table
# 或直接扫镜像（内部会先生成 SBOM）
grype registry.example.com/app:v1

Grype 特点：
  - 与 Syft 深度集成：SBOM 驱动，结果可复现
  - 支持多种输入：镜像、SBOM 文件、OCI 目录
  - 输出格式：table/json/cyclonedx/sarif

Clair 是 Harbor 的内置扫描引擎（v4 起）：
  - 分层索引：Indexer（解包+生成包清单）与 Matcher（匹配漏洞）
  - 通过 Harbor API 触发，结果存在 PostgreSQL
  - 支持 OS 与语言包漏洞匹配
部署形态：Kubernetes 内 Clair 组件（indexer/matcher/notifier）

# Syft 生成两种格式
syft registry.example.com/app:v1 -o cyclonedx-json > sbom.cdx.json
syft registry.example.com/app:v1 -o spdx-json > sbom.spdx.json

SBOM 也要可信：伪造的 SBOM 会让扫描失去意义
  - 用 cosign 签名 SBOM 附件（见镜像签名篇）
  - 验证时同时校验 SBOM 的签名与完整性
  - 生成与签名在 CI 内完成，保证来源可信

□ 每次构建生成新 SBOM 并随镜像发布（Harbor 2.5+/ECR 支持附件）
□ 定期对存量镜像补扫（新 CVE 披露后）——SBOM 让补扫更快
□ SBOM 归档：按镜像 digest 保存历史版本，便于审计回看

修复优先级（按风险面）：
  ① 运行时常驻进程依赖（如 Web 框架、TLS 库）
  ② 对外暴露端口组件的依赖（监听 0.0.0.0）
  ③ 攻击链可及组件（与输入处理相关的解析器）
  ④ 仅构建期/工具链依赖（风险低，可延后）
不追求"零漏洞"：把 CRITICAL+ 且运行时可达的先清掉

发现（扫描报告）→ 定级（severity+可达性）→ 修复（升级/重建）
→ 复扫验证 → 放行发布
关键：修复后重新扫描并保存新报告，形成"扫描-修复-复扫"闭环

# 构建工具只在 builder 阶段，运行时镜像最小化
FROM node:20 AS builder
COPY . .
RUN npm ci && npm run build

FROM node:20-slim
COPY --from=builder /app/dist /app/dist
USER node
ENTRYPOINT ["node", "/app/dist/server.js"]

最小化收益：
  - 更少包 → 更少 CVE（攻击面收敛）
  - 更小镜像 → 拉取快、扫描快、存储省

FROM scratch
COPY --from=builder /app/bin /app
ENTRYPOINT ["/app/bin"]
# 无包管理器：需在 CI 显式生成 SBOM 供扫描器使用

# CI 里对 scratch 镜像补生成 SBOM（基于构建产物）
syft dir:./dist -o cyclonedx-json > sbom.cdx.json
grype sbom:sbom.cdx.json

□ 锁定基础镜像 digest（而非 tag）：FROM node:20@sha256:...
□ 锁定依赖 lockfile（package-lock/go.sum/poetry.lock）
□ 构建产物可复现 → 每次重建的 SBOM 可对比、可回滚

# CI 中扫描并门禁：CRITICAL>0 或 HIGH>N 即失败
trivy image --exit-code 1 --severity CRITICAL,HIGH \
  --ignore-unfixed registry.example.com/app:v1

门禁设计原则：
  - 阻断条件：CRITICAL 必阻断；HIGH 可设阈值；MEDIUM 只告警
  - 基线豁免：遗留镜像用"已知清单"豁免，新引入必须为零
  - 区分：构建期工具链漏洞不阻断，运行时组件漏洞必阻断

steps:
  - uses: actions/checkout@v4
  - name: 构建镜像
    run: docker build -t $IMAGE .
  - name: 扫描镜像
    uses: aquasecurity/trivy-action@master
    with:
      image-ref: $IMAGE
      format: sarif
      output: trivy-results.sarif
      exit-code: '1'
      severity: CRITICAL,HIGH
  - name: 上传 SARIF 到 GitHub 安全中心
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: trivy-results.sarif

推荐：扫描门禁在"合并/发布"而非"每次提交"执行
  - PR 阶段：轻量扫描（只扫变更镜像）
  - 发布阶段：全量扫描 + 门禁，不通过不出 artifact
  - 避免：扫描拖慢开发者循环（CI 时间/误报噪音）

# 在 Harbor 启用自动扫描（推镜像后自动扫）
# Harbor 项目设置 → 扫描策略 → 自动扫描
# 或用 API 触发
curl -X POST https://harbor.example.com/api/v2.0/projects/library/ \
  -u admin:pass -H "Content-Type: application/json" \
  -d '{"auto_scan": true}'

Harbor 持续扫描能力：
  - 自动扫描新推送镜像 + 定时全量补扫
  - 漏洞分级展示、按 CVE 过滤
  - 配合保留策略：高危镜像禁止复制/拉取

ECR Enhanced Scanning（Inspector）：
  - 持续扫描 + 漏洞态势报告
  - 与 CI 门禁联动（findings 驱动）
  - 支持 Lambda/ECR 等资源统一管理

□ 定期输出镜像漏洞报告（按项目/仓库/时间维度）
□ 高危处置记录（修复版本、复扫结果）供审计
□ SBOM 归档满足许可证合规（SPDX）与供应链披露要求
□ 与签名/准入联动：无有效扫描报告的镜像不部署