"What is NPM package provenance?"

When we’re talking about web development, one of the biggest problems we face is security. Especially when we’re talking about Node.js development with packages distributed through NPM.

One of the biggest sources of attacks on enterprise systems comes through external packages that are installed without proper care. This has been tested a few times and continues to be a problem.

The problem isn’t even downloading the package, but rather not being able to be sure that the package came from where you expect it to come from or was published by who you expect. But that’s about to change.

NPM Package Provenance#

Recently NPM announced a new feature, package provenance. This will be the way you can verify that a package was made by whoever created it, and that it was also published from a trusted source.

The goal of provenance is not just to sign the code, but to create a link from the package to where it came from and what the original artifact was that generated it. One way would be to anchor the package to whoever created it through a private key, so whoever made the package can sign it with the private key and distribute a public key for verification.

However, this approach is a problem, because the point of failure is precisely the key. If it leaks, then all the security falls apart. That’s why they thought of a quite clever way to validate package ownership: anchor the identity to the server where it came from.

This creates a much stronger security point, since you need to replicate an entire infrastructure to replicate the package’s signature, which is not as trivial as stealing a key.

What’s the Secret?#

For this, they are using some solutions from Sigstore, especially one that accepts tokens in OpenID Connect format to create certificates that have a very short lifespan and are used only to sign provenance requests.

And that’s the big insight, because for each package publication, a key pair is generated that is used to sign the certificate, these keys are thrown away and replaced by a validity certificate. No one can sign the code anymore, but anyone who has the public certificate can validate that it was generated by a trusted source, that is, nobody has a key.

The second part of this process is verification, which is done in a service called Rekor, which is a public transaction log, basically all provenances end up there and are completely public for everyone to see. So you can download the log that contains the entire signed CI/CD environment and verify if it’s genuine with the command:

1
npm audit signatures

The Importance of CI/CD#

For all this to work, the CI/CD metadata needs to be trustworthy, especially because the information we’re trying to sign is precisely where the package was built.

The information I’m talking about includes unique container data where the CI process was started, such as hostnames, environment variables, and so on. In the case of Github Actions, this is the provenance document that is signed:

1
_type: https://in-toto.io/Statement/v0.1
2
subject:
3
- name: pkg:npm/sigstore@1.2.0
4
  digest:
5
    sha512: 16bf7e5b59e40522190a425047b8c39ffcc8d145cdb15a69fbb9834240a764e2311bda7ac8d5c1c7dc67b47b1f532607139e570e4915577fab61bae4cc079eb0
6
predicateType: https://slsa.dev/provenance/v0.2
7
predicate:
8
  buildType: https://github.com/npm/cli/gha/v2
9
  builder:
10
    id: https://github.com/actions/runner
11
  invocation:
12
    configSource:
13
      uri: git+https://github.com/sigstore/sigstore-js@refs/heads/main
14
      digest:
15
        sha1: 5b8c0801d1f5d105351a403f58c38269de93f680
16
      entryPoint: ".github/workflows/release.yml"
17
    environment:
18
      GITHUB_EVENT_NAME: push
19
      GITHUB_REF: refs/heads/main
20
      GITHUB_REPOSITORY: sigstore/sigstore-js
21
      GITHUB_REPOSITORY_ID: '495574555'
22
      GITHUB_REPOSITORY_OWNER_ID: '71096353'
23
      GITHUB_RUN_ATTEMPT: '1'
24
      GITHUB_RUN_ID: '4503589496'
25
      GITHUB_SHA: 5b8c0801d1f5d105351a403f58c38269de93f680
26
      GITHUB_WORKFLOW_REF: sigstore/sigstore-js/.github/workflows/release.yml@refs/heads/main
27
      GITHUB_WORKFLOW_SHA: 5b8c0801d1f5d105351a403f58c38269de93f680
28
  materials:
29
  - uri: git+https://github.com/sigstore/sigstore-js@refs/heads/main
30
    digest:
31
      sha1: 5b8c0801d1f5d105351a403f58c38269de93f680

To generate your own provenance file, NPM created a flag called --provenance, so just run npm publish --provenance and your package will be signed.¹

But then we have the question: Why get data from CI? Simply because it’s not easy to alter this data. Especially because, even if you try to modify the machine process by injecting a child_process, known servers like GitHub’s will still have information you can’t remove, such as IP addresses, for example. This way, NPM can cross-check the data in the sent provenance against the data that GitHub itself returns.

Because of this, we can’t generate provenances locally, that is, you won’t be able to use npm publish --provenance on your local machine because, unlike GitHub, your machine is not a trusted source of data.

What Happens Locally?#

Socket published a quite interesting article about how the package installation or publication process works. I’ll try to summarize it here.

When you publish a package with provenance:

1. The package is compressed into a .tar
2. NPM verifies your credentials and access token
3. The package is sent to your registry normally
4. The registry fetches the metadata from the connection (not from the package)
5. NPM obtains a certificate to sign your package that is populated with information that GitHub will provide directly from their infrastructure
6. NPM uses this certificate to create a unique signature of the tarball
7. This signature is recorded in Rekor
8. The tarball is saved in the registry
9. NPM includes all metadata and the location in Rekor inside the package at https://registry.npmjs.org/$PACKAGE/$VERSION#dist

When you install a package that has provenance

1. NPM obtains the package metadata
2. Downloads the package signature (the checksum)
3. Downloads the provenance log information from Rekor
4. Downloads the package
5. Attempts to match the checksum with the downloaded checksum
6. Attempts to match the Rekor metadata with the previously downloaded data

One of the packages you can verify this with is from Socket itself, just access the link https://registry.npmjs.org/-/npm/v1/attestations/@socketsecurity%2Fcli@0.5.1

There, you can enter the document until you find attestations[predicateType === https://slsa.dev/provenance/v0.2].bundle.verificationMaterial.tlogEntries[0].logIndex, which is a log number you can verify in Rekor.

There you can scroll down to the Data section and see that all CI-related metadata is there:

Conclusion#

The provenance process is quite interesting in itself, and it’s an excellent way to protect the package chain that is essential for modern development, but it’s also one of the easiest ways for someone to be hacked.

Currently, only GitHub Actions has verification for provenance, but according to NPM, other CIs are being added.