Initial docs for npm provenance
Co-authored-by: Philip Harrison <philip@mailharrison.com> Co-authored-by: Vanessa <vgrl@github.com> Co-authored-by: Zach Steindler <steiza@github.com> Co-authored-by: Brian DeHamer <bdehamer@github.com>
SiaraMist committed
Feb 13, 2023 at 20:15 UTC
90fadd9fac8b8b1ee78d7a8b68f0461d64a76d47
7 files changed
+181
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-scoped-public-packages.mdx
+7
@@ -88,6 +88,12 @@ By default, scoped packages are published with private visibility. To publish a
88
npm publish --access public
89
```
90
91
+ <Note>
92
+
93
+ **Note:** If you use GitHub Actions to publish your packages, you can generate provenance information for each package you publish. For more information, see "[Generating provenance statements][provenance-how-to]."
94
+
95
+ </Note>
96
+
97
3. To see your public package page, visit https://npmjs.com/package/\*package-name\*, replacing \*package-name\* with the name of your package. Public packages will say `public` below the package name on the npm website.
98
99
<>{shared['organization-package-public'].image}</>
@@ -104,3 +110,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
110
[developers]: /misc/developers#keeping-files-out-of-your-package
111
[cli-publish]: /cli/publish
112
[pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
113
+[provenance-how-to]: /generating-provenance-statements
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx
+7
@@ -70,6 +70,12 @@ npm install path/to/my-package
70
npm publish
71
```
72
73
+ <Note>
74
+
75
+ **Note:** If you use GitHub Actions to publish your packages, you can generate provenance information for each package you publish. For more information, see "[Generating provenance statements][provenance-how-to]."
76
+
77
+ </Note>
78
+
79
3. To see your public package page, visit https://npmjs.com/package/*package-name*, replacing *package-name* with the name of your package. Public packages will say `public` below the package name on the npm website.
80
81
For more information on the `publish` command, see the [CLI documentation][cli-publish].
@@ -83,3 +89,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
89
[developers]: /misc/developers#keeping-files-out-of-your-package
90
[cli-publish]: /cli/publish
91
[pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
92
+[provenance-how-to]: /generating-provenance-statements
content/packages-and-modules/getting-packages-from-the-registry/searching-for-and-choosing-packages-to-download.mdx
+49
@@ -36,3 +36,52 @@ Maintenance ranks packages according to the attention they are given by develope
36
### Optimal
37
38
Optimal combines the other three criteria (popularity, quality, maintenance) into one score in a meaningful way.
39
+
40
+## Package provenance
41
+
42
+When packages have been published with provenance, you can:
43
+
44
+- Verify where and how a package was published.
45
+- Validate that an authorized user published a package.
46
+
47
+You can use this information to audit packages and determine whether or not you want to consume them. For more information about npm provenance, see "[About npm provenance][about-provenance]."
48
+
49
+To view provenance information for a package in the npm registry:
50
+
51
+1. In the npm registry, navigate to a package.
52
+
53
+2. On the package's page, in the **Version** field to the right of the README, look for a green check mark. If there is a green check mark, this means the package was published with provenance.
54
+
55
+ <Screenshot src="packages-and-modules/getting-packages-from-the-registry/npm-provenance-check-mark.png" alt="Screenshot showing a Version field with a green check mark" />
56
+
57
+3. Click on the check mark, then click **View more details**.
58
+
59
+4. View the following information for the package:
60
+
61
+ - **Build Environment**: The environment used to build the package.
62
+ - **Build Summary**: A link to the workflow run that built the package.
63
+ - **Source Commit**: A link to the commit the package was built from.
64
+ - **Build File**: A link to the workflow file used to build the package.
65
+ - **Public Ledger**: A link to a transparency log entry attesting an authorized user published the package.
66
+
67
+ <Screenshot src="packages-and-modules/getting-packages-from-the-registry/npm-provenance.png" alt="Screenshot showing npm provenance information for a published package" />
68
+
69
+### Verifying provenance attestations
70
+
71
+When you download a package from the registry, you can verify the provenance of a package with the following CLI command:
72
+
73
+```
74
+npm audit signatures
75
+```
76
+
77
+This command checks the registry signatures and provenance attestations. If a package has missing or invalid signatures or attestations, it returns an error. This could indicate that a package has been tampered with.
78
+
79
+<Note>
80
+
81
+**Note:** In order to run the audit command to verify package provenance, you must:
82
+ - Install npm CLI version `v9.5.0` or later: `npm install -g npm@latest`
83
+ - Install dependencies with `npm install` or `npm ci`
84
+
85
+</Note>
86
+
87
+[about-provenance]: /generating-provenance-statements#about-npm-provenance
content/packages-and-modules/securing-your-code/generating-provenance-statements.mdx
new
+116
@@ -0,0 +1,116 @@
1
+---
2
+title: Generating provenance statements
3
+---
4
+
5
+You can generate provenance statements for the packages you publish. This allows you to publicly establish where a package was built and who published a package, which can increase supply-chain security for your packages.
6
+
7
+## About npm provenance
8
+
9
+npm provenance includes two types of attestations:
10
+
11
+- Provenance attestation
12
+- Publish attestation
13
+
14
+The provenance attestation is established by publicly providing a link to a package's source code and build instructions from the build environment. This allows developers to verify where and how your package was built before they download it.
15
+
16
+Publish attestations are generated by the registry when a package is published by an authorized user. When an npm package is published with provenance, it is signed by Sigstore public good servers and logged in a public transparency ledger, where users can view this information.
17
+
18
+### About Sigstore
19
+
20
+Sigstore is a collection of tools and services aimed at making it easy to use short-lived, ephemeral certificates to sign software. Its three main components are a CLI tool, a certificate authority, and a time-stamping transparency log.
21
+
22
+The certificate authority federates with any OIDC provider that includes verifiable build information. It acts as an intermediary between build systems and package registries by verifying the integrity of the OIDC token, issues a signing certificate that contains that build information, and then logging the signing certificate to an immutable ledger.
23
+
24
+The transparency log service provides a public, verifiable, tamper-evident ledger of signed attestations. This ensures transparency of the public service, as well as providing a way to detect attempts to tamper with a package if a package registry were to be compromised.
25
+
26
+
27
+## Provenance limitations
28
+
29
+- In order to publish a package with provenance, you must build your package with a supported cloud CI/CD provider. Today this includes GitHub Actions, and we are collaborating with additional providers to expand support. For more information on how to establish provenance using GitHub Actions, see "[Publishing packages with provenance via GitHub Actions][publishing-with-provenance]."
30
+- When a package in the npm registry has established provenance, it does not guarantee the package has no malicious code. Instead, npm provenance provides a verifiable link to the package's source code and build instructions, which developers can then audit and determine whether to trust it or not. For more information, see "[Searching for and choosing packages to download][provenance-info]."
31
+
32
+## Prerequisites
33
+
34
+Before you can publish your packages with provenance, you must:
35
+
36
+- Review the [Linux Foundation Immutable Record notice](https://lfprojects.org/policies/hosted-project-tools-immutable-records/), which applies to the public transparency log.
37
+
38
+- Install the latest version of the npm CLI. For more information, see "[Try the latest stable version of npm][update-npm]."
39
+
40
+- Set up a GitHub Actions workflow to publish your packages to the npm registry. For more information, see [Understanding GitHub Actions][understand-actions] in the GitHub documentation.
41
+
42
+## Publishing packages with provenance via GitHub Actions
43
+
44
+In order to establish provenance, you must use a supported cloud CI/CD provider to publish your packages. GitHub Actions is a supported CI/CD platform that allows you to automate software development tasks. For more information, see [GitHub Actions][github-actions] in the GitHub documentation.
45
+
46
+To update your GitHub Actions workflow to publish your packages with provenance, you must:
47
+
48
+- Give permission to mint an ID-token:
49
+
50
+ ```
51
+ permission:
52
+ id-token: write
53
+ ```
54
+
55
+- Add the `--provenance` flag to your publish command:
56
+
57
+ ```
58
+ npm publish --provenance
59
+ ```
60
+
61
+### Example GitHub Actions workflow
62
+
63
+This example workflow publishes a package to the npm registry with provenance.
64
+
65
+```
66
+name: Publish Package to npmjs
67
+on:
68
+ release:
69
+ types: [created]
70
+jobs:
71
+ build:
72
+ runs-on: ubuntu-latest
73
+ permissions:
74
+ contents: read
75
+ id-token: write
76
+ steps:
77
+ - uses: actions/checkout@v3
78
+ - uses: actions/setup-node@v3
79
+ with:
80
+ node-version: '18.x'
81
+ registry-url: 'https://registry.npmjs.org'
82
+ - run: npm install -g npm
83
+ - run: npm ci
84
+ - run: npm publish --provenance --access public
85
+ env:
86
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
87
+```
88
+
89
+### Using third-party package publishing tools
90
+
91
+If you publish your packages with tools that do not directly invoke the `npm publish` command, you can do one of the following in your GitHub Actions workflow to publish your packages with provenance.
92
+
93
+- **Configure environment variables:** In your GitHub Actions workflow, you can use an environment variable called `NPM_CONFIG_PROVENANCE`, and set it to `true`.
94
+- **Configure your `package.json` file:** You can add a `publishConfig` block to your `package.json` file:
95
+ ```json
96
+ "publishConfig": {
97
+ "provenance": true
98
+ },
99
+ ```
100
+- **Add an `.npmrc` file:** You can add an `.npmrc` file to your project with the following entry:
101
+ ```ini
102
+ provenance=true
103
+ ```
104
+
105
+<Note>
106
+
107
+**Note:** At this time, `lerna` and `yarn` are not supported tools for publishing your packages with provenance.
108
+
109
+</Note>
110
+
111
+
112
+[provenance-info]: /searching-for-and-choosing-packages-to-download#package-provenance
113
+[publishing-with-provenance]: #publishing-packages-with-provenance
114
+[update-npm]: /try-the-latest-stable-version-of-npm
115
+[github-actions]: https://docs.github.com/en/actions
116
+[understand-actions]: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions
\ No newline at end of file
src/theme/nav.yml
+2
@@ -154,6 +154,8 @@
154
url: /about-audit-reports
155
- title: Auditing package dependencies for security vulnerabilities
156
url: /auditing-package-dependencies-for-security-vulnerabilities
157
+ - title: Generating provenance statements
158
+ url: /generating-provenance-statements
159
- title: About ECDSA registry signatures
160
url: /about-registry-signatures
161
- title: Verifying ECDSA registry signatures
static/packages-and-modules/getting-packages-from-the-registry/npm-provenance-check-mark.png
Binary files /dev/null and b/static/packages-and-modules/getting-packages-from-the-registry/npm-provenance-check-mark.png differ
static/packages-and-modules/getting-packages-from-the-registry/npm-provenance.png
Binary files /dev/null and b/static/packages-and-modules/getting-packages-from-the-registry/npm-provenance.png differ