77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# 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.
|