replay

package
v0.38.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 57 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ArtifactTypeSnapshot is the artifactType for both the per-platform
	// snapshot index and the top-level multi-platform snapshot index.
	ArtifactTypeSnapshot = "application/vnd.docker.buildx.snapshots.v1+json"
	// ArtifactTypeMaterials is the artifactType for the materials artifact
	// manifest nested inside a per-platform snapshot index.
	ArtifactTypeMaterials = "application/vnd.docker.buildx.snapshots.materials.v1+json"
)

Media types and artifact types that identify buildx snapshots and the materials manifest child.

View Source 
const (
	CompareModeDigest   = "digest"
	CompareModeArtifact = "artifact"
)

Compare modes accepted by Verify.

View Source 
const (
	EventTypeNone               = ""
	EventTypeDescriptorMismatch = "DescriptorMismatch"
	EventTypeIndexBlobMismatch  = "IndexBlobMismatch"
	EventTypeConfigBlobMismatch = "ConfigBlobMismatch"
	EventTypeLayerBlobMismatch  = "LayerBlobMismatch"
)
View Source 
const VerifyVSAPredicateType = "https://slsa.dev/verification_summary/v1"

VerifyVSAPredicateType is the in-toto predicate type for a SLSA Verification Summary Attestation.

Variables

This section is empty.

Functions

func Build 

func Build(ctx context.Context, dockerCli command.Cli, builderName string, req *BuildRequest) (retErr error)

Build executes the replay request against the supplied builder.

Fail-fast: cross-check errors are reported per-subject with typed errors (Missing/ExtraSecretError, Missing/ExtraSSHError) before any solve starts; a local-context predicate fails with UnreplayableLocalContextError.

Mode selection:

  • BuildModeMaterials (default): recorded frontend + strict source-policy pinning via the session policy callback.
  • BuildModeFrontend: recorded frontend + NO strict pinning (sources float).

func BuildOptionsFromPredicate 

func BuildOptionsFromPredicate(s *Subject, pred *Predicate, req *BuildRequest) (build.Options, error)

BuildOptionsFromPredicate maps a (subject, predicate) pair to a build.Options. The resulting options have Exports left empty; Build populates them from the request.

func CheckSSH 

func CheckSSH(declared []*provenancetypes.SSH, provided []*buildflags.SSH) error

CheckSSH enforces the provenance vs. user-supplied SSH cross check.

func CheckSecrets 

func CheckSecrets(declared []*provenancetypes.Secret, provided buildflags.Secrets) error

CheckSecrets enforces the provenance vs. user-supplied secret-ID cross check: required (non-optional) IDs declared in provenance must be provided; any provided IDs not declared in provenance are rejected.

func CompareDigest 

func CompareDigest(subject, replay ocispecs.Descriptor) bool

CompareDigest returns whether subject and replay descriptors share the same manifest digest. This is the fastest check and is the default for `replay verify`.

func ErrCompareMismatch 

func ErrCompareMismatch(reason string, report any) error

ErrCompareMismatch constructs a CompareMismatchError.

func ErrExtraSSH 

func ErrExtraSSH(ids []string) error

ErrExtraSSH constructs an ExtraSSHError.

func ErrExtraSecret 

func ErrExtraSecret(ids []string) error

ErrExtraSecret constructs an ExtraSecretError.

func ErrMaterialNotFound 

func ErrMaterialNotFound(uri, dgst string) error

ErrMaterialNotFound constructs a MaterialNotFoundError.

func ErrMinModeProvenance 

func ErrMinModeProvenance() error

ErrMinModeProvenance constructs a MinModeProvenanceError.

func ErrMissingSSH 

func ErrMissingSSH(ids []string) error

ErrMissingSSH constructs a MissingSSHError.

func ErrMissingSecret 

func ErrMissingSecret(ids []string) error

ErrMissingSecret constructs a MissingSecretError.

func ErrNoProvenance 

func ErrNoProvenance(subject string) error

ErrNoProvenance constructs a NoProvenanceError.

func ErrNoProvenanceForManifest 

func ErrNoProvenanceForManifest(subject string) error

ErrNoProvenanceForManifest constructs a NoProvenanceError for an image manifest referenced directly.

func ErrNotImplemented 

func ErrNotImplemented(feature string) error

ErrNotImplemented constructs a NotImplementedError.

func ErrSignatureVerificationRequired 

func ErrSignatureVerificationRequired(source, envelope string) error

ErrSignatureVerificationRequired constructs a SignatureVerificationRequiredError.

