referrers-attestation-staging 镜像文档

1. 镜像概述和主要用途

referrers-attestation-staging 镜像（示例名称，实际使用时需替换为官方镜像名称）是一款专为 staging 环境设计的工具镜像，主要用于实现和测试 OCI（开放容器倡议）Referrers Attestation（引用者证明）的管理、验证与集成流程。该镜像聚焦于软件供应链安全领域，帮助开发和测试团队在预发布阶段（staging 环境）验证、管理引用者证明（referrers attestation），确保软件构建产物的来源、构建过程及完整性符合预设安全策略。

2. 核心功能和特性

2.1 OCI 规范支持

• 兼容 OCI Referrers API v1.0 规范，支持引用者（referrers）元数据的创建、查询、验证和删除。
• 支持 OCI Artifact Manifest 和 Attestation Manifest 格式解析。

2.2 Attestation 验证能力

• 集成主流 attestation 格式验证工具，支持 SLSA（Supply Chain Levels for Software Artifacts）、in-toto、SPDX 等规范的 attestation 验证。
• 提供内置策略引擎，可自定义验证规则（如签名算法、证明者身份、构建环境要求等）。

2.3 Staging 环境适配

• 提供与 staging 环境基础设施（如私有镜像仓库、密钥管理服务、日志系统）的集成配置模板。
• 支持低资源消耗模式，适配 staging 环境的测试资源限制。

2.4 工具集与可操作性

• 内置命令行工具（如 referrers-cli），支持交互式操作和脚本化调用。
• 提供 REST API 接口，便于与 CI/CD 管道或监控系统集成。

2.5 可观测性与安全性

• 详细日志记录（支持 JSON 格式），包含验证结果、错误信息和操作审计。
• 支持 TLS 加密通信，可配置 CA 证书验证外部服务（如镜像仓库）。

3. 使用场景和适用范围

3.1 典型使用场景

• CI/CD Staging 阶段验证：在应用部署到生产环境前，通过该镜像在 staging 环境中验证构建产物的 referrers attestation，确保供应链安全策略在预发布阶段已生效。
• 软件供应链安全测试：模拟生产环境中的 attestation 验证流程，测试不同攻击场景（如伪造 attestation、缺失 referrers 元数据）下的系统响应。
• Referrers 元数据管理测试：测试 referrers 元数据的创建、更新、删除逻辑，验证与 OCI 镜像仓库（如 Docker Registry、GitHub Container Registry）的兼容性。
• 多环境一致性验证：对比开发、staging、生产环境中 referrers attestation 的差异，确保跨环境策略执行的一致性。

3.2 适用范围

• 开发团队：验证本地构建产物的 referrers attestation 合规性。
• 测试团队：在 staging 环境中执行软件供应链安全测试用例。
• DevOps/SRE 团队：集成到 CI/CD 管道，自动化 staging 环境的 attestation 验证流程。
• 安全团队：审计 staging 环境中的 attestation 策略执行情况，优化安全规则。

4. 使用方法和配置说明

4.1 前置依赖

• Docker 19.03+ 或兼容的容器运行时（如 containerd）。
• 访问 staging 环境的 OCI 镜像仓库（需配置认证，如用户名密码、Token 或证书）。
• （可选）用于存储策略规则或证书的持久化存储（如本地目录、S3 兼容存储）。

4.2 基础使用（docker run）

4.2.1 交互式验证示例

通过命令行工具验证指定镜像的 referrers attestation：

docker run -it --rm \
  -e STAGING_REGISTRY_URL="[***]" \
  -e REGISTRY_AUTH="username:password" \  # 或使用 REGISTRY_TOKEN
  -v /local/certs:/etc/referrers/certs:ro \  # 挂载 CA 证书（若仓库使用自签名证书）
  referrers-attestation-staging:latest \
  referrers-cli verify --image "staging-registry.example.com/app:v1.0.0" --policy /etc/referrers/policy.json

4.2.2 后台服务模式（API 接口）

启动 REST API 服务，提供 attestation 验证和 referrers 管理接口：

