vsa

package
v0.32.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 26, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

provides types, structures, and generation functions for Verification Summary Attestations.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidDigest             = &VSAError{Type: "validation", Field: "digest", Message: "invalid digest format or value"}
	ErrMismatchVerifier          = &VSAError{Type: "validation", Field: "verifier", Message: "verifier ID mismatch"}
	ErrInvalidSLSALevel          = &VSAError{Type: "validation", Field: "verifiedLevels", Message: "invalid SLSA level format"}
	ErrMissingRequiredField      = &VSAError{Type: "validation", Field: "required", Message: "missing required field"}
	ErrInvalidVerificationResult = &VSAError{Type: "validation", Field: "verificationResult", Message: "invalid verification result"}
	ErrInvalidResourceURI        = &VSAError{Type: "validation", Field: "resourceUri", Message: "invalid resource URI"}
	ErrInvalidPredicateType      = &VSAError{Type: "validation", Field: "predicateType", Message: "invalid predicate type"}
	ErrInvalidStatementType      = &VSAError{Type: "validation", Field: "_type", Message: "invalid statement type"}
)

error types

Functions

func ExtractSLSALevels

func ExtractSLSALevels(levels []string) []string

extracts valid SLSA levels from a string slice

func Generate

func Generate(ctx context.Context, opts GenerateOptions) error

creates a VSA after successful attestation verification

func IsSLSATrackLevel

func IsSLSATrackLevel(level string) bool

checks if a level string is a valid SLSA track level

func WriteToFile

func WriteToFile(vsa *VSA, outputPath string) error

writes a VSA to a file in JSON format

Types

type Dependency

type Dependency struct {
	Name          string            `json:"name"`
	Digest        map[string]string `json:"digest"`
	URI           string            `json:"uri,omitempty"`
	VerifiedLevel string            `json:"verifiedLevel,omitempty"`
}

represents a software dependency for SLSA level analysis

type DigestSet

type DigestSet map[string]map[string]bool

represents a collection of digests organized by algorithm

type GenerateOptions

type GenerateOptions struct {
	ArtifactDigest    string
	VSASubjects       []VSASubject
	InputAttestations []ResourceDescriptor
	AttestationTypes  []string
	Signatures        []oci.Signature
	PolicyURI         string
	VSAOutput         string
	PolicyBundlePath  string
	PolicySchemasPath string
	PolicyDataPath    string
	Quiet             bool
	Version           string
	OpaVersion        string
}

contains options for VSA generation

type ResourceDescriptor

type ResourceDescriptor struct {
	URI    string            `json:"uri,omitempty"`
	Digest map[string]string `json:"digest,omitempty"`
}

a resource with URI and digest

type SLSATrackLevels

type SLSATrackLevels struct {
	BuildTrack      int
	DependencyTrack int
	SourceTrack     int
}

SLSA tracks and their levels

func ExtractSLSATrackLevels

func ExtractSLSATrackLevels(trackLevels []string) (SLSATrackLevels, error)

parses SLSA track levels from a list of strings

type SourceVSAOptions added in v0.30.0

type SourceVSAOptions struct {
	// RepoURI is the source repository (becomes resourceUri and subject name).
	RepoURI string
	// Commit is the verified git revision SHA (becomes the subject gitCommit digest).
	Commit string
	// SourceLevel is the highest SLSA_SOURCE_LEVEL_n the evidence supports.
	SourceLevel string
	// AdditionalLevels are non-numbered source-track assertions the verifier can
	// vouch for (e.g. a review-control annotation). These sit alongside the
	// numbered level in verifiedLevels per the source-track VSA spec, which
	// allows additional properties.
	AdditionalLevels []string
	// Passed is the overall verification result.
	Passed bool
	// PolicyURI identifies the policy the verification was performed against.
	PolicyURI string
	// PolicyDigest is the optional digest of that policy.
	PolicyDigest map[string]string
	// InputAttestations are the bundles this VSA summarizes.
	InputAttestations []ResourceDescriptor
	// AdditionalVerifiers records the verifying tool versions.
	AdditionalVerifiers map[string]string
}

SourceVSAOptions configures a standards-shaped SLSA Source VSA.

A Source VSA is a verification_summary/v1 statement whose subject is the source revision (the repo at a git commit) rather than a build artifact. See https://slsa.dev/spec/v1.2-rc1/verifying-source and the source-track level definitions at https://slsa.dev/spec/v1.2/source-requirements.

type VSA

type VSA struct {
	Type          string                 `json:"_type"`
	PredicateType string                 `json:"predicateType"`
	Subject       []VSASubject           `json:"subject"`
	Predicate     VSAPredicate           `json:"predicate"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`
}

Verification Summary Attestation based on the in-toto VSA specification / SLSA v1.1

func GenerateSourceVSA added in v0.30.0

func GenerateSourceVSA(opts SourceVSAOptions) (*VSA, error)

GenerateSourceVSA builds a standards-shaped SLSA Source VSA.

