SBOM: what a software bill of materials lists, how to produce one at each release, and where it stops
A software bill of materials (SBOM) is a machine-readable inventory of the components a piece of software is built from.
This guide explains what one holds under the 2021 NTIA minimum elements and the 2026 joint guidance that replaced them, how CycloneDX and SPDX differ, how a small team produces one for a web application at every release, how a component is identified so an advisory can be matched to it, and what a VEX statement adds. It comes with a worked component record and triage table across two releases, and a lab that generates real SBOMs offline.
In this guide
SBOM component record, VEX triage table and offline SBOM lab
A component record with one line for each fact an advisory needs: product and release, SBOM document, component identity, dependency path, build provenance, advisory match, VEX status and the question that still needs application analysis, with the source behind each line. A worked record for an invented application follows one component across two releases, from affected to fixed, and prints the triage table.
How to use itHide the instructions
The offline Node.js lab that produced it generates real CycloneDX and SPDX documents with npm sbom, and its files and outputs were copied in from a real run.
sbom.txt
Introduction3 lines
Part A. The component record39 lines
Part B. Worked record and triage table (invented)78 lines
Part C. The offline SBOM lab1,403 lines
Whole template1,532 lines
SBOM COMPONENT RECORD, VEX TRIAGE TABLE AND OFFLINE SBOM LAB
ILLUSTRATION AND TEMPLATE. Part A is a blank component record to copy into a ticket or spreadsheet. Part B fills it in for an invented application, sbomlab-invented-bookings, across two releases, against an invented advisory, INVENTED-SBOMLAB-0001. Part C is the offline lab that produced every value Part B copies. Every package name sits under the invented scope @sbomlab-invented, the organisation and the host vex.sbomlab-invented.example are invented, and the advisory describes no real flaw. Nothing here is a real package, vulnerability, VEX document, organisation or client. The SBOMs are real output of npm sbom, run against the invented project with npm's offline setting on.
PART A. THE COMPONENT RECORD
Fill one record for each advisory and each release that is still deployed. Write "unknown" or "none" instead of leaving a line blank: the 2026 minimum elements ask an SBOM author to say explicitly when information is unknown or withheld, and the same habit keeps a record honest.
Where each line comes from. "Source" names the document that defines the field. "This page's advice" marks a practice this guide recommends, not a rule from any standard.
A1 Product and release: the application the SBOM describes, its version and its package URL.
Source: CISA and partners, 2026 Minimum Elements for a Software Bill of Materials (Component Name, Component Version and Component Identifiers, which it applies to the target component as well as to the components listed). In the CycloneDX files in Part C this is metadata.component. In the SPDX files it is the package that documentDescribes names.
A2 SBOM document: the file, its data format and version, its generation context, the tool that wrote it, its identifier and its timestamp.
Source: 2026 Minimum Elements (SBOM Data Format Name, SBOM Data Format Version, SBOM Generation Context, SBOM Tool Name, SBOM Tool Version, SBOM Timestamp). CycloneDX v1.7 JSON reference (every BOM generated should have a unique serial number, even if its contents have not changed).
A3 Component identity: the name field as the SBOM has it, the version, and the package URL.
Source: 2026 Minimum Elements (Component Name, Component Version, Component Identifiers). README of the Package-URL project's purl-spec repository (scheme:type/namespace/name@version?qualifiers#subpath) and the project's npm type definition (the scope's @ sign is always percent encoded).
A4 Dependency path: each chain from the application to the component, and the direct dependency at the top of each chain.
Source: 2026 Minimum Elements (Component Dependency Relationship; Coverage includes transitive dependencies). CycloneDX v1.7 JSON reference (ref and dependsOn). SPDX 2.3.1, clause 11 (DEPENDS_ON and DEPENDENCY_OF).
A5 Build provenance: for the component, the build platform, the build type, the source and the place the statement can be checked. Write "none" when no provenance statement exists.
Source: SLSA v1.2 build provenance (builder.id, buildType, externalParameters, resolvedDependencies, subject). npm's documentation on viewing package provenance (the details shown for a package published with provenance are the build environment, build summary, source commit, build file and public ledger entry). Keeping it beside the SBOM entry is this page's advice.
A6 Advisory: its identifier, the package it names written as a package URL without a version, the affected range from its version fields, and the function it names if it names one.
Source: this page's advice.
A7 Match: whether the SBOM lists the package, and for each copy whether its version is inside the advisory's range. Comparing each copy's version with the advisory's range is this page's advice.
Source: 2026 Minimum Elements, Coverage (its example is that the recipient of an SBOM should be able to conclude that a newly reported vulnerability does not affect them if the SBOM does not list the component associated with the vulnerability).
A8 VEX status: the status, the justification if the status is not_affected, the action statement if it is affected, the author and the date.
Source: CISA, Minimum Requirements for VEX, April 2023 (the four status values; a not_affected statement should provide a justification; an affected statement must include an action statement; a VEX document must identify its author). OpenVEX specification v0.2.0 for the field names the lab's VEX document uses.
A9 Do the SBOM and the VEX statement agree?
Source: this page's advice. The checks are the ones triage.mjs makes in Part C.
A10 Remediation evidence: the release in which the component's version changed, the comparison of the two SBOMs that shows it, and the VEX statement for the new release.
Source: 2026 Minimum Elements, Frequency (a new build or release should come with a new SBOM that reflects the changes). Keeping the comparison, and the VEX statement for the new release beside it, is this page's advice.
A11 Still needs application analysis: is the affected function called, can input from outside reach it, and is a mitigating setting on? Who answered, on what evidence, and when.
Source: this page's advice. NTIA's 2021 report says a supplier's determination that a vulnerability does not affect a specific piece of software could be for a range of reasons: the compiler might remove the affected code from the component, the vulnerability may not be reachable in the execution path, in-line protections exist, or, in its words, a host of other reasons. Reading those as reasons of the same kind as this line's three questions is this page's own comparison, not NTIA's.
BLANK RECORD (copy one per advisory and release)
A1 Product, release, package URL:
A2 SBOM file / format and version / generation context / tool / identifier / timestamp:
A3 Component name field / version / package URL:
A4 Dependency path or paths / direct dependency that brings it in:
A5 Build provenance (or "none"):
A6 Advisory identifier / package URL without version / range / function named:
A7 Listed? / each copy inside the range?:
A8 VEX status / justification or action statement / author / date:
A9 SBOM and VEX agree?:
A10 Remediation evidence:
A11 Still needs application analysis / answered by / evidence / date:
PART B. WORKED RECORD AND TRIAGE TABLE (INVENTED)
The application: sbomlab-invented-bookings, an invented booking site with three local packages. Its package.json names two of them, a form helper (booking-forms) and a receipt formatter (receipt-text). The form helper depends on the third, a date parser (date-parse). Release 1.0.0 carries date-parse 1.4.0 and release 1.1.0 carries date-parse 1.4.2.
The advisory: INVENTED-SBOMLAB-0001, invented, in a file format of this lab's own. It names date-parse from 1.2.0, gives 1.4.2 as the first fixed version, and names one function, parseBookingDate.
The VEX document: written for this page with OpenVEX field names, in the name of an invented organisation. It has two statements, one for each release.
The people, dates and decisions are invented. Every version, identifier, path and status below was printed by the lab in Part C.
B1. WHAT THE DOCUMENTS SAY (lines A1 to A4 and A6 to A9, for both releases)
The output below is the lab's triage script, run against the two CycloneDX SBOMs npm generated in Part C. It was copied in from the captured run by a script. ROW 1 is the record for release 1.0.0 and ROW 2 the record for release 1.1.0. The TRIAGE TABLE block is the same information with one line per release, and the CHANGE block is the comparison line A10 asks for.
==== OUTPUT OF node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/bookings.openvex.json sboms/release-1.cdx.json sboms/release-2.cdx.json (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
SBOM AND VEX TRIAGE: INVENTED-SBOMLAB-0001
Advisory package: pkg:npm/%40sbomlab-invented/date-parse | introduced 1.2.0 | first fixed version 1.4.2
Function the advisory names: parseBookingDate
VEX document: https://vex.sbomlab-invented.example/bookings/2026-0001 | version 2 | author: Sbomlab Invented Bookings (an invented organisation)
ROW 1: sbomlab-invented-bookings 1.0.0 (pkg:npm/sbomlab-invented-bookings@1.0.0)
SBOM read: sboms/release-1.cdx.json | CycloneDX 1.5 | generation context: build | tool: npm cli 11.12.1
SBOM document: urn:uuid:50ed21bd-ee80-481f-a000-d4c7dbfc9665 | timestamp 2026-11-14T04:25:29.077Z
Name field of the application in this SBOM: release-1
Package listed: yes (1 copy)
Copy 1: version 1.4.0 (inside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.0
dependency path: sbomlab-invented-bookings@1.0.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.0
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: affected
VEX justification: none (only a not_affected statement carries one)
VEX action statement: Update to release 1.1.0 of sbomlab-invented-bookings, which carries date-parse 1.4.2.
SBOM and VEX agree: yes
Still needs application analysis: The author says affected. Where is this release still deployed, and can a visitor reach the feature that calls parseBookingDate there?
ROW 2: sbomlab-invented-bookings 1.1.0 (pkg:npm/sbomlab-invented-bookings@1.1.0)
SBOM read: sboms/release-2.cdx.json | CycloneDX 1.5 | generation context: build | tool: npm cli 11.12.1
SBOM document: urn:uuid:bd20ba43-3d08-41af-8b45-82776ed147c3 | timestamp 2026-11-14T04:25:29.657Z
Name field of the application in this SBOM: release-2
Package listed: yes (1 copy)
Copy 1: version 1.4.2 (outside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.2
dependency path: sbomlab-invented-bookings@1.1.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.2
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: fixed
VEX justification: none (only a not_affected statement carries one)
SBOM and VEX agree: yes
Still needs application analysis: Is this the build that is deployed, and does a test with the reported input pass against it?
TRIAGE TABLE
release | package | version | dependency path | VEX status | justification | still needs application analysis
1.0.0 | present | 1.4.0 | via @sbomlab-invented/booking-forms@2.1.0 | affected | none | The author says affected. Where is this release still deployed, and can a visitor reach the feature that calls parseBookingDate there?
1.1.0 | present | 1.4.2 | via @sbomlab-invented/booking-forms@2.1.0 | fixed | none | Is this the build that is deployed, and does a test with the reported input pass against it?
CHANGE FROM sboms/release-1.cdx.json TO sboms/release-2.cdx.json
application: 1.0.0 -> 1.1.0
unchanged: @sbomlab-invented/booking-forms 2.1.0
changed: @sbomlab-invented/date-parse 1.4.0 -> 1.4.2
unchanged: @sbomlab-invented/receipt-text 3.0.1
Result: no conflict between the SBOMs and the VEX document
exit code: 0
B2. WHAT THE DOCUMENTS DO NOT SAY (lines A5, A10 and A11, written for the invented team)
A5 Build provenance: none, for both releases. The lab's packages are local folders that were never published, so no provenance statement exists for date-parse or for the application, and the SBOMs npm wrote carry no provenance fields.
ILLUSTRATION ONLY, not taken from any document in this lab. Had date-parse been published with provenance, this line would record, in SLSA's field names:
builder.id the build platform that ran the build
buildType the template that defined the build process
externalParameters the external interface to the build, which SLSA says must be included in the provenance
resolvedDependencies the artefacts the build fetched, if known. SLSA's example is the git commit that a repository address resolved to
subject the artefacts the build produced
and, from the package's page on the npm registry, the build environment, build summary, source commit, build file and public ledger entry.
A10 Remediation evidence. The CHANGE block in B1 is the comparison: between the two SBOMs the application moved from 1.0.0 to 1.1.0, date-parse moved from 1.4.0 to 1.4.2, and booking-forms and receipt-text did not change. ROW 2 shows the VEX statement for release 1.1.0, status fixed, and the script found no disagreement between that statement and the SBOM.
A11 Still needs application analysis.
Release 1.0.0. Answered by the invented team by reading code, not by any document. The dependency path in ROW 1 pointed at booking-forms, and packages/@sbomlab-invented/booking-forms/index.mjs passes the date field of a submitted form to parseBookingDate. src/handle-booking.mjs passes a visitor's form fields to that helper. Nothing in the lab's code stands between the two. On that reading the team recorded affected, with the action statement ROW 1 prints. What the row still leaves open is its last line: where release 1.0.0 is still deployed.
Release 1.1.0. The documents agree, and two things remain that neither can show: whether the build running in production is the one this SBOM describes, and whether that build refuses the input the advisory reports. The lab tests neither. Its date parser is a harmless stub whose 1.4.2 version refuses text longer than 10 characters, which stands in for a fix. A real fix needs a real test against the real application.
WHAT THIS RECORD DOES NOT SHOW
- That either release has no vulnerabilities. The record covers one advisory and one package.
- That the fix works. "fixed" is the VEX author's statement about release 1.1.0. The SBOM shows the version changed, and nothing in either document exercises the code.
- That the two documents are correct. "SBOM and VEX agree: yes" means the script found no disagreement between them. Part C shows the same script reporting a conflict when a careless VEX document calls release 1.0.0 fixed.
- Anything about packages the SBOM does not list.
PART C. THE OFFLINE SBOM LAB
WHAT IT NEEDS
Node.js and npm. The five lab files import only node:fs, node:path, node:http, node:child_process, node:url, node:test and node:assert/strict, plus each other. The lab installs no package from a registry: npm install links the lab's own three local folders into each snapshot's node_modules folder. The Node.js documentation marks the test runner stable from version 20.0.0. npm's documentation for CLI version 11 lists the sbom command, and make-sboms.mjs prints the option list of the npm it finds. The outputs below were recorded on Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64).
WHAT IT TOUCHES
make-snapshots.mjs deletes any folder called snapshots in the folder it is run from (the lab folder, as SET-UP instructs), writes it again, and writes the folders advisory and vex. make-sboms.mjs writes a folder called npm-home (two empty configuration files and npm's cache folder, where npm wrote its own logs in the run recorded here) and deletes and rewrites a folder called sboms. npm install writes a node_modules folder and a package-lock.json inside each snapshot. The listener binds 127.0.0.1 on a port the operating system picks, and closes when the script ends. Nothing is uploaded.
HOW THE LAB KEPT NPM AWAY FROM A REGISTRY
Every npm command was started by make-sboms.mjs with --offline, --no-audit, --no-fund, --no-update-notifier and --ignore-scripts, with --userconfig and --globalconfig pointing at two empty files, with a cache folder of the lab's own, and with --registry set to the address of a listener the script opened on 127.0.0.1. The listener counts every request it receives. It counted 0 requests while npm ran, and 1 after the script sent its own self-test request, which shows the counter was working. That is evidence about these runs on this machine. It is not a statement about what npm does under other settings.
WHAT EACH FILE IS, AND IS NOT
make-snapshots.mjs writes text files. The date parser, form helper, receipt formatter and booking handler it writes are harmless stubs, and the lab never runs them.
make-sboms.mjs runs npm and saves what npm sbom prints. It does not edit the SBOMs. The serial numbers, document namespaces and timestamps inside them were generated by npm during the run and differ from file to file. Run it again and they will differ again.
sbom-readers.mjs reads an SBOM that is already parsed JSON. It was written against the documents npm 11.12.1 produced here, CycloneDX specVersion 1.5 and SPDX-2.3, and was not tried on documents from another tool or another format version. In SPDX it follows DEPENDS_ON and DEPENDENCY_OF, skips DESCRIBES, and lists any other relationship type as not followed.
triage.mjs reads documents, not code. It matches by package URL with the version removed, compares plain MAJOR.MINOR.PATCH versions only, and uses the last VEX statement in the document that names the vulnerability and the release. It does not compare statement timestamps, check signatures or read the application. Its "Still needs application analysis" lines are fixed wording chosen from the row's state, written for this page.
triage.test.mjs is the regression test. Sixteen of its tests build small documents in the test file. Three read the SBOMs make-sboms.mjs saved and are skipped when sboms/release-1.cdx.json is absent.
The advisory file is this lab's own format, not the format of any advisory database. The VEX document uses the field names in the OpenVEX specification v0.2.0. It was not checked with an OpenVEX tool, and it is not signed.
SET-UP
Make an empty folder, save the five files below into it under the names shown, and run the commands under RUN IT from that folder, in order.
==== File 1 of 5: make-snapshots.mjs ====
// make-snapshots.mjs: writes the invented project this lab reads, in folders
// next to this file. It deletes any snapshots folder already there, then
// writes two snapshots of one application (release-1 and release-2), each
// with three local packages, then one advisory file and two VEX documents.
// Nothing is downloaded and nothing is installed.
// Every package name, organisation, host, version and advisory is invented.
import fs from 'node:fs'
import path from 'node:path'
const SCOPE = '@sbomlab-invented'
const APP_NAME = 'sbomlab-invented-bookings'
const ADVISORY_ID = 'INVENTED-SBOMLAB-0001'
const INVENTED = 'INVENTED FOR THIS PAGE. '
// The two snapshots differ in the application's version, the date parser's
// version and the date parser's source (see buildDateParseSource).
const RELEASES = [
{ folder: 'release-1', appVersion: '1.0.0', dateParseVersion: '1.4.0' },
{ folder: 'release-2', appVersion: '1.1.0', dateParseVersion: '1.4.2' },
]
function writeText(filePath, text) {
fs.mkdirSync(path.dirname(filePath), { recursive: true })
fs.writeFileSync(filePath, text)
}
function writeJson(filePath, value) {
writeText(filePath, JSON.stringify(value, null, 2) + '\n')
}
function localPackageFolder(shortName) {
return 'packages/' + SCOPE + '/' + shortName
}
function buildAppManifest(release) {
return {
name: APP_NAME,
version: release.appVersion,
private: true,
description: INVENTED + 'A stand-in booking application.',
license: 'UNLICENSED',
type: 'module',
dependencies: {
[SCOPE + '/booking-forms']: 'file:' + localPackageFolder('booking-forms'),
[SCOPE + '/receipt-text']: 'file:' + localPackageFolder('receipt-text'),
},
}
}
function buildLocalManifest(shortName, version, description, dependencies) {
const manifest = {
name: SCOPE + '/' + shortName,
version: version,
description: INVENTED + description,
license: 'MIT',
type: 'module',
main: 'index.mjs',
}
if (dependencies) manifest.dependencies = dependencies
return manifest
}
// The date parser. The advisory names parseBookingDate. Both bodies are
// harmless stubs: there is no flaw here to study. The second version adds a
// length check, which stands in for the fix.
function buildDateParseSource(version) {
const lines = [
'// ' + INVENTED + 'A stand-in date parser, version ' + version + '.',
'export function parseBookingDate(text) {',
]
if (version !== '1.4.0') lines.push(" if (String(text).length > 10) throw new RangeError('date text is too long')")
lines.push(
" const parts = String(text).split('-').map(Number)",
' return new Date(Date.UTC(parts[0], parts[1] - 1, parts[2]))',
'}',
'',
'export function formatDay(date) {',
' return date.toISOString().slice(0, 10)',
'}',
'',
)
return lines.join('\n')
}
const BOOKING_FORMS_SOURCE = [
'// ' + INVENTED + 'A stand-in form helper. It passes the date field of a',
'// submitted booking form to parseBookingDate.',
"import { parseBookingDate, formatDay } from '" + SCOPE + "/date-parse'",
'',
'export function readBookingForm(fields) {',
' const day = parseBookingDate(fields.date)',
' return { name: String(fields.name), day: formatDay(day) }',
'}',
'',
].join('\n')
const RECEIPT_TEXT_SOURCE = [
'// ' + INVENTED + 'A stand-in receipt formatter. It does not use the date parser.',
'export function formatReceipt(booking) {',
" return 'Booking for ' + booking.name + ' on ' + booking.day",
'}',
'',
].join('\n')
const APP_SOURCE = [
"// The invented application's own code. A visitor's form fields arrive here.",
"import { readBookingForm } from '" + SCOPE + "/booking-forms'",
"import { formatReceipt } from '" + SCOPE + "/receipt-text'",
'',
'export function handleBookingRequest(fields) {',
' return formatReceipt(readBookingForm(fields))',
'}',
'',
].join('\n')
function writeSnapshot(release) {
const root = path.join('snapshots', release.folder)
const dateParse = { [SCOPE + '/date-parse']: 'file:../date-parse' }
writeJson(path.join(root, 'package.json'), buildAppManifest(release))
writeText(path.join(root, 'src/handle-booking.mjs'), APP_SOURCE)
writeJson(path.join(root, localPackageFolder('booking-forms'), 'package.json'),
buildLocalManifest('booking-forms', '2.1.0', 'A stand-in form helper.', dateParse))
writeText(path.join(root, localPackageFolder('booking-forms'), 'index.mjs'), BOOKING_FORMS_SOURCE)
writeJson(path.join(root, localPackageFolder('date-parse'), 'package.json'),
buildLocalManifest('date-parse', release.dateParseVersion, 'A stand-in date parser.'))
writeText(path.join(root, localPackageFolder('date-parse'), 'index.mjs'), buildDateParseSource(release.dateParseVersion))
writeJson(path.join(root, localPackageFolder('receipt-text'), 'package.json'),
buildLocalManifest('receipt-text', '3.0.1', 'A stand-in receipt formatter.'))
writeText(path.join(root, localPackageFolder('receipt-text'), 'index.mjs'), RECEIPT_TEXT_SOURCE)
}
// This lab's own advisory file. It is not in any advisory database's format.
const ADVISORY = {
id: ADVISORY_ID,
note: INVENTED + 'This advisory describes no real package and no real flaw.',
summary: 'parseBookingDate in ' + SCOPE + '/date-parse accepts date text of any length',
package_purl: 'pkg:npm/%40sbomlab-invented/date-parse',
introduced: '1.2.0',
first_fixed_version: '1.4.2',
affected_function: 'parseBookingDate',
}
function productPurl(release) {
return 'pkg:npm/' + APP_NAME + '@' + release.appVersion
}
function dateParsePurl(release) {
return ADVISORY.package_purl + '@' + release.dateParseVersion
}
function buildStatement(release, status, extraFields) {
const statement = {
vulnerability: { name: ADVISORY_ID, description: ADVISORY.note },
products: [{ '@id': productPurl(release), subcomponents: [{ '@id': dateParsePurl(release) }] }],
status: status,
}
return Object.assign(statement, extraFields)
}
// The VEX document the invented team publishes, with the field names of the
// OpenVEX specification v0.2.0. Its version field is 2 and it holds two
// statements, one for each release.
function buildVexDocument() {
return {
'@context': 'https://openvex.dev/ns/v0.2.0',
'@id': 'https://vex.sbomlab-invented.example/bookings/2026-0001',
author: 'Sbomlab Invented Bookings (an invented organisation)',
role: 'vendor',
timestamp: '2026-11-13T04:00:00Z',
version: 2,
statements: [
buildStatement(RELEASES[0], 'affected', {
timestamp: '2026-11-11T01:30:00Z',
action_statement: 'Update to release 1.1.0 of ' + APP_NAME + ', which carries date-parse 1.4.2.',
}),
buildStatement(RELEASES[1], 'fixed', {}),
],
}
}
// A careless edit of the same document: it calls release 1.0.0 fixed.
function buildCarelessVexDocument() {
const careless = buildVexDocument()
careless['@id'] = 'https://vex.sbomlab-invented.example/bookings/2026-0001-careless'
careless.statements[0] = buildStatement(RELEASES[0], 'fixed', { timestamp: '2026-11-11T01:30:00Z' })
return careless
}
fs.rmSync('snapshots', { recursive: true, force: true })
for (const release of RELEASES) writeSnapshot(release)
writeJson('advisory/' + ADVISORY_ID + '.json', ADVISORY)
writeJson('vex/bookings.openvex.json', buildVexDocument())
writeJson('vex/careless.openvex.json', buildCarelessVexDocument())
console.log('snapshots written: ' + fs.readdirSync('snapshots').sort().join(', '))
console.log('local packages in each: ' + fs.readdirSync(path.join('snapshots/release-1/packages', SCOPE)).sort().join(', '))
console.log('also written: advisory/' + ADVISORY_ID + '.json, vex/bookings.openvex.json, vex/careless.openvex.json')
==== File 2 of 5: make-sboms.mjs ====
// make-sboms.mjs: runs npm inside each snapshot folder and saves what npm
// sbom prints. It first prints the npm version and the first three
// paragraphs of npm sbom --help: the description, the usage line and the
// option list. Then, for each snapshot, it runs npm install, then npm sbom
// once for CycloneDX and once for SPDX. For release-1 it also runs npm sbom
// with --package-lock-only and prints the lines that differ from the first
// run.
//
// Before it starts npm, it opens an HTTP listener on 127.0.0.1 and passes
// that address to npm as the registry, with npm's offline setting on. The
// listener answers every request with status 503 and counts it. After the
// npm runs, the script sends the listener one request of its own, to show
// that the count works, and prints both counts.
import fs from 'node:fs'
import http from 'node:http'
import path from 'node:path'
import { spawn } from 'node:child_process'
const SNAPSHOTS = ['release-1', 'release-2']
const FORMATS = [
{ flag: 'cyclonedx', extension: 'cdx.json' },
{ flag: 'spdx', extension: 'spdx.json' },
]
function startListener(seenRequests) {
const server = http.createServer((request, response) => {
seenRequests.push(request.method + ' ' + request.url)
response.statusCode = 503
response.end()
})
return new Promise((resolve) => {
server.listen(0, '127.0.0.1', () => resolve(server))
})
}
function sendSelfTestRequest(registryAddress) {
return new Promise((resolve) => {
http.get(registryAddress + 'listener-self-test', { agent: false }, (response) => {
response.resume()
response.on('end', resolve)
})
})
}
// The settings every npm command in this lab runs with. The user and global
// configuration files they name are the two empty files main() writes, and
// the cache folder is the lab's own.
function buildNpmSettings(registryAddress) {
return [
'--offline', '--no-audit', '--no-fund', '--no-update-notifier', '--ignore-scripts',
'--registry', registryAddress,
'--userconfig', '../../npm-home/userconfig',
'--globalconfig', '../../npm-home/globalconfig',
'--cache', '../../npm-home/cache',
]
}
function runNpm(snapshot, npmArguments) {
const folder = path.join('snapshots', snapshot)
console.log('(in snapshots/' + snapshot + ') npm ' + npmArguments.join(' '))
return new Promise((resolve, reject) => {
const child = spawn('npm', npmArguments, { cwd: folder })
let printed = ''
child.stdout.on('data', (chunk) => { printed += chunk })
child.stderr.on('data', (chunk) => { printed += chunk })
child.on('error', reject)
child.on('close', (exitCode) => {
if (exitCode !== 0) return reject(new Error('npm exited with code ' + exitCode + '\n' + printed))
resolve(printed)
})
})
}
function saveSbom(fileName, text) {
const filePath = 'sboms/' + fileName
fs.writeFileSync(filePath, text)
console.log(' saved ' + filePath + ' (' + text.trimEnd().split('\n').length + ' lines)')
}
async function buildSnapshotSboms(snapshot, settings) {
const installOutput = await runNpm(snapshot, ['install'].concat(settings))
console.log(' npm printed: ' + installOutput.trim().split('\n').join(' | '))
for (const format of FORMATS) {
const sbomArguments = ['sbom', '--sbom-format', format.flag, '--sbom-type', 'application']
const sbomText = await runNpm(snapshot, sbomArguments.concat(settings))
saveSbom(snapshot + '.' + format.extension, sbomText)
}
}
async function buildLockOnlySbom(snapshot, settings) {
const sbomArguments = ['sbom', '--sbom-format', 'cyclonedx', '--sbom-type', 'application', '--package-lock-only']
const sbomText = await runNpm(snapshot, sbomArguments.concat(settings))
saveSbom(snapshot + '.lock-only.cdx.json', sbomText)
}
// Prints the first three paragraphs of the help text, each line marked "|".
function printHelpSummary(helpText) {
const paragraphs = helpText.trim().split('\n\n').slice(0, 3)
for (const paragraph of paragraphs) {
for (const line of paragraph.split('\n')) console.log(' | ' + line)
}
}
// Prints each line that differs between two saved files of equal length.
function printDifferingLines(firstName, secondName) {
const first = fs.readFileSync('sboms/' + firstName, 'utf8').split('\n')
const second = fs.readFileSync('sboms/' + secondName, 'utf8').split('\n')
console.log('Lines that differ between ' + firstName + ' and ' + secondName + ':')
if (first.length !== second.length) {
console.log(' the files have different lengths: ' + first.length + ' and ' + second.length + ' lines')
return
}
first.forEach((line, index) => {
if (line === second[index]) return
console.log(' line ' + (index + 1) + ': ' + line.trim() + ' -> ' + second[index].trim())
})
}
async function main() {
const seenRequests = []
const server = await startListener(seenRequests)
const registryAddress = 'http://127.0.0.1:' + server.address().port + '/'
const settings = buildNpmSettings(registryAddress)
fs.mkdirSync('npm-home', { recursive: true })
fs.writeFileSync('npm-home/userconfig', '')
fs.writeFileSync('npm-home/globalconfig', '')
fs.rmSync('sboms', { recursive: true, force: true })
fs.mkdirSync('sboms')
const npmVersion = (await runNpm(SNAPSHOTS[0], ['--version'].concat(settings))).trim()
console.log('Node.js ' + process.version + ', npm ' + npmVersion)
const helpText = await runNpm(SNAPSHOTS[0], ['sbom', '--help'].concat(settings))
printHelpSummary(helpText)
for (const snapshot of SNAPSHOTS) await buildSnapshotSboms(snapshot, settings)
await buildLockOnlySbom(SNAPSHOTS[0], settings)
printDifferingLines('release-1.cdx.json', 'release-1.lock-only.cdx.json')
const seenWhileNpmRan = seenRequests.length
await sendSelfTestRequest(registryAddress)
console.log('Requests the listener saw while npm ran: ' + seenWhileNpmRan)
console.log('Requests the listener saw after the self-test request: ' + seenRequests.length + ' (' + seenRequests.slice(seenWhileNpmRan).join(', ') + ')')
server.close()
}
main().catch((error) => {
console.log(error.message)
process.exitCode = 1
})
==== File 3 of 5: sbom-readers.mjs ====
// sbom-readers.mjs: reads one SBOM, as CycloneDX JSON or SPDX 2.3 JSON in the
// shapes npm sbom writes, into one plain structure: the application, its
// components, and a list of which component depends on which. It also splits
// package URLs and finds the dependency paths from the application to one
// component. It reads JSON that is already parsed and opens no files.
// Splits a package URL into the part before the version and the version.
// Qualifiers (after ?) and a subpath (after #) are dropped.
export function splitPurl(purl) {
const core = String(purl).split('#')[0].split('?')[0]
const versionMarker = core.indexOf('@', core.lastIndexOf('/') + 1)
if (versionMarker === -1) return { withoutVersion: core, version: null }
return { withoutVersion: core.slice(0, versionMarker), version: core.slice(versionMarker + 1) }
}
// "pkg:npm/%40scope/name" becomes "@scope/name", for printing only.
export function readPackageName(purlWithoutVersion) {
const afterType = purlWithoutVersion.slice(purlWithoutVersion.indexOf('/') + 1)
return decodeURIComponent(afterType)
}
// The label printed for a component: package name and version, taken from
// its package URL when it has one, otherwise from its name field.
export function labelFor(component) {
if (!component.purl) return component.name + '@' + component.version
const parts = splitPurl(component.purl)
return readPackageName(parts.withoutVersion) + '@' + (parts.version || component.version)
}
function addEdge(edges, fromId, toId) {
if (!edges[fromId]) edges[fromId] = []
edges[fromId].push(toId)
}
// CycloneDX: the application is metadata.component, each dependency is an
// entry in components, and dependencies lists what each bom-ref depends on.
export function readCycloneDx(document) {
const toComponent = (item) => ({ id: item['bom-ref'], name: item.name, version: item.version, purl: item.purl })
const metadata = document.metadata || {}
const tool = (metadata.tools || [])[0] || {}
const edges = {}
for (const entry of document.dependencies || []) {
for (const target of entry.dependsOn || []) addEdge(edges, entry.ref, target)
}
return {
format: 'CycloneDX ' + document.specVersion,
generationContext: ((metadata.lifecycles || [])[0] || {}).phase || 'not stated',
tool: [tool.vendor, tool.name, tool.version].filter(Boolean).join(' ') || 'not stated',
documentId: document.serialNumber || 'not stated',
timestamp: metadata.timestamp || 'not stated',
root: toComponent(metadata.component),
components: (document.components || []).map(toComponent),
edges: edges,
relationshipsNotFollowed: [],
}
}
function readSpdxPurl(spdxPackage) {
const reference = (spdxPackage.externalRefs || []).find((item) => item.referenceType === 'purl')
return reference ? reference.referenceLocator : undefined
}
// SPDX 2.3: every package, the application included, is an entry in packages,
// and documentDescribes names the application. DEPENDS_ON points from the
// dependent to its dependency. DEPENDENCY_OF points the other way. DESCRIBES
// is skipped. Any other relationship type is listed as not followed.
export function readSpdx(document) {
const toComponent = (item) => ({ id: item.SPDXID, name: item.name, version: item.versionInfo, purl: readSpdxPurl(item) })
const packages = (document.packages || []).map(toComponent)
const describedIds = document.documentDescribes || []
const edges = {}
const notFollowed = []
for (const relationship of document.relationships || []) {
const type = relationship.relationshipType
if (type === 'DEPENDS_ON') addEdge(edges, relationship.spdxElementId, relationship.relatedSpdxElement)
else if (type === 'DEPENDENCY_OF') addEdge(edges, relationship.relatedSpdxElement, relationship.spdxElementId)
else if (type !== 'DESCRIBES' && !notFollowed.includes(type)) notFollowed.push(type)
}
return {
format: document.spdxVersion,
generationContext: 'not stated',
tool: ((document.creationInfo || {}).creators || []).join(', ') || 'not stated',
documentId: document.documentNamespace || 'not stated',
timestamp: (document.creationInfo || {}).created || 'not stated',
root: packages.find((item) => describedIds.includes(item.id)),
components: packages.filter((item) => !describedIds.includes(item.id)),
edges: edges,
relationshipsNotFollowed: notFollowed,
}
}
export function readSbom(document) {
if (document.bomFormat === 'CycloneDX') return readCycloneDx(document)
if (typeof document.spdxVersion === 'string') return readSpdx(document)
throw new Error('not a CycloneDX or SPDX JSON document')
}
// Every path from the application to one component, depth first. An id is
// never visited twice on one path, so a cycle cannot loop.
export function findPaths(sbom, targetId) {
const found = []
function walk(currentId, visited) {
for (const nextId of sbom.edges[currentId] || []) {
if (visited.includes(nextId)) continue
const next = visited.concat([nextId])
if (nextId === targetId) found.push(next)
else walk(nextId, next)
}
}
walk(sbom.root.id, [sbom.root.id])
return found
}
==== File 4 of 5: triage.mjs ====
// triage.mjs: reads documents, not code. Given one advisory file, one VEX
// document with OpenVEX field names and one or more SBOMs, it prints one
// triage row per SBOM: whether the advisory's package is listed, at which
// version, by which dependency path, what the VEX document says about that
// release, and whether the SBOM and the VEX statement agree. It exits with
// code 1 if any row has a conflict or an incomplete VEX statement.
//
// It matches components by package URL, not by the name field. It compares
// plain MAJOR.MINOR.PATCH versions only. It does not read the application's
// code, so it cannot say whether the affected function is called.
//
// Usage: node triage.mjs ADVISORY-FILE VEX-FILE SBOM-FILE (more SBOM files)
import fs from 'node:fs'
import { fileURLToPath } from 'node:url'
import { splitPurl, readPackageName, labelFor, readSbom, findPaths } from './sbom-readers.mjs'
const INSIDE = 'inside the advisory range'
const OUTSIDE = 'outside the advisory range'
const CANNOT_COMPARE = 'cannot compare this version'
// Plain MAJOR.MINOR.PATCH only. Anything else returns null.
function parseVersion(text) {
const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(text))
if (!match) return null
return [Number(match[1]), Number(match[2]), Number(match[3])]
}
export function compareVersions(left, right) {
const first = parseVersion(left)
const second = parseVersion(right)
if (!first || !second) return null
for (let index = 0; index < 3; index++) {
if (first[index] !== second[index]) return first[index] < second[index] ? -1 : 1
}
return 0
}
// Inside the range means: at or above introduced, and below first_fixed_version.
export function checkRange(advisory, version) {
const fromIntroduced = compareVersions(version, advisory.introduced)
const fromFixed = compareVersions(version, advisory.first_fixed_version)
if (fromIntroduced === null || fromFixed === null) return CANNOT_COMPARE
return fromIntroduced >= 0 && fromFixed < 0 ? INSIDE : OUTSIDE
}
// The copies of the advisory's package in one SBOM, matched by package URL
// with the version removed.
export function findCopies(advisory, sbom) {
const byId = { [sbom.root.id]: sbom.root }
for (const component of sbom.components) byId[component.id] = component
const matches = sbom.components.filter((component) => component.purl && splitPurl(component.purl).withoutVersion === advisory.package_purl)
return matches.map((component) => ({
name: component.name,
version: component.version,
purl: component.purl,
rangeVerdict: checkRange(advisory, component.version),
paths: findPaths(sbom, component.id).map((ids) => ids.map((id) => labelFor(byId[id] || { name: id, version: '?' }))),
}))
}
// The statement about one vulnerability and one product. When several match,
// the last one in the document is used. Statement timestamps are not compared.
export function findVexStatement(vexDocument, vulnerabilityName, productPurl) {
let found = null
for (const statement of vexDocument.statements || []) {
if (!statement.vulnerability || statement.vulnerability.name !== vulnerabilityName) continue
const products = statement.products || []
if (products.some((product) => product['@id'] === productPurl)) found = statement
}
return found
}
function listSubcomponentPurls(statement, productPurl) {
const product = (statement.products || []).find((item) => item['@id'] === productPurl)
return ((product && product.subcomponents) || []).map((item) => item['@id'])
}
// Checks the VEX statement against what the SBOM lists. "yes" means no
// disagreement was found between the two documents, nothing more.
export function judgeAgreement(copies, statement, productPurl) {
if (!statement) return 'no VEX statement for this release'
const status = statement.status
if (status === 'affected' && !statement.action_statement) return 'INCOMPLETE: an affected statement needs an action statement'
if (status === 'not_affected' && !statement.justification && !statement.impact_statement) {
return 'INCOMPLETE: a not_affected statement needs a justification or an impact statement'
}
const isListed = copies.length > 0
const hasCopyInRange = copies.some((copy) => copy.rangeVerdict === INSIDE)
if (status === 'fixed' && hasCopyInRange) return 'CONFLICT: the VEX statement says fixed, but the SBOM lists a version inside the advisory range'
if (status === 'affected' && !isListed) return 'CONFLICT: the VEX statement says affected, but the SBOM does not list the package'
if (status === 'affected' && !hasCopyInRange) return 'CONFLICT: the VEX statement says affected, but no listed version is inside the advisory range'
if (status === 'not_affected' && statement.justification === 'component_not_present' && isListed) {
return 'CONFLICT: the justification is component_not_present, but the SBOM lists the package'
}
const namedPurls = listSubcomponentPurls(statement, productPurl)
if (isListed && namedPurls.length > 0 && !copies.some((copy) => namedPurls.includes(copy.purl))) {
return 'CONFLICT: the VEX statement names a subcomponent version the SBOM does not list'
}
return 'yes'
}
// The question the two documents leave open, chosen from what they do say.
export function chooseOpenQuestion(advisory, copies, statement) {
const affectedCode = advisory.affected_function || 'the affected code'
const status = statement ? statement.status : 'none'
if (copies.length === 0) {
return 'Does this SBOM cover everything in the build that is deployed? A package copied into the source tree or bundled by another tool would not be listed.'
}
if (status === 'affected') {
return 'The author says affected. Where is this release still deployed, and can a visitor reach the feature that calls ' + affectedCode + ' there?'
}
if (status === 'not_affected') return 'The author says not affected. Does the evidence behind the justification still hold for this build?'
if (copies.some((copy) => copy.rangeVerdict !== OUTSIDE)) {
return 'Is ' + affectedCode + ' called in this application, can input from outside reach it, and is a mitigating setting on?'
}
return 'Is this the build that is deployed, and does a test with the reported input pass against it?'
}
export function buildRow(advisory, vexDocument, sbom, sbomFile) {
const product = splitPurl(sbom.root.purl)
const copies = findCopies(advisory, sbom)
const statement = findVexStatement(vexDocument, advisory.id, sbom.root.purl)
return {
sbomFile: sbomFile,
sbom: sbom,
productName: readPackageName(product.withoutVersion),
productVersion: product.version,
copies: copies,
statement: statement,
agreement: judgeAgreement(copies, statement, sbom.root.purl),
question: chooseOpenQuestion(advisory, copies, statement),
}
}
function describeJustification(statement) {
if (!statement) return 'none'
if (statement.status !== 'not_affected') return 'none (only a not_affected statement carries one)'
return statement.justification || 'none given'
}
function describeBroughtInBy(pathLabels) {
if (pathLabels.length === 2) return 'the application itself (a direct dependency)'
return pathLabels[1] + ' (the direct dependency on this path)'
}
function describeCopyCount(count) {
if (count === 0) return 'no'
return count === 1 ? 'yes (1 copy)' : 'yes (' + count + ' copies)'
}
function printCopy(copy, number) {
console.log(' Copy ' + number + ': version ' + copy.version + ' (' + copy.rangeVerdict + ')')
console.log(' name field: ' + copy.name + ' | package URL: ' + copy.purl)
if (copy.paths.length === 0) console.log(' dependency path: none found from the application in this SBOM')
for (const pathLabels of copy.paths) {
console.log(' dependency path: ' + pathLabels.join(' > '))
console.log(' brought in by: ' + describeBroughtInBy(pathLabels))
}
}
function printRow(row, number) {
const sbom = row.sbom
console.log('')
console.log('ROW ' + number + ': ' + row.productName + ' ' + row.productVersion + ' (' + sbom.root.purl + ')')
console.log(' SBOM read: ' + row.sbomFile + ' | ' + sbom.format + ' | generation context: ' + sbom.generationContext + ' | tool: ' + sbom.tool)
console.log(' SBOM document: ' + sbom.documentId + ' | timestamp ' + sbom.timestamp)
console.log(' Name field of the application in this SBOM: ' + sbom.root.name)
if (sbom.relationshipsNotFollowed.length > 0) console.log(' Relationship types not followed: ' + sbom.relationshipsNotFollowed.join(', '))
console.log(' Package listed: ' + describeCopyCount(row.copies.length))
row.copies.forEach((copy, index) => printCopy(copy, index + 1))
console.log(' VEX status: ' + (row.statement ? row.statement.status : 'none recorded'))
console.log(' VEX justification: ' + describeJustification(row.statement))
if (row.statement && row.statement.action_statement) console.log(' VEX action statement: ' + row.statement.action_statement)
if (row.statement && row.statement.impact_statement) console.log(' VEX impact statement: ' + row.statement.impact_statement)
console.log(' SBOM and VEX agree: ' + row.agreement)
console.log(' Still needs application analysis: ' + row.question)
}
function summariseRow(row) {
const versions = row.copies.map((copy) => copy.version).join(', ') || 'none'
const firstPath = row.copies.length > 0 && row.copies[0].paths.length > 0 ? row.copies[0].paths[0] : null
const via = firstPath ? (firstPath.length === 2 ? 'direct' : 'via ' + firstPath[1]) : 'none'
const status = row.statement ? row.statement.status : 'none recorded'
const justification = row.statement && row.statement.status === 'not_affected' ? row.statement.justification || 'none given' : 'none'
return [row.productVersion, row.copies.length > 0 ? 'present' : 'absent', versions, via, status, justification, row.question]
}
function printTable(rows) {
const headings = ['release', 'package', 'version', 'dependency path', 'VEX status', 'justification', 'still needs application analysis']
const lines = [headings].concat(rows.map(summariseRow))
const widths = lines[0].map((heading, column) => Math.max(...lines.map((line) => line[column].length)))
console.log('')
console.log('TRIAGE TABLE')
for (const line of lines) console.log(line.map((cell, column) => cell.padEnd(widths[column])).join(' | ').trimEnd())
}
function listVersionsByPackage(sbom) {
const versions = {}
for (const component of sbom.components) {
if (component.purl) versions[readPackageName(splitPurl(component.purl).withoutVersion)] = component.version
}
return versions
}
// What changed between two SBOMs given one after the other on the command line.
function printChanges(earlier, later) {
const before = listVersionsByPackage(earlier.sbom)
const after = listVersionsByPackage(later.sbom)
const names = Array.from(new Set(Object.keys(before).concat(Object.keys(after)))).sort()
console.log('')
console.log('CHANGE FROM ' + earlier.sbomFile + ' TO ' + later.sbomFile)
console.log(' application: ' + earlier.productVersion + ' -> ' + later.productVersion)
for (const name of names) {
if (before[name] === after[name]) console.log(' unchanged: ' + name + ' ' + before[name])
else console.log(' changed: ' + name + ' ' + (before[name] || 'not listed') + ' -> ' + (after[name] || 'not listed'))
}
}
function readJson(filePath) {
return JSON.parse(fs.readFileSync(filePath, 'utf8'))
}
function printHeader(advisory, vexDocument) {
console.log('SBOM AND VEX TRIAGE: ' + advisory.id)
console.log('Advisory package: ' + advisory.package_purl + ' | introduced ' + advisory.introduced + ' | first fixed version ' + advisory.first_fixed_version)
console.log('Function the advisory names: ' + (advisory.affected_function || 'none'))
console.log('VEX document: ' + vexDocument['@id'] + ' | version ' + vexDocument.version + ' | author: ' + vexDocument.author)
}
function main() {
const advisory = readJson(process.argv[2])
const vexDocument = readJson(process.argv[3])
const sbomFiles = process.argv.slice(4)
const rows = sbomFiles.map((sbomFile) => buildRow(advisory, vexDocument, readSbom(readJson(sbomFile)), sbomFile))
printHeader(advisory, vexDocument)
rows.forEach((row, index) => printRow(row, index + 1))
printTable(rows)
for (let index = 1; index < rows.length; index++) printChanges(rows[index - 1], rows[index])
const problems = rows.filter((row) => row.agreement.startsWith('CONFLICT') || row.agreement.startsWith('INCOMPLETE'))
console.log('')
console.log('Result: ' + (problems.length === 0 ? 'no conflict between the SBOMs and the VEX document' : problems.length + ' row(s) with a conflict or an incomplete statement'))
process.exitCode = problems.length === 0 ? 0 : 1
}
// True when this file is the script node was started with, false when a test imports it.
function isRunDirectly() {
if (!process.argv[1]) return false
return fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
}
if (isRunDirectly()) main()
==== File 5 of 5: triage.test.mjs ====
// triage.test.mjs: regression tests for triage.mjs and sbom-readers.mjs, for
// the Node.js test runner. The first group builds small SBOM and VEX objects
// in this file. The second group reads the SBOMs that make-sboms.mjs saved,
// and is skipped when sboms/release-1.cdx.json is not there.
import test from 'node:test'
import assert from 'node:assert/strict'
import fs from 'node:fs'
import { splitPurl, readSbom, findPaths } from './sbom-readers.mjs'
import {
compareVersions, checkRange, findCopies, findVexStatement, judgeAgreement,
chooseOpenQuestion, buildRow,
} from './triage.mjs'
const ADVISORY = {
id: 'INVENTED-TEST-0001',
package_purl: 'pkg:npm/%40sbomlab-invented/date-parse',
introduced: '1.2.0',
first_fixed_version: '1.4.2',
affected_function: 'parseBookingDate',
}
const APP_PURL = 'pkg:npm/sbomlab-invented-bookings@1.0.0'
function component(name, version) {
const purlName = name.replace('@', '%40')
return { 'bom-ref': name + '@' + version, type: 'library', name: name, version: version, purl: 'pkg:npm/' + purlName + '@' + version }
}
// A CycloneDX document with the application, a form helper and a date parser.
function buildCycloneDx(dateParseVersion, rootDependsOn) {
const forms = component('@sbomlab-invented/booking-forms', '2.1.0')
const dates = component('@sbomlab-invented/date-parse', dateParseVersion)
return {
bomFormat: 'CycloneDX',
specVersion: '1.5',
metadata: { component: { 'bom-ref': 'app@1.0.0', name: 'some-folder', version: '1.0.0', purl: APP_PURL } },
components: [forms, dates],
dependencies: [
{ ref: 'app@1.0.0', dependsOn: rootDependsOn || [forms['bom-ref']] },
{ ref: forms['bom-ref'], dependsOn: [dates['bom-ref']] },
{ ref: dates['bom-ref'], dependsOn: [] },
],
}
}
function buildVex(status, extraFields) {
const statement = Object.assign({
vulnerability: { name: ADVISORY.id },
products: [{ '@id': APP_PURL }],
status: status,
}, extraFields)
return { '@id': 'https://vex.sbomlab-invented.example/test', version: 1, author: 'test', statements: [statement] }
}
test('splitPurl separates the version and keeps the scope percent-encoded', () => {
assert.deepEqual(splitPurl('pkg:npm/%40sbomlab-invented/date-parse@1.4.0'), { withoutVersion: 'pkg:npm/%40sbomlab-invented/date-parse', version: '1.4.0' })
assert.deepEqual(splitPurl('pkg:npm/plain-name'), { withoutVersion: 'pkg:npm/plain-name', version: null })
assert.equal(splitPurl('pkg:npm/plain-name@2.0.0?vcs_url=x#lib').version, '2.0.0')
})
test('compareVersions orders by number, not by text', () => {
assert.equal(compareVersions('1.4.0', '1.4.2'), -1)
assert.equal(compareVersions('1.10.0', '1.9.0'), 1)
assert.equal(compareVersions('2.0.0', '2.0.0'), 0)
assert.equal(compareVersions('2.0.0-beta.1', '2.0.0'), null)
})
test('checkRange: introduced is inside, the first fixed version is outside', () => {
assert.equal(checkRange(ADVISORY, '1.2.0'), 'inside the advisory range')
assert.equal(checkRange(ADVISORY, '1.4.0'), 'inside the advisory range')
assert.equal(checkRange(ADVISORY, '1.4.2'), 'outside the advisory range')
assert.equal(checkRange(ADVISORY, '1.1.9'), 'outside the advisory range')
assert.equal(checkRange(ADVISORY, '1.4.0-rc.1'), 'cannot compare this version')
})
test('a transitive copy is found with its path through the direct dependency', () => {
const sbom = readSbom(buildCycloneDx('1.4.0'))
const copies = findCopies(ADVISORY, sbom)
assert.equal(copies.length, 1)
assert.deepEqual(copies[0].paths, [['sbomlab-invented-bookings@1.0.0', '@sbomlab-invented/booking-forms@2.1.0', '@sbomlab-invented/date-parse@1.4.0']])
})
test('a copy reached two ways gets two paths', () => {
const document = buildCycloneDx('1.4.0', ['@sbomlab-invented/booking-forms@2.1.0', '@sbomlab-invented/date-parse@1.4.0'])
const copies = findCopies(ADVISORY, readSbom(document))
assert.equal(copies[0].paths.length, 2)
})
test('a cycle in the dependency list does not loop', () => {
const document = buildCycloneDx('1.4.0')
document.dependencies[2].dependsOn = ['@sbomlab-invented/booking-forms@2.1.0']
assert.equal(findPaths(readSbom(document), '@sbomlab-invented/date-parse@1.4.0').length, 1)
})
test('the match uses the package URL, so a different name field does not hide a copy', () => {
const document = buildCycloneDx('1.4.0')
document.components[1].name = 'a-folder-name'
assert.equal(findCopies(ADVISORY, readSbom(document)).length, 1)
})
test('SPDX DEPENDENCY_OF and DEPENDS_ON give the same path as CycloneDX', () => {
const packages = [
{ SPDXID: 'SPDXRef-app', name: 'app', versionInfo: '1.0.0', externalRefs: [{ referenceType: 'purl', referenceLocator: APP_PURL }] },
{ SPDXID: 'SPDXRef-forms', name: 'forms', versionInfo: '2.1.0', externalRefs: [{ referenceType: 'purl', referenceLocator: 'pkg:npm/%40sbomlab-invented/booking-forms@2.1.0' }] },
{ SPDXID: 'SPDXRef-dates', name: 'dates', versionInfo: '1.4.0', externalRefs: [{ referenceType: 'purl', referenceLocator: 'pkg:npm/%40sbomlab-invented/date-parse@1.4.0' }] },
]
const document = {
spdxVersion: 'SPDX-2.3',
documentDescribes: ['SPDXRef-app'],
packages: packages,
relationships: [
{ spdxElementId: 'SPDXRef-DOCUMENT', relatedSpdxElement: 'SPDXRef-app', relationshipType: 'DESCRIBES' },
{ spdxElementId: 'SPDXRef-forms', relatedSpdxElement: 'SPDXRef-app', relationshipType: 'DEPENDENCY_OF' },
{ spdxElementId: 'SPDXRef-forms', relatedSpdxElement: 'SPDXRef-dates', relationshipType: 'DEPENDS_ON' },
{ spdxElementId: 'SPDXRef-dates', relatedSpdxElement: 'SPDXRef-forms', relationshipType: 'TEST_DEPENDENCY_OF' },
],
}
const sbom = readSbom(document)
const fromCycloneDx = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
assert.deepEqual(findCopies(ADVISORY, sbom)[0].paths, fromCycloneDx[0].paths)
assert.deepEqual(sbom.relationshipsNotFollowed, ['TEST_DEPENDENCY_OF'])
})
test('a package the SBOM does not list gives no copies and the coverage question', () => {
const document = buildCycloneDx('1.4.0')
document.components.pop()
const row = buildRow(ADVISORY, buildVex('under_investigation'), readSbom(document), 'test')
assert.equal(row.copies.length, 0)
assert.match(row.question, /cover everything in the build that is deployed/)
})
test('with no VEX statement, a version inside the range asks the three application questions', () => {
const row = buildRow(ADVISORY, { statements: [] }, readSbom(buildCycloneDx('1.4.0')), 'test')
assert.equal(row.agreement, 'no VEX statement for this release')
assert.match(row.question, /called in this application, can input from outside reach it, and is a mitigating setting on/)
})
test('when two statements name the same product, the later one in the document is used', () => {
const vex = buildVex('under_investigation')
vex.statements.push({ vulnerability: { name: ADVISORY.id }, products: [{ '@id': APP_PURL }], status: 'fixed' })
assert.equal(findVexStatement(vex, ADVISORY.id, APP_PURL).status, 'fixed')
assert.equal(findVexStatement(vex, ADVISORY.id, 'pkg:npm/another-product@1.0.0'), null)
})
test('fixed is a conflict while the SBOM still lists a version inside the range', () => {
const copies = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
assert.match(judgeAgreement(copies, buildVex('fixed').statements[0], APP_PURL), /^CONFLICT: the VEX statement says fixed/)
const updated = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.2')))
assert.equal(judgeAgreement(updated, buildVex('fixed').statements[0], APP_PURL), 'yes')
})
test('component_not_present is a conflict when the SBOM lists the package', () => {
const copies = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
const statement = buildVex('not_affected', { justification: 'component_not_present' }).statements[0]
assert.match(judgeAgreement(copies, statement, APP_PURL), /^CONFLICT: the justification is component_not_present/)
})
test('a statement that names another subcomponent version is a conflict', () => {
const copies = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
const statement = buildVex('affected', { action_statement: 'update' }).statements[0]
statement.products[0].subcomponents = [{ '@id': 'pkg:npm/%40sbomlab-invented/date-parse@1.3.0' }]
assert.match(judgeAgreement(copies, statement, APP_PURL), /names a subcomponent version the SBOM does not list/)
})
test('affected without an action statement, and not_affected without a reason, are incomplete', () => {
const copies = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
assert.match(judgeAgreement(copies, buildVex('affected').statements[0], APP_PURL), /^INCOMPLETE: an affected statement/)
assert.match(judgeAgreement(copies, buildVex('not_affected').statements[0], APP_PURL), /^INCOMPLETE: a not_affected statement/)
const withReason = buildVex('not_affected', { justification: 'vulnerable_code_not_in_execute_path' }).statements[0]
assert.equal(judgeAgreement(copies, withReason, APP_PURL), 'yes')
})
test('a not_affected statement still leaves a question about its evidence', () => {
const statement = buildVex('not_affected', { justification: 'vulnerable_code_not_in_execute_path' }).statements[0]
const copies = findCopies(ADVISORY, readSbom(buildCycloneDx('1.4.0')))
assert.match(chooseOpenQuestion(ADVISORY, copies, statement), /evidence behind the justification still hold/)
})
const savedSbomsExist = fs.existsSync('sboms/release-1.cdx.json')
const readSaved = (name) => readSbom(JSON.parse(fs.readFileSync('sboms/' + name, 'utf8')))
test('saved SBOMs: CycloneDX and SPDX of each release list the same copies and paths', { skip: !savedSbomsExist }, () => {
const advisory = JSON.parse(fs.readFileSync('advisory/INVENTED-SBOMLAB-0001.json', 'utf8'))
for (const release of ['release-1', 'release-2']) {
const fromCycloneDx = findCopies(advisory, readSaved(release + '.cdx.json'))
const fromSpdx = findCopies(advisory, readSaved(release + '.spdx.json'))
assert.equal(fromCycloneDx.length, 1)
assert.deepEqual(fromSpdx.map((copy) => [copy.version, copy.purl, copy.paths]), fromCycloneDx.map((copy) => [copy.version, copy.purl, copy.paths]))
}
})
test('saved SBOMs: release 1 is inside the advisory range and release 2 is outside', { skip: !savedSbomsExist }, () => {
const advisory = JSON.parse(fs.readFileSync('advisory/INVENTED-SBOMLAB-0001.json', 'utf8'))
assert.equal(findCopies(advisory, readSaved('release-1.cdx.json'))[0].rangeVerdict, 'inside the advisory range')
assert.equal(findCopies(advisory, readSaved('release-2.cdx.json'))[0].rangeVerdict, 'outside the advisory range')
})
test('saved SBOMs: the published VEX document agrees with both, and the careless one does not', { skip: !savedSbomsExist }, () => {
const advisory = JSON.parse(fs.readFileSync('advisory/INVENTED-SBOMLAB-0001.json', 'utf8'))
const published = JSON.parse(fs.readFileSync('vex/bookings.openvex.json', 'utf8'))
const careless = JSON.parse(fs.readFileSync('vex/careless.openvex.json', 'utf8'))
for (const release of ['release-1', 'release-2']) {
assert.equal(buildRow(advisory, published, readSaved(release + '.cdx.json'), release).agreement, 'yes')
}
assert.match(buildRow(advisory, careless, readSaved('release-1.cdx.json'), 'release-1').agreement, /^CONFLICT/)
})
==== RUN IT ====
node make-snapshots.mjs
node make-sboms.mjs
node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/bookings.openvex.json sboms/release-1.cdx.json sboms/release-2.cdx.json
node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/bookings.openvex.json sboms/release-1.spdx.json sboms/release-2.spdx.json
node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/careless.openvex.json sboms/release-1.cdx.json sboms/release-2.cdx.json
node --test triage.test.mjs
Each output below was copied from the captured run by a script. The "exit code" line at the end of each was added by the capture script. No line of these outputs showed a local file path, so none was cut for that reason. The SBOM files are shown in part, and each cut is marked where it was made, with the numbers of the lines that were cut.
==== OUTPUT OF node make-snapshots.mjs (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
snapshots written: release-1, release-2
local packages in each: booking-forms, date-parse, receipt-text
also written: advisory/INVENTED-SBOMLAB-0001.json, vex/bookings.openvex.json, vex/careless.openvex.json
exit code: 0
==== snapshots/release-1/package.json, as make-snapshots.mjs wrote it ====
{
"name": "sbomlab-invented-bookings",
"version": "1.0.0",
"private": true,
"description": "INVENTED FOR THIS PAGE. A stand-in booking application.",
"license": "UNLICENSED",
"type": "module",
"dependencies": {
"@sbomlab-invented/booking-forms": "file:packages/@sbomlab-invented/booking-forms",
"@sbomlab-invented/receipt-text": "file:packages/@sbomlab-invented/receipt-text"
}
}
==== advisory/INVENTED-SBOMLAB-0001.json (invented, this lab's own format) ====
{
"id": "INVENTED-SBOMLAB-0001",
"note": "INVENTED FOR THIS PAGE. This advisory describes no real package and no real flaw.",
"summary": "parseBookingDate in @sbomlab-invented/date-parse accepts date text of any length",
"package_purl": "pkg:npm/%40sbomlab-invented/date-parse",
"introduced": "1.2.0",
"first_fixed_version": "1.4.2",
"affected_function": "parseBookingDate"
}
==== vex/bookings.openvex.json (invented, OpenVEX field names) ====
{
"@context": "https://openvex.dev/ns/v0.2.0",
"@id": "https://vex.sbomlab-invented.example/bookings/2026-0001",
"author": "Sbomlab Invented Bookings (an invented organisation)",
"role": "vendor",
"timestamp": "2026-11-13T04:00:00Z",
"version": 2,
"statements": [
{
"vulnerability": {
"name": "INVENTED-SBOMLAB-0001",
"description": "INVENTED FOR THIS PAGE. This advisory describes no real package and no real flaw."
},
"products": [
{
"@id": "pkg:npm/sbomlab-invented-bookings@1.0.0",
"subcomponents": [
{
"@id": "pkg:npm/%40sbomlab-invented/date-parse@1.4.0"
}
]
}
],
"status": "affected",
"timestamp": "2026-11-11T01:30:00Z",
"action_statement": "Update to release 1.1.0 of sbomlab-invented-bookings, which carries date-parse 1.4.2."
},
{
"vulnerability": {
"name": "INVENTED-SBOMLAB-0001",
"description": "INVENTED FOR THIS PAGE. This advisory describes no real package and no real flaw."
},
"products": [
{
"@id": "pkg:npm/sbomlab-invented-bookings@1.1.0",
"subcomponents": [
{
"@id": "pkg:npm/%40sbomlab-invented/date-parse@1.4.2"
}
]
}
],
"status": "fixed"
}
]
}
vex/careless.openvex.json is the same document with a different @id and with its first statement changed: status fixed for release 1.0.0, and no action statement.
==== OUTPUT OF node make-sboms.mjs (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
(in snapshots/release-1) npm --version --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
Node.js v26.0.0, npm 11.12.1
(in snapshots/release-1) npm sbom --help --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
| Generate a Software Bill of Materials (SBOM)
| Usage:
| npm sbom
| Options:
| [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
| [--package-lock-only] [--sbom-format <cyclonedx|spdx>]
| [--sbom-type <library|application|framework>]
| [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
| [--workspaces]
(in snapshots/release-1) npm install --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
npm printed: added 3 packages in 128ms
(in snapshots/release-1) npm sbom --sbom-format cyclonedx --sbom-type application --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
saved sboms/release-1.cdx.json (117 lines)
(in snapshots/release-1) npm sbom --sbom-format spdx --sbom-type application --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
saved sboms/release-1.spdx.json (113 lines)
(in snapshots/release-2) npm install --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
npm printed: added 3 packages in 112ms
(in snapshots/release-2) npm sbom --sbom-format cyclonedx --sbom-type application --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
saved sboms/release-2.cdx.json (117 lines)
(in snapshots/release-2) npm sbom --sbom-format spdx --sbom-type application --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
saved sboms/release-2.spdx.json (113 lines)
(in snapshots/release-1) npm sbom --sbom-format cyclonedx --sbom-type application --package-lock-only --offline --no-audit --no-fund --no-update-notifier --ignore-scripts --registry http://127.0.0.1:49359/ --userconfig ../../npm-home/userconfig --globalconfig ../../npm-home/globalconfig --cache ../../npm-home/cache
saved sboms/release-1.lock-only.cdx.json (117 lines)
Lines that differ between release-1.cdx.json and release-1.lock-only.cdx.json:
line 5: "serialNumber": "urn:uuid:50ed21bd-ee80-481f-a000-d4c7dbfc9665", -> "serialNumber": "urn:uuid:22852626-29d2-43e3-a9ac-0ec2a7742996",
line 8: "timestamp": "2026-11-14T04:25:29.077Z", -> "timestamp": "2026-11-14T04:25:30.053Z",
line 11: "phase": "build" -> "phase": "pre-build"
Requests the listener saw while npm ran: 0
Requests the listener saw after the self-test request: 1 (GET /listener-self-test)
exit code: 0
==== sboms/release-1.cdx.json, as npm sbom wrote it: the document header, the date-parse component and the dependency list ====
{
"$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"serialNumber": "urn:uuid:50ed21bd-ee80-481f-a000-d4c7dbfc9665",
"version": 1,
"metadata": {
"timestamp": "2026-11-14T04:25:29.077Z",
"lifecycles": [
{
"phase": "build"
}
],
"tools": [
{
"vendor": "npm",
"name": "cli",
"version": "11.12.1"
}
],
"component": {
"bom-ref": "sbomlab-invented-bookings@1.0.0",
"type": "application",
"name": "release-1",
"version": "1.0.0",
"scope": "required",
"description": "INVENTED FOR THIS PAGE. A stand-in booking application.",
"purl": "pkg:npm/sbomlab-invented-bookings@1.0.0",
"properties": [
{
"name": "cdx:npm:package:private",
"value": "true"
}
],
"externalReferences": []
}
},
"components": [
(lines 39 to 56 of 117 cut)
{
"bom-ref": "@sbomlab-invented/date-parse@1.4.0",
"type": "library",
"name": "@sbomlab-invented/date-parse",
"version": "1.4.0",
"scope": "required",
"description": "INVENTED FOR THIS PAGE. A stand-in date parser.",
"purl": "pkg:npm/%40sbomlab-invented/date-parse@1.4.0",
"properties": [],
"externalReferences": [],
"licenses": [
{
"license": {
"id": "MIT"
}
}
]
},
(lines 75 to 92 of 117 cut)
],
"dependencies": [
{
"ref": "sbomlab-invented-bookings@1.0.0",
"dependsOn": [
"@sbomlab-invented/booking-forms@2.1.0",
"@sbomlab-invented/receipt-text@3.0.1"
]
},
{
"ref": "@sbomlab-invented/booking-forms@2.1.0",
"dependsOn": [
"@sbomlab-invented/date-parse@1.4.0"
]
},
{
"ref": "@sbomlab-invented/date-parse@1.4.0",
"dependsOn": []
},
{
"ref": "@sbomlab-invented/receipt-text@3.0.1",
"dependsOn": []
}
]
}
==== sboms/release-2.cdx.json, as npm sbom wrote it: the date-parse component ====
(lines 1 to 56 of 117 cut)
{
"bom-ref": "@sbomlab-invented/date-parse@1.4.2",
"type": "library",
"name": "@sbomlab-invented/date-parse",
"version": "1.4.2",
"scope": "required",
"description": "INVENTED FOR THIS PAGE. A stand-in date parser.",
"purl": "pkg:npm/%40sbomlab-invented/date-parse@1.4.2",
"properties": [],
"externalReferences": [],
"licenses": [
{
"license": {
"id": "MIT"
}
}
]
},
(lines 75 to 117 of 117 cut)
==== sboms/release-1.spdx.json, as npm sbom wrote it: the document header, the date-parse package and the relationships ====
{
"spdxVersion": "SPDX-2.3",
"dataLicense": "CC0-1.0",
"SPDXID": "SPDXRef-DOCUMENT",
"name": "sbomlab-invented-bookings@1.0.0",
"documentNamespace": "http://spdx.org/spdxdocs/sbomlab-invented-bookings-1.0.0-810c0262-d50b-413e-a2a1-51130cf9b3ca",
"creationInfo": {
"created": "2026-11-14T04:25:29.272Z",
"creators": [
"Tool: npm/cli-11.12.1"
]
},
"documentDescribes": [
"SPDXRef-Package-sbomlab-invented-bookings-1.0.0"
],
"packages": [
(lines 17 to 53 of 113 cut)
{
"name": "@sbomlab-invented/date-parse",
"SPDXID": "SPDXRef-Package-sbomlab-invented.date-parse-1.4.0",
"versionInfo": "1.4.0",
"packageFileName": "packages/@sbomlab-invented/date-parse",
"description": "INVENTED FOR THIS PAGE. A stand-in date parser.",
"downloadLocation": "NOASSERTION",
"filesAnalyzed": false,
"homepage": "NOASSERTION",
"licenseDeclared": "MIT",
"externalRefs": [
{
"referenceCategory": "PACKAGE-MANAGER",
"referenceType": "purl",
"referenceLocator": "pkg:npm/%40sbomlab-invented/date-parse@1.4.0"
}
]
},
(lines 72 to 89 of 113 cut)
],
"relationships": [
{
"spdxElementId": "SPDXRef-DOCUMENT",
"relatedSpdxElement": "SPDXRef-Package-sbomlab-invented-bookings-1.0.0",
"relationshipType": "DESCRIBES"
},
{
"spdxElementId": "SPDXRef-Package-sbomlab-invented.booking-forms-2.1.0",
"relatedSpdxElement": "SPDXRef-Package-sbomlab-invented-bookings-1.0.0",
"relationshipType": "DEPENDENCY_OF"
},
{
"spdxElementId": "SPDXRef-Package-sbomlab-invented.receipt-text-3.0.1",
"relatedSpdxElement": "SPDXRef-Package-sbomlab-invented-bookings-1.0.0",
"relationshipType": "DEPENDENCY_OF"
},
{
"spdxElementId": "SPDXRef-Package-sbomlab-invented.date-parse-1.4.0",
"relatedSpdxElement": "SPDXRef-Package-sbomlab-invented.booking-forms-2.1.0",
"relationshipType": "DEPENDENCY_OF"
}
]
}
==== sboms/release-2.spdx.json, as npm sbom wrote it: the date-parse package ====
(lines 1 to 53 of 113 cut)
{
"name": "@sbomlab-invented/date-parse",
"SPDXID": "SPDXRef-Package-sbomlab-invented.date-parse-1.4.2",
"versionInfo": "1.4.2",
"packageFileName": "packages/@sbomlab-invented/date-parse",
"description": "INVENTED FOR THIS PAGE. A stand-in date parser.",
"downloadLocation": "NOASSERTION",
"filesAnalyzed": false,
"homepage": "NOASSERTION",
"licenseDeclared": "MIT",
"externalRefs": [
{
"referenceCategory": "PACKAGE-MANAGER",
"referenceType": "purl",
"referenceLocator": "pkg:npm/%40sbomlab-invented/date-parse@1.4.2"
}
]
},
(lines 72 to 113 of 113 cut)
==== OUTPUT OF node triage.mjs with the CycloneDX SBOMs ====
Shown in full in Part B, section B1.
==== OUTPUT OF node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/bookings.openvex.json sboms/release-1.spdx.json sboms/release-2.spdx.json (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
SBOM AND VEX TRIAGE: INVENTED-SBOMLAB-0001
Advisory package: pkg:npm/%40sbomlab-invented/date-parse | introduced 1.2.0 | first fixed version 1.4.2
Function the advisory names: parseBookingDate
VEX document: https://vex.sbomlab-invented.example/bookings/2026-0001 | version 2 | author: Sbomlab Invented Bookings (an invented organisation)
ROW 1: sbomlab-invented-bookings 1.0.0 (pkg:npm/sbomlab-invented-bookings@1.0.0)
SBOM read: sboms/release-1.spdx.json | SPDX-2.3 | generation context: not stated | tool: Tool: npm/cli-11.12.1
SBOM document: http://spdx.org/spdxdocs/sbomlab-invented-bookings-1.0.0-810c0262-d50b-413e-a2a1-51130cf9b3ca | timestamp 2026-11-14T04:25:29.272Z
Name field of the application in this SBOM: sbomlab-invented-bookings
Package listed: yes (1 copy)
Copy 1: version 1.4.0 (inside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.0
dependency path: sbomlab-invented-bookings@1.0.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.0
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: affected
VEX justification: none (only a not_affected statement carries one)
VEX action statement: Update to release 1.1.0 of sbomlab-invented-bookings, which carries date-parse 1.4.2.
SBOM and VEX agree: yes
Still needs application analysis: The author says affected. Where is this release still deployed, and can a visitor reach the feature that calls parseBookingDate there?
ROW 2: sbomlab-invented-bookings 1.1.0 (pkg:npm/sbomlab-invented-bookings@1.1.0)
SBOM read: sboms/release-2.spdx.json | SPDX-2.3 | generation context: not stated | tool: Tool: npm/cli-11.12.1
SBOM document: http://spdx.org/spdxdocs/sbomlab-invented-bookings-1.1.0-6ef3b181-be52-47d0-bd88-001422ae3c5d | timestamp 2026-11-14T04:25:29.850Z
Name field of the application in this SBOM: sbomlab-invented-bookings
Package listed: yes (1 copy)
Copy 1: version 1.4.2 (outside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.2
dependency path: sbomlab-invented-bookings@1.1.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.2
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: fixed
VEX justification: none (only a not_affected statement carries one)
SBOM and VEX agree: yes
Still needs application analysis: Is this the build that is deployed, and does a test with the reported input pass against it?
TRIAGE TABLE
release | package | version | dependency path | VEX status | justification | still needs application analysis
1.0.0 | present | 1.4.0 | via @sbomlab-invented/booking-forms@2.1.0 | affected | none | The author says affected. Where is this release still deployed, and can a visitor reach the feature that calls parseBookingDate there?
1.1.0 | present | 1.4.2 | via @sbomlab-invented/booking-forms@2.1.0 | fixed | none | Is this the build that is deployed, and does a test with the reported input pass against it?
CHANGE FROM sboms/release-1.spdx.json TO sboms/release-2.spdx.json
application: 1.0.0 -> 1.1.0
unchanged: @sbomlab-invented/booking-forms 2.1.0
changed: @sbomlab-invented/date-parse 1.4.0 -> 1.4.2
unchanged: @sbomlab-invented/receipt-text 3.0.1
Result: no conflict between the SBOMs and the VEX document
exit code: 0
==== OUTPUT OF node triage.mjs advisory/INVENTED-SBOMLAB-0001.json vex/careless.openvex.json sboms/release-1.cdx.json sboms/release-2.cdx.json (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
SBOM AND VEX TRIAGE: INVENTED-SBOMLAB-0001
Advisory package: pkg:npm/%40sbomlab-invented/date-parse | introduced 1.2.0 | first fixed version 1.4.2
Function the advisory names: parseBookingDate
VEX document: https://vex.sbomlab-invented.example/bookings/2026-0001-careless | version 2 | author: Sbomlab Invented Bookings (an invented organisation)
ROW 1: sbomlab-invented-bookings 1.0.0 (pkg:npm/sbomlab-invented-bookings@1.0.0)
SBOM read: sboms/release-1.cdx.json | CycloneDX 1.5 | generation context: build | tool: npm cli 11.12.1
SBOM document: urn:uuid:50ed21bd-ee80-481f-a000-d4c7dbfc9665 | timestamp 2026-11-14T04:25:29.077Z
Name field of the application in this SBOM: release-1
Package listed: yes (1 copy)
Copy 1: version 1.4.0 (inside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.0
dependency path: sbomlab-invented-bookings@1.0.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.0
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: fixed
VEX justification: none (only a not_affected statement carries one)
SBOM and VEX agree: CONFLICT: the VEX statement says fixed, but the SBOM lists a version inside the advisory range
Still needs application analysis: Is parseBookingDate called in this application, can input from outside reach it, and is a mitigating setting on?
ROW 2: sbomlab-invented-bookings 1.1.0 (pkg:npm/sbomlab-invented-bookings@1.1.0)
SBOM read: sboms/release-2.cdx.json | CycloneDX 1.5 | generation context: build | tool: npm cli 11.12.1
SBOM document: urn:uuid:bd20ba43-3d08-41af-8b45-82776ed147c3 | timestamp 2026-11-14T04:25:29.657Z
Name field of the application in this SBOM: release-2
Package listed: yes (1 copy)
Copy 1: version 1.4.2 (outside the advisory range)
name field: @sbomlab-invented/date-parse | package URL: pkg:npm/%40sbomlab-invented/date-parse@1.4.2
dependency path: sbomlab-invented-bookings@1.1.0 > @sbomlab-invented/booking-forms@2.1.0 > @sbomlab-invented/date-parse@1.4.2
brought in by: @sbomlab-invented/booking-forms@2.1.0 (the direct dependency on this path)
VEX status: fixed
VEX justification: none (only a not_affected statement carries one)
SBOM and VEX agree: yes
Still needs application analysis: Is this the build that is deployed, and does a test with the reported input pass against it?
TRIAGE TABLE
release | package | version | dependency path | VEX status | justification | still needs application analysis
1.0.0 | present | 1.4.0 | via @sbomlab-invented/booking-forms@2.1.0 | fixed | none | Is parseBookingDate called in this application, can input from outside reach it, and is a mitigating setting on?
1.1.0 | present | 1.4.2 | via @sbomlab-invented/booking-forms@2.1.0 | fixed | none | Is this the build that is deployed, and does a test with the reported input pass against it?
CHANGE FROM sboms/release-1.cdx.json TO sboms/release-2.cdx.json
application: 1.0.0 -> 1.1.0
unchanged: @sbomlab-invented/booking-forms 2.1.0
changed: @sbomlab-invented/date-parse 1.4.0 -> 1.4.2
unchanged: @sbomlab-invented/receipt-text 3.0.1
Result: 1 row(s) with a conflict or an incomplete statement
exit code: 1
==== OUTPUT OF node --test triage.test.mjs (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
✔ splitPurl separates the version and keeps the scope percent-encoded (1.27325ms)
✔ compareVersions orders by number, not by text (0.119834ms)
✔ checkRange: introduced is inside, the first fixed version is outside (0.077542ms)
✔ a transitive copy is found with its path through the direct dependency (0.527084ms)
✔ a copy reached two ways gets two paths (0.085292ms)
✔ a cycle in the dependency list does not loop (0.063125ms)
✔ the match uses the package URL, so a different name field does not hide a copy (0.087375ms)
✔ SPDX DEPENDENCY_OF and DEPENDS_ON give the same path as CycloneDX (0.178042ms)
✔ a package the SBOM does not list gives no copies and the coverage question (0.199416ms)
✔ with no VEX statement, a version inside the range asks the three application questions (0.114167ms)
✔ when two statements name the same product, the later one in the document is used (0.059792ms)
✔ fixed is a conflict while the SBOM still lists a version inside the range (0.088ms)
✔ component_not_present is a conflict when the SBOM lists the package (0.068166ms)
✔ a statement that names another subcomponent version is a conflict (0.07175ms)
✔ affected without an action statement, and not_affected without a reason, are incomplete (0.084334ms)
✔ a not_affected statement still leaves a question about its evidence (0.058666ms)
✔ saved SBOMs: CycloneDX and SPDX of each release list the same copies and paths (0.364209ms)
✔ saved SBOMs: release 1 is inside the advisory range and release 2 is outside (0.112792ms)
✔ saved SBOMs: the published VEX document agrees with both, and the careless one does not (0.225167ms)
ℹ tests 19
ℹ suites 0
ℹ pass 19
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 86.0595
exit code: 0
==== READING THE OUTPUT ====
The format versions. npm 11.12.1 wrote CycloneDX with specVersion 1.5 and SPDX with spdxVersion SPDX-2.3. The full CycloneDX documents were 117 lines each and the full SPDX documents 113 lines each.
The application's name. In the CycloneDX files the application's name field is the folder npm ran in, release-1 or release-2, and the package name sbomlab-invented-bookings appears in the bom-ref and the package URL. In the SPDX files the name field is sbomlab-invented-bookings. The triage script identifies the release by its package URL, so both formats give the same product name and version in each ROW line.
The component. The date-parse entry has the same package URL in both formats. The CycloneDX entry has an empty properties list, an empty externalReferences list and no hashes. The SPDX entry gives downloadLocation as NOASSERTION.
The dependency direction. The CycloneDX dependency list says booking-forms depends on date-parse. The SPDX relationships say the same thing the other way round: date-parse is DEPENDENCY_OF booking-forms. The example in npm's documentation for version 11 shows DEPENDS_ON instead. sbom-readers.mjs reads both, and both triage runs print the same dependency path and the same triage table.
The generation context. The SBOM built from the installed tree has the lifecycle phase build. The one built with --package-lock-only has pre-build, and the script's comparison found three differing lines between the two: the serial number, the timestamp and the phase.
The careless VEX document. With a statement that calls release 1.0.0 fixed, the script prints a CONFLICT for ROW 1, because the SBOM for that release lists 1.4.0, inside the advisory's range, and it exits with code 1.
==== WHAT WAS NOT TESTED ====
The lab ran on macOS only, with npm 11.12.1 only. It did not run npm 12. Its packages are local folders linked by npm install, so the SBOMs show no registry package: no hash, no download address and no provenance. It did not test workspaces, the omit option, development, optional or peer dependencies, aliases or git dependencies. The SBOMs were not validated against the CycloneDX or SPDX schemas, the VEX document was not checked against the OpenVEX schema, and nothing was signed. The scripts were not tried on CycloneDX 1.7 or SPDX 3 documents, or on SBOMs from any other generator. The application's own code was never run.
==== USING IT ON YOUR OWN PROJECT ====
1. In your pipeline, after the clean install that builds the release, run npm sbom with the format your recipient asks for, and save the output under the release's version. The settings make-sboms.mjs passes are there to keep this lab offline. The lab did not run npm under any other configuration, so it cannot say what npm contacts under yours.
2. Keep one SBOM for every release, not only the latest.
3. When an advisory arrives, write its package as a package URL without a version, its range and the function it names into a file like the lab's advisory file, and run triage.mjs against the SBOM of every release that is still deployed.
4. Give each "Still needs application analysis" line to someone who can read the code. Record their answer as a statement in your VEX document and run the script again. Exit code 1 means the SBOM and the VEX document disagree, or a statement is incomplete.
5. Fill one record from Part A for each release, and keep it with the SBOM, the VEX document and the notes from the analysis.What an SBOM is
A software bill of materials (SBOM) is an inventory of what a piece of software is made of.
The 2021 report from the United States Department of Commerce and NTIA, The Minimum Elements For a Software Bill of Materials (SBOM), defines it as a formal record containing the details and supply chain relationships of various components used in building software.
The 2026 joint guidance that replaced that report, written by CISA with 17 partner organisations, describes an SBOM as a nested inventory, a list of ingredients that make up software applications and systems.
For a web application, the components are the packages the build installs: the framework, the libraries your developers chose, and the libraries those brought with them. Your lockfile already holds a version of that list. An SBOM puts it into a format that someone outside the team, or a tool that has never seen your repository, can read: an entry for each component with a name, a version and an identifier, and a record of which component depends on which.
NTIA's report says an SBOM provides those who produce, purchase and operate software with information that enhances their understanding of the supply chain, most notably the potential to track known and newly emerged vulnerabilities and risks. It adds that SBOM will not solve all software security problems. Both halves matter, and this guide spends as long on the second as on the first.
This page covers the inventory itself. How a compromised package or build step reaches a site belongs to the supply chain attacks guide, and finding and updating vulnerable packages belongs to the dependency security guide. The CI/CD security guide covers the pipeline that should produce the SBOM, the SAST guide covers analysing your own source code for flaws, and the planned Node.js security guide covers the runtime.
Who asks for an SBOM
A request for an SBOM can come from a customer's procurement or security team, from a standard that customer works to, or from your own engineers after an incident.
CISA's Secure by Demand guide, written for organisations that buy software, asks whether the manufacturer generates an SBOM in a standard, machine-readable format and makes it available to customers, and whether the SBOM enumerates all third-party dependencies, including open source software components. The vendor security questionnaire template on this site carries a version of that question.
Two OWASP documents ask for the inventory. ASVS 5.0 requirement 15.1.2, at Level 2, is that an inventory catalogue, such as a software bill of materials, is maintained of all third-party libraries in use, including verifying that components come from pre-defined, trusted and continually maintained repositories. OWASP Top 10:2025 lists centrally generating and managing an SBOM among its prevention measures for A03 Software Supply Chain Failures.
One government instrument explains where the minimum elements in the next section came from. Executive Order 14028 of 12 May 2021, as published in the United States Federal Register, says in section 4(e) that the Secretary of Commerce, acting through the Director of NIST, shall issue guidance identifying practices that enhance the security of the software supply chain, and that the guidance shall include standards, procedures or criteria regarding providing a purchaser a Software Bill of Materials (SBOM) for each product directly or by publishing it on a public website.
Section 4(f) says the Secretary of Commerce, in coordination with the Assistant Secretary for Communications and Information and the Administrator of NTIA, shall publish minimum elements for an SBOM within 60 days.
Section 4(k) says the Director of OMB shall take appropriate steps to require that agencies comply with the section 4(e) guidance with respect to software procured after the date of the order.
Those clauses are addressed to United States federal officials. This page quotes the 2021 text as published and says nothing about what is in force today.
The 2026 joint guidance frames the request in general terms. Its key actions are that organisations should request SBOMs that satisfy the updated minimum elements, should use available tools to generate, ingest and analyse SBOM data, and should generate SBOMs that satisfy them.
It also says the minimum elements do not create new requirements, and that the publication does not constitute advice for compliance, regulatory or legal purposes. This page does not say whether any of these documents applies to your business.
What an SBOM lists: the minimum elements
Two documents define the baseline, and the second replaces the first.
NTIA's report of 12 July 2021 set out minimum elements in three areas: Data Fields, Automation Support, and Practices and Processes. Its seven data fields are Supplier Name, Component Name, Version of the Component, Other Unique Identifiers, Dependency Relationship, Author of SBOM Data and Timestamp. Under Automation Support it named SPDX, CycloneDX and SWID tags as the data formats being used to generate and consume SBOMs.
Its practices and processes are Frequency, Depth, Known Unknowns, Distribution and Delivery, Access Control, and Accommodation of Mistakes. Its scope section says the minimum elements should not be interpreted to create new federal requirements.
The replacement is 2026 Minimum Elements for a Software Bill of Materials (SBOM), published on 29 July 2026, which says it updates and replaces the NTIA publication. Its version history lists three versions: 1.0, the initial version of 12 July 2021; 2.0, a draft document published on 22 August 2025; and 2.1, of 29 July 2026, updated in collaboration with co-authoring organisations and based on comments received in response to a request for comment on a draft.
The authors are CISA and 17 partners, among them the United States NSA and FBI and the Australian Signals Directorate's Australian Cyber Security Centre.
The 2026 document sets baseline expectations in two groups: Data Fields, the data that makes up the SBOM document, and Practices and Processes, how an entity engages with and documents the SBOM data. The data fields come in two sets.
- SBOM Metadata, nine fields about the SBOM document itself: SBOM Author, SBOM Author Signature, SBOM Data Format Name, SBOM Data Format Version, SBOM Generation Context, SBOM Timestamp, SBOM Tool Name, SBOM Tool Version and SBOM Version.
- Component Data, eight fields about the target component, meaning the software the SBOM is generated for, and every subcomponent it lists: Component Producer, Component Dependency Relationship, Component Hash Value, Component Hash Algorithm, Component Identifiers, Component License, Component Name and Component Version.
- Practices and Processes, six elements: Accommodation of Updates to SBOM Data, Coverage, Distribution and Delivery, Explicitly Identifying Unknown Information, Frequency and Machine-Processable Data.
What changed from 2021
Four of the changes bear on a small team, in this page's judgement. Component Producer replaces Supplier Name, which the document says has proven ambiguous in practice, particularly around distributors of software. Coverage replaces Depth: an SBOM should include information for all components that make up the target software, including transitive dependencies, with no minimum depth, where the 2021 minimum was the top-level dependencies with enough detail to seek out the transitive dependencies recursively.
SWID tags are no longer on the list of data formats.
And where information for a data field is not provided, the author is asked to state explicitly whether it is unknown to them or is being withheld.
What an SBOM leaves out
An SBOM is an inventory, and both documents are plain about that.
The 2026 guidance says an SBOM alone is data about software components, and that analysis of SBOMs transforms data into insights about associated risks. NTIA's report says SBOM data is primarily static, reflecting the properties of the specific built software at a point in time, while vulnerability data is dynamic and evolves over time, and it recommends that vulnerability data be tracked in separate data structures from the SBOM.
Read against a web application, that leaves several things outside the document. These are this page's own observations, not a list from either source:
- Flaws in the code your team wrote. An SBOM names components. It does not examine how your own code uses them.
- Whether a listed component's vulnerable function is called, and whether input from outside can reach it.
- Configuration: which features are switched on, what the server sends, and who may call which route.
- Anything that is not a declared dependency. npm's documentation for CLI version 11 describes npm sbom as listing the dependencies for the current project. Code pasted into the repository, or a script the browser loads from another server, is not one of those.
- The services the application runs on and calls: the host, the database and third-party APIs. The SBOMs npm wrote in this page's lab list packages only.
CycloneDX and SPDX: the two formats
The 2026 guidance names two data formats as currently widely used by software ecosystem stakeholders to generate and consume SBOMs: SPDX and CycloneDX.
It says organisations should accept any widely used, interoperable and machine-processable SBOM format, and should avoid accepting SBOMs for new software generated in deprecated versions of any format.
CycloneDX is developed by the OWASP Foundation and Ecma International. Its specification overview gives the current version as 1.7, released on 2025-10-21, and lists its standard as ECMA-424, published on 2025-12-10, under technical committee TC54.
The overview says the BOM metadata includes the target component the BOM describes, and that components describe the complete inventory of first-party and third-party components. The CycloneDX 1.7 reference has that inventory as a components list. It says a component requires a type and a name, and can carry a version, a package URL and a bom-ref, an identifier that must be unique within the BOM.
In the same reference a separate dependencies list holds the graph: each entry references one component by its bom-ref and lists the bom-refs of its direct dependencies.
The 1.7 reference also has a vulnerabilities section, in which an analysis records an assessment of the impact and exploitability of a vulnerability, and a compositions section that describes how complete the listing is.
SPDX's specifications page calls the SPDX specification an international open standard, ISO/IEC 5962:2021, and lists 3.0 as the current version. The specification text is more exact about which version the ISO number covers. The conformance clause of SPDX 2.3.1 says version 2.3 followed ISO/IEC 5962:2021, SPDX Specification V2.2.1, and added new fields, that 2.3.1 is a maintenance release of 2.3 that does not add new fields, and that the latest edition is version 3.0.1, dated December 2024.
So the ISO number refers to version 2.2.1. The SPDX documents npm wrote in the lab declare SPDX-2.3.
In those documents, every package is an entry in one packages list, the application included. By the 2.3.1 specification, a package has a mandatory name and a required SPDX identifier, an optional version, a download location that may be NOASSERTION, and external references, each with a category such as PACKAGE-MANAGER.
Dependencies are relationships between two identifiers, and the direction matters: DEPENDS_ON is used when A depends on B, and DEPENDENCY_OF when A is a dependency of B. SPDX 3.0.1 defines nine profiles, of which Core is mandatory and the others, among them Software and Security, are optional.
For a small team the choice is less about the formats than about who will read the file. These points are this page's advice, drawn from the lab:
- Ask the customer or tool that will read the SBOM which format and version it accepts, and produce that. The lab's two formats came from the same installed tree with one option changed.
- Check the version written inside the file. npm 11.12.1 wrote CycloneDX with specVersion 1.5 and SPDX with SPDX-2.3 in the lab, the versions the examples in npm's documentation for CLI version 11 show. CycloneDX's overview gives 1.7 as its current version, and the SPDX specification gives 3.0.1 as its latest edition. Whether a recipient accepts the versions npm writes is for the recipient to say.
- The same fact can sit in different places. In the lab's CycloneDX files the application's name field holds the folder npm ran in, and its package name appears in the bom-ref and the package URL. In the SPDX files the name field holds the package name.
- Dependency direction differs. The CycloneDX files list what each component depends on. The SPDX files npm wrote use DEPENDENCY_OF, which points from the dependency to its dependent, although the example in npm's documentation for CLI version 11 shows DEPENDS_ON. The lab's script reads both, and one of its regression tests fails if the direction is misread.
Producing an SBOM at each release
For a Node.js project, npm has a command for the job. npm's documentation for CLI version 11 describes npm sbom as generating a Software Bill of Materials listing the dependencies for the current project, in either SPDX or CycloneDX format, with the options omit, package-lock-only, sbom-format, sbom-type, workspace and workspaces. sbom-format takes cyclonedx or spdx, with a documented default of null, and sbom-type is the type of package the generated SBOM describes: library by default, or application or framework.
The documentation page read for this guide covers version 11.21.2, which it marks as Legacy. The lab ran npm 11.12.1, whose own help text lists the same six options.
When to generate one is the Frequency element. The 2026 guidance says each software version or update should have an associated SBOM, and that when a component producer issues a new build or release, they or the SBOM author should also generate a new SBOM to reflect the changes.
For a web application deployed from a pipeline, this page reads that as one SBOM for each release you deploy, stored under that release's version.
Where it is generated matters as much. NTIA's report says that, while there are many unique circumstances, those requesting SBOM data should try to obtain it from the instance of the build, since the instance of the build captures the details of the software as built, including any changes made by the compiler or other tools.
The 2026 guidance adds a field for this, SBOM Generation Context: the relative software lifecycle phase and data available at the time the SBOM was generated, for which references such as before build, build and after build are enough. The CycloneDX 1.7 reference says lifecycles communicate the stage or stages in which data in the BOM was captured: its pre-build phase is a BOM consisting of information obtained prior to a build process, and its build phase is one consisting of information obtained during a build process where component inventory is available for use.
The lab shows the field at work. Run against the installed tree, npm sbom wrote the phase build. Run again with package-lock-only, which npm's documentation for CLI version 11 says loads only the information in the package lock, it wrote pre-build, and that line, the serial number and the timestamp were the only three lines that differed between the two files.
This page's advice follows from both sources: generate the SBOM in the pipeline, from the same clean install that produced the release, and not on a developer's machine. npm ci is the install that npm's documentation, read at CLI version 12, says is meant for automated environments such as continuous integration and deployment.
It needs an existing lockfile, and exits with an error instead of updating the lockfile when its dependencies do not match those in package.json. The lab adds a reason of its own: npm wrote the name of the folder it ran in into the application's name field, release-1 in one SBOM and release-2 in the other, for an application whose package name is the same in both.
Where to keep it
Keep each SBOM with the release it describes. The 2026 guidance says SBOMs should be available promptly to those who need them, and gives examples of how: an SBOM can accompany installation, or be accessible through a version-specific URL, an API to a database, or a public repository.
Executive Order 14028's definition says SBOMs gain greater value when collectively stored in a repository that can be easily queried by other applications and systems.
For a small team, this page's advice is modest. Store the file beside the release artefact, named by release version and commit, and keep every release's file, not only the latest, because the question an advisory raises is which releases contained the component. Decide who may read it, since an SBOM tells its reader exactly which versions you run.
If it goes to customers, the guidance has a field for signing it: SBOM Author Signature, a digital signature attributable to the SBOM author, which it says provides assurance that the information was not modified after signature generation.
Component identity: one package, several names
Matching an advisory to an SBOM depends on both documents naming the same thing the same way, and that is the hard part of the whole exercise.
NTIA's report says the challenges created by the lack of a single, well-understood and widely used name space for software are well documented. The 2026 guidance says there is not yet a universal solution to the problem of software identification, though there has been progress, and asks for at least one software identifier for a component, using common identifiers such as Common Platform Enumeration (CPE) and Package-URL (PURL).
A package URL, or purl, is the identifier npm wrote for every component in the lab. The README of the Package-URL project's purl-spec repository describes a purl as a URL composed of seven components: scheme:type/namespace/name@version?qualifiers#subpath. In the README's component table, the scheme is the constant pkg.
The type is the package type or protocol, such as npm, maven or pypi. The namespace is optional and type-specific, the name is required, and the version, qualifiers and subpath are optional. The README says the components form a hierarchy from the most significant on the left to the least significant on the right.
Its examples include pkg:pypi/django@1.11.1 and pkg:npm/%40angular/animation@12.3.1. It says PURL is an Ecma standard, ECMA-427, and that the core PURL syntax is defined in the Package-URL Specification, ECMA-427.
The second example shows a detail worth knowing before you search an SBOM as text. In the npm type, the namespace is used for the scope of a scoped package, and the type definition says the scope's @ sign is always percent encoded. So the package that package.json calls @sbomlab-invented/date-parse appears in the lab's SBOMs as pkg:npm/%40sbomlab-invented/date-parse@1.4.0.
The lab's two SBOMs for one release name that one package four ways: the name field (@sbomlab-invented/date-parse), the CycloneDX bom-ref (@sbomlab-invented/date-parse@1.4.0), the SPDX identifier (SPDXRef-Package-sbomlab-invented.date-parse-1.4.0) and the purl. The lab's script matches on the purl with the version removed, and one of its regression tests changes a component's name field to confirm the match still holds.
What a dependency path tells you
An SBOM that listed components without relationships could say a package is present.
One that carries the dependency graph can also say why. The 2026 guidance defines Component Dependency Relationship as the relationship between two components, where one component is necessary for the operation of the other, and says the information supports the capability to build a dependency graph.
Both formats have a rule about silence in that graph. The CycloneDX 1.7 reference says a component that has no dependencies of its own must be declared as an empty element within the graph, and that a component not represented in the graph may have unknown dependencies.
In SPDX 2.3.1, NONE on the right hand side of a relationship indicates that an element has no other elements connected by that relationship, and NOASSERTION that the author is not asserting whether there are any.
The path is what turns a match into a task. In the lab, the package the invented advisory names is not in the application's package.json. The graph shows it arriving through one direct dependency, a form helper, so the fix is first a question about that dependency, and the form helper is the first code to read when asking whether the affected function is called.
The dependency security guide covers the npm commands that print the same chain from an installed tree, and the routes for updating a package several levels down.
SBOM vulnerability management: matching an advisory to an SBOM
The 2026 guidance describes the use directly: after learning new vulnerability information, an organisation can assess whether its SBOMs contain or reference a vulnerable component.
Under Coverage it gives the reverse case as an example: the recipient of an SBOM should be able to conclude that a newly reported vulnerability does not affect them if the SBOM does not list the component associated with the vulnerability. That conclusion leans on the SBOM being complete, which is this page's reading of why Coverage asks for all components, transitive dependencies included.
An advisory supplies the other half of the match. The OSV schema, for one, describes affected versions as a timeline of events, among them the version that introduces a vulnerability and the version that fixes it. Matching is then four checks, and the order is this page's advice:
- Identity. Write the advisory's package as a purl without a version, and look for components whose purl, with its version removed, is the same. Do not search on the name field alone.
- Version. Compare each listed version with the advisory's range, taken from its version fields. A version the comparison cannot parse is unknown, not clear.
- Every copy. The 2026 guidance says multiple instances of a component with differences in metadata should each be listed separately. On this page's reading, that means one package can appear more than once.
- Every release still running. Run the check against the SBOM of each release that is deployed anywhere, not only the newest.
A match is a question, not a finding
NTIA's report says not all vulnerabilities in components create risks in the software that depends on them, and that focusing on upstream vulnerable components that have been deemed not to have an impact on the downstream software will waste time and resources. Someone has to do the deeming. A way to record their answer is what VEX provides.
What a VEX statement adds
VEX stands for Vulnerability Exploitability eXchange.
CISA's Minimum Requirements for VEX, published in April 2023, says VEX indicates the status of a software product or component with respect to a vulnerability. A VEX statement conveys a single status for a single vulnerability and one or more products. The document allows four status values, some with further requirements:
- not_affected: no remediation or mitigation is required, and the vulnerability does not affect the listed products. The statement should provide a justification, and must provide an impact statement explaining how or why if it does not.
- affected: actions are recommended by the author to remediate, mitigate or otherwise address the vulnerability. The statement must include an action statement, which should describe actions to remediate or mitigate it.
- fixed: the listed products contain fixes for the vulnerability.
- under_investigation: the author or other relevant parties are investigating and have not yet declared a final status. The document expects this status to change once the investigation has reached a conclusion.
Justifications, and who may issue a statement
A justification is one of five values: Component_not_present, Vulnerable_code_not_present, Vulnerable_code_not_in_execute_path, Vulnerable_code_cannot_be_controlled_by_adversary and Inline_mitigations_already_exist. The document describes the first as the vulnerable subcomponent not being included in the product. On this page's reading, that is the one of the five an SBOM can support directly.
The other four are statements about code and behaviour. The dependency security guide works through a not_affected decision for a function the code does not call, with the evidence such a record needs.
On who may issue one, the document says VEX documents can be authored by the supplier of the software or by a third party. A VEX document must identify its author, the author must be an individual or organisation, and the author is responsible for the content of the document.
It also says VEX does not specify, assume or imply any default status that is not explicitly provided in VEX statements. This page reads that plainly: a release nobody has made a statement about has no status, which is different from not_affected. The document says it does not represent official CISA policy and does not impose or mandate compliance.
Formats, and why their status names should not be mixed
CISA's document says that, as of its writing, CSAF, CycloneDX and OpenVEX can contain or be used to generate VEX documents. The lab's VEX document uses OpenVEX field names. The OpenVEX specification, version 0.2.0, uses the same four status labels, requires @context, @id, author, timestamp, version and statements at document level, lets a product's @id take a purl as its value, and gives a product a subcomponents list, which it says will most often be one or more of the product's dependencies.
It also allows an identifier of your own for the vulnerability: for internal identifying schemes, its only requirement is that the vulnerability has an ID string to address it.
CycloneDX records the same kind of judgement under different names. In version 1.7, a vulnerability's analysis state is one of resolved, resolved_with_pedigree, exploitable, in_triage, false_positive and not_affected, and its justifications are a different list, among them code_not_present and code_not_reachable, whose description is that the vulnerable code is not invoked at runtime.
Only not_affected is spelt the same in both vocabularies. This page's advice is that a record should say which format it is written in and use that format's own values.
Where SBOM data helps triage, and where it stops
Put the pieces together and an advisory raises eight questions.
This split is the page's own. An SBOM kept for each release, with a VEX document beside it, answers five of them from documents alone:
- Is the component present? The SBOM lists it or does not.
- Which version? The component entry says, and the advisory's range says whether that version is covered.
- By which dependency path? The graph names the direct dependency that brings it in.
- In which releases? One SBOM for each release answers for each.
- Has its supplier said the product is affected? A VEX statement records a status, and who made the call.
The three questions no inventory answers
Three questions remain, and they need someone to analyse the application:
- Is the vulnerable function called? The advisory may name it. Whether your code, or the dependency between your code and it, calls that function is a fact about code.
- Can data an outsider controls reach it? A function called only with values your own code builds is a different exposure from one fed a form field.
- Is a mitigating setting on? A feature switch, a parser option or a limit in front of the function can change the answer, and none of them is in the SBOM.
What each document is evidence of
NTIA's report says the supplier must make some reliable determination that a vulnerability does not affect a specific piece of software, and that this could be for a range of reasons: the compiler might remove the affected code from the component, the vulnerability may not be reachable in the execution path, in-line protections exist, or, in its words, a host of other reasons.
Reading those as reasons of the same kind as the three questions above is this page's own comparison, not NTIA's.
The OpenVEX specification is candid about two of the justifications. Of vulnerable_code_cannot_be_controlled_by_adversary and of inline_mitigations_already_exist it says the justification could be difficult to prove conclusively.
So read each document for what it is. An SBOM with no matches means no published advisory has been matched to a listed component on the day you checked. It says nothing about flaws in your own code, or in components nobody has reported on.
A fixed status means the author says the release contains the fix. A not_affected status is a claim with an author and a date, and with evidence if it was done well.
None of the three is a statement that an application has no vulnerabilities, and this page does not treat any of them as one.
The worked record on this page follows one component through that sequence: listed in release 1.0.0 inside the advisory's range, reached through one direct dependency, analysed and declared affected, then updated in release 1.1.0 and declared fixed. Its last line for each release is the question the documents leave open.
What to do with a match
When an advisory matches a component in one of your SBOMs, work through it in this order.
The order is this page's advice.
- Confirm the match: the purl, the version against the advisory's range, every copy, and every release still deployed.
- Check for exploitation. CISA says organisations should use its Known Exploited Vulnerabilities catalogue as an input to their vulnerability management prioritisation framework. The dependency security guide covers severity and exploit evidence.
- Follow the dependency path to the code that calls the affected package, and answer the three questions above. If someone outside the team is waiting, under_investigation is the status that says so.
- Decide. If the affected code is called with input from outside, this page would record affected, with an action statement that says what to update to or what to switch off meanwhile. If it is not, record not_affected with its justification and the evidence.
- Fix it and keep the evidence. Update the package, ship the release, generate that release's SBOM from its build, and compare it with the previous one. The comparison should show the component's version change and nothing you did not expect.
- Publish the new status. Add a fixed statement for the new release and leave the affected statement for the old one in place, since each describes its own release. Check the VEX document against the SBOMs before it goes out: the lab's script reports a conflict and exits with code 1 when a statement says fixed for a release whose SBOM still lists a version inside the advisory's range.
- Keep the SBOMs, the VEX document and the notes from the analysis together, by release.
Build provenance is a separate record
An SBOM says what is inside a build.
Provenance says where the build came from, and it is a different document. SLSA describes provenance as the verifiable information about software artifacts describing where, when and how something was produced. Its build provenance format identifies the build platform (builder.id) and the template that defined the build process (buildType), includes the external interface to the build (externalParameters), captures the artefacts the build fetched, if known (resolvedDependencies), and identifies the artefacts the build produced (subject). npm has a provenance attestation of its own for packages on its registry: npm says it publicly provides a link to a package's source code and build instructions from the build environment, and that publishing with provenance requires a supported cloud CI/CD provider using a cloud-hosted runner.
The lab's packages are local folders that were never published, so no provenance statement exists for them, and the worked record shows the provenance fields as a labelled illustration with nothing filled in from evidence. For a published dependency the two records answer different questions: the SBOM entry gives the version you have, and the provenance details npm shows for a package published with provenance include its source commit and build file.
The CI/CD security guide covers what a deployer can check in an attested artefact, and the supply chain attacks guide covers what provenance does not prove.
Where a security review or test fits
Clever Ops does not monitor dependencies and does not sell a scanning subscription.
Scans are a step inside a check or test. The component record and the lab on this page are for your own team to run at each release.
Components come into Clever Ops work as part of reviewing an application. A secure code review reads the lockfile against the package manifest and checks new packages and versions against published advisories. A vulnerability assessment confirms a component by its exact version and by whether the affected feature is switched on.
Each report covers the build that was reviewed, on the dates it was reviewed, so a release published afterwards is outside what it can speak to.
If Clever Ops built or hosts the site, the work is a security review rather than an independent test, and the report says who built it and who hosts it.
Frequently asked questions
A software bill of materials: an inventory of the components a piece of software is built from. NTIA's 2021 report defines it as a formal record containing the details and supply chain relationships of various components used in building software. For a web application that means the packages the build installs, each with a name, a version and an identifier, and the relationships between them.
Both are open formats for the same inventory, and the 2026 joint guidance from CISA and 17 partner organisations names them as the two currently widely used. CycloneDX, developed by the OWASP Foundation and Ecma International, is at version 1.7 and lists ECMA-424 as its standard. SPDX gives 3.0.1 as its latest edition, and ISO/IEC 5962:2021 is its version 2.2.1. They arrange the same facts differently: CycloneDX keeps a components list and a separate dependency graph, while SPDX 2.3 expresses dependencies as relationships between packages.
VEX is Vulnerability Exploitability eXchange. CISA's Minimum Requirements for VEX says it indicates the status of a software product or component with respect to a vulnerability, using one of four values: not_affected, affected, fixed or under_investigation. The same document says VEX documents can be authored by the supplier of the software or by a third party, and that a VEX document must identify its author.
At every release. The 2026 guidance says each software version or update should have an associated SBOM, and that a new build or release should come with a new SBOM that reflects the changes. NTIA's 2021 report says that, while there are many unique circumstances, those requesting SBOM data should try to obtain it from the instance of the build. This page's advice is to generate it in the pipeline, from the same clean install that produced the release.
With npm sbom. npm's documentation for CLI version 11 describes the command as generating an SBOM listing the dependencies for the current project in either SPDX or CycloneDX format, chosen with the sbom-format option. In the lab on this page, npm 11.12.1 wrote CycloneDX 1.5 and SPDX 2.3 documents from an installed tree with npm's offline setting on, and a local listener standing in for the registry received no request from it. Check which format version your recipient accepts.
An identifier for a software package, written as a URL. The README of the Package-URL project's purl-spec repository gives its seven components as scheme:type/namespace/name@version?qualifiers#subpath, where the scheme is the constant pkg and the type is the package type, such as npm. In the npm type the scope's @ sign is always percent encoded, so a scoped package begins pkg:npm/%40. This page's advice is to match on the purl, not the name field, when checking an advisory against an SBOM.
No. An SBOM lists components, and matching compares those components with advisories published so far. It says nothing about flaws in code your team wrote, about components nobody has reported on, or about whether a matched flaw can be reached in your application. NTIA's report says SBOM will not solve all software security problems, and the 2026 guidance says an SBOM alone is data about software components.
No. Clever Ops does not monitor dependencies or sell a scanning subscription. A secure code review reads the lockfile against the package manifest and checks packages and versions against published advisories for the build reviewed. The record and lab on this page are for your team to run between reviews.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.