fix(content): harden Docker practice guide

2026-08-10 16:37:34 +00:00 · 2026-06-16 21:23:21 -07:00
parent f4e684afeb
commit 9fdffa9d91
67 changed files with 343 additions and 278 deletions
@@ -20,7 +20,7 @@ Docker 守护进程在启动容器时，会在后台为容器创建一套独立
 > 为了缓解内核漏洞带来的威胁，生产环境务必保持宿主机 Linux 内核的及时修补与更新，或者借助诸如 gVisor、Kata Containers 等提供了独立内核的安全容器技术。同时，需要及时修补容器运行时（如 runC）的漏洞。2025 年 11 月披露的一系列 runC 容器逃逸漏洞（CVE-2025-31133、CVE-2025-52565、CVE-2025-52881）就表明，即使内核保持更新，运行时层的缺陷仍然可能导致容器隔离被突破。

 通过命名空间，Docker 也能限制进程从外部环境获取信息。
-例如，由于进程环境被隔离，进程在内部其实是无法感知到外部宿主机的存在的。它既不能获取其他容器的进程列表，也无法通过网络与其他系统进行交互（除非经过配置）。
+例如，由于进程环境被隔离，进程在内部通常无法直接感知外部宿主机的进程和挂载命名空间。网络命名空间隔离的是网络栈；默认 bridge 网络通常允许容器主动访问外部网络，限制的是外部直接访问容器服务。若要限制出站访问，需要使用 `none` 网络、防火墙、Kubernetes NetworkPolicy 或运行时策略。

 ### 18.1.3 用户命名空间与提权防护

@@ -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