builders

package
v0.1.0-alpha.3 Latest Latest
Warning

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

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

Documentation

Overview

Package builders holds the registry of build platforms the verifier can bind to their signing identity: for each known builder, who must have signed the provenance for its builder.id to count as proven rather than merely claimed.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SplitRef

func SplitRef(id string) (base, ref string)

SplitRef separates a builder id or signer subject from the ref it carries after the first @, if any.

Types

type Builder

type Builder struct {
	// ID is the builder id as provenance records it in builder.id, without
	// the @ref the GitHub builders append.
	ID string `yaml:"id"`
	// IDMatch is how ID is compared with builder.id; exact by default.
	IDMatch IDMatch `yaml:"idMatch,omitempty"`
	// Title names the builder for people.
	Title string `yaml:"title,omitempty"`
	// Description explains what the builder is and how it is bound.
	Description string `yaml:"description,omitempty"`
	// Issuer is the OIDC issuer of the builder's signing certificate. With
	// Signer unset, the signer identity is derived from it and ID: a
	// sigstore identity from Issuer whose subject starts with ID (the
	// builder's ref follows it after an @).
	Issuer string `yaml:"issuer,omitempty"`
	// Signer is the identity spec (see sapi.NewIdentityFromSpec) the
	// provenance must be signed by, when it cannot be derived from
	// Issuer and ID.
	Signer string `yaml:"signer,omitempty"`
	// Ref constrains the ref carried by the signer identity; any by
	// default.
	Ref RefPolicy `yaml:"ref,omitempty"`
	// Delegated marks a builder that runs other builders: its certificate
	// proves the delegator ran, while builder.id names the delegated
	// builder, which is not expected to equal the signer identity.
	Delegated bool `yaml:"delegated,omitempty"`
	// SourceRepositoryBound asserts the signing certificate's source
	// repository is the repository the artifact was built from, so it
	// can be compared with the expected source.
	SourceRepositoryBound bool `yaml:"sourceRepositoryBound,omitempty"`
	// contains filtered or unexported fields
}

Builder describes a build platform and the identity that signs the provenance it produces.

func ParseBinding

func ParseBinding(s string) (*Builder, error)

ParseBinding parses a builder given on the command line as "id=signer-spec" or "id=issuer": the value is an identity spec when it has a spec's shape (type(...)::..., spiffe://..., ref:...) and an OIDC issuer otherwise. The binding is exact on id, accepts any ref and, having no way to know, does not bind the source repository.

func (*Builder) Identity

func (b *Builder) Identity() *sapi.Identity

Identity returns the parsed signer identity. Nil before Validate.

func (*Builder) MatchesID

func (b *Builder) MatchesID(builderID string) bool

MatchesID reports whether builderID (its @ref ignored) names this builder.

func (*Builder) MatchesSigner

func (b *Builder) MatchesSigner(signer *sapi.Identity) bool

MatchesSigner reports whether signer, an identity recorded on a verified signature, is this builder's signer.

func (*Builder) SignerSpec

func (b *Builder) SignerSpec() string

SignerSpec returns the identity spec the builder's provenance must be signed by: Signer when set, else one derived from Issuer and ID.

func (*Builder) Validate

func (b *Builder) Validate() error

Validate checks the entry is complete and its signer identity parses.

type IDMatch

type IDMatch string

IDMatch says how a registry entry's id is compared with a provenance's builder.id (with its @ref removed).

const (
	// IDMatchExact requires builder.id to be the entry's id.
	IDMatchExact IDMatch = "exact"
	// IDMatchPrefix accepts any builder.id starting with the entry's id,
	// for platforms where the builder is the workflow that ran and its
	// identity is what the certificate names.
	IDMatchPrefix IDMatch = "prefix"
)

type RefPolicy

type RefPolicy string

RefPolicy constrains the ref a signer identity carries after its @ (https://github.com/org/repo/.github/workflows/build.yml@refs/tags/v1.2.3).

const (
	// RefAny accepts any ref, including none.
	RefAny RefPolicy = "any"
	// RefSemverTag requires a release tag, refs/tags/vX.Y.Z: a builder
	// running from a branch or an arbitrary tag is not the released
	// builder its id names.
	RefSemverTag RefPolicy = "semver-tag"
)

func (RefPolicy) Allows

func (p RefPolicy) Allows(ref string) bool

Allows reports whether ref satisfies the policy.

type Registry

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

Registry is an ordered set of builders. Exact-id entries take precedence over prefix entries in lookups, so a specific builder can be described alongside the platform pattern that would also match it.

func Load

func Load(path string) (*Registry, error)

Load reads a registry from a YAML file or a directory of YAML files.

func LoadEmbedded

func LoadEmbedded() (*Registry, error)

LoadEmbedded loads the builders compiled into the binary.

func New

func New(builders ...*Builder) (*Registry, error)

New returns a registry holding the given builders, validated. A later entry with the same id and idMatch replaces an earlier one, so user-supplied entries override the embedded ones.

func Parse

func Parse(data []byte) (*Registry, error)

Parse reads a registry file's YAML.

func (*Registry) Add

func (r *Registry) Add(b *Builder) error

Add validates b and adds it to the registry, replacing an entry with the same id and idMatch.

func (*Registry) Builders

func (r *Registry) Builders() []*Builder

Builders returns the entries, exact ids first.

func (*Registry) ForSigner

func (r *Registry) ForSigner(signer *sapi.Identity) *Builder

ForSigner returns the builder whose signer identity signer is, or nil when no known builder signs with it.

func (*Registry) Len

func (r *Registry) Len() int

Len returns the number of entries.

func (*Registry) Lookup

func (r *Registry) Lookup(builderID string) *Builder

Lookup returns the builder that builderID names, or nil when the registry does not know it.

func (*Registry) Merge

func (r *Registry) Merge(other *Registry) error

Merge adds every builder of other into r, with other's entries replacing r's on the same id.

Jump to

Keyboard shortcuts

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