docker run -d --name referrers-attestation-service \
  -p 8080:8080 \  # API 端口映射
  -e STAGING_REGISTRY_URL="[***]" \
  -e API_PORT=8080 \
  -e LOG_LEVEL=info \  # 日志级别：debug, info, warn, error
  -e TLS_ENABLED=true \
  -v /local/policy:/etc/referrers/policy:ro \  # 挂载策略文件目录
  -v /local/certs:/etc/referrers/certs:ro \  # 挂载 TLS 证书和 CA 证书
  referrers-attestation-staging:latest \
  server --config /etc/referrers/config.yaml

4.3 Docker Compose 配置示例

适用于多服务集成场景（如与 staging 环境的日志系统、密钥管理服务联动）：

version: "3.8"
services:
  referrers-attestation:
    image: referrers-attestation-staging:latest
    container_name: referrers-attestation-staging
    restart: unless-stopped
    ports:
      - "8080:8080"  # API 端口
    environment:
      - STAGING_REGISTRY_URL=[***]
      - REGISTRY_TOKEN=${REGISTRY_TOKEN}  # 从环境变量注入认证 Token
      - API_PORT=8080
      - LOG_LEVEL=info
      - POLICY_PATH=/etc/referrers/policy/default.json  # 默认策略文件路径
      - TLS_CERT_PATH=/etc/referrers/certs/server.crt
      - TLS_KEY_PATH=/etc/referrers/certs/server.key
    volumes:
      - ./local-policy:/etc/referrers/policy:ro  # 本地策略文件目录
      - ./local-certs:/etc/referrers/certs:ro  # 本地证书目录
      - ./logs:/var/log/referrers  # 日志持久化
    networks:
      - staging-network  # 接入 staging 环境网络

networks:
  staging-network:
    external: true  # 假设已存在 staging 环境网络

4.4 环境变量说明

4.5 命令行工具使用

镜像内置 referrers-cli 工具，支持以下核心命令：

验证 Attestation

# 验证指定镜像的 referrers attestation 是否符合策略
referrers-cli verify \
  --image "staging-registry.example.com/app:v1.0.0" \  # 目标镜像（含标签或 digest）
  --policy /etc/referrers/policy/staging-policy.json \  # 策略文件路径
  --registry-url $STAGING_REGISTRY_URL \                # 镜像仓库 URL（可省略，默认使用环境变量）
  --auth $REGISTRY_AUTH                                 # 认证信息（可省略，默认使用环境变量）

列出 Referrers 元数据

# 列出指定镜像的所有 referrers 元数据
referrers-cli list \
  --image "staging-registry.example.com/app@sha256:abc123..." \  # 目标镜像（digest 格式）
  --output json                                                 # 输出格式：json 或 table

创建 Referrers 记录

# 为镜像创建 referrers 记录（需仓库写入权限）
referrers-cli create \
  --image "staging-registry.example.com/app:v1.0.0" \
  --attestation-file ./local-attestation.json \  # 本地 attestation 文件（需通过卷挂载到容器内）
  --media-type "application/vnd.in-toto+json"    # attestation 媒体类型

4.6 持久化与数据管理

• 策略文件：建议通过卷挂载（如 -v ./local-policy:/etc/referrers/policy）持久化自定义策略，避免容器重启后配置丢失。
• 日志数据：日志默认输出到标准输出（stdout），可通过 Docker 日志驱动收集；也可配置日志文件路径（通过 LOG_FILE 环境变量），并挂载卷持久化（如 -v ./logs:/var/log/referrers）。
• 证书文件：若 staging 环境镜像仓库使用自签名 TLS 证书，需将 CA 证书挂载到容器内（如 -v ./certs:/etc/ssl/certs），并配置系统信任（或通过工具参数 --ca-cert /etc/ssl/certs/ca.crt 指定）。

5. 注意事项

• 权限控制：运行容器时建议使用非 root 用户（可通过 --user 参数指定），降低安全风险。
• 资源限制：staging 环境资源可能有限，建议通过 --memory 和 --cpus 参数限制容器资源（如 --memory 512m --cpus 0.5）。
• 版本兼容性：确保镜像版本与 staging 环境的 OCI 镜像仓库版本兼容（建议使用镜像仓库官方文档推荐的 OCI Referrers API 版本）。
• 认证安全：避免在命令行或配置文件中明文存储认证信息，优先使用环境变量注入或密钥管理服务（如 Vault）动态获取。