attest

package
v0.1.0-rc.3 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package attest generates in-toto attestations for the SLSA predicate types.

The entry point is the Writer. It owns a single, canonical option set and maps it onto the per-version generator packages (attest/build/v1, attest/build/v02, attest/vsa/v1). Callers can dispatch on a format with Writer.Attest, or call a format-specific method directly to pin the output to a known version.

Index

Constants

View Source
const (
	PredicateTypeSlsaProvenanceV1  = buildgenv1.PredicateTypeURI
	PredicateTypeSlsaProvenanceV02 = buildgenv02.PredicateTypeURI
	PredicateTypeVsaV1             = vsagenv1.PredicateTypeURI
)

Predicate type URIs for the supported formats, sourced from the per-version generator packages so there is a single definition of each.

Variables

View Source
var ErrUnknownVersion = errors.New("unknown attestation version")

ErrUnknownVersion is returned by Attest when handed a format it cannot produce.

Functions

func ParsePredicate

func ParsePredicate(version AttestationVersion, data []byte) (proto.Message, error)

ParsePredicate parses JSON into the official SLSA predicate proto for the version. Parsing is strict: fields the predicate proto does not define are rejected rather than dropped, so malformed or mismatched predicates fail here instead of producing an attestation that silently lost content.

Types

type AttestationVersion

type AttestationVersion string

AttestationVersion is a typed identifier for one of the attestation formats (predicate type + version) the Writer knows how to generate. It is passed to Writer.Attest to select the format to produce.

const (
	// SlsaProvenanceV1 selects the SLSA Build provenance predicate, v1.
	SlsaProvenanceV1 AttestationVersion = "slsa-provenance-v1"
	// SlsaProvenanceV02 selects the SLSA Build provenance predicate, v0.2.
	SlsaProvenanceV02 AttestationVersion = "slsa-provenance-v0.2"
	// VsaV1 selects the SLSA Verification Summary Attestation predicate, v1.
	VsaV1 AttestationVersion = "vsa-v1"
)

func (AttestationVersion) NewPredicate

func (v AttestationVersion) NewPredicate() proto.Message

NewPredicate returns an empty instance of the official SLSA predicate proto for the version, suitable as an Options.Predicate base. Returns nil for unknown versions.

func (AttestationVersion) PredicateType

func (v AttestationVersion) PredicateType() string

PredicateType returns the predicate type URI for the version, or the empty string if the version is unknown.

func (AttestationVersion) Valid

func (v AttestationVersion) Valid() bool

Valid returns true if v is a version the Writer can generate.

type AttestationWriter

type AttestationWriter interface {
	PredicateType() string
	Statement(subjects []*intoto.ResourceDescriptor) (*intoto.Statement, error)
}

AttestationWriter is implemented by each per-version generator. Given a set of subjects it produces the in-toto statement carrying that version's predicate.

type Completeness

type Completeness struct {
	Parameters  bool
	Environment bool
	Materials   bool
}

Completeness mirrors the SLSA build provenance v0.2 completeness flags. It is a legacy-only concept with no v1 equivalent.

type OptFn

type OptFn func(*Options) error

OptFn is a functional option mutating an Options value.

func WithBuildConfig

func WithBuildConfig(s *structpb.Struct) OptFn

WithBuildConfig sets buildConfig (v0.2 only).

func WithBuildType

func WithBuildType(buildType string) OptFn

WithBuildType sets the build type URI.

func WithBuilderDependencies

func WithBuilderDependencies(deps ...*intoto.ResourceDescriptor) OptFn

WithBuilderDependencies appends builder dependencies (v1 only).

func WithBuilderID

func WithBuilderID(id string) OptFn

WithBuilderID sets the builder id URI.

func WithBuilderVersion

func WithBuilderVersion(version map[string]string) OptFn

WithBuilderVersion merges builder version entries (v1 only).

func WithByproducts

func WithByproducts(deps ...*intoto.ResourceDescriptor) OptFn

WithByproducts appends byproducts (v1 only).

func WithCompleteness

func WithCompleteness(parameters, environment, materials bool) OptFn

WithCompleteness sets metadata.completeness (v0.2 only).

func WithConfigSourceDigest

