<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Implementing Software Provenance — API Reference

## SLSA Verifier CLI

```bash
# Verify generic artifact
slsa-verifier verify-artifact <artifact> \
  --provenance-path <provenance.intoto.jsonl> \
  --source-uri github.com/<org>/<repo> \
  --source-tag <tag>

# Verify container image
slsa-verifier verify-image <image-uri> \
  --source-uri github.com/<org>/<repo>

# Verify with builder ID
slsa-verifier verify-artifact <artifact> \
  --provenance-path <provenance> \
  --source-uri github.com/<org>/<repo> \
  --builder-id https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml
```

## SLSA GitHub Generator Workflows

```yaml
# Generic artifact provenance (SLSA Level 3)
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.0.0
with:
  base64-subjects: "<base64-encoded sha256 digests>"

# Container image provenance
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v2.0.0
with:
  image: ghcr.io/<org>/<repo>
  digest: ${{ steps.build.outputs.digest }}
```

## in-toto CLI

```bash
# Record a build step
in-toto-run --step-name build --products app.tar.gz -- make build

# Record with signing key
in-toto-run --step-name build --signing-key builder.pem --products app.tar.gz -- make build

# Verify supply chain layout
in-toto-verify --layout layout.json --layout-keys key.pub

# Create layout
in-toto-match-products --step-name build --products app.tar.gz
```

## Cosign Provenance Attestation

```bash
# Attest provenance to container image
cosign attest --predicate provenance.json --type slsaprovenance app:latest

# Verify provenance attestation
cosign verify-attestation --type slsaprovenance --key cosign.pub app:latest

# Keyless attestation (Sigstore)
cosign attest --predicate provenance.json --type slsaprovenance app:latest --yes
```

## SLSA Levels Reference

| Level | Build | Provenance | Source |
|-------|-------|------------|--------|
| L0 | Any | None | Any |
| L1 | Automated | Exists | Any |
| L2 | Hosted | Authenticated | Any |
| L3 | Hardened | Non-falsifiable | Verified |

## Provenance Statement Schema (SLSA v1)

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{"name": "artifact.tar.gz", "digest": {"sha256": "..."}}],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://slsa.dev/build-types/github-actions/v1",
      "externalParameters": {"source": {"uri": "git+https://...", "digest": {"sha1": "..."}}},
      "internalParameters": {}
    },
    "runDetails": {
      "builder": {"id": "https://github.com/actions/runner"},
      "metadata": {"invocationId": "...", "startedOn": "..."}
    }
  }
}
```
