ZeroClaw 发布工件验证指南基于 GitHub Artifact Attestations 的 SLSA 在线与离线验证【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 以 GitHub artifact attestations 作为所有可下载发布资产的规范来源canonical provenance机制为每次稳定发布记录资产摘要digest、源码提交与发布工作流身份形成 SLSA v1.0 Build Level 2 出处证明。本指南完整讲解如何在联网环境中在线验证发布资产、如何在完全断网的环境中借助zeroclaw-vX.Y.Z-verification.tar.gz离线归档完成引导式信任验证以及如何核对 SPDX/CycloneDX 双格式 SBOM 与 cosign 签名的 GHCR 容器镜像。读完本文你将掌握 ZeroClaw 从下载即信任升级为可独立核验来源的完整实操路径并理解其证明边界与威胁模型。验证机制概览出处证明能证明什么、不能证明什么ZeroClaw 的发布管线以 release-stable-manual.yml 中的publish任务为核心通过actions/attest当前锁定v4.2.2为每个发布载荷生成 SLSA v1.0 Build Level 2 出处证明并记录在 GitHub 的 artifact-attestation API 中。完整的威胁模型与验证路径定义见 docs/security/slsa-provenance.md。一次成功的验证能够确立本地文件与签名证明attestation中的摘要一致该证明是为 ZeroClaw 仓库签发的release-stable-manual.yml是签名工作流signer workflow证明指向预期的源码提交source commit。它确立的是构建来源与记录的构建指令但不能证明源码经过人工评审、依赖是安全的也不能排除维护者账号、GitHub 托管 runner 或 GitHub 控制平面被攻陷的可能。完整威胁模型如下表源自 slsa-provenance.md威胁是否覆盖说明发布页写入权限被滥用、替换载荷是被替换的文件与已签名摘要不匹配验证失败本地构建被伪装成官方 CI 构建是签名工作流与源码摘要检查失败开发者机器被攻陷部分本地构建的替代物无法通过验证但被窃取的维护者凭证仍可能授权仓库变更恶意或有漏洞的依赖否出处只记录来源内容安全由 SBOM 与漏洞分析负责GitHub 托管 runner 被攻陷否runner 可在证明步骤之前篡改输入维护者账号被攻陷否授权账号可改动源码或工作流指令GitHub OIDC 或控制平面被攻陷否GitHub 是签名与托管证明存储的信任根缺失 Phase A 证明否尽力而为best-effort的失败会在发布说明中披露消费方不得把缺失当作成功发布工作流当前把证明视为尽力而为的 Phase A 输出continue-on-error: true。因此在使用验证材料之前务必先查阅发布说明release notes说明中会明确本次是否产出了在线出处证明与离线归档。若某项证明步骤失败发布仍会继续但发布说明必须披露缺口并链接到对应的工作流运行。在线验证直连 GitHub 核验资产联网环境下验证最简单。安装 GitHub CLI下载资产然后对照发布工作流与源码提交执行验证VERSIONvX.Y.Z SOURCE_DIGEST40-character-release-commit ASSETzeroclaw-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要点说明SOURCE_DIGEST应使用发布 tag 所指向的完整 40 位提交哈希而不是缩写或 tag 名本身--signer-workflow必须精确匹配release-stable-manual.yml的完整仓库路径签名身份绑定在该工作流上验证成功时命令会打印已核验的证明与主题subject摘要同样的命令适用于install.sh、SHA256SUMS、两个 SBOM 文件以及验证归档verification archive。从实现侧看publish任务仅在作业级别授予id-token: write与attestations: write权限见 release-stable-manual.yml工作流级不授予 OIDC 权限因此validate、build等非签名作业无法铸造 OIDC 令牌——这是最小权限原则在签名链路上的体现。离线验证通过验证归档实现断网信任由合并后的发布工作流产出且 Phase A 输出完整的发布会额外发布一个归档zeroclaw-vX.Y.Z-verification.tar.gz。其中包含每个发布载荷对应的一个artifact.attestation.jsonl离线证明包trusted_root.jsonlGitHub 与 Sigstore 的信任根材料ATTESTATION-BUNDLES.md工件名、SHA-256 摘要与包名的索引。注意一个结构性问题归档无法包含对自身的证明否则会形成循环摘要改动归档内容必然改变其被证明的摘要。因此信任引导必须在联网时完成——先在线验证归档与最终校验和文件再将工件、归档与校验和文件一并转移到离线环境。连网暂存步骤Connected stagingVERSIONvX.Y.Z SOURCE_DIGEST40-character-release-commit ASSETzeroclaw-x86_64-unknown-linux-gnu.tar.gz VERIFY_ARCHIVEzeroclaw-${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 -断网验证步骤Disconnected verification当--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.jsonlgh attestation verify在提供了--bundle和--custom-trusted-root后即可完全离线执行这是断网环境下完成密钥级keyless验证的关键。SHA256SUMS与验证归档属于在线引导元数据在归档内部没有对应包而归档构建之前已存在的所有载荷包括install.sh和两个 SBOM都包含各自的离线包。从实现看归档的构建逻辑严格遵循先证明、后打包的顺序见 release-stable-manual.yml先对release-assets/*执行attest_payloads再下载每个离线包并逐一用gh attestation verify校验--bundle指向下载的包、--custom-trusted-root指向刚抓取的信任根随后生成ATTESTATION-BUNDLES.md索引并打包。gh attestation trusted-root抓取信任根且脚本兼容冒号与连字符两种 bundle 文件名形式部分平台文件系统拒绝冒号。最终SHA256SUMS只在归档存在后生成先find后xargs sha256sum排除自身并且不得在元数据证明之后修改——任何修改都会让SHA256SUMS与verification archive的证明失效这正是 release-attestation-runbook.md 强调不要把校验和生成挪到归档创建之前、也不要在证明后编辑 SHA256SUMS的原因。SBOM双格式、带校验和、可验证每次发布都会发布两个经校验和与证明的 SBOM 文件文件格式zeroclaw-vX.Y.Z-sbom.spdx.jsonSPDX JSONzeroclaw-vX.Y.Z-sbom.cdx.jsonCycloneDX JSON对任一 SBOM 使用与二进制资产完全相同的在线或离线证明命令即可核验之后可交给 Syft、Grype 等工具进一步审查其内容。SBOM 由sbom作业中的anchore/sbom-action锁定v0.24.2分别以spdx-json与cyclonedx-json格式生成见 release-stable-manual.yml两个文件都会进入发布资产与验证归档。需要留意的是SBOM 生成属于发布管线的硬性前置任一 SBOM 生成步骤失败都会在发布前终止流程避免发布部分覆盖或半成品的物料清单见 release-attestation-runbook.md 的失败症状表。容器镜像cosign 按摘要签名验证GHCR 容器镜像独立于 GitHub 可下载资产证明路径仍由 cosign 按摘要digest签名二者互不替代。验证命令IMAGEghcr.io/zeroclaw-labs/zeroclaw TAGvX.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}而不是验证可变的 tag。工作流侧docker作业同样只在作业级授予id-token: writecosign 无密钥 OIDC 签名所必需见 release-stable-manual.yml并通过sigstore/cosign-installer锁定v3.8.1执行cosign sign发布后的演练检查清单要求两个 GHCR 镜像变体均能以不可变摘要通过 cosign 验证。发布后的检查清单与演练要求正式发布后维护者应确认以下资产形态源自 release-runbook.md 的 Step 6[ ] GitHub Release 存在且标记为 Latest [ ] Release notes 非空 [ ] SHA256SUMS 资产存在且非空 [ ] SPDX 与 CycloneDX 两个 SBOM 资产均存在 [ ] 恰好一个 zeroclaw-vX.Y.Z-verification.tar.gz 资产存在 [ ] 不存在散落的 *.bundle、*.attestation.jsonl 或 *.intoto.jsonl 资产 [ ] 至少一个二进制归档可下载抽查 linux x86_64 [ ] Docker 预构建与生成矩阵作业均绿色任何涉及发布证明的工作流变更之后必须在关闭追踪 issue 前由人工维护者完整执行一遍在线与断网验证演练命令见 release-attestation-runbook.md并将发布 tag、工作流运行 URL、精确命令与脱敏输出记录在实现 PR 中。仅做工作流 lint 或act本地模拟不能替代该演练——两者都无法铸造 GitHub 生产环境的 OIDC 证明。从实现到消费publish 作业的证明流水线publish作业权限contents: write、id-token: write、attestations: write按固定顺序执行证明相关操作见 release-stable-manual.yml 与 release-attestation-runbook.md生成 SPDX 与 CycloneDX 两个 SBOM收集全部发布载荷包括install.sh与两个 SBOM通过 GitHub 对这些载荷执行证明attest_payloadscontinue-on-error: true下载并本地核验每个离线包gh attestation downloadgh attestation verify失败重试 5 次将包、信任根与索引打包成一个验证归档生成最终SHA256SUMS包含验证归档对SHA256SUMS与验证归档分别证明attest_checksums、attest_verification_archive从release-assets/*创建 GitHub Release。值得注意的失败语义Attest release payloads失败时发布继续此时任何下载载荷都没有可信出处需在发布说明披露Package offline verification archive失败时在线验证仍然可用但无离线归档SBOM 生成失败则发布在发布前停止。HTTP 401/429/5xx、OIDC token 或 GitHub API 故障属于服务性问题可查 GitHub Status 后在服务恢复时重试而缺失id-token: write或attestations: write权限属于工作流回归而非瞬时故障。关键约束是证明依赖工作流运行签发的 GitHub OIDC 令牌事后无法从维护者工作站重建。实践建议与验证边界始终先读发布说明确认本次发布是否声明产出了在线出处证明与离线归档Phase A 尽力而为模式下没有证明不等于验证通过。离线场景走完整引导链先在线验证归档与SHA256SUMS再迁移载荷与解包材料到断网环境最后用--bundle--custom-trusted-root完成零网络验证。固定部署用摘要容器镜像与二进制资产都优先以不可变摘要校验而非可变 tag。理解证明边界SLSA Build Level 2 证明回答的是在哪里、由谁构建不回答代码是否安全内容安全交由 SBOM 与漏洞扫描工具处理。相关仓库证据验证命令的规范来源是 release-verification.md威胁模型与验证路径见 slsa-provenance.md管线实现见 release-stable-manual.yml维护者演练要求见 release-attestation-runbook.md完整发布流程见 release-runbook.md。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
