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
- Variables
- func ParsePredicate(version AttestationVersion, data []byte) (proto.Message, error)
- type AttestationVersion
- type AttestationWriter
- type Completeness
- type OptFn
- func WithBuildConfig(s *structpb.Struct) OptFn
- func WithBuildType(buildType string) OptFn
- func WithBuilderDependencies(deps ...*intoto.ResourceDescriptor) OptFn
- func WithBuilderID(id string) OptFn
- func WithBuilderVersion(version map[string]string) OptFn
- func WithByproducts(deps ...*intoto.ResourceDescriptor) OptFn
- func WithCompleteness(parameters, environment, materials bool) OptFn
- func WithConfigSourceDigest(digest map[string]string) OptFn
- func WithConfigSourceEntryPoint(entryPoint string) OptFn
- func WithConfigSourceURI(uri string) OptFn
- func WithDependencyLevels(levels map[string]uint64) OptFn
- func WithEnvironment(s *structpb.Struct) OptFn
- func WithExternalParameters(s *structpb.Struct) OptFn
- func WithFinishedOn(t time.Time) OptFn
- func WithHashAlgorithms(algos ...string) OptFn
- func WithInputAttestations(inputs ...*intoto.ResourceDescriptor) OptFn
- func WithInternalParameters(s *structpb.Struct) OptFn
- func WithInvocationID(id string) OptFn
- func WithPolicyDigest(digest map[string]string) OptFn
- func WithPolicyURI(uri string) OptFn
- func WithPredicate(p proto.Message) OptFn
- func WithReproducible(reproducible bool) OptFn
- func WithResolvedDependencies(deps ...*intoto.ResourceDescriptor) OptFn
- func WithResourceURI(uri string) OptFn
- func WithSigner(s Signer) OptFn
- func WithSlsaVersion(version string) OptFn
- func WithStartedOn(t time.Time) OptFn
- func WithSubjects(subjects ...*intoto.ResourceDescriptor) OptFn
- func WithTimeVerified(t time.Time) OptFn
- func WithVerificationResult(result string) OptFn
- func WithVerifiedLevels(levels ...string) OptFn
- func WithVerifierID(id string) OptFn
- func WithWriter(w io.Writer) OptFn
- type Options
- type Signer
- type Writer
- func (w *Writer) Attest(version AttestationVersion, subjects []string, fn ...OptFn) error
- func (w *Writer) AttestSlsaProvenanceV1(subjects []string, fn ...OptFn) error
- func (w *Writer) AttestSlsaProvenanceV02(subjects []string, fn ...OptFn) error
- func (w *Writer) AttestVSAV1(subjects []string, fn ...OptFn) error
- func (w *Writer) SetImplementation(impl attesterImpl)
Constants ¶
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 ¶
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 ¶
Completeness mirrors the SLSA build provenance v0.2 completeness flags. It is a legacy-only concept with no v1 equivalent.
type OptFn ¶
OptFn is a functional option mutating an Options value.
func WithBuildConfig ¶
WithBuildConfig sets buildConfig (v0.2 only).
func WithBuildType ¶
WithBuildType sets the build type URI.
func WithBuilderDependencies ¶
func WithBuilderDependencies(deps ...*intoto.ResourceDescriptor) OptFn
WithBuilderDependencies appends builder dependencies (v1 only).
func WithBuilderVersion ¶
WithBuilderVersion merges builder version entries (v1 only).
func WithByproducts ¶
func WithByproducts(deps ...*intoto.ResourceDescriptor) OptFn
WithByproducts appends byproducts (v1 only).
func WithCompleteness ¶
WithCompleteness sets metadata.completeness (v0.2 only).
func WithConfigSourceDigest ¶
WithConfigSourceDigest merges invocation.configSource.digest (v0.2 only).
func WithConfigSourceEntryPoint ¶
WithConfigSourceEntryPoint sets invocation.configSource.entryPoint (v0.2 only).
func WithConfigSourceURI ¶
WithConfigSourceURI sets invocation.configSource.uri (v0.2 only).
func WithDependencyLevels ¶
WithDependencyLevels merges dependencyLevels entries.
func WithEnvironment ¶
WithEnvironment sets invocation.environment (v0.2 only).
func WithExternalParameters ¶
WithExternalParameters sets the external parameters (v0.2: invocation.parameters).
func WithFinishedOn ¶
WithFinishedOn sets the build finish time (v0.2: metadata.buildFinishedOn).
func WithHashAlgorithms ¶
WithHashAlgorithms sets the digest algorithms used to hash subject files.
func WithInputAttestations ¶
func WithInputAttestations(inputs ...*intoto.ResourceDescriptor) OptFn
WithInputAttestations appends inputAttestations.
func WithInternalParameters ¶
WithInternalParameters sets the internal parameters (v1 only).
func WithInvocationID ¶
WithInvocationID sets the build invocation id (v0.2: metadata.buildInvocationId).
func WithPolicyDigest ¶
WithPolicyDigest merges policy.digest entries.
func WithPredicate ¶
WithPredicate sets a base predicate the content options are merged onto.
func WithReproducible ¶
WithReproducible sets metadata.reproducible (v0.2 only).
func WithResolvedDependencies ¶
func WithResolvedDependencies(deps ...*intoto.ResourceDescriptor) OptFn
WithResolvedDependencies appends resolved dependencies (v0.2: materials).
func WithSigner ¶
WithSigner sets the signer used to sign the attestation.
func WithStartedOn ¶
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 ¶
WithTimeVerified sets timeVerified.
func WithVerificationResult ¶
WithVerificationResult sets verificationResult, e.g. "PASSED".
func WithVerifiedLevels ¶
WithVerifiedLevels appends verifiedLevels.
func WithWriter ¶
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 ¶
AttestSlsaProvenanceV1 generates a SLSA build provenance v1 attestation.
func (*Writer) AttestSlsaProvenanceV02 ¶
AttestSlsaProvenanceV02 generates a SLSA build provenance v0.2 attestation.
func (*Writer) AttestVSAV1 ¶
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. |