func ErrUnpinnedContext 

func ErrUnpinnedContext(uri string) error

ErrUnpinnedContext constructs an UnpinnedContextError.

func ErrUnreplayableLocalContext 

func ErrUnreplayableLocalContext(sources []string) error

ErrUnreplayableLocalContext constructs an UnreplayableLocalContextError.

func ErrUnsupportedPredicate 

func ErrUnsupportedPredicate(predicateType string) error

ErrUnsupportedPredicate constructs an UnsupportedPredicateError.

func ErrUnsupportedSubject 

func ErrUnsupportedSubject(kind string) error

ErrUnsupportedSubject constructs an UnsupportedSubjectError.

func MaterialsManifest 

func MaterialsManifest(layers []ocispecs.Descriptor) (ocispecs.Manifest, ocispecs.Descriptor, []byte, error)

MaterialsManifest builds the materials artifact manifest descriptor (the image-manifest document plus its serialized bytes and descriptor) from the ordered list of layer descriptors. The caller owns the task of copying the referenced layer bytes (and the empty config) into the snapshot store; this function produces only the manifest document and its addressable descriptor.

The layers parameter is used verbatim and must already include (in order):

  1. http material layers (mediaType application/octet-stream)
  2. container-blob layers (mediaType vnd.oci.image.layer.v1.tar+gzip or the recorded equivalent)
  3. image-material root-index blobs kept opaque (mediaType vnd.oci.image.index.v1+json)

func MultiPlatformSnapshotIndex 

func MultiPlatformSnapshotIndex(perPlatform []ocispecs.Descriptor) (ocispecs.Index, ocispecs.Descriptor, []byte, error)

MultiPlatformSnapshotIndex wraps N per-platform snapshot index descriptors into a top-level index. Each input descriptor must already carry its `Platform` field so consumers can pick the right child.

func OCIEmptyConfigBytes 

func OCIEmptyConfigBytes() []byte

OCIEmptyConfigBytes returns the raw bytes of the OCI empty config (`{}`) that callers must write into the snapshot content store so the materials artifact manifest has a valid content-addressable config blob.

func OCIEmptyConfigDescriptor 

func OCIEmptyConfigDescriptor() ocispecs.Descriptor

OCIEmptyConfigDescriptor returns the descriptor buildx uses for the empty config on the materials artifact manifest. The two bytes of the empty config are inlined via the descriptor's `data` field (OCI 1.1) so a consumer never has to fetch the empty-config blob separately.

func PerPlatformSnapshotIndex 

func PerPlatformSnapshotIndex(
	attestManifest ocispecs.Descriptor,
	materialsManifestDesc ocispecs.Descriptor,
	imageMaterialManifests []ocispecs.Descriptor,
) (ocispecs.Index, ocispecs.Descriptor, []byte, error)

PerPlatformSnapshotIndex builds a per-platform snapshot index. `attestManifest` is the ORIGINAL provenance attestation manifest descriptor; it becomes the index's `subject` and its blob must be copied into the snapshot content store by the caller.

`materialsManifestDesc` — descriptor of the materials artifact manifest — is included as the first entry in `manifests[]` when non-zero. Passing a zero descriptor omits the materials manifest entirely (used when `--include-materials=false`).

`imageMaterialManifests` — platform-specific image manifests for each image material — follow the materials manifest. Each descriptor's `Digest` addresses the platform-specific manifest that the original build actually used; its chain (manifest + config + layers) is expected to be present in the snapshot store.

func ReplayPinCallback 

func ReplayPinCallback(idx *PinIndex) policysession.PolicyCallback

ReplayPinCallback returns a policysession.PolicyCallback that enforces the pin index. Sources covered by the index are ALLOWed when their requested digest matches; unknown sources are DENY (fail-closed); covered sources with wrong digest are DENY with a DenyMessage.

func ReportJSON 

func ReportJSON(r *CompareReport) ([]byte, error)

ReportJSON serializes a CompareReport to JSON. A nil report is emitted as an empty object.

func ReportMatched 

func ReportMatched(r *CompareReport) bool

ReportMatched reports whether a CompareReport represents a successful compare (no divergence events). An empty tree counts as matched.

func Snapshot 

func Snapshot(ctx context.Context, dockerCli command.Cli, builderName string, req *SnapshotRequest) error

Snapshot produces a replay snapshot for the supplied subjects/predicates and writes it through the configured --output target. This function does NOT invoke build.Build — snapshot is pure content movement plus manifest assembly.

