# 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

```bash
TAG=v0.87.1
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:

```bash
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:

```bash
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.

```bash
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:

```bash
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:

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

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

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

## Inspect scanner accuracy evidence

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

```bash
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`](graph/SECURITY_GRAPH_EPIC_PROOF.md):

```bash
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.
