Documentation
¶
Overview ¶
Package source provides verification of SLSA source provenance attestations. It validates Sigstore bundles containing source provenance predicates, checking repository URI, commit SHA, and computing SLSA Source Track levels.
Index ¶
Constants ¶
const ( SLSASourceLevel0 = "SLSA_SOURCE_LEVEL_0" SLSASourceLevel1 = "SLSA_SOURCE_LEVEL_1" SLSASourceLevel2 = "SLSA_SOURCE_LEVEL_2" SLSASourceLevel3 = "SLSA_SOURCE_LEVEL_3" )
Canonical SLSA source-track levels (https://slsa.dev/spec/v1.2/source-requirements). The numeric ceiling is L3; two-party review (the v1.2 "L4" tier) has no numbered token and is recorded only as a non-numbered annotation.
Variables ¶
This section is empty.
Functions ¶
func ComputeSourceLevelFromControls ¶ added in v0.36.0
func ComputeSourceLevelFromControls(tc *SourceReviewControls, allowedBypass []string, baseLevel string) (string, []string)
ComputeSourceLevelFromControls promotes the source level to SLSA_SOURCE_LEVEL_3 when the enforced technical controls prove it, and emits the factual controls as non-numbered ORG_SOURCE_* annotations regardless of the numeric outcome.
L3 is earned iff: force-push blocked AND at least one required status check AND retained/immutable history (linear-history OR deletion-blocked) AND the bypass list is AUTHORITATIVE (BypassActorsComplete) AND every bypass actor is narrow (allowlisted, or none at all) AND continuity is recorded. Two-party review is NOT required for L3 (it is the separate v1.2 review tier) and never produces a numeric SLSA_SOURCE_LEVEL_4 — only the ORG_SOURCE_TWO_PARTY_REVIEWED annotation.
FAIL-CLOSED: BypassActorsComplete==false means an empty BypassActors is UNKNOWN (not "none"), so the bypass leg fails; an empty ContinuityStartRevision is UNDETERMINED, so the continuity leg fails. Either keeps the level at baseLevel.
func MapToCanonicalSourceLevel ¶ added in v0.30.0
MapToCanonicalSourceLevel maps the verification evidence to the canonical SLSA source-track level the evidence actually proves, staying deliberately conservative to avoid overclaiming.
The SLSA source track (v1.2) grants:
- L1: source is in a modern VCS and a Source VSA/provenance is issued.
- L2: change history is continuous, immutable, and retained.
- L3: the org's technical controls (branch protection, force-push blocked, required status checks, bypass disabled or narrowly declared) are continuously enforced and recorded in attestations. No human review is required for L3.
- Two-party review is a separate, higher control (the v1.2 "L4" tier), recorded as a non-numbered annotation — never as a numbered level (there is no SLSA_SOURCE_LEVEL_4 token).
A verified source-provenance signature proves L1: the revision is version controlled and provenance exists. It does NOT by itself prove the continuity (L2) or continuous-enforcement (L3) controls — those require recorded + enforced branch-protection evidence, which this verify path does not yet receive. So provenance evidence alone maps to L1 here, and the level is never inferred from the builder identity (that conflated L3 with the build platform and over-claimed).
Types ¶
type SourceProvenancePredicate ¶
type SourceProvenancePredicate struct {
BuildDefinition struct {
BuildType string `json:"buildType"`
ExternalParameters struct {
Repository string `json:"repository"`
Ref string `json:"ref"`
Workflow struct {
Repository string `json:"repository"`
Ref string `json:"ref"`
Path string `json:"path"`
} `json:"workflow"`
} `json:"externalParameters"`
ResolvedDependencies []struct {
URI string `json:"uri"`
Digest map[string]string `json:"digest"`
} `json:"resolvedDependencies"`
} `json:"buildDefinition"`
RunDetails struct {
Builder struct {
ID string `json:"id"`
} `json:"builder"`
Metadata struct {
InvocationID string `json:"invocationId"`
StartedOn string `json:"startedOn"`
} `json:"metadata"`
} `json:"runDetails"`
}
SourceProvenancePredicate represents relevant fields from a SLSA provenance predicate used for source provenance verification.
type SourceReviewControls ¶ added in v0.36.0
type SourceReviewControls struct {
ForcePushBlocked bool
RequiredLinearHistory bool
DeletionBlocked bool
RequiredSignatures bool
RequiredStatusChecks []string
BypassActors []string
BypassActorsComplete bool
ContinuityStartRevision string
// TwoPartyReviewed is derived from the source-review summary (>= 2 distinct
// approvers). It feeds the ORG_SOURCE_TWO_PARTY_REVIEWED annotation only —
// review is the v1.2 "L4" tier, never folded into the numeric L3.
TwoPartyReviewed bool
}
SourceReviewControls is the enforced branch-protection evidence extracted from a signature-verified source-review attestation. It is the verifier-side view of the producer's technicalControls block (pkg/predicate.SourceReviewTechnicalControls); kept as a local mirror so pkg/source stays dependency-free (matching the SourceProvenancePredicate pattern).
func VerifySourceReviewControls ¶ added in v0.36.0
func VerifySourceReviewControls(bundlePath string, opts VerifyOptions) (*SourceReviewControls, error)
VerifySourceReviewControls loads a source-review attestation bundle, verifies its signature under an ENFORCED signer identity, and extracts the recorded technical controls. It mirrors VerifySourceProvenance's load→root→verify shape. It REQUIRES opts.CertIdentity: an unverified (WithoutIdentitiesUnsafe) source-review bundle must never be able to promote the source level, so the caller can only obtain controls from a verified signer. Any error means "no verified controls" — the caller degrades to the base level, it does not block.
type VerificationResult ¶
type VerificationResult struct {
Verified bool `json:"verified"`
RepoURI string `json:"repo_uri,omitempty"`
Commit string `json:"commit,omitempty"`
SourceRef string `json:"source_ref,omitempty"`
SLSASourceLevel string `json:"slsa_source_level,omitempty"`
BuilderID string `json:"builder_id,omitempty"`
Claims map[string]string `json:"claims,omitempty"`
ErrorMsg string `json:"error,omitempty"`
Warnings []string `json:"warnings,omitempty"`
}
VerificationResult holds the outcome of source provenance verification.
func VerifySourceProvenance ¶
func VerifySourceProvenance(bundlePath string, opts VerifyOptions) (*VerificationResult, error)
VerifySourceProvenance verifies a Sigstore bundle containing source provenance. It validates the bundle signature, extracts the in-toto statement, and checks that the repo URI and commit SHA match the expected values.
type VerifyOptions ¶
type VerifyOptions struct {
// RepoURI is the expected source repository URI.
RepoURI string
// Commit is the expected source commit SHA.
Commit string
// SourceRef is the expected source ref (e.g., refs/heads/main). Optional.
SourceRef string
// CertIdentity is the expected OIDC subject in the signing certificate.
CertIdentity string
// CertIssuer is the expected OIDC issuer URL.
CertIssuer string
}
VerifyOptions configures source provenance verification.
Source Files