SeedPass/docs/supply_chain_release_integrity.md

Supply Chain and Release Integrity

This document defines the release trust chain for SeedPass and provides the evidence expected by checklist item #8 in docs/security_readiness_checklist.md.

Scope

• Dependency lock and hash integrity (requirements.lock).
• Vulnerability review process for runtime dependencies.
• Release artifact checksums and signing.

Controls

1. Locked dependencies:

   • Dependencies are pinned and hash-locked in requirements.lock.
   • CI and release automation regenerate the lock file from src/requirements.txt and fail on drift.
   • scripts/release_integrity.py check-lockfile enforces that pinned entries and SHA-256 hashes are present.

2. CVE review:

   • pip-audit runs in CI (.github/workflows/dependency-audit.yml) and at release time (.github/workflows/release-integrity.yml).
   • Vulnerabilities must be remediated before release unless a temporary exception is documented with a tracked advisory ID and owner.
   • Current temporary exception: GHSA-wj6h-64fc-37mp.

3. Artifact integrity:

   • Release artifacts are built with python -m build.
   • scripts/release_integrity.py generate creates a deterministic SHA256SUMS manifest.
   • scripts/release_integrity.py verify re-checks artifacts against SHA256SUMS.
   • SHA256SUMS is signed in GitHub Actions using keyless cosign, producing:
     • SHA256SUMS.sig
     • SHA256SUMS.pem

Release Workflow

Workflow: .github/workflows/release-integrity.yml

On every published GitHub release, the workflow:

1. Verifies lockfile integrity and lock drift.
2. Runs CVE audit on pinned dependencies.
3. Builds source/wheel artifacts.
4. Generates and verifies SHA256SUMS.
5. Signs SHA256SUMS with keyless cosign.
6. Uploads artifacts and integrity files to the GitHub release.

Manual Verification

From a checkout that includes release assets:

python scripts/release_integrity.py verify --checksum-file SHA256SUMS --base-dir .
cosign verify-blob \
  --certificate SHA256SUMS.pem \
  --signature SHA256SUMS.sig \
  SHA256SUMS

Evidence

• Workflow: .github/workflows/release-integrity.yml
• Tooling: scripts/release_integrity.py, src/seedpass/release_integrity.py
• Tests: src/tests/test_release_integrity_utils.py

Remaining Work To Mark Checklist Item #8 Done

1. Execute at least one tagged production release through .github/workflows/release-integrity.yml and record the run URL/artifact links in docs/security_readiness_checklist.md.
2. Eliminate the temporary audit exception (GHSA-wj6h-64fc-37mp) or document formal risk acceptance with expiration date and owner.
3. Add branch/release protection so publishable tags require successful Release Integrity and Dependency Audit checks before release publication.
4. Add maintainer verification runbook for release consumers that includes:
   • python scripts/release_integrity.py verify --checksum-file SHA256SUMS --base-dir .
   • cosign verify-blob --certificate SHA256SUMS.pem --signature SHA256SUMS.sig SHA256SUMS
   • expected identity/issuer constraints for keyless signing.