codekingpro/portable-devtools

1---
2title: npm-sbom
3section: 1
4description: Generate a Software Bill of Materials (SBOM)
5---
6
7### Synopsis
8
9```bash
10npm sbom
11```
12
13### Description
14
15The `npm sbom` command generates a Software Bill of Materials (SBOM) listing the dependencies for the current project.
16SBOMs can be generated in either [SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format.
17
18### Example CycloneDX SBOM
19
20```json
21{
22  "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
23  "bomFormat": "CycloneDX",
24  "specVersion": "1.5",
25  "serialNumber": "urn:uuid:09f55116-97e1-49cf-b3b8-44d0207e7730",
26  "version": 1,
27  "metadata": {
28    "timestamp": "2023-09-01T00:00:00.001Z",
29    "lifecycles": [
30      {
31        "phase": "build"
32      }
33    ],
34    "tools": [
35      {
36        "vendor": "npm",
37        "name": "cli",
38        "version": "10.1.0"
39      }
40    ],
41    "component": {
42      "bom-ref": "simple@1.0.0",
43      "type": "library",
44      "name": "simple",
45      "version": "1.0.0",
46      "scope": "required",
47      "author": "John Doe",
48      "description": "simple react app",
49      "purl": "pkg:npm/simple@1.0.0",
50      "properties": [
51        {
52          "name": "cdx:npm:package:path",
53          "value": ""
54        }
55      ],
56      "externalReferences": [],
57      "licenses": [
58        {
59          "license": {
60            "id": "MIT"
61          }
62        }
63      ]
64    }
65  },
66  "components": [
67    {
68      "bom-ref": "lodash@4.17.21",
69      "type": "library",
70      "name": "lodash",
71      "version": "4.17.21",
72      "scope": "required",
73      "author": "John-David Dalton",
74      "description": "Lodash modular utilities.",
75      "purl": "pkg:npm/lodash@4.17.21",
76      "properties": [
77        {
78          "name": "cdx:npm:package:path",
79          "value": "node_modules/lodash"
80        }
81      ],
82      "externalReferences": [
83        {
84          "type": "distribution",
85          "url": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"
86        },
87        {
88          "type": "vcs",
89          "url": "git+https://github.com/lodash/lodash.git"
90        },
91        {
92          "type": "website",
93          "url": "https://lodash.com/"
94        },
95        {
96          "type": "issue-tracker",
97          "url": "https://github.com/lodash/lodash/issues"
98        }
99      ],
100      "hashes": [
101        {
102          "alg": "SHA-512",
103          "content": "bf690311ee7b95e713ba568322e3533f2dd1cb880b189e99d4edef13592b81764daec43e2c54c61d5c558dc5cfb35ecb85b65519e74026ff17675b6f8f916f4a"
104        }
105      ],
106      "licenses": [
107        {
108          "license": {
109            "id": "MIT"
110          }
111        }
112      ]
113    }
114  ],
115  "dependencies": [
116    {
117      "ref": "simple@1.0.0",
118      "dependsOn": [
119        "lodash@4.17.21"
120      ]
121    },
122    {
123      "ref": "lodash@4.17.21",
124      "dependsOn": []
125    }
126  ]
127}
128```
129
130### Example SPDX SBOM
131
132```json
133{
134  "spdxVersion": "SPDX-2.3",
135  "dataLicense": "CC0-1.0",
136  "SPDXID": "SPDXRef-DOCUMENT",
137  "name": "simple@1.0.0",
138  "documentNamespace": "http://spdx.org/spdxdocs/simple-1.0.0-bf81090e-8bbc-459d-bec9-abeb794e096a",
139  "creationInfo": {
140    "created": "2023-09-01T00:00:00.001Z",
141    "creators": [
142      "Tool: npm/cli-10.1.0"
143    ]
144  },
145  "documentDescribes": [
146    "SPDXRef-Package-simple-1.0.0"
147  ],
148  "packages": [
149    {
150      "name": "simple",
151      "SPDXID": "SPDXRef-Package-simple-1.0.0",
152      "versionInfo": "1.0.0",
153      "packageFileName": "",
154      "description": "simple react app",
155      "primaryPackagePurpose": "LIBRARY",
156      "downloadLocation": "NOASSERTION",
157      "filesAnalyzed": false,
158      "homepage": "NOASSERTION",
159      "licenseDeclared": "MIT",
160      "externalRefs": [
161        {
162          "referenceCategory": "PACKAGE-MANAGER",
163          "referenceType": "purl",
164          "referenceLocator": "pkg:npm/simple@1.0.0"
165        }
166      ]
167    },
168    {
169      "name": "lodash",
170      "SPDXID": "SPDXRef-Package-lodash-4.17.21",
171      "versionInfo": "4.17.21",
172      "packageFileName": "node_modules/lodash",
173      "description": "Lodash modular utilities.",
174      "downloadLocation": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
175      "filesAnalyzed": false,
176      "homepage": "https://lodash.com/",
177      "licenseDeclared": "MIT",
178      "externalRefs": [
179        {
180          "referenceCategory": "PACKAGE-MANAGER",
181          "referenceType": "purl",
182          "referenceLocator": "pkg:npm/lodash@4.17.21"
183        }
184      ],
185      "checksums": [
186        {
187          "algorithm": "SHA512",
188          "checksumValue": "bf690311ee7b95e713ba568322e3533f2dd1cb880b189e99d4edef13592b81764daec43e2c54c61d5c558dc5cfb35ecb85b65519e74026ff17675b6f8f916f4a"
189        }
190      ]
191    }
192  ],
193  "relationships": [
194    {
195      "spdxElementId": "SPDXRef-DOCUMENT",
196      "relatedSpdxElement": "SPDXRef-Package-simple-1.0.0",
197      "relationshipType": "DESCRIBES"
198    },
199    {
200      "spdxElementId": "SPDXRef-Package-simple-1.0.0",
201      "relatedSpdxElement": "SPDXRef-Package-lodash-4.17.21",
202      "relationshipType": "DEPENDS_ON"
203    }
204  ]
205}
206```
207
208### Package lock only mode
209
210If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.
211This means that information from the package.json files of your dependencies will not be included in the result set (e.g.
212description, homepage, engines).
213
214### Configuration
215
216#### `omit`
217
218* Default: 'dev' if the `NODE_ENV` environment variable is set to
219  'production'; otherwise, empty.
220* Type: "dev", "optional", or "peer" (can be set multiple times)
221
222Dependency types to omit from the installation tree on disk.
223
224Note that these dependencies _are_ still resolved and added to the
225`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
226physically installed on disk.
227
228If a package type appears in both the `--include` and `--omit` lists, then
229it will be included.
230
231If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
232variable will be set to `'production'` for all lifecycle scripts.
233
234
235
236#### `package-lock-only`
237
238* Default: false
239* Type: Boolean
240
241If set to true, the current operation will only use the `package-lock.json`,
242ignoring `node_modules`.
243
244For `update` this means only the `package-lock.json` will be updated,
245instead of checking `node_modules` and downloading dependencies.
246
247For `list` this means the output will be based on the tree described by the
248`package-lock.json`, rather than the contents of `node_modules`.
249
250
251
252#### `sbom-format`
253
254* Default: null
255* Type: "cyclonedx" or "spdx"
256
257SBOM format to use when generating SBOMs.
258
259
260
261#### `sbom-type`
262
263* Default: "library"
264* Type: "library", "application", or "framework"
265
266The type of package described by the generated SBOM. For SPDX, this is the
267value for the `primaryPackagePurpose` field. For CycloneDX, this is the
268value for the `type` field.
269
270
271
272#### `workspace`
273
274* Default:
275* Type: String (can be set multiple times)
276
277Enable running a command in the context of the configured workspaces of the
278current project while filtering by running only the workspaces defined by
279this configuration option.
280
281Valid values for the `workspace` config are either:
282
283* Workspace names
284* Path to a workspace directory
285* Path to a parent workspace directory (will result in selecting all
286  workspaces within that folder)
287
288When set for the `npm init` command, this may be set to the folder of a
289workspace which does not yet exist, to create the folder and set it up as a
290brand new workspace within the project.
291
292This value is not exported to the environment for child processes.
293
294#### `workspaces`
295
296* Default: null
297* Type: null or Boolean
298
299Set to true to run the command in the context of **all** configured
300workspaces.
301
302Explicitly setting this to false will cause commands like `install` to
303ignore workspaces altogether. When not set explicitly:
304
305- Commands that operate on the `node_modules` tree (install, update, etc.)
306will link workspaces into the `node_modules` folder. - Commands that do
307other things (test, exec, publish, etc.) will operate on the root project,
308_unless_ one or more workspaces are specified in the `workspace` config.
309
310This value is not exported to the environment for child processes.
311## See Also
312
313* [package spec](/using-npm/package-spec)
314* [dependency selectors](/using-npm/dependency-selectors)
315* [package.json](/configuring-npm/package-json)
316* [workspaces](/using-npm/workspaces)
317