func WithConfigSourceDigest(digest map[string]string) OptFn

WithConfigSourceDigest merges invocation.configSource.digest (v0.2 only).

func WithConfigSourceEntryPoint

func WithConfigSourceEntryPoint(entryPoint string) OptFn

WithConfigSourceEntryPoint sets invocation.configSource.entryPoint (v0.2 only).

func WithConfigSourceURI

func WithConfigSourceURI(uri string) OptFn

WithConfigSourceURI sets invocation.configSource.uri (v0.2 only).

func WithDependencyLevels

func WithDependencyLevels(levels map[string]uint64) OptFn

WithDependencyLevels merges dependencyLevels entries.

func WithEnvironment

func WithEnvironment(s *structpb.Struct) OptFn

WithEnvironment sets invocation.environment (v0.2 only).

func WithExternalParameters

func WithExternalParameters(s *structpb.Struct) OptFn

WithExternalParameters sets the external parameters (v0.2: invocation.parameters).

func WithFinishedOn

func WithFinishedOn(t time.Time) OptFn

WithFinishedOn sets the build finish time (v0.2: metadata.buildFinishedOn).

func WithHashAlgorithms

func WithHashAlgorithms(algos ...string) OptFn

WithHashAlgorithms sets the digest algorithms used to hash subject files.

func WithInputAttestations

func WithInputAttestations(inputs ...*intoto.ResourceDescriptor) OptFn

WithInputAttestations appends inputAttestations.

func WithInternalParameters

func WithInternalParameters(s *structpb.Struct) OptFn

WithInternalParameters sets the internal parameters (v1 only).

func WithInvocationID

func WithInvocationID(id string) OptFn

WithInvocationID sets the build invocation id (v0.2: metadata.buildInvocationId).

func WithPolicyDigest

func WithPolicyDigest(digest map[string]string) OptFn

WithPolicyDigest merges policy.digest entries.

func WithPolicyURI

func WithPolicyURI(uri string) OptFn

WithPolicyURI sets policy.uri.

func WithPredicate

func WithPredicate(p proto.Message) OptFn

WithPredicate sets a base predicate the content options are merged onto.

func WithReproducible

func WithReproducible(reproducible bool) OptFn

WithReproducible sets metadata.reproducible (v0.2 only).

func WithResolvedDependencies

func WithResolvedDependencies(deps ...*intoto.ResourceDescriptor) OptFn

WithResolvedDependencies appends resolved dependencies (v0.2: materials).

func WithResourceURI

func WithResourceURI(uri string) OptFn

WithResourceURI sets resourceUri.

func WithSigner

func WithSigner(s Signer) OptFn

WithSigner sets the signer used to sign the attestation.

func WithSlsaVersion

func WithSlsaVersion(version string) OptFn

WithSlsaVersion sets slsaVersion.

func WithStartedOn

func WithStartedOn(t time.Time) OptFn

WithStartedOn sets the build start time (v0.2: metadata.buildStartedOn).

func WithSubjects

func WithSubjects(subjects ...*intoto.ResourceDescriptor) OptFn

WithSubjects appends pre-built subject descriptors for artifacts only known by their digest. They are added to the statement after the hashed files.

func WithTimeVerified

func WithTimeVerified(t time.Time) OptFn

WithTimeVerified sets timeVerified.

func WithVerificationResult

func WithVerificationResult(result string) OptFn

WithVerificationResult sets verificationResult, e.g. "PASSED".

func WithVerifiedLevels

func WithVerifiedLevels(levels ...string) OptFn

WithVerifiedLevels appends verifiedLevels.

func WithVerifierID

func WithVerifierID(id string) OptFn

WithVerifierID sets verifier.id.

func WithWriter

func WithWriter(w io.Writer) OptFn

WithWriter sets the destination for the serialized attestation.

type Options

