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 ¶
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" )
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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.