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).
const ControlledBuilderAnnotation = "ORG_SOURCE_CONTROLLED_BUILDER"
ControlledBuilderAnnotation is the non-numbered verifiedLevels entry asserting that the provenance was produced by a recognized, controlled CI builder (a builder-ID prefix the verifier trusts, plus a recognized build type). It proves a recognized controlled builder — NOT that two parties reviewed the change; review is a separate source-track control this heuristic does not observe. It is recorded alongside — not as — the numbered SLSA_SOURCE_LEVEL_n.
Variables ¶
This section is empty.
Functions ¶
func ComputeSLSASourceLevel ¶
func ComputeSLSASourceLevel(signatureVerified bool, pred SourceProvenancePredicate) string
ComputeSLSASourceLevel evaluates the SLSA Source Track level based on the predicate.
L1: Version controlled + provenance exists L2: Provenance is cryptographically verified (signatureVerified must be true) L3: Verified provenance from two-party review (branch protection claims)
func IsComputedSourceLevel3 ¶ added in v0.30.0
IsComputedSourceLevel3 reports whether a ComputeSLSASourceLevel result indicates L3 (a recognized controlled builder plus a recognized build type). It accepts both the canonical SLSA_SOURCE_LEVEL_3 token and the legacy SLSA_SOURCE_L3 form so callers stay correct regardless of whether the canonical-token fix has merged; once it has, only the canonical form occurs and the legacy arm is inert.
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: continuous, immutable, retained branch history.
- L3: org technical controls (branch protection, required reviews, status checks) are continuously enforced and attested.
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. So provenance evidence alone maps to L1 here; a recognized controlled builder, when detected, is surfaced separately via ControlledBuilderAnnotation.
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 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