Skip to content

release-provenance.md

Latest commit

 

History

History
164 lines (122 loc) · 6.11 KB

release-provenance.md

File metadata and controls

164 lines (122 loc) · 6.11 KB
Raw

Release Provenance and SBOM Checklist

AES Secure Vault is an educational and portfolio tool, not production vault software. Release artifacts improve package reviewability, but they do not certify the package as compliance-ready or production-grade cryptography.

This checklist addresses OWASP Top 10:2025 A03 Software Supply Chain Failures and A08 Software or Data Integrity Failures by producing:

  • A CycloneDX JSON SBOM generated from the project metadata and requirements
  • A SHA-256 checksum manifest for source files and built distribution files
  • An unsigned local provenance statement with git commit, tag, build commands, Python version, OWASP mapping, and release boundary
  • GitHub artifact attestations for the built distributions and transparency artifacts when the release workflow runs in GitHub Actions
  • Optional PyPI Trusted Publishing with PyPI digital attestations when the PyPI project and GitHub environment are already configured

Release Checklist

Run from a clean checkout:

python -m pip install -r requirements-dev.txt
python -m pytest test_secure_vault.py test_release_workflow.py -v
Remove-Item -LiteralPath .\dist -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\release-artifacts -Recurse -Force -ErrorAction SilentlyContinue
python -m build
git tag v1.1.1
python tools/generate_release_artifacts.py --require-tag --require-clean

If the tag already exists, verify that git describe --tags --exact-match HEAD prints the intended release tag before generating artifacts.

The generated files are written to:

release-artifacts/<tag-or-version-commit>/

Expected files:

aes-secure-vault-1.1.1.sbom.cdx.json
aes-secure-vault-1.1.1.provenance.local.json
aes-secure-vault-1.1.1.sha256

GitHub and PyPI Release Upload

Attach the three generated files to the matching GitHub release. If the package is also published to PyPI, keep the GitHub release linked from the PyPI project URL so reviewers can find the SBOM and checksums.

Use release-note wording like:

This release publishes SBOM, checksum, and local provenance artifacts for
reviewability. AES Secure Vault remains an educational authenticated-encryption
tool and is not production vault software.

Do not describe the SBOM or checksum file as a security certification.

GitHub Actions Release Workflow

The repository release workflow lives at .github/workflows/release.yml.

On a v*.*.* tag push it:

  1. Runs the test suite on Python 3.11 and 3.13.
  2. Builds the source distribution and wheel.
  3. Generates the SBOM, checksum manifest, and local provenance statement.
  4. Creates GitHub artifact attestations for the distribution and transparency files.
  5. Creates or updates the matching GitHub release and uploads the artifacts.
  6. Downloads the assets from that published release and verifies GitHub asset digests, the flat checksum manifest, provenance tag/commit binding, and every GitHub artifact attestation.

The separate .github/workflows/verify-published-release.yml workflow repeats that public verification weekly and on manual request. It fails closed when an expected distribution, SBOM, provenance statement, checksum, digest, or attestation is absent.

The workflow keeps build and publish duties separate. The PyPI job has only id-token: write and downloads already-built artifacts instead of rebuilding inside the privileged publishing step.

PyPI Trusted Publishing Gate

PyPI publishing is intentionally manual. It only runs from workflow_dispatch on a v* tag when publish_to_pypi is true and trusted_publisher_configured is set to yes.

Before enabling that input, configure both sides:

  1. Create a GitHub environment named pypi.
  2. In PyPI, add a Trusted Publisher for:
    • PyPI project: aes-secure-vault
    • Owner: MDP-Studio
    • Repository: AES-256-GCM-Python-Tool
    • Workflow: release.yml
    • Environment: pypi
  3. Re-run the release workflow from the signed release tag with publish_to_pypi=true and trusted_publisher_configured=yes.

If the GitHub pypi environment is missing, the preflight job fails before the publish job. If the PyPI Trusted Publisher is missing or mismatched, PyPI will reject the OIDC exchange and no package is published.

Do not add a long-lived PyPI API token unless there is a documented emergency rollback decision. The normal path is tokenless Trusted Publishing.

What Attestations Mean

GitHub artifact attestations bind the workflow identity to the built files and can be verified with GitHub tooling. PyPI digital attestations, generated by the Trusted Publishing upload path, bind the PyPI distribution files to the same GitHub OIDC identity.

These attestations, SBOMs, checksums, and local provenance files are release transparency controls. They are not:

  • independent cryptographic certification
  • evidence of FIPS, Common Criteria, SOC 2, ISO 27001, or production vault compliance
  • proof that AES-GCM or Argon2id were independently implemented or formally verified by this project

Verify an Artifact

After downloading a release artifact set:

sha256sum -c aes-secure-vault-1.1.1.sha256

Or use the repository verifier from a checkout:

python tools/verify_published_release.py --tag v1.1.1

On Windows PowerShell, verify a single file with:

Get-FileHash .\aes-secure-vault-1.1.1.sbom.cdx.json -Algorithm SHA256

The published-release verifier downloads the matching GitHub release, checks GitHub's release-asset digests, verifies every flat SHA-256 manifest entry, binds local provenance to the tag commit, and uses gh attestation verify with the repository, signer workflow, source ref, and source commit constrained.

For fixture-based or disconnected testing, provide --metadata-file, --asset-root, --expected-commit, and the explicit --skip-attestations exception. The test suite uses the verifier's injected attestation callback and does not contact GitHub. Never use the exception in the release or scheduled CI workflows.

Version 1.1.0 is a legacy transparency release. Its checksum manifest names files that were not all uploaded, so the new verifier correctly rejects it.