attest

package
v0.2.8 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package attest verifies the Sigstore artifact attestations that pi-go's release workflow publishes.

Every tagged release signs two statements per artifact: SLSA build provenance, which ties the artifact to the workflow run that produced it, and an SBOM. Both are stored by GitHub against the artifact's SHA-256 digest, so verification starts from the bytes on disk and never trusts a filename, a version string compiled into the binary, or the download URL.

Trust is anchored in the public-good Sigstore TUF root: pi-go is a public repository, so its attestations are signed with certificates from fulcio.sigstore.dev and logged in Rekor. Attestations GitHub generates on its own for release assets are signed by a different, GitHub-operated authority and are deliberately out of scope here — this package answers "did dimetron/pi-go's release workflow build these bytes", not "is this file attached to some GitHub release".

Index

Constants

View Source
const (
	// DefaultRepo is the repository whose release workflow signs official
	// pi-go builds.
	DefaultRepo = "dimetron/pi-go"

	// WorkflowPath is the only workflow permitted to sign a release. Pinning
	// it matters: without it, any workflow in the repository — including one
	// added by a pull request — would satisfy the identity check.
	WorkflowPath = ".github/workflows/release.yml"
)
View Source
const (
	PredicateSLSAProvenanceV1 = "https://slsa.dev/provenance/v1"
	PredicateSPDXPrefix       = "https://spdx.dev/Document"
	PredicateCycloneDX        = "https://cyclonedx.org/bom"
)

Predicate types, as they appear in the in-toto statement.

Variables

View Source
var ErrNoAttestations = errors.New("no attestations found for this artifact")

ErrNoAttestations reports that GitHub holds no attestation for a digest. It is not a verification failure: a locally built binary, or one from a release predating attestation, will never have one.

Functions

func FileDigest

func FileDigest(path string) (string, error)

FileDigest returns the hex-encoded SHA-256 of the file at path. This is the only identity an artifact has as far as verification is concerned.

func TUFCacheDir

func TUFCacheDir() (string, error)

TUFCacheDir is where the Sigstore TUF metadata is cached. It lives under pi-go's own state directory so that `pi verify` does not write into a location shared with other Sigstore tooling.

Types

type Fetcher

type Fetcher struct {
	// HTTPClient defaults to http.DefaultClient.
	HTTPClient *http.Client
	// BaseURL defaults to https://api.github.com. Tests override it.
	BaseURL string
	// Token is optional. The endpoint is public for public repositories;
	// a token only raises the rate limit.
	Token string
	// UserAgent is sent with every request.
	UserAgent string
}

Fetcher retrieves attestation bundles from GitHub's attestations API.

func (*Fetcher) Fetch

func (f *Fetcher) Fetch(ctx context.Context, repo, digest string) ([]*bundle.Bundle, error)

Fetch returns every bundle GitHub holds for digest, which is the hex-encoded SHA-256 of the artifact. It returns ErrNoAttestations when the digest is unknown to GitHub.

type Provenance

type Provenance struct {
	Repository string `json:"repository,omitempty"`
	Workflow   string `json:"workflow,omitempty"`
	Ref        string `json:"ref,omitempty"`
	Commit     string `json:"commit,omitempty"`
	RunURL     string `json:"runURL,omitempty"`
	BuildType  string `json:"buildType,omitempty"`
}

Provenance is the part of a SLSA v1 build-provenance predicate worth showing a user: which workflow, at which ref, from which commit, in which run.

type Result

type Result struct {
	PredicateType  string      `json:"predicateType"`
	SignerIdentity string      `json:"signerIdentity,omitempty"`
	SignedAt       time.Time   `json:"signedAt,omitempty"`
	Provenance     *Provenance `json:"provenance,omitempty"`
	SBOM           *SBOM       `json:"sbom,omitempty"`

	// Predicate is the raw predicate, kept so `pi verify --sbom` can print
	// the SBOM document itself rather than a summary of it.
	Predicate json.RawMessage `json:"-"`
}

Result is one verified attestation.

type SBOM

type SBOM struct {
	Format   string `json:"format"`
	Version  string `json:"version,omitempty"`
	Name     string `json:"name,omitempty"`
	Packages int    `json:"packages"`

	// Ecosystems counts packages by purl type ("golang", "github", ...), so
	// the summary says something about what is in the document rather than
	// just how big it is.
	Ecosystems map[string]int `json:"ecosystems,omitempty"`
}

SBOM summarizes an SPDX or CycloneDX document without holding onto it.

func (*SBOM) EcosystemsSorted

func (s *SBOM) EcosystemsSorted() []string

EcosystemsSorted renders the ecosystem counts deterministically, most packages first, so output does not shuffle between runs of a map.

type Verifier

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

Verifier checks bundles against the public-good Sigstore trust root and an identity policy naming a specific repository's release workflow.

func NewVerifier

func NewVerifier(repo string) (*Verifier, error)

NewVerifier builds a verifier for repo, refreshing the Sigstore TUF trust root over the network. Callers that already hold trusted material — tests, mainly — should use NewVerifierWithMaterial.

func NewVerifierWithMaterial

func NewVerifierWithMaterial(repo string, material root.TrustedMaterial) (*Verifier, error)

NewVerifierWithMaterial builds a verifier over caller-supplied trusted material.

func (*Verifier) Verify

func (v *Verifier) Verify(b *bundle.Bundle, digest string) (*Result, error)

Verify checks one bundle against the policy and the artifact digest.

Jump to

Keyboard shortcuts

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