dockerCli + builderName are consumed only to construct a buildx image resolver so that image materials can be fetched from their recorded registries. They may be zero when all materials are resolvable purely via req.Materials (e.g. tests that pre-pin an --materials=oci-layout store).

func SubjectKey 

func SubjectKey(s *Subject) string

SubjectKey returns a stable identifier for a subject, used as the map key for build.Build's map[string]Options input.

func VerifySignatures 

func VerifySignatures(ctx context.Context, dockerCli command.Cli, subjects []*Subject) error

VerifySignatures verifies signatures attached to the selected image subjects' provenance attestations. One verifier provider is shared across all platforms so its trust-root state is initialized only once. Unsigned images remain valid replay inputs; a published but invalid signature fails closed. Standalone Sigstore bundles are already verified while loading.

Types

type BuildMode 

type BuildMode string

BuildMode is a replay mode. 

const (
	BuildModeMaterials BuildMode = "materials"
	BuildModeFrontend  BuildMode = "frontend"
)

type BuildPlan 

type BuildPlan struct {
	// Subjects is one SubjectBuildPlan per replay target.
	Subjects []SubjectBuildPlan `json:"subjects"`
}

BuildPlan is the JSON-serializable dry-run payload for `replay build`. Field names are stable and consumed by tests / tooling.

func MakeBuildPlan 

func MakeBuildPlan(req *BuildRequest) (*BuildPlan, error)

MakeBuildPlan constructs the dry-run plan for a BuildRequest. It runs the same pre-solve checks as Build, so any condition that would fail the replay before the solve fails the dry-run with the same error.

type BuildPlanConfig 

type BuildPlanConfig struct {
	Frontend      string            `json:"frontend"`
	FrontendAttrs map[string]string `json:"frontendAttrs,omitempty"`
	Context       string            `json:"context,omitempty"`
	Filename      string            `json:"filename,omitempty"`
	Target        string            `json:"target,omitempty"`
	BuildArgs     map[string]string `json:"buildArgs,omitempty"`
	Labels        map[string]string `json:"labels,omitempty"`
	NoCache       bool              `json:"noCache,omitempty"`
	NoCacheFilter []string          `json:"noCacheFilter,omitempty"`
	Secrets       []PlanSecret      `json:"secrets,omitempty"`
	SSH           []string          `json:"ssh,omitempty"`
	NetworkMode   string            `json:"networkMode,omitempty"`
	Exports       []string          `json:"exports,omitempty"`
}

BuildPlanConfig mirrors the build.Options fields replay derives from the predicate — enough for a user to eyeball that the replay will run as expected.

type BuildRequest 

type BuildRequest struct {
	// Targets is the set of (subject, predicate) pairs to replay. For a
	// single-platform subject this is len 1; multi-platform inputs fan
	// out into multiple targets sharing the other fields below.
	Targets []Target

	// Mode selects a replay strategy. Empty defaults to BuildModeMaterials.
	Mode BuildMode

	// Materials resolves provenance materials to local content stores. May
	// be nil, in which case the default sentinel-only resolver is used.
	Materials *MaterialsResolver

	// NetworkMode controls the network mode for RUN instructions in the
	// replayed build (default | none). Empty uses the recorded mode.
	// Material resolution is NOT affected.
	NetworkMode string

	// Secrets / SSH hold the user-supplied specs for the replayed solve.
	// Cross-checked against each predicate via Secrets()/SSH() before any
	// solve begins.
	Secrets buildflags.Secrets
	SSH     []*buildflags.SSH

	// Exports are the buildflags-parsed --output specs.
	Exports []*buildflags.ExportEntry

	// Tags are "--tag" values to apply to image/oci/docker exports. Flow
	// matches `docker buildx build`: the tags become the `name=` attribute
	// on each eligible export via build/opt.go toSolveOpt.
	Tags []string

	// Progress controls the display mode for replay progress output.
	Progress progressui.DisplayMode
}

BuildRequest is a single replay-build invocation spanning one or more targets that share the same user-supplied flags.

type CompareEvent 

type CompareEvent struct {
	Type   string               `json:"type,omitempty"`
	Inputs [2]CompareEventInput `json:"inputs,omitempty"`
	Diff   string               `json:"diff,omitempty"`
}

CompareEvent records a single divergence at one tree node.

type CompareEventInput 

type CompareEventInput struct {
	Descriptor *ocispecs.Descriptor `json:"descriptor,omitempty"`
	Index      *ocispecs.Index      `json:"index,omitempty"`
	Manifest   *ocispecs.Manifest   `json:"manifest,omitempty"`
}

