[UI/UX support for attestations] Audit Supported Attestation Types

[nlhkabu]

Mental models for the different types of attestations

Attestations can have different types of "predicates" which define the specific content and format of the claim being made about a package artifact. In practice, this creates different types of attestations for end users to understand.

Image source: https://slsa.dev/attestation-model

Predicates supported on npm, PYPI, RubyGems

Registry	Predicate Name	Predicate URI (Full Link)	Mental Model / Purpose	Key Question it Answers	Example Rekor Log
PyPI	PyPI Publish	https://docs.pypi.org/attestations/publish/v1/	A verified and tamper-proof record, signed by PyPI itself, confirming that that a release file was uploaded via a PyPI Trusted Publisher, and that a specific Trusted Publisher identity was used to publish the file, such as a particular GitHub Actions workflow, etc.	Can I verify that this exact file was uploaded to PyPI by the project's official, pre-authorized publishing workflow, and not by some other means like a compromised developer's API token?	https://search.sigstore.dev/?logIndex=227282797
PyPI	SLSA Provenance	https://slsa.dev/provenance/v1	A verifiable and tamper-proof record, signed by the build platform (e.g., GitHub Actions, Google Cloud Build), that details exactly how a software artifact was produced, cryptographically linking the final artifact back to its original source code, build instructions, and dependencies.	"Can I verify that this software artifact was securely built from the expected source code, by a trusted build system, and that it wasn't tampered with during the build process?"	None generated to date.
npm	SLSA Provenance	https://slsa.dev/provenance/v1	A verifiable and tamper-proof record, signed by the build platform (e.g., GitHub Actions, Google Cloud Build), that details exactly how a software artifact was produced, cryptographically linking the final artifact back to its original source code, build instructions, and dependencies.	"Can I verify that this software artifact was securely built from the expected source code, by a trusted build system, and that it wasn't tampered with during the build process?"	https://search.sigstore.dev/?logIndex=243056726
npm	npm Publish	https://github.com/npm/attestation/tree/main/specs/publish/v0.1	A verifiable and tamper-proof record, signed by npm itself, creating an authoritative link between a package's identity (name and version) and its content (hash)	Is the package I just downloaded with this specific content hash the same one that the npm registry officially recognises as this package name and version?"	https://search.sigstore.dev/?logIndex=211457175
RubyGems	No formal predicate name	No formal predicate spec	A verified and tamper-proof record, signed by RubyGems itself, confirming that that a release file was uploaded via a RubyGems Trusted Publisher, and that a specific Trusted Publisher identity was used to publish the file, such as a particular GitHub Actions workflow, etc.	Can I verify that this exact file was uploaded to RubyGems by the project's official, pre-authorized publishing workflow, and not by some other means like a compromised developer's API token?	https://search.sigstore.dev/?logIndex=225255766

1. SLSA Provenance

   • The predicate standard used by build platforms (e.g. GitHub, GitLab, etc.) to attest the details of an artifact build
   • Supported by npm and PyPI
   • All attestations exposed on the npm UI are SLSA provenance
   • Currently there are no SLSA attestions on PyPI. This is because there is no widely adopted workflow for PyPI project maintainers to generate SLSA provenance attestations. See this (unofficial) documentation for an example SLSA publishing workflow for PyPI.

2. Publish Attestations

   • These are predicates created by PyPI, npm and RubyGems, who can "sign" an attestation
   • PyPI and npm have defined a formal predicate for their publish attestations, RubyGems have not (TBC)
   • PyPI and RubyGems publish attestations include information about the Trusted publisher and associated build workflow.
   • npm's publish attestation does not include trusted publisher information, or information about the build workflow. Currently, publish attestations are not exposed in npm's UI

UI Considerations

Package repositories can display multiple attestations per file/package (each with a different predicates).

• "Currently PyPI supports two attestations per file: one for each of the allowed predicates." (see PyPI docs). However there are currently no PyPI packages with multiple attestations.
• In the future, more predicate types may emerge, as different organisations or users choose to verify packages for their own purposes
• In the future, established/existing predicate types will publish new versions (e.g. SLSA versioning). Currently there are both SLSA v.02 and SLSA v.1 attestations on npm (3, 836 and 26,757 respectively, as of 2025-06-17)
• For users to differentiate between the different types of attestations, and understand what they each mean, the predicate type (including version) must be exposed (and explained) in the UI. Currently PyPI exposes the predicate type, but does not explain it. Neither npm or RubyGems expose the predicate type.

[steiza]

I would probably describe the npm publish attestation differently. Here's an example npm publish attestation:

_type: https://in-toto.io/Statement/v0.1
subject:
  - name: pkg:npm/semver@7.7.2
    digest:
      sha512: >-
        445d05c3eacee4031ff4c0326915c8e005745258f994c1ea571c5d4a08956e2c52097a049a65ff8e4d02b89c38fb74aaae860ef55a1487e1dcb898afbed25e98
predicateType: https://github.com/npm/attestation/tree/main/specs/publish/v0.1
predicate:
  name: semver
  version: 7.7.2
  registry: https://registry.npmjs.org

The subject does say what's in the package (the information in the subject) but there isn't any information about who published - that would come from the workload identity in the SLSA Provenance. Instead, the point of the publish attestation is the registry attesting that this artifact (with this hash) is part of this named package at this version. That information is also in the subject of the SLSA Provenance attestation, but that's constructed inside the GitHub Actions workflow. Only npm has the key material to create the npm Publish attestations, and so it is an authoritative source for what a specific package name and version should contain.

[nlhkabu]

Thanks very much for this clarification @steiza . I've updated the description to reflect this. Please let me know if this is still missing the point :)

[nlhkabu]

A further question @steiza :

Do you know if the intention is to expand the npm publish predicate to include information about the trusted publisher and build workflow once npm supports OICD (https://github.com/orgs/community/discussions/161015) ?

[steiza]

Your update looks good to me!

Do you know if the intention is to expand the npm publish predicate to include information about the trusted publisher and build workflow once npm supports OIDC?

Not in the first release, but this is very much being considered for follow-on work.

[nlhkabu]

@steiza if you have a moment, would also love your feedback on #77, especially the section about how repos will choose which attestation predicates to support in future

[nlhkabu]

See ssci.io/attestations-deck - a great reference for what attestations are and what they do. Thank you to @hepwori for this resource link :)

Slides 14, 15, 16 are most relevant re: users understanding the different types of attestations are and assessing their trustworthiness.