Documentation
¶
Overview ¶
Package vsa provides a version-neutral in-memory representation of SLSA Verification Summary Attestations and the adapters that map the on-the-wire proto types (vsa/v0.2, vsa/v1, …) onto it.
Adding support for a new VSA version is a single-file change: drop in an Adapter implementation that knows how to read the new proto and populate VSA, and register it with init(). Verification code always reads from VSA — never from version-specific protos — so it is insulated from upstream schema churn.
Index ¶
Constants ¶
const ( ResultPassed = "PASSED" ResultFailed = "FAILED" )
Result values defined by the SLSA spec for the VSA verificationResult field.
const PredicateTypeV02 = "https://slsa.dev/verification_summary/v0.2"
PredicateTypeV02 is the predicate-type URI for SLSA VSA v0.2.
const PredicateTypeV1 = "https://slsa.dev/verification_summary/v1"
PredicateTypeV1 is the predicate-type URI for SLSA VSA v1.
Variables ¶
var ErrNotVSA = errors.New("not a VSA predicate type")
ErrNotVSA is returned when a statement carries a predicate type that no registered Adapter handles.
Functions ¶
func IsVSAPredicateType ¶
IsVSAPredicateType reports whether uri is a registered VSA predicate-type URI.
func Marshal ¶
Marshal renders an in-toto Statement as indented JSON suitable for writing to stdout.
func PredicateTypes ¶
func PredicateTypes() []string
PredicateTypes returns the URIs of every registered VSA adapter. Order is unspecified.
Types ¶
type Adapter ¶
type Adapter interface {
// PredicateType returns the URI this adapter handles, e.g.
// "https://slsa.dev/verification_summary/v1".
PredicateType() string
// Convert maps parsed (the value the registered predicate parser
// placed in the in-toto statement's Predicate.Parsed) into a *VSA.
// Returns an error if parsed is not the type this adapter expects.
Convert(parsed any) (*VSA, error)
}
Adapter converts a parsed VSA predicate payload of a specific version into the normalized VSA representation. Implementations declare their predicate-type URI so the registry can dispatch by statement.predicateType.
Convert takes `any` rather than proto.Message so individual versions can pick the wire-format path that fits — v1 round-trips cleanly through protojson, but v0.2 ships json_name overrides that conflict with the camelCase the SLSA spec actually uses, so it parses through encoding/json into a hand-rolled struct. Each adapter type-asserts its expected concrete type.
type InputAttestation ¶
InputAttestation references one of the attestations consumed by the verifier as evidence.
type Policy ¶
Policy describes the policy the verifier evaluated the subject against. Digest is keyed by hash algorithm (e.g. "sha256") and will be empty if the producer didn't include digests.
type SummaryInput ¶
type SummaryInput struct {
// VerifierID is recorded in verifier.id — the identity of the tool
// that performed the verification.
VerifierID string
// TimeVerified is the moment the verification ran. The zero value is
// omitted from the predicate.
TimeVerified time.Time
// Subjects are the in-toto subjects the VSA attests about, normally
// the subjects of the verified attestation.
Subjects []*intoto.ResourceDescriptor
// ResourceURI is the URI of the resource the verification covers
// (resourceUri). Empty is omitted.
ResourceURI string
// PolicyURI, when set, records the policy the verifier evaluated
// against in policy.uri.
PolicyURI string
// VerificationResult is "PASSED" or "FAILED" (ResultPassed /
// ResultFailed).
VerificationResult string
// VerifiedLevels lists the SLSA levels the verification established,
// e.g. []string{"SLSA_BUILD_LEVEL_3"}.
VerifiedLevels []string
// SLSAVersion records the slsaVersion field; empty is omitted.
SLSAVersion string
}
SummaryInput carries the values a verifier needs to emit a VSA v1 statement summarising its own evaluation. It is the write-side counterpart to the read-side Adapter conversions: callers populate it from a verification result and call Statement to obtain an unsigned in-toto Statement.
type VSA ¶
type VSA struct {
// PredicateType is the URI of the source predicate the adapter
// converted from, e.g. "https://slsa.dev/verification_summary/v1".
PredicateType string
Verifier Verifier
TimeVerified time.Time
ResourceURI string
Policy Policy
InputAttestations []InputAttestation
VerificationResult string
VerifiedLevels []string
DependencyLevels map[string]uint64
// SLSAVersion is empty for v0.2 VSAs (the field does not exist in
// that schema).
SLSAVersion string
}
VSA is the version-neutral in-memory representation of a SLSA Verification Summary Attestation predicate. Every supported VSA predicate version is converted to this shape via a registered Adapter before any verification logic runs against it.
Field semantics follow VSA v1; v0.2-only differences are folded in by the v0.2 adapter (e.g. the single PolicyLevel becomes a one-element VerifiedLevels slice; SLSAVersion stays empty).
func FromParsed ¶
FromParsed converts an already-parsed predicate payload into the normalized VSA shape, dispatching to the adapter registered for predicateType. Returns ErrNotVSA if no adapter handles predicateType.
func FromStatement ¶
func FromStatement(stmt attestation.Statement) (*VSA, error)
FromStatement extracts a *VSA from an attestation.Statement. The statement's predicate must already be parsed (via the parsers registered in this package, which the envelope loader runs automatically). Returns ErrNotVSA if the statement's predicate type is not a registered VSA version.
Source Files