Skip to content

Clarify terminology around artifact attestation generation

We currently document "artifact attestation" as a feature, but this does not align with industry-standard terminology for what constitutes an "attestation".

We should clarify that what we are producing today is simply "build provenance metadata". It is not signed and thus should not be referred to as an "attestation".

See diagram and description of an attestation's constituent components (copied below): https://slsa.dev/attestation-model#model-and-terminology

Components:

  • Artifact: Immutable blob of data described by an attestation, usually identified by cryptographic content hash. Examples: file content, git commit, container digest. MAY also include a mutable locator, such as a package name or URI.
  • Attestation: Authenticated, machine-readable metadata about one or more software artifacts. An attestation MUST contain at least:
    • Envelope: Authenticates the message. At a minimum, it MUST contain:
      • Message: Content (statement) of the attestation. The message type SHOULD be authenticated and unambiguous to avoid confusion attacks.
      • Signature: Denotes the attester who created the attestation.
    • Statement: Binds the attestation to a particular set of artifacts. This is a separate layer to allow for predicate-agnostic processing and storage/lookup. MUST contain at least:
      • Subject: Identifies which artifacts the predicate applies to.
      • Predicate: Metadata about the subject. The predicate type SHOULD be explicit to avoid misinterpretation.
    • Predicate: Arbitrary metadata in a predicate-specific schema. MAY contain:
      • Link: (repeated) Reference to a related artifact, such as build dependency. Effectively forms a [hypergraph] where the nodes are artifacts and the hyperedges are attestations. It is helpful for the link to be standardized to allow predicate-agnostic graph processing.
  • Bundle: A collection of Attestations, which are usually but not necessarily related.
  • Storage/Lookup: Convention for where attesters place attestations and how verifiers find attestations for a given artifact.