发布产物验证

ZeroClaw 使用 GitHub 制品证明作为可下载发布资产的规范溯源机制。每次成功的证明都会将资产摘要、源代码提交和发布工作流标识记录为 SLSA v1.0 Build Level 2 溯源信息。

证明可以表明工件在何处以及如何构建，但无法证明有人审查过源代码、依赖项是否安全，也无法证明维护者账户、GitHub 托管的运行器或 GitHub 控制平面未被入侵。完整的威胁模型请参阅代码库中的 docs/security/slsa-provenance.md。

发布工作流当前将证明视为尽力而为的 A 阶段输出。在依赖验证材料之前，请查阅发布说明；其中会说明在线溯源信息和离线存档是否已生成。

在线验证

安装 GitHub CLI，下载一个资源文件，并对照发布工作流和源提交进行验证：

VERSION=vX.Y.Z
SOURCE_DIGEST=<40-character-release-commit>
ASSET=zeroclaw-x86_64-unknown-linux-gnu.tar.gz

gh release download "$VERSION" --repo zeroclaw-labs/zeroclaw \
  --pattern "$ASSET"
gh attestation verify "$ASSET" \
  --repo zeroclaw-labs/zeroclaw \
  --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
  --source-digest "$SOURCE_DIGEST"

使用发布标签所显示的完整提交。命令执行成功后会打印已验证的证明和主题摘要。同一命令同样适用于 install.sh、SHA256SUMS、两个 SBOM 文件以及验证归档文件。

离线验证

由整合工作流生成、具备完整 Phase A 输出的发布，会发布一个名为 zeroclaw-vX.Y.Z-verification.tar.gz 的归档文件。其中包含：

为每个发布负载生成一个 <artifact>.attestation.jsonl 包；
trusted_root.jsonl，GitHub 和 Sigstore 的可信根材料；
ATTESTATION-BUNDLES.md，一个包含制品名称、SHA-256 摘要和 bundle 名称的索引。

归档文件不能包含其自身的证明，否则会产生循环摘要。在联网状态下，通过在线验证归档文件和最终校验和文件来建立初始信任。然后将制品、归档文件和校验和文件传输到离线环境。

已连接的暂存步骤

VERSION=vX.Y.Z
SOURCE_DIGEST=<40-character-release-commit>
ASSET=zeroclaw-x86_64-unknown-linux-gnu.tar.gz
VERIFY_ARCHIVE="zeroclaw-${VERSION}-verification.tar.gz"

gh release download "$VERSION" --repo zeroclaw-labs/zeroclaw \
  --pattern "$ASSET" \
  --pattern SHA256SUMS \
  --pattern "$VERIFY_ARCHIVE"

gh attestation verify "$VERIFY_ARCHIVE" \
  --repo zeroclaw-labs/zeroclaw \
  --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
  --source-digest "$SOURCE_DIGEST"
gh attestation verify SHA256SUMS \
  --repo zeroclaw-labs/zeroclaw \
  --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
  --source-digest "$SOURCE_DIGEST"

awk -v file="$VERIFY_ARCHIVE" '$2 == file { print }' SHA256SUMS | sha256sum -c -
mkdir verification
tar -xzf "$VERIFY_ARCHIVE" -C verification

在传输之前，还需将构件摘要与 SHA256SUMS 中对应的行进行比对：

awk -v file="$ASSET" '$2 == file { print }' SHA256SUMS | sha256sum -c -

离线验证步骤

当 --bundle 和 --custom-trusted-root 均指向暂存的验证材料时，无需发起任何网络请求：

gh attestation verify "$ASSET" \
  --repo zeroclaw-labs/zeroclaw \
  --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \
  --source-digest "$SOURCE_DIGEST" \
  --bundle "verification/${ASSET}.attestation.jsonl" \
  --custom-trusted-root verification/trusted_root.jsonl

SHA256SUMS 和验证存档是在线引导元数据，存档内部不包含 bundle。所有在存档构建之前就已存在的载荷，包括 install.sh 和两个 SBOM，则包含在内。

软件物料清单

每个版本都会发布两个带有校验和并经过证明的 SBOM 文件：

文件	格式
`zeroclaw-vX.Y.Z-sbom.spdx.json`	SPDX JSON
`zeroclaw-vX.Y.Z-sbom.cdx.json`	CycloneDX JSON

使用与二进制资产相同的在线或离线证明命令验证任一 SBOM。随后，Syft 或 Grype 等工具即可检查经过验证的文件。

容器镜像

GHCR 容器镜像仍由 cosign 按摘要签名。这与可下载发布资产的 GitHub-attestation 路径无关。

IMAGE=ghcr.io/zeroclaw-labs/zeroclaw
TAG=vX.Y.Z

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "^https://github.com/zeroclaw-labs/zeroclaw/" \
  "${IMAGE}:${TAG}"

对于固定部署，解析摘要并验证 ${IMAGE}@${DIGEST}，而非可变标签。

Keyboard shortcuts