You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: deps/npm/docs/content/commands/npm-audit.md
+49-8
Original file line number
Diff line number
Diff line change
@@ -43,14 +43,55 @@ output, it simply changes the command's failure threshold.
43
43
44
44
### Audit Signatures
45
45
46
-
This command can also audit the integrity values of the packages in your
47
-
tree against any signatures present in the registry they were downloaded
48
-
from. npm will attempt to download the keys from `/-/npm/v1/keys` on
49
-
each the registry used to download any given package. It will then
50
-
check the `dist.signatures` object in the package itself, and verify the
51
-
`sig` present there using the `keyid` there, matching it with a key
52
-
returned from the registry. The command for this is `npm audit
53
-
signatures`
46
+
To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.
47
+
48
+
Registry signatures can be verified using the following `audit` command:
49
+
50
+
```bash
51
+
$ npm audit signatures
52
+
```
53
+
54
+
The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
55
+
56
+
1. Signatures are provided in the package's `packument` in each published version within the `dist` object:
See this [example](https://registry.npmjs.org/light-cycle/1.4.3) of a signed package from the public npm registry.
69
+
70
+
The `sig` is generated using the following template: `${package.name}@${package.version}:${package.dist.integrity}` and the `keyid` has to match one of the public signing keys below.
71
+
72
+
2. Public signing keys are provided at `registry-host.tld/-/npm/v1/keys` in the following format:
73
+
74
+
```
75
+
{
76
+
"keys": [{
77
+
"expires": null,
78
+
"keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
79
+
"keytype": "ecdsa-sha2-nistp256",
80
+
"scheme": "ecdsa-sha2-nistp256",
81
+
"key": "{{B64_PUBLIC_KEY}}"
82
+
}]
83
+
}
84
+
```
85
+
86
+
Keys response:
87
+
88
+
-`expires`: null or a simplified extended <ahref="https://en.wikipedia.org/wiki/ISO_8601"target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
89
+
-`keydid`: sha256 fingerprint of the public key
90
+
-`keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
91
+
-`scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
92
+
-`key`: base64 encoded public key
93
+
94
+
See this <ahref="https://registry.npmjs.org/-/npm/v1/keys"target="_blank">example key's response from the public npm registry</a>.
will cause the command to fail. This option does not filter the report
172
172
output, it simply changes the command's failure threshold.</p>
173
173
<h3id="audit-signatures">Audit Signatures</h3>
174
-
<p>This command can also audit the integrity values of the packages in your
175
-
tree against any signatures present in the registry they were downloaded
176
-
from. npm will attempt to download the keys from <code>/-/npm/v1/keys</code> on
177
-
each the registry used to download any given package. It will then
178
-
check the <code>dist.signatures</code> object in the package itself, and verify the
179
-
<code>sig</code> present there using the <code>keyid</code> there, matching it with a key
180
-
returned from the registry. The command for this is <code>npm audit signatures</code></p>
174
+
<p>To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.</p>
175
+
<p>Registry signatures can be verified using the following <code>audit</code> command:</p>
176
+
<prelang="bash"><code>$ npm audit signatures
177
+
</code></pre>
178
+
<p>The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:</p>
179
+
<ol>
180
+
<li>Signatures are provided in the package's <code>packument</code> in each published version within the <code>dist</code> object:</li>
<p>See this <ahref="https://registry.npmjs.org/light-cycle/1.4.3">example</a> of a signed package from the public npm registry.</p>
191
+
<p>The <code>sig</code> is generated using the following template: <code>${package.name}@${package.version}:${package.dist.integrity}</code> and the <code>keyid</code> has to match one of the public signing keys below.</p>
192
+
<olstart="2">
193
+
<li>Public signing keys are provided at <code>registry-host.tld/-/npm/v1/keys</code> in the following format:</li>
194
+
</ol>
195
+
<pre><code>{
196
+
"keys": [{
197
+
"expires": null,
198
+
"keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
199
+
"keytype": "ecdsa-sha2-nistp256",
200
+
"scheme": "ecdsa-sha2-nistp256",
201
+
"key": "{{B64_PUBLIC_KEY}}"
202
+
}]
203
+
}
204
+
</code></pre>
205
+
<p>Keys response:</p>
206
+
<ul>
207
+
<li><code>expires</code>: null or a simplified extended <!-- raw HTML omitted -->ISO 8601 format<!-- raw HTML omitted -->: <code>YYYY-MM-DDTHH:mm:ss.sssZ</code></li>
208
+
<li><code>keydid</code>: sha256 fingerprint of the public key</li>
209
+
<li><code>keytype</code>: only <code>ecdsa-sha2-nistp256</code> is currently supported by the npm CLI</li>
210
+
<li><code>scheme</code>: only <code>ecdsa-sha2-nistp256</code> is currently supported by the npm CLI</li>
211
+
<li><code>key</code>: base64 encoded public key</li>
212
+
</ul>
213
+
<p>See this <!-- raw HTML omitted -->example key's response from the public npm registry<!-- raw HTML omitted -->.</p>
181
214
<h3id="audit-endpoints">Audit Endpoints</h3>
182
215
<p>There are two audit endpoints that npm may use to fetch vulnerability
183
216
information: the <code>Bulk Advisory</code> endpoint and the <code>Quick Audit</code> endpoint.</p>
0 commit comments