type Options struct {
	// Writer is where the serialized attestation is written (default os.Stdout).
	Writer io.Writer
	// HashAlgorithms are the digest algorithms used to hash subjects (default sha256).
	HashAlgorithms []string
	// Subjects are pre-built subject descriptors added to the statement after
	// the hashed subject files, for artifacts only known by their digest.
	Subjects []*intoto.ResourceDescriptor
	// Predicate is an optional base predicate the content options are merged
	// onto. It must match the target version's concrete predicate type.
	Predicate proto.Message
	// Signer, when set, signs the serialized statement and the signed artifact
	// (sigstore bundle or DSSE envelope) is emitted instead of the bare
	// statement. When nil the statement is emitted unsigned.
	Signer Signer

	// --- Build provenance content (canonical / modern names) ---
	BuildType            string
	BuilderID            string
	ExternalParameters   *structpb.Struct             // v0.2: invocation.parameters
	InternalParameters   *structpb.Struct             // v1 only
	ResolvedDependencies []*intoto.ResourceDescriptor // v0.2: materials
	BuilderVersion       map[string]string            // v1 only
	BuilderDependencies  []*intoto.ResourceDescriptor // v1 only
	Byproducts           []*intoto.ResourceDescriptor // v1 only
	InvocationID         string                       // v0.2: metadata.buildInvocationId
	StartedOn            *timestamppb.Timestamp       // v0.2: metadata.buildStartedOn
	FinishedOn           *timestamppb.Timestamp       // v0.2: metadata.buildFinishedOn

	// --- Build provenance content with no v1 equivalent (v0.2 only) ---
	ConfigSourceURI        string
	ConfigSourceDigest     map[string]string
	ConfigSourceEntryPoint string
	Environment            *structpb.Struct
	BuildConfig            *structpb.Struct
	Reproducible           *bool
	Completeness           *Completeness

	// --- Verification summary attestation content ---
	VerifierID         string
	TimeVerified       *timestamppb.Timestamp
	ResourceURI        string
	PolicyURI          string
	PolicyDigest       map[string]string
	InputAttestations  []*intoto.ResourceDescriptor
	VerificationResult string
	VerifiedLevels     []string
	DependencyLevels   map[string]uint64
	SlsaVersion        string
}

Options is the single, canonical option set for the Writer. Field names use the latest (v1) terminology; the Writer maps them to each predicate version's own option set at attest time (see mapping.go). Fields that exist only in an older predicate are kept here too so the one option set stays complete.

type Signer

type Signer interface {
	SignStatement(data []byte, funcs ...signeroptions.SignOptFn) (signer.SignedArtifact, error)
}

Signer signs a serialized in-toto statement, returning the signed artifact (a sigstore bundle or a DSSE envelope). It is satisfied by *signer.Signer from github.com/carabiner-dev/signer.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer generates attestations. The zero value is usable; it lazily wires in the default implementation on first use.

func (*Writer) Attest

func (w *Writer) Attest(version AttestationVersion, subjects []string, fn ...OptFn) error

Attest generates an attestation in the requested format over the given subject paths, dispatching to the matching format-specific method.

func (*Writer) AttestSlsaProvenanceV1

func (w *Writer) AttestSlsaProvenanceV1(subjects []string, fn ...OptFn) error

AttestSlsaProvenanceV1 generates a SLSA build provenance v1 attestation.

func (*Writer) AttestSlsaProvenanceV02

func (w *Writer) AttestSlsaProvenanceV02(subjects []string, fn ...OptFn) error

AttestSlsaProvenanceV02 generates a SLSA build provenance v0.2 attestation.

func (*Writer) AttestVSAV1

func (w *Writer) AttestVSAV1(subjects []string, fn ...OptFn) error

AttestVSAV1 generates a SLSA verification summary attestation v1.

func (*Writer) SetImplementation

func (w *Writer) SetImplementation(impl attesterImpl)

SetImplementation overrides the internal implementation (for tests).

Directories

Path Synopsis
build
v02
Package v02 generates SLSA build provenance v0.2 attestations.
Package v02 generates SLSA build provenance v0.2 attestations.
v1
Package v1 generates SLSA build provenance v1 attestations.
Package v1 generates SLSA build provenance v1 attestations.
internal
statement
Package statement assembles in-toto v1 statements from a predicate proto and a set of subjects.
Package statement assembles in-toto v1 statements from a predicate proto and a set of subjects.
vsa
v1
Package v1 generates SLSA verification summary attestations (VSA) v1.
Package v1 generates SLSA verification summary attestations (VSA) v1.

Jump to

Keyboard shortcuts

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