验证发布

每个 DispatchAtlas 发布候选都由单个经审计的工作流构建，该工作流在 Python 分发之外发出一组可独立验证的供应链产物：SHA-256 哈希、Sigstore signature bundles、GitHub build provenance attestations、一个 SBOM attestation，以及一个 CycloneDX software bill of materials。本页说明如何验证每一项。

全文中请将 vX.Y.Z 替换为你下载的发布标签。

📦 附加到发布的产物

产物	用途
`.whl`、`.tar.gz`	Python wheel 与源分发。
`SHA256SUMS.txt`	每个分发产物的 SHA-256 哈希。
`*.sigstore.json`	Sigstore signature bundle（每个产物一个）。
`sbom.cyclonedx.json`	经审计构建环境的 CycloneDX SBOM。

GitHub build provenance 与 SBOM attestations 随仓库的 attestation 记录存储，而非作为发布附件，并通过 GitHub CLI 验证。

🔢 验证哈希

将分发产物与 SHA256SUMS.txt 下载到同一目录，然后检查它们：

sha256sum --check SHA256SUMS.txt

每一行必须报告 OK。

✍️ 验证 Sigstore 签名

发布通过工作流的 OpenID Connect 身份以无密钥 Sigstore 签名为每个产物签名。安装 cosign 并验证某产物的 bundle：

cosign verify-blob \
  --bundle dispatchatlas-vX.Y.Z-py3-none-any.whl.sigstore.json \
  --certificate-identity-regexp 'https://github.com/ahmed-g-gad/dispatchatlas/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  dispatchatlas-vX.Y.Z-py3-none-any.whl

成功运行会打印 Verified OK。同一命令对 SHA256SUMS.txt 与 sbom.cyclonedx.json 针对其 bundle 进行验证。

🧾 验证 GitHub build provenance

每个分发都携带一份签名的 provenance 声明，描述构建它的工作流、提交与 runner。用 GitHub CLI 验证它：

gh attestation verify dispatchatlas-vX.Y.Z-py3-none-any.whl \
  --repo ahmed-g-gad/dispatchatlas

输出确认该产物由发布工作流在预期提交处构建。

🧰 检视 SBOM

CycloneDX SBOM 枚举构建环境中的每个组件及其包 URL、许可证与内容哈希。用任何支持 CycloneDX 的工具检视它，或直接读取组件列表：

python -c "import json; d = json.load(open('sbom.cyclonedx.json')); \
print('\n'.join(c['name'] + ' ' + c.get('version', '') for c in d['components']))"

SBOM 自身亦被 attested；用以下命令验证 SBOM attestation：

gh attestation verify dispatchatlas-vX.Y.Z-py3-none-any.whl \
  --repo ahmed-g-gad/dispatchatlas \
  --predicate-type https://cyclonedx.org/bom

🚨 报告验证失败

若你从官方发布下载的某产物的任何验证步骤失败，请勿安装它。通过项目安全策略中的渠道报告该差异。