Per the source track, the subject is the revision (repo + gitCommit digest), resourceUri is the repository, and verifiedLevels MUST contain only the highest SLSA source level met. The source control system is the expected issuer of a Source VSA; autogov issues it here as a downstream verifier and records that in verifier.id (see the issuer note in the docs).

func GenerateVSA

func GenerateVSA(imageRef string, policyURI string, verificationResults map[string]bool) (*VSA, error)

creates a VSA for successful AutoGov validation calls GenerateVSAWithOptions w/ default options

func GenerateVSAWithOptions

func GenerateVSAWithOptions(imageRef string, policyURI string, verificationResults map[string]bool, opts VSAOptions) (*VSA, error)

creates a VSA w/ opts

func GenerateVSAWithSubjects

func GenerateVSAWithSubjects(imageRef string, subjects []VSASubject, policyURI string, verificationResults map[string]bool, opts VSAOptions) (*VSA, error)

creates a VSA with multiple subjects

func ValidateVSA

func ValidateVSA(vsaBytes []byte) (*VSA, error)

validates an existing VSA (SLSA v1.1 compliant)

func (*VSA) GetSupportedDigestAlgorithms

func (v *VSA) GetSupportedDigestAlgorithms() []string

returns the digest algorithms present in VSA subjects

func (*VSA) IsVerificationPassed

func (v *VSA) IsVerificationPassed() bool

checks if the VSA indicates successful verification

func (*VSA) SerializeVSA

func (v *VSA) SerializeVSA() ([]byte, error)

converts VSA to JSON bytes

func (*VSA) ValidateComprehensive

func (v *VSA) ValidateComprehensive() error

performs comprehensive VSA validation

func (*VSA) ValidateDigestFormats

func (v *VSA) ValidateDigestFormats() error

validates that all digests in VSA subjects have proper format

func (*VSA) ValidateDigests

func (v *VSA) ValidateDigests(expectedDigests []string) error

validates that expected digests are present in VSA subjects multiple digest formats: sha256:abc123, sha1:def456, etc. are supported

type VSAError

type VSAError struct {
	Type    string
	Field   string
	Message string
	Cause   error
}

structured error for VSA operations

func NewParsingError

func NewParsingError(field, message string, cause error) *VSAError

creates a parsing error

func NewVSAError

func NewVSAError(errorType, field, message string, cause error) *VSAError

creates a new VSA error with the specified details

func NewValidationError

func NewValidationError(field, message string, cause error) *VSAError

creates a validation error

func (*VSAError) Error

func (e *VSAError) Error() string

func (*VSAError) Unwrap

func (e *VSAError) Unwrap() error

type VSALevel

type VSALevel struct {
	Level string `json:"level"`           // e.g., "SLSA_BUILD_LEVEL_3"
	Track string `json:"track,omitempty"` // e.g., "BUILD", "SOURCE"
}

represents a verified SLSA level (for internal use only) actual VSA predicate uses string array for verifiedLevels per spec

func (*VSALevel) UnmarshalJSON

func (v *VSALevel) UnmarshalJSON(data []byte) error

implements custom JSON unmarshaling for backward compatibility both string format (legacy) and object format (new) are supported

type VSAOptions

type VSAOptions struct {
	Subjects            []VSASubject         `json:"subjects,omitempty"`
	InputAttestations   []ResourceDescriptor `json:"inputAttestations,omitempty"`
	PolicyDigest        map[string]string    `json:"policyDigest,omitempty"`
	Dependencies        []Dependency         `json:"dependencies,omitempty"`
	AdditionalVerifiers map[string]string    `json:"additionalVerifiers,omitempty"`
}

provides config

type VSAPolicy

type VSAPolicy struct {
	Content string            `json:"content,omitempty"` // Policy content (e.g., Datalog, Rego)
	URI     string            `json:"uri,omitempty"`     // Policy URI
	Digest  map[string]string `json:"digest,omitempty"`  // Policy digest
}

policy information (supports both content and URI)

type VSAPredicate

type VSAPredicate struct {
	Verifier           VSAVerifier          `json:"verifier"`
	TimeVerified       string               `json:"timeVerified"`
	ResourceURI        string               `json:"resourceUri"`
	Policy             VSAPolicy            `json:"policy"`
	InputAttestations  []ResourceDescriptor `json:"inputAttestations,omitempty"`
	VerificationResult string               `json:"verificationResult"`
	VerifiedLevels     []string             `json:"verifiedLevels,omitempty"`
	DependencyLevels   map[string]uint64    `json:"dependencyLevels,omitempty"`
	SlsaVersion        string               `json:"slsaVersion,omitempty"`
}

type VSASubject

type VSASubject struct {
	URI    string            `json:"uri"`
	Digest map[string]string `json:"digest,omitempty"`
}

type VSAVerifier

type VSAVerifier struct {
	ID      string            `json:"id"`
	Version map[string]string `json:"version,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL