-
Notifications
You must be signed in to change notification settings - Fork 21
Description
Attestations on npm
Summary
npm effectively presents attestations through a discoverable UI with clear visual cues, successfully communicating a baseline of trust to users. However, the supporting documentation splits content for consumers and maintainers, making it difficult for users to find crucial context on the value and limitations of provenance.
The primary opportunity for npm is to create (and prominently expose) unified, consumer-focused documentation that helps users fully interpret the data provided in the UI, bridging the gap between seeing the information and understanding its practical security implications.
Attestations discoverability
Attestations on npm are relitively easy to find.
They are located at the bottom of the package page, directly below the readme provided by the package author, under a "Provenance" heading:
There is also a green check mark next to the version information in the sidebar, that, when clicked, shows a small popover saying "Built with tool
":
Clicking on the "View more details" link on this popover redirects users to Provenance section at the bottom of the package page. Note that this link does not work when clicked from the code or dependency tabs (this is a bug).
Green check marks are also present on the Versions page, next to each release:
These check marks also launch popovers, which link to the Provenance section at the bottom of each version's page.
Attestations content
Left Side
- Green checkmark:
- This provides a visual indicator that the package is "correct" or "approved"
- This matches the other green checkmarks throughout the interface, visually and conceptually linking them together
- Built and signed on
GitHub Actions
:- This indicates the platform where the software was compiled/packaged and cryptographically signed.
- View build summary link
- This links to the automated workflow (in this case GitHub actions) that produced the package
Right Side
Provides the verifiable links that tie the final package back to its origins:
- Source Commit:
- This links to the exact version of the source code that was used for this build, identified by a unique Git commit hash
(06cd267)
- This links to the exact version of the source code that was used for this build, identified by a unique Git commit hash
- Build File:
- This is a link to the configuration file (.github/workflows/release.yml) that defined the build steps for GitHub Actions.
- Public Ledger:
- This links to the entry ID in Sigstore's public, immutable transparency log (Rekor). Anyone can use this ID to look up and verify that this attestation was recorded and has not been altered.
Error state
A warning is added to the attestations UI when npm cannot find the linked source commit and repository (example):
In this scenario, a warning banner is also added to the top of the page:
How users are likely to understand this interface
The Security Architect (Concerned / Informed)
- Likely to understand all fields
- Likely to appreciate the link to the "Transparency log entry", and probably click on it
- Likely to understand the attestations warning and investigate the package further
The Pragmatic Developer (Somewhat Concerned / Informed)
- Likely to get an immediate, at-a-glance sense of trust from the green checkmark icon and the words "GitHub Actions."
- Likely to understand the "Source Commit" link
- Likely to understand "built and signed on" indicates the way the package was created and signed by an automated process.
- Unlikely to understand the significance of the Rekor log, nor click on it
- Likely to understand the attestations warning and investigate the package further
The Incidental Consumer (Not Concerned / Not Informed)
- Likely to notice the green checkmark icon, which they may intuitively interpret as "good" or "safe."
- Likely to understand the term "Provenance", and therefore conceptually understand that the content below is about the origin/history of the package
- Likely to understand "built and signed on" indicates that the package was created and signed by an official process.
- Likely to understand the attestations warning, but unlikely to understand how to investigate further. May instead choose a completely different package to avoid risk.
- May recognise "GitHub" as a common (and trustworthy) software tool
- Unlikely to understand "Source Commit," "Build File" or "Public Ledger," nor click on any of the links
Other security features on npm
Compared to PyPI, npm exposes fewer security signals within its UI.
- Does not highlight when the user is viewing an older version
- Does not "verify" package metadata generated from the
package.json
file
Does have a workflow for reporting malware, with a button displayed on the sidebar:
Does expose package dependencies and dependents:
Supporting Documentation
npm's attestation content is split between content for end consumers, and content for package maintainers. End users are linked to the content for maintainers, near the top of the documentation:
The end user documentation is not included in the main documentation sidebar, instead it is linked to from npm's "Searching For and Choosing Packages" documentation. This content does not effectively signal the importance of attestations / provenance when selecting a package, meaning that many users will not find the end user documentation:
The end user documentation explains how package consumers can identify packages with provenance via a green check mark on the npm website, view the associated build and source details, and verify them locally using the npm audit signatures command.
However, this documentation does not:
-
Help users understand "why" attestations matter: The documentation is a how-to guide that is very light on explaining why provenance matters. It doesn't explain the threat models attestations help mitigate (e.g., maintainer account takeover, compromised build infrastructure).
-
Guide users to understand / interpret the information: The documentation tells users what they can see (source commit, build file) but provides no guidance on what to do with that information. It doesn't tell a consumer what to look for in a build workflow to determine if it's trustworthy.
-
Define terms: Key concepts like "transparency log" are mentioned without explanation. The underlying technology (Sigstore) is only explained in the linked content for package maintainers.
-
Explain attestations limitations: The most important caveat (that "provenance does not guarantee the package has no malicious code") is buried in the content for package maintainers, not in the user-facing documentation.
-
Provide example npm audit signatures output: The article tells you how to run the audit command but doesn't show what the output looks like for either a successful or failed verification.
There is an opportunity to include attestation documentation in npm's "Securing your code" documentation:
This content would benefit from some restructuring, to differentiate between the mechanisms end users should consider when installing packages, vs the mechanisms package maintainers can set up when publishing packages.
Metadata
Metadata
Assignees
Labels
Type
Projects
Status