# SLSA Source Track Capture (SC3)

Status: Active (partial implementation) | Last Updated: 2026-02-10
Scope: Define deterministic capture of SLSA Source Track data for replay bundles and CycloneDX 1.7 + CBOM exports. Align scanner record/replay with source and build provenance signals.

## Objectives
- Persist source provenance required by SLSA 1.2 Source Track: repo URI, resolved ref, commit, source review controls, and policy snapshot signals.
- Make data replayable offline with no network dependency.
- Keep ordering and hashes deterministic with canonical JSON and explicit hash algorithm prefixes.

## Shipped Defaults (2026-02-10)
- Build provenance policy supports Source Track controls:
  - `minimumReviewApprovals`
  - `requireNoSelfMerge`
  - `requireProtectedBranch`
  - `requireStatusChecksPassed`
  - `requirePolicyHash`
- Source metadata is captured from build parameters using keys such as:
  - `sourceRef`
  - `sourceReviewCount` or `sourceApproverIds`
  - `sourceAuthorId` and `sourceMergedById`
  - `sourceBranchProtected`
  - `sourceStatusChecksPassed`
  - `sourcePolicyHash`
- Source policy violations emit deterministic `SourcePolicyFailed` findings.
- In-toto predicate output now includes source review and policy evidence fields.

## Minimal Fields (Per Build)
- `source.repo`: canonical repository URI.
- `source.ref`: fully-qualified source ref (`refs/heads/main`, tag, or immutable commit).
- `source.commit`: immutable source commit.
- `source.review.count`: numeric review approval count.
- `source.review.approvers`: sorted approver identity list.
- `source.review.authorId`: source author identity.
- `source.review.mergedById`: merge actor identity.
- `source.branchProtected`: boolean signal from SCM policy enforcement.
- `source.statusChecksPassed`: boolean signal for required CI checks.
- `source.policyHash`: deterministic digest for branch/review policy snapshot.

## JSON Shape (Current Direction)
```json
{
  "source": {
    "repo": "https://example.invalid/demo",
    "ref": "refs/heads/main",
    "commit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "policyHash": "sha256:policy123",
    "review": {
      "count": 2,
      "approvers": ["approver-a", "approver-b"],
      "authorId": "author-a",
      "mergedById": "approver-a",
      "branchProtected": true,
      "statusChecksPassed": true
    }
  }
}
```

## Determinism Rules
- Canonical JSON (lexicographic keys, UTF-8, no pretty-print) before hashing/signing.
- UTC timestamps with `Z` suffix in exported provenance when timestamps are included.
- Hash values must include algorithm prefix (`sha256:`, `b3:`).

## Verification Expectations
- Verifier fails closed when required Source Track controls are absent or violated.
- Verifier links source control evidence (review, policy hash, branch/status signals) with build provenance identity.
- No external fetch is allowed during verification.

## Fixtures
- `docs/modules/scanner/fixtures/cdx17-cbom/source-track.sample.json`

## Remaining Work
- Extend replay manifest schema to include source hash material (`treeHash`, invocation hash, DSSE hash) and offline recomputation assets.
- Add a dedicated offline source-track verifier script for CAS-bound evidence inputs.
- Add first-class SCM/CI attestation ingestion for source controls beyond parameter maps.