人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载本文面向 ZeroClaw 的维护者与安全研究者完整解读仓库中docs/maintainers/release-attestation-runbook.md定义的发布制品签名流程release-stable-manual.yml工作流的publish任务如何按固定顺序生成 SBOM、签署可下载产物、打包离线验证归档并发布 GitHub Release同时结合 .github/workflows/release-stable-manual.yml、release-verification.md、slsa-provenance.md 与自动化契约测试说明每一步的底层原理、失败时的预期行为以及维护者必须执行的发布演练rehearsal。读完本文你可以独立完成一次 ZeroClaw 稳定版发布的在线/离线签名验证并能按清单排查发布签名链路中的各类故障。一、契约总览什么是 ZeroClaw 的发布签名机制ZeroClaw 将GitHub artifact attestationsGitHub 制品签名确立为所有可下载发布产物的唯一权威来源机制canonical downloadable-asset mechanism。每次成功的签名都会把产物的摘要digest、源提交source commit和发布工作流身份记录为SLSA v1.0 Build Level 2的 provenance来源证明。该机制的核心载体是 .github/workflows/release-stable-manual.yml 中的publish任务。它遵循 best-effort Phase A 策略——所有签名与归档步骤都带continue-on-error: true即失败不会阻塞发布但必须在发布说明中披露缺失项。值得强调的是签名机制验证的是产物在哪里、由谁、按什么指令构建build origin 与 build instructions它不证明源码经过人工审查、依赖安全无漏洞也不证明维护者账号、GitHub 托管 Runner 或 GitHub 控制面未被攻破。完整的威胁模型见 docs/security/slsa-provenance.md。二、publish 任务的执行序列顺序即契约publish任务按以下顺序执行 8 个操作任何一步都不能调整生成SPDX 与 CycloneDX 两种格式的 SBOM软件物料清单收集全部发布载荷包括install.sh与两份 SBOM通过 GitHub 对这些载荷进行attestation 签名下载并本地校验每一个离线 bundle将 bundle、可信根trusted root与索引打包为一个验证归档生成最终SHA256SUMS其中包含验证归档本身对SHA256SUMS与验证归档分别签名从release-assets/*创建 GitHub Release。两个不可违反的顺序约束不得把校验和生成提前到归档创建之前——否则归档创建后校验和即过期不得在签名之后编辑SHA256SUMS——任何修改都会产生 stale metadata陈旧元数据导致已签名内容与实际发布内容不一致。这一顺序约束并非只是文档约定仓库还通过自动化契约测试将其固化scripts/ci/release_attestation_contract_test.py 中的test_final_checksums_follow_archive_and_are_never_rewritten直接断言了verification_archive步骤必须出现在 Generate final checksums 之前、校验和签名必须在归档签名之前、且全部必须在 Create tag and release 之前test_verification_archive_is_staged_and_validated_before_publication则断言归档先在$RUNNER_TEMP下构建、用tar -tzf验证可读后才mv进release-assets避免损坏的归档进入发布目录。2.1 签名动作的精细设计工作流中对actions/attest的使用恰好是3 次契约测试test_direct_attestation_action_is_used_exactly_three_times断言步骤 id签名对象作用attest_payloadsrelease-assets/*全部二进制、install.sh、两份 SBOM为每个可下载载荷生成 provenanceattest_checksumsrelease-assets/SHA256SUMS为最终校验和文件签名attest_verification_archivezeroclaw-tag-verification.tar.gz为离线验证归档签名attest_verification_archive步骤的条件是steps.verification_archive.outcome successverification_archive步骤又要求attest_payloads.outcome success。也就是说只有载荷签名成功才允许打包离线归档只有归档打包成功才对其签名。同时契约测试明确禁止了冗余签名路径的存在工作流中不得出现slsa-framework/slsa-github-generator、cosign sign-blob、hash-artifacts:等旧式签名机制cosign 仅保留在docker任务中用于 GHCR 容器镜像签名。2.2 权限模型OIDC 令牌的最小化授予publish任务在 job 级别声明三个权限permissions: contents: write id-token: write attestations: write契约测试test_publish_keeps_required_attestation_permissions与test_sboms_are_read_only_inputs_to_publish验证id-token: write与attestations: write只在publish任务出现而 SBOM 生成任务仅持有contents: read。工作流顶层的注释说明了设计动机OIDC 令牌按 job 授予非签名 job 无法铸造 OIDC 令牌避免validate、build、redeploy等任务意外获得 keyless 签名能力。三、失败症状矩阵签名链路故障时会发生什么由于采用 best-effort 策略不同步骤失败对发布的影响各不相同维护者必须按下面的矩阵预期行为失败步骤预期发布行为消费者影响Attest release payloads签名发布载荷发布继续没有任何可下载载荷具备可信来源证明发布说明须披露该缺口Package offline verification archive打包离线验证归档发布继续在线载荷验证仍然可用但不发布离线归档Attest final checksums签名最终校验和发布继续载荷仍可验证但发布说明不宣传离线引导offline bootstrap路径Attest verification archive签名验证归档发布继续归档可能存在但发布说明不宣传用于可信离线暂存任一 SBOM 生成步骤发布在公开前停止既不会发布部分 SBOM 覆盖也不会发布半组装好的 release最后一行是唯一硬阻断SBOM 是发布的前置依赖缺少任一格式都会让publish的 Verify required release assets 步骤直接失败——该步骤会检查 12 项必需资产6 个 Linux/Android tar.gz、2 个 macOS tar.gz、1 个 Windows zip、DMG、2 份 SBOM任何缺失都会exit 1。3.1 故障分类瞬时错误 vs 工作流回归瞬时故障HTTP 401、429、5xx、OIDC-token 错误或 GitHub API 失败。应查看 GitHub Status 等服务健康状态待服务恢复后重试整个工作流。工作流回归缺少id-token: write或attestations: write权限。这是工作流定义本身的回归重试无效必须修复权限配置。签名有一个根本性约束需要牢记attestation 依赖工作流运行时的 GitHub 签发 OIDC 令牌无法事后在维护者工作站上重建。因此一旦某个发布跑完而未成功签名该发布的签名缺口是永久性的只能靠发布说明披露。四、发布演练Rehearsal更改契约后的强制检查清单每当改动发布签名契约例如调整工作流、签名动作或归档内容之后下一次发布必须由人工维护者在关闭 issue #9101 之前完整执行下面的清单。仅凭工作流 lint、dry run 或历史发布记录都不能替代本次演练[ ] Release contains both SBOM formats. [ ] Release contains SHA256SUMS and exactly one *-verification.tar.gz. [ ] Release contains no *.bundle, loose *.attestation.jsonl, or *.intoto.jsonl assets. [ ] SHA256SUMS contains the verification archive and all other release assets. [ ] gh attestation verify succeeds online for a binary, install.sh, one SBOM, SHA256SUMS, and the verification archive. [ ] The archive contains trusted_root.jsonl, ATTESTATION-BUNDLES.md, and one bundle for every payload listed in its index. [ ] With network access disabled, gh attestation verify succeeds for the spot-checked binary using only its extracted bundle and trusted root. [ ] Both GHCR image variants remain cosign-verifiable by immutable digest. [ ] Release notes state the Build Level 2 claim and threat-model limits.演练的执行要求是全量、真实的必须把发布标签、工作流运行 URL、所用命令与脱敏后的输出记录到实现该变更的 PR 中不得以工作流 lint 通过dry run 成功或上次发布没问题作为演练完成的依据。关于禁止散落签名产物这一点仓库有双重保障归档内的 bundle 统一命名为artifact.attestation.jsonl并集中存放且契约测试test_release_uploads_only_the_consolidated_asset_directory断言发布只通过gh release create $TAG release-assets/*上传整合目录不存在gh release upload的散装上传路径。五、手动巡检命令维护者现场验证演练与日常巡检可直接使用下面的命令序列注意TAG与SOURCE_DIGEST两个变量需要先填写TAGvX.Y.Z SOURCE_DIGESTrelease-commit-sha VERIFY_ARCHIVEzeroclaw-${TAG}-verification.tar.gz gh release view $TAG --repo zeroclaw-labs/zeroclaw \ --json assets --jq .assets[].name gh release download $TAG --repo zeroclaw-labs/zeroclaw \ --pattern SHA256SUMS --pattern $VERIFY_ARCHIVE awk -v file$VERIFY_ARCHIVE $2 file { print } SHA256SUMS | sha256sum -c - gh attestation verify $VERIFY_ARCHIVE \ --repo zeroclaw-labs/zeroclaw \ --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \ --source-digest $SOURCE_DIGEST tar -tzf $VERIFY_ARCHIVE这段脚本的作用逐条说明gh release view --json assets --jq .assets[].name列出发布页全部资产名用于确认恰好一个*-verification.tar.gz、两份 SBOM 与SHA256SUMS存在且没有散落的.attestation.jsonlgh release download只拉取校验和文件与验证归档awk ... | sha256sum -c -从SHA256SUMS中精确提取归档对应行做本地摘要校验而非校验整个文件gh attestation verify在线验证归档的 provenance指定 signer 工作流与源提交摘要tar -tzf确认归档内容可读。归档内部的结构约定由 docs/security/slsa-provenance.md 与 release-verification.md 共同确认为每个发布载荷对应一个artifact.attestation.jsonl离线签名 bundletrusted_root.jsonlGitHub 与 Sigstore 的可信根材料ATTESTATION-BUNDLES.md制品名、SHA-256 摘要与 bundle 名的索引表。六、消费者视角在线验证与离线验证维护者巡检命令与消费者验证命令保持同一套参数约定。完整的消费者命令以 docs/book/src/maintainers/release-verification.md 为准且演练时必须逐字verbatim测试这些命令。6.1 在线验证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_DIGESTSOURCE_DIGEST必须使用发布标签指向的完整提交 SHA。同样的命令适用于install.sh、SHA256SUMS、两份 SBOM 与验证归档。6.2 离线验证隔离网络环境归档不能包含自身的签名 bundle——否则会改变被签名的摘要形成循环依赖。因此离线验证的正确姿势是先在联网暂存环境在线验证归档与SHA256SUMS再把它们与载荷一起搬入离线环境# 联网暂存步骤 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# 断网验证步骤不再发起任何网络请求 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断网验证的关键在于--bundle与--custom-trusted-root两个参数前者指向从归档解出的本地 bundle后者指向本地可信根从而完全摆脱对 GitHub 的实时查询。注意SHA256SUMS与验证归档是在线引导元数据归档内不包含它们自身的 bundle而归档创建前存在的所有载荷含install.sh与两份 SBOM都各有 bundle。七、SBOM 与容器镜像另外两条可验证的发布面7.1 双格式 SBOM每个稳定版发布两份被校验和被签名的 SBOM文件格式zeroclaw-vX.Y.Z-sbom.spdx.jsonSPDX JSONzeroclaw-vX.Y.Z-sbom.cdx.jsonCycloneDX JSON生成动作位于sbom任务使用anchore/sbom-action对仓库根路径扫描两次分别输出spdx-json与cyclonedx-json。这两份 SBOM 是publish的只读输入——该任务权限只有contents: read契约测试test_sboms_are_read_only_inputs_to_publish专门防回归从权限层面杜绝 SBOM 生成任务本身被用于签名。消费者可用与二进制相同的在线/离线签名命令验证 SBOM之后再用 Syft 或 Grype 等工具分析其内容。7.2 GHCR 容器镜像cosign 按摘要签名容器镜像走独立于 GitHub attestation 的 cosign 路径。docker任务用sigstore/cosign-installer安装 cosignbuild-push-action推送后用cosign sign --yes按**不可变摘要digest**签名——先解析出build-push.outputs.digest再对ghcr.io/zeroclaw-labs/zeroclawdigest签名这样即使标签被改动签名仍然有效。演练清单要求两种 GHCR 镜像变体标准版与-debian变体均可按摘要通过 cosign 验证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}而非可变标签。八、安全边界provenance 能证明什么不能证明什么仓库在 docs/security/slsa-provenance.md 中给出了完整的威胁模型摘要如下威胁是否覆盖说明发布页写权限替换载荷是被替换的文件与已签名摘要不匹配验证失败把本地构建冒充官方 CI 构建是signer 工作流与源摘要检查会失败开发者机器被入侵部分本地伪造产物验证失败但被盗的维护者凭证可能授权仓库变更恶意/脆弱依赖否Provenance 只记录来源SBOM 与漏洞分析才负责内容被入侵的 GitHub 托管 Runner否Runner 可在签名步骤之前篡改输入被入侵的维护者账号否有权限的账号可改源码或工作流指令GitHub OIDC 或控制面被入侵否GitHub 是签名与签名存储的信任根Phase A 签名缺失否尽力而为的失败会在发布说明中披露消费者不得把缺失当作成功这一边界也直接影响发布说明的措辞工作流会在 release notes 中追加 Verify SLSA Provenance 章节声明SLSA v1.0 Build Level 2主张并明确其局限——provenance proves build origin and instructions, not human review or immunity from maintainer-account, runner, dependency, or GitHub control-plane compromise。若载荷签名失败发布说明则改为披露 Provenance attestation was unavailable in this best-effort Phase A release 并附上工作流运行链接。九、与发布主流程的衔接签名链路的执行节点位于整体发布流程的publish任务其上游依赖validate、release-notes、build、build-desktop、build-desktop-linux、build-desktop-windows、sbom七个任务。build任务矩阵覆盖 10 个目标含 4 个 Linux 变体、2 个 macOS、Android、Windows 等先由 xtask 的cargo generate features --selection dist解析特性集再以--no-default-features --features构建并顺带构建zerocodeTUI 与zerorelay中继build-desktop则产出 macOS Universal DMG。这些构建产物全部进入release-assets后才轮到签名、归档、校验和与发布——这也解释了为什么该工作流 90 分钟超时上限、发布窗口如此紧张从而引出发布前必须先本地 dry-run见 release-runbook.md 的 Step 3的纪律。十、总结把发布签名当作一条可测试的契约ZeroClaw 的发布签名体系有三个值得其他项目借鉴的设计点顺序即安全签名 → 打包归档 → 最终校验和 → 元数据签名 → 发布每一环都依赖前序产物SHA256SUMS一旦签名就不可再动best-effort 但要透明失败不阻断发布但发布说明必须披露缺口并链接工作流运行消费者据此判断可用的验证材料契约测试固化scripts/ci/release_attestation_contract_test.py 把权限最小化、步骤顺序、归档暂存校验、禁止冗余签名路径等安全属性全部转成单测任何工作流改动若破坏这些属性CI 直接失败。对 ZeroClaw 维护者而言实际执行时只需记住三件事改动签名契约后必须跑完整演练清单巡检用gh attestation verifysha256sum -c这套固定命令离线场景务必先在线验证归档与SHA256SUMS再用--bundle与--custom-trusted-root完成断网验证。这样每次稳定版发布都能为消费者提供可追溯、可离线复核的供应链安全证据。赞分享人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载相关推荐ZeroClaw 发布工件验证指南基于 GitHub Artifact Attestations 的 SLSA 在线与离线验证ZeroClaw 发布工件验证指南基于 GitHub Artifact Attestations 的 SLSA 在线与离线验证 ZeroClaw 以 GitH人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAGGoCD制品签名验证自动化验签与部署控制GoCD制品签名验证自动化验签与部署控制 1. 制品安全挑战与GoCD解决方案 在持续集成/持续部署CI/CD流程中制品Artifact作为代码从开CI/CDDevOps后端任务调度Authelia 制品签名与 SLSA 供应链溯源验证指南Authelia 制品签名与 SLSA 供应链溯源验证指南 本指南基于 Authelia 官方安全文档系统讲解 Authelia 发布制品的 GPG 签名体系后端认证鉴权单点登录身份认证应用安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ZeroClaw 发布制品签名与验证 Runbook：GitHub Artifact Attestations 实战指南
人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载本文面向 ZeroClaw 的维护者与安全研究者完整解读仓库中docs/maintainers/release-attestation-runbook.md定义的发布制品签名流程release-stable-manual.yml工作流的publish任务如何按固定顺序生成 SBOM、签署可下载产物、打包离线验证归档并发布 GitHub Release同时结合 .github/workflows/release-stable-manual.yml、release-verification.md、slsa-provenance.md 与自动化契约测试说明每一步的底层原理、失败时的预期行为以及维护者必须执行的发布演练rehearsal。读完本文你可以独立完成一次 ZeroClaw 稳定版发布的在线/离线签名验证并能按清单排查发布签名链路中的各类故障。一、契约总览什么是 ZeroClaw 的发布签名机制ZeroClaw 将GitHub artifact attestationsGitHub 制品签名确立为所有可下载发布产物的唯一权威来源机制canonical downloadable-asset mechanism。每次成功的签名都会把产物的摘要digest、源提交source commit和发布工作流身份记录为SLSA v1.0 Build Level 2的 provenance来源证明。该机制的核心载体是 .github/workflows/release-stable-manual.yml 中的publish任务。它遵循 best-effort Phase A 策略——所有签名与归档步骤都带continue-on-error: true即失败不会阻塞发布但必须在发布说明中披露缺失项。值得强调的是签名机制验证的是产物在哪里、由谁、按什么指令构建build origin 与 build instructions它不证明源码经过人工审查、依赖安全无漏洞也不证明维护者账号、GitHub 托管 Runner 或 GitHub 控制面未被攻破。完整的威胁模型见 docs/security/slsa-provenance.md。二、publish 任务的执行序列顺序即契约publish任务按以下顺序执行 8 个操作任何一步都不能调整生成SPDX 与 CycloneDX 两种格式的 SBOM软件物料清单收集全部发布载荷包括install.sh与两份 SBOM通过 GitHub 对这些载荷进行attestation 签名下载并本地校验每一个离线 bundle将 bundle、可信根trusted root与索引打包为一个验证归档生成最终SHA256SUMS其中包含验证归档本身对SHA256SUMS与验证归档分别签名从release-assets/*创建 GitHub Release。两个不可违反的顺序约束不得把校验和生成提前到归档创建之前——否则归档创建后校验和即过期不得在签名之后编辑SHA256SUMS——任何修改都会产生 stale metadata陈旧元数据导致已签名内容与实际发布内容不一致。这一顺序约束并非只是文档约定仓库还通过自动化契约测试将其固化scripts/ci/release_attestation_contract_test.py 中的test_final_checksums_follow_archive_and_are_never_rewritten直接断言了verification_archive步骤必须出现在 Generate final checksums 之前、校验和签名必须在归档签名之前、且全部必须在 Create tag and release 之前test_verification_archive_is_staged_and_validated_before_publication则断言归档先在$RUNNER_TEMP下构建、用tar -tzf验证可读后才mv进release-assets避免损坏的归档进入发布目录。2.1 签名动作的精细设计工作流中对actions/attest的使用恰好是3 次契约测试test_direct_attestation_action_is_used_exactly_three_times断言步骤 id签名对象作用attest_payloadsrelease-assets/*全部二进制、install.sh、两份 SBOM为每个可下载载荷生成 provenanceattest_checksumsrelease-assets/SHA256SUMS为最终校验和文件签名attest_verification_archivezeroclaw-tag-verification.tar.gz为离线验证归档签名attest_verification_archive步骤的条件是steps.verification_archive.outcome successverification_archive步骤又要求attest_payloads.outcome success。也就是说只有载荷签名成功才允许打包离线归档只有归档打包成功才对其签名。同时契约测试明确禁止了冗余签名路径的存在工作流中不得出现slsa-framework/slsa-github-generator、cosign sign-blob、hash-artifacts:等旧式签名机制cosign 仅保留在docker任务中用于 GHCR 容器镜像签名。2.2 权限模型OIDC 令牌的最小化授予publish任务在 job 级别声明三个权限permissions: contents: write id-token: write attestations: write契约测试test_publish_keeps_required_attestation_permissions与test_sboms_are_read_only_inputs_to_publish验证id-token: write与attestations: write只在publish任务出现而 SBOM 生成任务仅持有contents: read。工作流顶层的注释说明了设计动机OIDC 令牌按 job 授予非签名 job 无法铸造 OIDC 令牌避免validate、build、redeploy等任务意外获得 keyless 签名能力。三、失败症状矩阵签名链路故障时会发生什么由于采用 best-effort 策略不同步骤失败对发布的影响各不相同维护者必须按下面的矩阵预期行为失败步骤预期发布行为消费者影响Attest release payloads签名发布载荷发布继续没有任何可下载载荷具备可信来源证明发布说明须披露该缺口Package offline verification archive打包离线验证归档发布继续在线载荷验证仍然可用但不发布离线归档Attest final checksums签名最终校验和发布继续载荷仍可验证但发布说明不宣传离线引导offline bootstrap路径Attest verification archive签名验证归档发布继续归档可能存在但发布说明不宣传用于可信离线暂存任一 SBOM 生成步骤发布在公开前停止既不会发布部分 SBOM 覆盖也不会发布半组装好的 release最后一行是唯一硬阻断SBOM 是发布的前置依赖缺少任一格式都会让publish的 Verify required release assets 步骤直接失败——该步骤会检查 12 项必需资产6 个 Linux/Android tar.gz、2 个 macOS tar.gz、1 个 Windows zip、DMG、2 份 SBOM任何缺失都会exit 1。3.1 故障分类瞬时错误 vs 工作流回归瞬时故障HTTP 401、429、5xx、OIDC-token 错误或 GitHub API 失败。应查看 GitHub Status 等服务健康状态待服务恢复后重试整个工作流。工作流回归缺少id-token: write或attestations: write权限。这是工作流定义本身的回归重试无效必须修复权限配置。签名有一个根本性约束需要牢记attestation 依赖工作流运行时的 GitHub 签发 OIDC 令牌无法事后在维护者工作站上重建。因此一旦某个发布跑完而未成功签名该发布的签名缺口是永久性的只能靠发布说明披露。四、发布演练Rehearsal更改契约后的强制检查清单每当改动发布签名契约例如调整工作流、签名动作或归档内容之后下一次发布必须由人工维护者在关闭 issue #9101 之前完整执行下面的清单。仅凭工作流 lint、dry run 或历史发布记录都不能替代本次演练[ ] Release contains both SBOM formats. [ ] Release contains SHA256SUMS and exactly one *-verification.tar.gz. [ ] Release contains no *.bundle, loose *.attestation.jsonl, or *.intoto.jsonl assets. [ ] SHA256SUMS contains the verification archive and all other release assets. [ ] gh attestation verify succeeds online for a binary, install.sh, one SBOM, SHA256SUMS, and the verification archive. [ ] The archive contains trusted_root.jsonl, ATTESTATION-BUNDLES.md, and one bundle for every payload listed in its index. [ ] With network access disabled, gh attestation verify succeeds for the spot-checked binary using only its extracted bundle and trusted root. [ ] Both GHCR image variants remain cosign-verifiable by immutable digest. [ ] Release notes state the Build Level 2 claim and threat-model limits.演练的执行要求是全量、真实的必须把发布标签、工作流运行 URL、所用命令与脱敏后的输出记录到实现该变更的 PR 中不得以工作流 lint 通过dry run 成功或上次发布没问题作为演练完成的依据。关于禁止散落签名产物这一点仓库有双重保障归档内的 bundle 统一命名为artifact.attestation.jsonl并集中存放且契约测试test_release_uploads_only_the_consolidated_asset_directory断言发布只通过gh release create $TAG release-assets/*上传整合目录不存在gh release upload的散装上传路径。五、手动巡检命令维护者现场验证演练与日常巡检可直接使用下面的命令序列注意TAG与SOURCE_DIGEST两个变量需要先填写TAGvX.Y.Z SOURCE_DIGESTrelease-commit-sha VERIFY_ARCHIVEzeroclaw-${TAG}-verification.tar.gz gh release view $TAG --repo zeroclaw-labs/zeroclaw \ --json assets --jq .assets[].name gh release download $TAG --repo zeroclaw-labs/zeroclaw \ --pattern SHA256SUMS --pattern $VERIFY_ARCHIVE awk -v file$VERIFY_ARCHIVE $2 file { print } SHA256SUMS | sha256sum -c - gh attestation verify $VERIFY_ARCHIVE \ --repo zeroclaw-labs/zeroclaw \ --signer-workflow zeroclaw-labs/zeroclaw/.github/workflows/release-stable-manual.yml \ --source-digest $SOURCE_DIGEST tar -tzf $VERIFY_ARCHIVE这段脚本的作用逐条说明gh release view --json assets --jq .assets[].name列出发布页全部资产名用于确认恰好一个*-verification.tar.gz、两份 SBOM 与SHA256SUMS存在且没有散落的.attestation.jsonlgh release download只拉取校验和文件与验证归档awk ... | sha256sum -c -从SHA256SUMS中精确提取归档对应行做本地摘要校验而非校验整个文件gh attestation verify在线验证归档的 provenance指定 signer 工作流与源提交摘要tar -tzf确认归档内容可读。归档内部的结构约定由 docs/security/slsa-provenance.md 与 release-verification.md 共同确认为每个发布载荷对应一个artifact.attestation.jsonl离线签名 bundletrusted_root.jsonlGitHub 与 Sigstore 的可信根材料ATTESTATION-BUNDLES.md制品名、SHA-256 摘要与 bundle 名的索引表。六、消费者视角在线验证与离线验证维护者巡检命令与消费者验证命令保持同一套参数约定。完整的消费者命令以 docs/book/src/maintainers/release-verification.md 为准且演练时必须逐字verbatim测试这些命令。6.1 在线验证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_DIGESTSOURCE_DIGEST必须使用发布标签指向的完整提交 SHA。同样的命令适用于install.sh、SHA256SUMS、两份 SBOM 与验证归档。6.2 离线验证隔离网络环境归档不能包含自身的签名 bundle——否则会改变被签名的摘要形成循环依赖。因此离线验证的正确姿势是先在联网暂存环境在线验证归档与SHA256SUMS再把它们与载荷一起搬入离线环境# 联网暂存步骤 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# 断网验证步骤不再发起任何网络请求 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断网验证的关键在于--bundle与--custom-trusted-root两个参数前者指向从归档解出的本地 bundle后者指向本地可信根从而完全摆脱对 GitHub 的实时查询。注意SHA256SUMS与验证归档是在线引导元数据归档内不包含它们自身的 bundle而归档创建前存在的所有载荷含install.sh与两份 SBOM都各有 bundle。七、SBOM 与容器镜像另外两条可验证的发布面7.1 双格式 SBOM每个稳定版发布两份被校验和被签名的 SBOM文件格式zeroclaw-vX.Y.Z-sbom.spdx.jsonSPDX JSONzeroclaw-vX.Y.Z-sbom.cdx.jsonCycloneDX JSON生成动作位于sbom任务使用anchore/sbom-action对仓库根路径扫描两次分别输出spdx-json与cyclonedx-json。这两份 SBOM 是publish的只读输入——该任务权限只有contents: read契约测试test_sboms_are_read_only_inputs_to_publish专门防回归从权限层面杜绝 SBOM 生成任务本身被用于签名。消费者可用与二进制相同的在线/离线签名命令验证 SBOM之后再用 Syft 或 Grype 等工具分析其内容。7.2 GHCR 容器镜像cosign 按摘要签名容器镜像走独立于 GitHub attestation 的 cosign 路径。docker任务用sigstore/cosign-installer安装 cosignbuild-push-action推送后用cosign sign --yes按**不可变摘要digest**签名——先解析出build-push.outputs.digest再对ghcr.io/zeroclaw-labs/zeroclawdigest签名这样即使标签被改动签名仍然有效。演练清单要求两种 GHCR 镜像变体标准版与-debian变体均可按摘要通过 cosign 验证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}而非可变标签。八、安全边界provenance 能证明什么不能证明什么仓库在 docs/security/slsa-provenance.md 中给出了完整的威胁模型摘要如下威胁是否覆盖说明发布页写权限替换载荷是被替换的文件与已签名摘要不匹配验证失败把本地构建冒充官方 CI 构建是signer 工作流与源摘要检查会失败开发者机器被入侵部分本地伪造产物验证失败但被盗的维护者凭证可能授权仓库变更恶意/脆弱依赖否Provenance 只记录来源SBOM 与漏洞分析才负责内容被入侵的 GitHub 托管 Runner否Runner 可在签名步骤之前篡改输入被入侵的维护者账号否有权限的账号可改源码或工作流指令GitHub OIDC 或控制面被入侵否GitHub 是签名与签名存储的信任根Phase A 签名缺失否尽力而为的失败会在发布说明中披露消费者不得把缺失当作成功这一边界也直接影响发布说明的措辞工作流会在 release notes 中追加 Verify SLSA Provenance 章节声明SLSA v1.0 Build Level 2主张并明确其局限——provenance proves build origin and instructions, not human review or immunity from maintainer-account, runner, dependency, or GitHub control-plane compromise。若载荷签名失败发布说明则改为披露 Provenance attestation was unavailable in this best-effort Phase A release 并附上工作流运行链接。九、与发布主流程的衔接签名链路的执行节点位于整体发布流程的publish任务其上游依赖validate、release-notes、build、build-desktop、build-desktop-linux、build-desktop-windows、sbom七个任务。build任务矩阵覆盖 10 个目标含 4 个 Linux 变体、2 个 macOS、Android、Windows 等先由 xtask 的cargo generate features --selection dist解析特性集再以--no-default-features --features构建并顺带构建zerocodeTUI 与zerorelay中继build-desktop则产出 macOS Universal DMG。这些构建产物全部进入release-assets后才轮到签名、归档、校验和与发布——这也解释了为什么该工作流 90 分钟超时上限、发布窗口如此紧张从而引出发布前必须先本地 dry-run见 release-runbook.md 的 Step 3的纪律。十、总结把发布签名当作一条可测试的契约ZeroClaw 的发布签名体系有三个值得其他项目借鉴的设计点顺序即安全签名 → 打包归档 → 最终校验和 → 元数据签名 → 发布每一环都依赖前序产物SHA256SUMS一旦签名就不可再动best-effort 但要透明失败不阻断发布但发布说明必须披露缺口并链接工作流运行消费者据此判断可用的验证材料契约测试固化scripts/ci/release_attestation_contract_test.py 把权限最小化、步骤顺序、归档暂存校验、禁止冗余签名路径等安全属性全部转成单测任何工作流改动若破坏这些属性CI 直接失败。对 ZeroClaw 维护者而言实际执行时只需记住三件事改动签名契约后必须跑完整演练清单巡检用gh attestation verifysha256sum -c这套固定命令离线场景务必先在线验证归档与SHA256SUMS再用--bundle与--custom-trusted-root完成断网验证。这样每次稳定版发布都能为消费者提供可追溯、可离线复核的供应链安全证据。赞分享人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载相关推荐ZeroClaw 发布工件验证指南基于 GitHub Artifact Attestations 的 SLSA 在线与离线验证ZeroClaw 发布工件验证指南基于 GitHub Artifact Attestations 的 SLSA 在线与离线验证 ZeroClaw 以 GitH人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAGGoCD制品签名验证自动化验签与部署控制GoCD制品签名验证自动化验签与部署控制 1. 制品安全挑战与GoCD解决方案 在持续集成/持续部署CI/CD流程中制品Artifact作为代码从开CI/CDDevOps后端任务调度Authelia 制品签名与 SLSA 供应链溯源验证指南Authelia 制品签名与 SLSA 供应链溯源验证指南 本指南基于 Authelia 官方安全文档系统讲解 Authelia 发布制品的 GPG 签名体系后端认证鉴权单点登录身份认证应用安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
