fix(content): harden Docker practice guide

18_security/18.6_image_security.md

@@ -217,7 +217,7 @@ grype sbom:sbom.json --add-cpes-if-none
 
 ### 18.6.3 镜像签名与验证
 
-镜像签名确保镜像的来源可信且未被篡改。两种主流方案是 Cosign 和 Notary。
+镜像签名确保镜像的来源可信且未被篡改。新项目通常优先评估 Cosign (Sigstore) 或 Notary Project 的 Notation；Docker Content Trust / Notary v1 属于历史路径。
 
 #### Cosign - 现代签名解决方案
 
@@ -269,13 +269,25 @@ cosign verify --key cosign.pub "$IMAGE_DIGEST"
 # 在 GitHub Actions 等 CI 中无需存储密钥
 cosign sign --yes "$IMAGE_DIGEST"
 
-# 验证时自动使用 OIDC 令牌验证身份
+# 验证时检查签名证书中的 OIDC 身份声明是否匹配预期 workflow 与 issuer
 cosign verify "$IMAGE_DIGEST" \
   --certificate-identity https://github.com/myorg/myrepo/.github/workflows/build.yml@refs/heads/main \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```
 
-#### Docker Content Trust 与 Notary
+#### Notary Project / Notation
+
+Notation 是 Notary Project 的 OCI 签名工具，适合希望采用 CNCF Notary Project 规范、或使用 registry/云厂商原生集成的团队。与 Cosign 类似，生产环境应围绕不可变 digest 做签名和策略校验。
+
+```bash
+# 签名已推送的镜像 digest
+notation sign myregistry.com/myapp@sha256:<digest>
+
+# 验证签名
+notation verify myregistry.com/myapp@sha256:<digest>
+```
+
+#### Docker Content Trust 与 Notary v1
 
 > **注意：DCT 退役时间线**
 >
@@ -283,7 +295,7 @@ cosign verify "$IMAGE_DIGEST" \
 >
 > 新项目应优先使用上文介绍的 **Cosign (Sigstore)** 或 registry 原生签名/证明能力；现有 DCT 用户应先盘点依赖、验证替代方案，再制定迁移计划。
 
-Docker Content Trust 使用 Notary 实现镜像签名，是 Docker 官方的传统签名解决方案。
+Docker Content Trust 使用 Notary v1 实现镜像签名，是 Docker 官方的传统签名解决方案，不建议新项目采用。
 
 **历史用法示例（不建议新项目采用）：**
 
@@ -353,17 +365,7 @@ trivy image --scanners vuln,misconfig registry:5000/myapp:latest
 
 **Harbor（私有镜像仓库）的安全扫描：**
 
-```yaml
-# harbor.yml 配置示例
-trivy:
-  enabled: true
-  # 启用镜像扫描
-  image_source: "Official"
-
-# 默认扫描配置
-scan_on_push: true  # 推送时自动扫描
-scan_all: true      # 扫描仓库中的所有镜像
-```
+Harbor 的扫描器应在管理界面的 **Interrogation Services / Scanner** 中配置；推送自动扫描通常在项目级 **Configuration** 中启用。不要把扫描策略误写成通用 `harbor.yml` 顶层字段。实际部署时应按所用 Harbor 版本文档配置 scanner、项目策略和漏洞阻断阈值。
 
 #### 5. 政策执行
 
@@ -427,13 +429,33 @@ jobs:
       if: github.event_name == 'push'
       uses: sigstore/cosign-installer@v3
 
-    - name: Build Docker image for scan
+    - name: Login to Registry
+      if: github.event_name == 'push'
+      uses: docker/login-action@v4
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Build and push Docker image
+      if: github.event_name == 'push'
+      id: build-push
+      uses: docker/build-push-action@v7
+      with:
+        context: .
+        push: true
+        tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+        provenance: mode=max
+        sbom: true
+
+    - name: Build Docker image for pull request scan
+      if: github.event_name == 'pull_request'
       uses: docker/build-push-action@v7
       with:
         context: .
         push: false
         load: true
-        tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+        tags: local/${{ env.IMAGE_NAME }}:pr
 
     - name: Run Trivy vulnerability scan
       # 安全提醒：2026 年 3 月 19 日 Trivy GitHub Actions 遭受供应链攻击，
@@ -441,7 +463,7 @@ jobs:
       # 使用前请到 https://github.com/aquasecurity/trivy-action/releases 核实 SHA 对应正确版本。
       uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # v0.35.0
       with:
-        image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+        image-ref: ${{ github.event_name == 'push' && format('{0}/{1}@{2}', env.REGISTRY, env.IMAGE_NAME, steps.build-push.outputs.digest) || format('local/{0}:pr', env.IMAGE_NAME) }}
         format: 'sarif'
         output: 'trivy-results.sarif'
         severity: 'HIGH,CRITICAL'
@@ -454,7 +476,7 @@ jobs:
     - name: Generate SBOM
       uses: anchore/sbom-action@v0
       with:
-        image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+        image: ${{ github.event_name == 'push' && format('{0}/{1}@{2}', env.REGISTRY, env.IMAGE_NAME, steps.build-push.outputs.digest) || format('local/{0}:pr', env.IMAGE_NAME) }}
         format: cyclonedx-json
         output-file: sbom-cyclonedx.json
 
@@ -464,23 +486,6 @@ jobs:
         name: sbom
         path: sbom-cyclonedx.json
 
-    - name: Login to Registry and Push
-      if: github.event_name == 'push'
-      uses: docker/login-action@v4
-      with:
-        registry: ${{ env.REGISTRY }}
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Push image
-      if: github.event_name == 'push'
-      id: build-push
-      uses: docker/build-push-action@v7
-      with:
-        context: .
-        push: true
-        tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-
     - name: Sign image with Cosign
       if: github.event_name == 'push'
       run: |
@@ -529,7 +534,9 @@ generate:sbom:
     - syft docker-archive://image.tar -o cyclonedx > sbom.xml
   artifacts:
     reports:
-      sbom: sbom.xml
+      cyclonedx: sbom.xml
+
+# 如需让 GitLab 安全面板摄取容器扫描结果，应输出 GitLab 兼容的 container_scanning 报告。
 
 push:
   stage: push