CompareEventInput carries the relevant object for one side of a mismatch.

type CompareMismatchError 

type CompareMismatchError struct {
	// Report is typed as any so callers can surface either the basic compare
	// tree or a future richer report format without breaking the error type.
	Report any
	Reason string
}

CompareMismatchError is returned by `replay verify` when the replayed artifact does not match the subject. The wrapped Report may be nil when no structured diff is available (digest comparison).

func (*CompareMismatchError) Error 

func (e *CompareMismatchError) Error() string

type CompareReport 

type CompareReport struct {
	CompareEvent
	Context  string           `json:"context,omitempty"`
	Children []*CompareReport `json:"children,omitempty"`
}

CompareReport is the basic per-node event tree emitted by replay verify.

func CompareArtifact 

func CompareArtifact(ctx context.Context, subject, replay *Subject) (*CompareReport, error)

CompareArtifact walks both subject and replay stores and returns a CompareReport describing any divergence.

The comparison is content-addressed: it reports which descriptors differ, not how their contents differ. A manifest-digest match short-circuits the walk and returns an empty report (no divergence). A mismatch at any level surfaces as an event node populated with inputs referring to the two sides.

type ExtraSSHError 

type ExtraSSHError struct {
	IDs []string
}

ExtraSSHError is returned when the user supplies SSH agents that the provenance does not declare.

func (*ExtraSSHError) Error 

func (e *ExtraSSHError) Error() string

type ExtraSecretError 

type ExtraSecretError struct {
	IDs []string
}

ExtraSecretError is returned when the user supplies secrets that the provenance does not declare.

func (*ExtraSecretError) Error 

func (e *ExtraSecretError) Error() string

type MaterialNotFoundError 

type MaterialNotFoundError struct {
	URI    string
	Digest string
}

MaterialNotFoundError indicates a provenance material that the resolver could not locate in any configured store.

func (*MaterialNotFoundError) Error 

func (e *MaterialNotFoundError) Error() string

type MaterialsResolver 

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

MaterialsResolver resolves provenance materials to a (descriptor, provider) pair the replay pipeline can use to serve content locally. Lookup order:

  1. overrides keyed by URI or "sha256:<digest>"
  2. explicit stores, in the order listed on `--materials`
  3. the `provenance` sentinel (fetch from the URI recorded in provenance)

Explicit stores and overrides are only consumed by `replay snapshot`; `replay build` and `replay verify` support the provenance sentinel only.

func NewMaterialsResolver 

func NewMaterialsResolver(specs []string) (*MaterialsResolver, error)

NewMaterialsResolver parses the --materials list and returns a resolver. Spec forms accepted:

  • "provenance" — sentinel (default when the --materials list is empty)
  • "oci-layout://<path>[:<tag>]" — OCI layout store
  • "<absolute-path>" — raw content store (blobs/<alg>/<hex>)
  • "<key>=<spec>" — override: <key> is the URI or "sha256:<digest>"; <spec> is any of the above narrowed to one blob.

func (*MaterialsResolver) HasExplicitSources 

func (r *MaterialsResolver) HasExplicitSources() bool

HasExplicitSources reports whether replay would need to inject locally resolved material content into a solve. The provenance sentinel alone does not require injection because BuildKit fetches those sources normally.

func (*MaterialsResolver) HasStores 

func (r *MaterialsResolver) HasStores() bool

HasStores reports whether any explicit stores are configured. The primary use is driving behavior when the resolver has only a sentinel.

func (*MaterialsResolver) Overrides 

func (r *MaterialsResolver) Overrides() map[string]string

Overrides returns an iteration-stable copy of the configured overrides for tests and dry-run inspection.

func (*MaterialsResolver) Resolve 

func (r *MaterialsResolver) Resolve(ctx context.Context, uri string, dgst digest.Digest, opts ...ResolveOption) (ocispecs.Descriptor, content.Provider, error)

Resolve returns the descriptor and content.Provider that serve the material with the given (uri, dgst). Exactly one of uri / dgst may be empty; when both are empty an error is returned.

Strict by default: materials not covered by the configured stores / overrides and not reachable via the sentinel produce MaterialNotFoundError. The provenance sentinel is NOT a network fetch — it signals that BuildKit may resolve the material itself, subject to the source-policy pin callback. A caller that requires a concrete (descriptor, provider) pair for a sentinel-only material should use the store-backed resolution path.

