SeedPass/docs/release_verification_runbook.md

Release Verification Runbook

Purpose: provide maintainers and consumers a deterministic process to verify SeedPass release artifacts and signatures.

Inputs

• Release assets downloaded from GitHub release:
  • SHA256SUMS
  • SHA256SUMS.sig
  • SHA256SUMS.pem
  • distribution artifacts (dist/*.whl, dist/*.tar.gz)
• Local checkout of this repository (for verifier script).

1) Verify artifact checksums

python scripts/release_integrity.py verify --checksum-file SHA256SUMS --base-dir .

Expected result: no mismatches and process exits 0.

2) Verify keyless signature and certificate constraints

cosign verify-blob \
  --certificate SHA256SUMS.pem \
  --signature SHA256SUMS.sig \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/PR0M3TH3AN/SeedPass/.github/workflows/release-integrity.yml@refs/tags/.+$' \
  SHA256SUMS

Expected result:

• signature verification passes,
• certificate issuer is GitHub OIDC,
• certificate identity matches this repository release-integrity.yml workflow on a tag ref.

3) Verify release workflow provenance (maintainers)

1. Open the workflow run referenced by the release.
2. Confirm workflow name: Release Integrity.
3. Confirm job verify-and-sign succeeded.
4. Confirm uploaded assets include:
   • dist/*
   • SHA256SUMS
   • SHA256SUMS.sig
   • SHA256SUMS.pem

4) Failure handling

• If checksum verification fails:
  • treat artifacts as untrusted,
  • re-download release assets,
  • if mismatch persists, open security incident and halt rollout.
• If signature verification fails:
  • treat release as untrusted,
  • verify you used the exact release assets,
  • if still failing, open security incident and halt rollout.

5) Record evidence

For each release, record in docs/security_readiness_checklist.md:

• release tag,
• workflow run URL,
• verification executor/date,
• pass/fail status.