Skip to content

RELEASE_VERIFICATION.md

Latest commit

 

History

History
108 lines (78 loc) · 3.61 KB

RELEASE_VERIFICATION.md

File metadata and controls

108 lines (78 loc) · 3.61 KB

Release Verification

agent-bom release tags publish verifiable release assets, not just package files.

For each tagged GitHub Release, expect:

  • Python distribution files: agent_bom-<version>.tar.gz, agent_bom-<version>-py3-none-any.whl
  • Sigstore bundles for each distribution: *.sigstore.json
  • SLSA provenance bundles for each distribution: *.intoto.jsonl
  • CycloneDX SBOM: agent-bom-sbom.cdx.json

Download release assets

TAG=v0.86.5
VERSION="${TAG#v}"
mkdir -p /tmp/agent-bom-release && cd /tmp/agent-bom-release
gh release download "$TAG" --repo msaad00/agent-bom

Verify Python release signatures

Verify the wheel or source distribution against the Sigstore bundle generated by release CI:

cosign verify-blob "agent_bom-${VERSION}-py3-none-any.whl" \
  --bundle "agent_bom-${VERSION}-py3-none-any.whl.sigstore.json" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github.com/msaad00/agent-bom/.github/workflows/release.yml@.*'

Do the same for the source tarball if you consume that artifact:

cosign verify-blob "agent_bom-${VERSION}.tar.gz" \
  --bundle "agent_bom-${VERSION}.tar.gz.sigstore.json" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github.com/msaad00/agent-bom/.github/workflows/release.yml@.*'

Inspect SLSA provenance

The release job exports GitHub Attestations as .intoto.jsonl bundles so the provenance is attached to the GitHub Release, not hidden inside Actions only.

head -n 5 "agent_bom-${VERSION}-py3-none-any.whl.intoto.jsonl"

If you want to verify provenance directly from GitHub Attestations instead of using the exported bundle:

gh attestation verify "agent_bom-${VERSION}-py3-none-any.whl" \
  --repo msaad00/agent-bom

Inspect the self-SBOM

Release CI also publishes a CycloneDX SBOM for the Python environment used to build the release:

jq -r '.metadata.component.name, .metadata.component.version' agent-bom-sbom.cdx.json

You can also run agent-bom against that SBOM directly:

agent-bom sbom agent-bom-sbom.cdx.json -f json

Inspect scanner accuracy evidence

Release candidates also carry a checked-in scanner accuracy baseline:

uv run python scripts/generate_accuracy_baseline.py --check
jq '.runtime_red_team, .finding_state_accounting' docs/accuracy-baseline.json

The baseline separates active unresolved findings from VEX-suppressed, fixed-verified, accepted-risk, and false-positive states. It is intentionally not a claim of customer-wide real-world false-positive or false-negative rates; those require a published external corpus.

Inspect graph epic proof

Graph release claims are backed by the closure artifact in docs/graph/SECURITY_GRAPH_EPIC_PROOF.md:

python scripts/check_graph_epic_proof.py
pytest tests/test_graph_schema_ui_parity.py tests/test_graph_edge_counts.py tests/test_graph_visual_snapshot.py tests/test_effective_reach.py tests/test_evidence_policy.py

What this proves

  • the distribution artifacts were signed by GitHub Actions OIDC via Sigstore
  • the build provenance is available as SLSA attestations
  • the release includes a self-SBOM that can be inspected or rescanned later
  • scanner accuracy claims are backed by a versioned local evidence artifact
  • graph readability/trust claims are linked to deterministic, checked-in proof

This is the release trust baseline. Runtime trust, container attestations, and registry-specific provenance still live in their own workflows and docs.