Snapshot-backed stores are detected at lookup time. When `dgst` matches a snapshot's materials-manifest layer AND the layer is an image-material root manifest/index stashed as opaque bytes by `replay snapshot`, Resolve returns the platform-specific child manifest descriptor reachable through the snapshot index's `manifests[]`. The caller should pass WithPlatform so the correct child can be picked.

func (*MaterialsResolver) Sentinel 

func (r *MaterialsResolver) Sentinel() bool

Sentinel reports whether the `provenance` sentinel is enabled. The sentinel authorises a fallback fetch from the URI recorded in the provenance.

type MinModeProvenanceError 

type MinModeProvenanceError struct{}

MinModeProvenanceError is returned when the provenance was recorded with mode=min, which omits the build arguments, secrets and SSH needed to reconstruct the build.

func (*MinModeProvenanceError) Error 

func (e *MinModeProvenanceError) Error() string

type MissingSSHError 

type MissingSSHError struct {
	IDs []string
}

MissingSSHError is returned when provenance declares required SSH agents that the user did not provide.

func (*MissingSSHError) Error 

func (e *MissingSSHError) Error() string

type MissingSecretError 

type MissingSecretError struct {
	IDs []string
}

MissingSecretError is returned when provenance declares required secrets that the user did not provide.

func (*MissingSecretError) Error 

func (e *MissingSecretError) Error() string

type NoProvenanceError 

type NoProvenanceError struct {
	Subject string
	// Manifest is set when the subject is an image manifest referenced
	// directly rather than through its image index.
	Manifest bool
}

NoProvenanceError is returned when no SLSA provenance attestation could be found for a subject.

func (*NoProvenanceError) Error 

func (e *NoProvenanceError) Error() string

type NotImplementedError 

type NotImplementedError struct {
	Feature string
}

NotImplementedError marks a feature that is not yet implemented.

func (*NotImplementedError) Error 

func (e *NotImplementedError) Error() string

type PinIndex 

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

PinIndex is a resolved, URI/digest-keyed view of the predicate's ResolvedDependencies suitable for fast policy-callback lookup.

Exact material identifiers and lossy aliases are kept separate. An alias can name more than one pin (for example the same image tag at two digests), so it must never use last-write-wins selection.

func NewPinIndex 

func NewPinIndex(p *Predicate) *PinIndex

NewPinIndex builds a PinIndex from the predicate's ResolvedDependencies. When a material has multiple digest entries (e.g. sha256 + sha512), the sha256 entry is preferred; otherwise the first entry wins. Materials without a usable digest are skipped.

func (*PinIndex) Lookup 

func (p *PinIndex) Lookup(uri string) (digest.Digest, bool)

Lookup resolves a URI to its pinned digest. Returns ("", false) when the URI is not covered by the index.

type PlanMaterial 

type PlanMaterial struct {
	URI string `json:"uri,omitempty"`
	// Platform is populated for image materials only — either parsed
	// from the purl `?platform=` qualifier or, when the URI doesn't
	// carry one, from the predicate's builder platform.
	Platform *ocispecs.Platform `json:"platform,omitempty"`
	Digest   string             `json:"digest,omitempty"`
	// Kind is one of: "image", "image-blob" (container-blob), "http",
	// "git", or "unknown".
	Kind string `json:"kind"`
	// Included reports whether `replay snapshot` would copy this
	// material's bytes into the snapshot.
	Included bool `json:"included,omitempty"`
	// Size is the total byte size this material contributes to the
	// snapshot — the root index plus the platform-matched manifest
	// chain (config + all layer descriptor sizes). Only populated for
	// image materials during snapshot dry-run; computed from manifest
	// metadata alone (no layer bodies are fetched).
	Size int64 `json:"size,omitempty"`
}

PlanMaterial describes one provenance material. Different dry-run modes populate different subsets of the fields, but the JSON shape stays stable.

type PlanSecret 

type PlanSecret struct {
	ID       string `json:"id"`
	Optional bool   `json:"optional,omitempty"`
}

PlanSecret describes one declared secret plus whether it is optional.

type Predicate 

type Predicate provenancetypes.ProvenancePredicateSLSA1

Predicate is a named type over ProvenancePredicateSLSA1 so replay code can attach accessors without copying or wrapping. The receiver is never nil: callers must have obtained a non-nil *Predicate from Subject.Predicate.

func (*Predicate) BuilderPlatform 

func (p *Predicate) BuilderPlatform() ocispecs.Platform

BuilderPlatform returns the platform the original builder ran on, parsed from InternalParameters.builderPlatform. Falls back to the runtime host platform when the field is missing or malformed.

func (*Predicate) ConfigSource 

func (p *Predicate) ConfigSource() provenancetypes.ProvenanceConfigSourceSLSA1

ConfigSource returns the configSource descriptor recorded on the predicate.

func (*Predicate) DefaultPlatform 

func (p *Predicate) DefaultPlatform() (*ocispecs.Platform, bool)

DefaultPlatform returns the effective provenance default platform for resolving host-side image sources during replay. It prefers the recorded platform-qualified image materials when they all agree, and otherwise falls back to the recorded builderPlatform field.

func (*Predicate) FallbackTargetPlatform 

func (p *Predicate) FallbackTargetPlatform() (*ocispecs.Platform, bool)

FallbackTargetPlatform infers the target platform from the build's LLB for older provenance that does not record targetPlatform. BuildKit injects TARGETPLATFORM into Dockerfile exec environments. A single provenance statement must agree on that value; mixed or malformed values are not safe to use as an implicit replay target.

func (*Predicate) Frontend 

func (p *Predicate) Frontend() string

Frontend returns the frontend id recorded on the predicate, falling back to dockerfile.v0 when the predicate does not record one.

func (*Predicate) FrontendAttrs 

func (p *Predicate) FrontendAttrs() map[string]string

FrontendAttrs returns the recorded frontend attrs with attestation-related keys stripped. Returns a fresh map so callers can mutate it.

func (*Predicate) IsMinMode 

func (p *Predicate) IsMinMode() bool

IsMinMode reports whether the provenance was recorded with mode=min. Only mode=max records the build definition. mode=min also drops build arguments, labels, secrets and SSH from the recorded request, so the original build cannot be reconstructed from it.

func (*Predicate) Locals 

func (p *Predicate) Locals() []*provenancetypes.LocalSource

Locals returns the local-context sources recorded on the predicate. A non-empty result should cause replay to fail with UnreplayableLocalContextError.

func (*Predicate) RecordedBuilderPlatform 

func (p *Predicate) RecordedBuilderPlatform() (*ocispecs.Platform, bool)

RecordedBuilderPlatform returns the platform recorded in InternalParameters.builderPlatform when present and valid.

func (*Predicate) ResolvedDependencies 

func (p *Predicate) ResolvedDependencies() []slsa1.ResourceDescriptor

ResolvedDependencies returns every material recorded on the predicate. Classification by URI scheme is left to the caller (see MaterialsResolver).

func (*Predicate) SSH 

func (p *Predicate) SSH() []*provenancetypes.SSH

SSH returns the declared SSH entries from the predicate's request.

func (*Predicate) Secrets 

func (p *Predicate) Secrets() []*provenancetypes.Secret

Secrets returns the declared secrets from the predicate's request.

func (*Predicate) TargetPlatform 

func (p *Predicate) TargetPlatform() (*ocispecs.Platform, bool)

TargetPlatform returns the target platform recorded in provenance, falling back to the build's LLB for older attestations that lack the field.

type ResolveOption 

type ResolveOption func(*resolveOptions)

ResolveOption customises a Resolve call.

func WithBuilderPlatform 

func WithBuilderPlatform(p ocispecs.Platform) ResolveOption

WithBuilderPlatform attaches the original builder's platform (recorded in provenance) so the snapshot-backed store can fall back to it when the subject platform has no match in an image material's root index.

func WithPlatform 

func WithPlatform(p *ocispecs.Platform) ResolveOption

WithPlatform attaches a target platform to a Resolve call. When resolving an image material against a snapshot-backed store this selects the per-platform child to return.

type SignatureTimestamp 

type SignatureTimestamp struct {
	Type      string    `json:"type"`
	URI       string    `json:"uri,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

SignatureTimestamp is one verified observer timestamp from a Sigstore bundle, typically a transparency-log or timestamp-authority observation.

type SignatureVerification 

type SignatureVerification struct {
	Verified               bool                 `json:"verified"`
	Type                   string               `json:"type"`
	Identity               string               `json:"identity"`
	CertificateIssuer      string               `json:"certificateIssuer,omitempty"`
	SubjectAlternativeName string               `json:"subjectAlternativeName,omitempty"`
	Issuer                 string               `json:"issuer,omitempty"`
	SourceRepositoryURI    string               `json:"sourceRepositoryURI,omitempty"`
	SourceRepositoryRef    string               `json:"sourceRepositoryRef,omitempty"`
	BuildSignerURI         string               `json:"buildSignerURI,omitempty"`
	RunnerEnvironment      string               `json:"runnerEnvironment,omitempty"`
	Timestamps             []SignatureTimestamp `json:"timestamps,omitempty"`
	TrustRootLastUpdated   *time.Time           `json:"trustRootLastUpdated,omitempty"`
	TrustRootWarning       string               `json:"trustRootWarning,omitempty"`
}

SignatureVerification describes a cryptographically verified Sigstore bundle. Identity is informational: replay accepts unsigned provenance too, so verification does not imply that a separate authorization policy has approved this signer.

type SignatureVerificationRequiredError 

type SignatureVerificationRequiredError struct {
	// Source is the user-visible input that carries the signed envelope
	// (file path for attestation-file inputs).
	Source string
	// Envelope describes the detected envelope shape ("dsse" or
	// "sigstore-bundle") so the user can tell what was rejected.
	Envelope string
}

SignatureVerificationRequiredError is returned when a signed envelope cannot be verified from the available trust material. Replay never silently unwraps such an attestation.

func (*SignatureVerificationRequiredError) Error 

func (e *SignatureVerificationRequiredError) Error() string

type SnapshotPlan 

type SnapshotPlan []SnapshotPlanTarget

SnapshotPlan is the JSON-serializable dry-run payload for `replay snapshot` — one entry per snapshot target.

func MakeSnapshotPlan 

func MakeSnapshotPlan(ctx context.Context, dockerCli command.Cli, builderName string, req *SnapshotRequest) (SnapshotPlan, error)

MakeSnapshotPlan constructs the dry-run plan for a SnapshotRequest. For each image material, the root index + platform-matched manifest bodies are fetched so their descriptor sizes can be summed — layer bodies are not fetched.

type SnapshotPlanTarget 

type SnapshotPlanTarget struct {
	// Subject is the subject descriptor (already carries platform).
	Subject ocispecs.Descriptor `json:"subject"`
	// Materials lists each recorded material and whether the snapshot
	// would include its content.
	Materials []PlanMaterial `json:"materials"`
}

SnapshotPlanTarget is the per-subject snapshot dry-run plan.

type SnapshotRequest 

type SnapshotRequest struct {
	// Targets are the per-platform (subject, predicate) pairs to snapshot.
	// Each subject must carry a non-empty AttestationManifest descriptor
	// (image / oci-layout subjects only; attestation-file inputs are
	// rejected upstream).
	Targets []Target
	// IncludeMaterials controls whether material content is copied and the
	// materials artifact manifest is emitted.
	IncludeMaterials bool
	// Materials resolves image / http / container-blob materials to a local
	// (descriptor, provider) pair. Required when IncludeMaterials is true.
	Materials *MaterialsResolver
	// Output is the parsed --output spec. Exactly one form is allowed
	// (local / oci / registry).
	Output *buildflags.ExportEntry
	// Progress receives step events and non-fatal warnings. May be nil —
	// in that case events are silently dropped.
	Progress progress.Writer
}

SnapshotRequest is the input to Snapshot.

type Subject 

type Subject struct {
	Descriptor ocispecs.Descriptor
	Provider   content.Provider
	// contains filtered or unexported fields
}

Subject is one replayable unit: a single manifest-level descriptor plus a content.Provider that serves that descriptor, its referrers, and the predicate blob.

For image and oci-layout inputs, Descriptor is the produced artifact's manifest descriptor. For an attestation-file input, Descriptor points at the predicate blob in an in-memory content.Provider and there is no produced artifact.

func LoadSubjects 

func LoadSubjects(ctx context.Context, dockerCli command.Cli, builderName, input string) ([]*Subject, error)

LoadSubjects parses a user-supplied input and returns one Subject per manifest to replay. An image index expands into N subjects (one per child manifest); a single image manifest or attestation file returns 1.

Input forms:

  • docker-image://<ref> — explicit remote reference.
  • oci-layout://<path>[:<tag>] — explicit OCI layout directory.
  • <path-to-file> — local attestation file (in-toto / DSSE).
  • <path-to-directory> — treated as an OCI layout.
  • <bare ref> — valid image reference (docker-image).

func (*Subject) AttestationManifest 

func (s *Subject) AttestationManifest() ocispecs.Descriptor

AttestationManifest returns the attestation manifest descriptor associated with this subject, or the zero descriptor if none was found (or the subject was loaded from a local attestation file).

func (*Subject) InputRef 

func (s *Subject) InputRef() string

InputRef returns the user-supplied input string that produced this subject. Used for diagnostics.

func (*Subject) IsAttestationFile 

func (s *Subject) IsAttestationFile() bool

IsAttestationFile reports whether this subject was loaded from a local attestation file (no produced artifact is available).

func (*Subject) Predicate 

func (s *Subject) Predicate(ctx context.Context) (*Predicate, error)

Predicate locates and parses the SLSA v1 provenance predicate attached to Descriptor via Provider. Returns UnsupportedPredicateError on a non-v1 predicateType and NoProvenanceError when none is found.

func (*Subject) Signature 

func (s *Subject) Signature() *SignatureVerification

Signature returns verified signature metadata, or nil for unsigned provenance and images.

type SubjectBuildPlan 

type SubjectBuildPlan struct {
	// Descriptor is the subject descriptor (digest + mediaType + size).
	Descriptor ocispecs.Descriptor `json:"descriptor"`
	// Signature describes the verified signer of a standalone Sigstore bundle
	// or image-attached provenance. It is absent for unsigned provenance.
	Signature *SignatureVerification `json:"signature,omitempty"`
	// BuildConfig summarises the solve parameters replay would use.
	BuildConfig BuildPlanConfig `json:"buildConfig"`
	// Materials lists the resolved provenance materials.
	Materials []PlanMaterial `json:"materials"`
}

SubjectBuildPlan is the per-subject build-mode dry-run plan.

type Target 

type Target struct {
	Subject   *Subject
	Predicate *Predicate
}

Target pairs one subject with its already-loaded predicate. A replay operation spans N targets (one per platform, typically from a multi- platform LoadSubjects fan-out).

type UnpinnedContextError 

type UnpinnedContextError struct {
	URI string
}

UnpinnedContextError is returned when the provenance does not record a digest for a Git subdirectory build context, so replay cannot pin it.

func (*UnpinnedContextError) Error 

func (e *UnpinnedContextError) Error() string

type UnreplayableLocalContextError 

type UnreplayableLocalContextError struct {
	LocalSources []string
}

UnreplayableLocalContextError signals that the original build used a local filesystem context which replay cannot reproduce.

func (*UnreplayableLocalContextError) Error 

func (e *UnreplayableLocalContextError) Error() string

type UnsupportedPredicateError 

type UnsupportedPredicateError struct {
	PredicateType string
}

UnsupportedPredicateError signals that the attached predicate is not SLSA provenance.

func (*UnsupportedPredicateError) Error 

func (e *UnsupportedPredicateError) Error() string

type UnsupportedSubjectError 

type UnsupportedSubjectError struct {
	Kind string
}

UnsupportedSubjectError signals that the supplied subject kind is not compatible with the invoked subcommand.

func (*UnsupportedSubjectError) Error 

func (e *UnsupportedSubjectError) Error() string

type VerifyRequest 

type VerifyRequest struct {
	// Subject is the loaded subject (exactly one — multi-platform subjects
	// are verified one at a time by the caller).
	Subject *Subject
	// Predicate is the subject's provenance predicate.
	Predicate *Predicate
	// Mode selects the comparison strategy: "digest" (default) or
	// "artifact" (descriptor tree walk).
	Mode string
	// Materials resolver, same semantics as BuildRequest.Materials.
	Materials *MaterialsResolver
	// Network controls the replayed build's RUN-network mode.
	Network string
	// Secrets / SSH mirror the BuildRequest shape for secret pass-through.
	Secrets buildflags.Secrets
	SSH     []*buildflags.SSH
	// Output is an optional type=local --output spec for the VSA and diff
	// report.
	Output *buildflags.ExportEntry
	// Progress is the progress display mode for the replayed build.
	Progress progressui.DisplayMode
}

VerifyRequest is the library-level input to Verify.

type VerifyResult 

type VerifyResult struct {
	Matched    bool
	DiffReport *CompareReport
	// VSABytes is the in-toto Statement bytes written when req.Output is
	// set; empty otherwise.
	VSABytes []byte
}

VerifyResult is the library-level result of a verification.

func Verify 

func Verify(ctx context.Context, dockerCli command.Cli, builderName string, req *VerifyRequest) (_ *VerifyResult, retErr error)

Verify replays the subject to an ephemeral OCI layout, compares, and optionally writes a VSA + diff report to req.Output.

On a mismatch the returned error is a typed CompareMismatchError wrapping the diff report; callers should not attempt to interpret Matched=false with nil error.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.