Dependency security and software composition analysis: what your site runs, and what to update first
Every package your site installs brings code your team did not write, and each of those packages can bring more.
This guide covers the routine side of dependency security: listing direct and transitive dependencies, keeping installs tied to the lockfile, reading an advisory against how your code uses the package, choosing what to update first, and proving the update took. It comes with a triage worksheet, a worked decision for a vulnerable function the code does not call, and a lockfile lab that runs offline.
In this guide
Dependency update triage worksheet, worked decision and offline lockfile lab
A worksheet with one row per advisory and installed copy, covering paths, lockfile provenance, reachability, fixed versions and exploit evidence, with the source behind each column. A worked decision for an invented advisory follows, including a not_affected record for a vulnerable function that the code loading it does not import, then an offline Node.js lab whose files and outputs were copied in from a real run.
dependency-security.txt
Introduction3 lines
Part A. The worksheet45 lines
Part B. Worked decision (invented)59 lines
Part C. The offline lockfile lab1,124 lines
Whole template1,240 lines
DEPENDENCY UPDATE TRIAGE WORKSHEET, WORKED DECISION AND OFFLINE LOCKFILE LAB
ILLUSTRATION AND TEMPLATE. Part A is a blank worksheet to copy into a ticket or spreadsheet. Part B fills it in for an invented project, lab-storefront, and an invented advisory, LAB-2026-0001. Part C is the offline lab that produced the evidence Part B relies on. Every package name in Parts B and C sits under the invented scope @lab-invented, both hosts (registry.lab.test and packages.unexpected.example) are invented, and the advisory describes no real flaw. Nothing here is a real package, registry, vulnerability or client, and nothing in the lab opens a network connection.
PART A. THE WORKSHEET
Fill one row for each advisory and each installed copy of the affected package. A lockfile can hold the same package more than once at different versions, and each copy can need a different answer. Write "unknown" rather than leaving a cell blank: an unknown is something to find out, not a pass.
Where each column 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 Advisory: its ID and any aliases (GHSA, CVE, OSV), the database it came from, and the date you read it.
Source: GitHub Advisory Database documentation (GHSA IDs; advisories published in the OSV format); OSV schema (aliases field).
A2 Package and installed version: the version field of this copy's lockfile entry, and its location key, such as node_modules/a/node_modules/b.
Source: npm package-lock.json documentation (packages maps package locations to their details).
A3 Path or paths from your package.json: "direct" if package.json names it, otherwise "transitive through" the direct dependency at the top of each chain, with the range each parent asks for at every step.
Source: npm explain documentation (prints the chain of dependencies causing a package to be installed). The lab's lockfile-paths.mjs prints the same chains from the lockfile alone.
A4 Lockfile provenance: the resolved address, whether its host is on your allow-list, and whether an integrity value is recorded.
Source: npm package-lock.json documentation (resolved is where the package was actually resolved from; integrity is a sha512 or sha1 Subresource Integrity string). The allow-list, and treating a missing integrity value as a fault, are this page's advice.
A5 Affected range and fixed version: copied from the advisory's version fields, not its description.
Source: GitHub Advisory Database documentation (affected versions and patched versions); OSV schema (introduced, fixed and last_affected events). Reading the fields rather than the prose is this page's advice.
A6 Does each range on the path allow the fixed version? For every parent in A3, yes or no. Then the route: update within the existing ranges, update the parent to a release whose range allows the fix, or set an override.
Source: npm semantic versioning documentation (it lists the update types a package can accept, among them patch releases, for example ~1.0.4, and minor releases, for example ^1.0.4); npm update documentation (its caret and tilde examples, including ~1.1.1 as equivalent to >=1.1.1 <1.2.0); npm package.json overrides documentation.
A7 Affected function, and whether your code reaches it: the function the advisory names, if it names one. Then reached / not reached / unknown, and how you know: a text search (name the files), a test that exercises the path, or a call graph from a named tool. Include callers inside other packages on the path, not only your own code.
Source: OSV schema (it leaves ecosystem_specific and database_specific for each ecosystem and database to define; its example is the Go ecosystem, which records in ecosystem_specific the affected functions, the modules the packages were found in, and a severity on the Go project's own scale). Requiring the "how you know" is this page's advice.
A8 Severity as published: the CVSS version, vector and score the advisory carries, and its label. Copy them; do not rescore.
Source: FIRST CVSS v3.1 and v4.0 specifications (the vector string should be displayed with the score); GitHub Advisory Database documentation (it supports CVSS 3.1 and 4.0; if GitHub obtains a CVE, it uses the CVSS version the maintainer assigned, 3.1 or 4.0, and if the CVE is imported, it supports versions 4.0, 3.1 and 3.0).
A9 Exploit evidence: listed in CISA's KEV catalogue (yes / no / not possible without a CVE ID), the EPSS score and percentile with the date read (CVEs only), and any exploitation the advisory itself reports.
Source: CISA's KEV criteria (an assigned CVE ID is the first); FIRST EPSS (a probability for published CVEs over the next 30 days); GitHub Advisory Database documentation (EPSS scores from FIRST for advisories containing CVEs with corresponding EPSS data).
A10 Decision: update now / update the parent / override / not affected / under investigation. For "not affected", name the justification.
Source: CISA, Minimum Requirements for VEX, April 2023 (status values not_affected, affected, fixed and under_investigation, and the not_affected justifications).
A11 Decided by and approved by (names and roles), and the date.
Source: this page's advice. A VEX document must also identify its author, per the same CISA document.
A12 Review again: by the remediation time frame your own documentation sets, or at the first trigger you list, whichever comes first.
Source: OWASP ASVS 5.0 requirement 15.1.1 (Level 1) asks for documented, risk-based remediation time frames; 15.2.1 (Level 1) asks that components have not breached them. The triggers are this page's advice.
A13 Proof the change took: the lockfile diff, a clean install that followed the lockfile, the installed version shown by npm ls or npm explain, and a repeat of the scan that raised the advisory.
Source: npm package-lock.json, npm ci, npm ls and npm audit documentation. Asking for all four is this page's advice.
BLANK ROW (copy one per advisory and installed copy)
A1 Advisory:
A2 Package, version, lockfile location:
A3 Paths from package.json, with each parent's range:
A4 Resolved address / host allowed? / integrity recorded?:
A5 Affected range / fixed version:
A6 Ranges on the path allow the fix? / route:
A7 Affected function / reached? / how we know:
A8 CVSS version, vector, score, label:
A9 KEV / EPSS (date) / exploitation reported:
A10 Decision (and VEX justification if not affected):
A11 Decided by / approved by / date:
A12 Review again by / triggers:
A13 Proof the change took:
PART B. WORKED DECISION (INVENTED)
The project: lab-storefront, an invented shop whose package.json names three dependencies from the invented @lab-invented scope. The advisory: LAB-2026-0001, invented, in the OSV format, covering @lab-invented/text-kit from 1.5.0 up to the fix in 2.3.2 and naming one function, renderTemplate. Every version, path, range, host and reachability result below was read from the lab output in Part C. The people, dates, release notes and decisions are invented.
The lockfile holds two copies of text-kit, so the worksheet has two rows.
ROW 1: the top-level copy
A1 LAB-2026-0001 (invented). No aliases: no CVE, no GHSA. Read 2026-11-14.
A2 @lab-invented/text-kit 2.3.0 at node_modules/@lab-invented/text-kit.
A3 Direct: root wants ^2.1.0. Also transitive through @lab-invented/forms 3.1.0, which wants ^2.0.0. npm ls marks the second as "deduped": one copy serves both.
A4 https://registry.lab.test/... / host allowed: yes / sha512 integrity recorded: yes.
A5 Affected from 1.5.0, fixed in 2.3.2. The lab's check: 2.3.0 is affected.
A6 ^2.1.0 allows 2.3.2: yes. ^2.0.0 allows 2.3.2: yes. Route: update within the existing ranges (npm update @lab-invented/text-kit).
A7 renderTemplate. The storefront's own source imports slugify only (reachability run on fixture/src). Not checked inside forms, because the decision does not depend on it.
A8 CVSS v3.1 vector AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N, a base score of 9.1, which the v3.1 rating scale calls Critical.
A9 KEV: not possible, no CVE ID. EPSS: none, no CVE. Exploitation reported in the advisory: none.
A10 Update now. The fix sits inside both ranges, so leaving it costs more to justify than to do.
A11 Lead developer, approved by the site owner, 2026-11-14.
A12 Not needed once A13 is complete.
A13 To record: the lockfile diff (text-kit 2.3.0 to 2.3.2, with a new resolved address and integrity value), a clean npm ci on the build runner, npm ls showing 2.3.2 at the top level, and a repeat of the scan. The lab can show only the diff and a repeat of its own range check (lockfile-diff.mjs and lockfile-paths.mjs against after-update-lock.json), because the other two need a registry.
ROW 2: the copy nested under cms-client
A1 LAB-2026-0001 (invented), as row 1.
A2 @lab-invented/text-kit 1.8.4 at node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit.
A3 Transitive only: root wants @lab-invented/cms-client ^4.0.0 (4.2.1 installed), and cms-client wants text-kit ~1.8.0. npm explain lists cms-client as the only package this copy serves.
A4 https://registry.lab.test/... / host allowed: yes / sha512 integrity recorded: yes.
A5 Affected from 1.5.0, fixed in 2.3.2. The lab's check: 1.8.4 is affected, and it still is after the row 1 update.
A6 ~1.8.0 allows 2.3.2: no. npm's update documentation gives ~1.1.1 as equivalent to >=1.1.1 <1.2.0. Reading ~1.8.0 by the same pattern, this page takes it to stop below 1.9.0. Routes: (a) cms-client 5.0.0, an invented major release whose range allows 2.3.2, but its release notes list changes the storefront's own code would need; (b) an override forcing text-kit 2.3.2 under cms-client, which would run cms-client 4.2.1 against a major version it was not written for.
A7 renderTemplate. The storefront's own code imports text-kit by name in one place, slugify, and npm explain shows the storefront's own dependency on text-kit is met by the top-level copy, not this one. The only package this copy serves is cms-client, so the reachability script was run on cms-client 4.2.1's installed folder: it imports escapeHtml by name and nothing else from text-kit, and the script found no import it could not follow.
A8 As row 1.
A9 As row 1: no KEV listing possible, no EPSS score, no exploitation reported.
A10 Not affected, justification Vulnerable_code_not_in_execute_path, recorded as a decision with the evidence below. cms-client 5.0.0 is planned as normal work rather than forced now.
A11 Lead developer, approved by the site owner, 2026-11-14.
A12 By the remediation time frame in the project's dependency policy, or at the first trigger below.
A13 Not applicable until the cms-client update lands; then as row 1, checking that this nested copy has gone.
THE DECISION RECORD FOR ROW 2 (written with the VEX field names in CISA's Minimum Requirements for VEX)
Scope: this statement is about one installed copy: @lab-invented/text-kit 1.8.4 at node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit, on the path lab-storefront > @lab-invented/cms-client 4.2.1. The other copy, text-kit 2.3.0 at node_modules/@lab-invented/text-kit, was affected, and row 1 updated it to 2.3.2 in the release named below.
vul_id: LAB-2026-0001 (invented)
product_id: lab-storefront, the release built from the reviewed commit that includes row 1's update
subcomponent_id: @lab-invented/text-kit 1.8.4 at node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit
status: not_affected. In the document's words, no remediation or mitigation is required, and the vulnerability does not affect the listed product. The cms-client 5.0.0 update is still planned, as this page's advice.
justification: Vulnerable_code_not_in_execute_path. The document describes this as vulnerable code, likely in the subcomponent, that cannot be executed due to the way it is used by the product, typically because the product includes the vulnerable code but does not call or otherwise use it.
impact_statement: renderTemplate is present in this copy, but no file searched imports it by name. npm explain shows the storefront's own dependency on text-kit is met by the top-level copy, which row 1 updates. The only package npm explain shows asking for this copy, cms-client 4.2.1, imports escapeHtml from it and nothing else.
author: lead developer (name), approved by the site owner (name); date 2026-11-14
Evidence kept with the record:
1. npm explain output showing the nested copy serves cms-client 4.2.1 only.
2. The reachability output for fixture/src and for cms-client's installed folder, with the file list each run read.
3. The advisory's own function list, and the date it was read.
4. The exact cms-client and text-kit versions from the lockfile (A2).
What this record does not show: that renderTemplate can never run. The search read text. It would miss a call made through code that is generated, bundled or minified differently from the files read, through a name built at run time, or from a package that loads this copy in a way the lockfile does not show. It is a decision the team made on stated evidence, and it holds only while that evidence does.
What would change it (re-run Part C and reopen the row):
- Any change to cms-client's version, or to its lockfile entry.
- A revised advisory: a new affected function, a wider range, or a backported fix in the 1.x line.
- A CVE alias, a KEV listing, or exploitation reported for the advisory.
- The storefront starting to use a cms-client feature that renders templates.
- The reachability script reporting an import it cannot follow, or any import of renderTemplate.
- The review date in A12.
PART C. THE OFFLINE LOCKFILE LAB
WHAT IT NEEDS
Node.js, with nothing to install. The scripts import only node:fs, node:path, node:crypto, node:test and node:assert/strict, and install no packages. The Node.js documentation marks the test runner stable from version 20.0.0. The outputs below were recorded on Node.js v26.0.0 and npm 11.12.1, on macOS 27.2.1 (arm64). npm is needed only for the two optional npm commands.
WHAT IT TOUCHES
make-fixture.mjs writes a folder called fixture next to the scripts and replaces it on every run. Nothing is downloaded or installed: the folders under fixture/node_modules are written as plain files so that npm ls, npm explain and the scripts have a tree to read. The integrity values are sha512 hashes of short stand-in strings, not of real package archives, so npm could not install from these lockfiles. The two npm commands were run with npm's offline setting on, its update check off, a separate cache folder, and empty user and global configuration files.
WHAT EACH SCRIPT IS, AND IS NOT
lockfile-paths.mjs reads a lockfile as JSON. It is not npm: it resolves no versions, evaluates no ranges and contacts no registry. To decide which copy a dependency name points at, it follows the lockfile's folder nesting (the dependent's own node_modules folder, then each enclosing package's, then the root's). It compares hosts as text. npm's documentation notes that registry.npmjs.org in a lockfile is a magic value meaning "the currently configured registry". This page's reading: a host this script shows is not always where an install will fetch from.
reachability.mjs reads files as text. It lists the names one package's entry file exports and the names the scanned files import by name. It does not run code or follow calls. It cannot tell what code reached through dynamic access, a re-export or a require() call goes on to use, so it lists those import forms as ones it cannot follow instead of guessing, and it does not see calls made from packages it was not pointed at.
advisory.mjs reads the advisory as JSON and applies the OSV evaluation steps for SEMVER ranges to plain MAJOR.MINOR.PATCH versions only. Unlike OSV's pseudocode, it reads the events in the order the advisory lists them instead of sorting them, and it reports limit events and other range types as ones it cannot compare.
lockfile-diff.mjs compares two lockfiles as JSON.
lockfile.test.mjs is the regression test: it fails when an entry has no sha512 integrity value or was not resolved over https from an allowed host.
SET-UP
Make an empty folder, save the six files below into it under the names shown, and run the commands under RUN IT from that folder. The commands that set LOCKFILE use the syntax of macOS and Linux shells; on Windows, set it the way your shell does.
==== File 1 of 6: make-fixture.mjs ====
// make-fixture.mjs: writes the invented project this lab reads, in a folder
// called fixture next to this file. Nothing is downloaded and nothing is
// installed. The node_modules folders are written as plain files so that
// npm ls, npm explain and the scripts in this lab have a tree to read.
// Every package name, host, version and advisory here is invented.
import fs from 'node:fs'
import path from 'node:path'
import crypto from 'node:crypto'
const ROOT = 'fixture'
const REGISTRY = 'https://registry.lab.test/'
const UNEXPECTED = 'https://packages.unexpected.example/'
function writeText(relativePath, text) {
const filePath = path.join(ROOT, relativePath)
fs.mkdirSync(path.dirname(filePath), { recursive: true })
fs.writeFileSync(filePath, text)
}
function writeJson(relativePath, value) {
writeText(relativePath, JSON.stringify(value, null, 2) + '\n')
}
// The integrity format the lockfile uses: sha512, base64. Each value is the
// hash of a short stand-in string, not of a real package archive, so npm
// could not install from these lockfiles.
function standInIntegrity(name, version) {
const text = 'invented archive ' + name + '@' + version
return 'sha512-' + crypto.createHash('sha512').update(text).digest('base64')
}
function tarball(registry, name, version) {
const shortName = name.split('/').pop()
return registry + name + '/-/' + shortName + '-' + version + '.tgz'
}
// The installed tree, in the order npm writes lockfile keys.
const INSTALLED = [
{ location: 'node_modules/@lab-invented/cms-client', name: '@lab-invented/cms-client', version: '4.2.1',
dependencies: { '@lab-invented/http-lite': '^1.0.0', '@lab-invented/text-kit': '~1.8.0' } },
{ location: 'node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit',
name: '@lab-invented/text-kit', version: '1.8.4' },
{ location: 'node_modules/@lab-invented/forms', name: '@lab-invented/forms', version: '3.1.0',
dependencies: { '@lab-invented/text-kit': '^2.0.0' } },
{ location: 'node_modules/@lab-invented/http-lite', name: '@lab-invented/http-lite', version: '1.4.2' },
{ location: 'node_modules/@lab-invented/text-kit', name: '@lab-invented/text-kit', version: '2.3.0' },
]
const ROOT_MANIFEST = {
name: 'lab-storefront',
version: '1.0.0',
private: true,
type: 'module',
dependencies: {
'@lab-invented/cms-client': '^4.0.0',
'@lab-invented/forms': '^3.0.0',
'@lab-invented/text-kit': '^2.1.0',
},
}
function lockEntry(item, registry) {
const entry = {
version: item.version,
resolved: tarball(registry, item.name, item.version),
integrity: standInIntegrity(item.name, item.version),
}
if (item.dependencies) entry.dependencies = item.dependencies
return entry
}
function buildLockfile(installed) {
const packages = {
'': { name: ROOT_MANIFEST.name, version: ROOT_MANIFEST.version, dependencies: ROOT_MANIFEST.dependencies },
}
for (const item of installed) packages[item.location] = lockEntry(item, REGISTRY)
return { name: ROOT_MANIFEST.name, version: ROOT_MANIFEST.version, lockfileVersion: 3, requires: true, packages: packages }
}
// The careless lockfile: one entry resolved from a host nobody configured,
// and one entry with its integrity value missing.
function buildCarelessLockfile() {
const lockfile = buildLockfile(INSTALLED)
const forms = lockfile.packages['node_modules/@lab-invented/forms']
forms.resolved = tarball(UNEXPECTED, '@lab-invented/forms', '3.1.0')
delete lockfile.packages['node_modules/@lab-invented/http-lite'].integrity
return lockfile
}
// The shape of the change npm update @lab-invented/text-kit would make here:
// the top-level copy moves to 2.3.2. Written by this script, not by npm.
function buildAfterUpdateLockfile() {
const updated = INSTALLED.map((item) => {
if (item.location !== 'node_modules/@lab-invented/text-kit') return item
return Object.assign({}, item, { version: '2.3.2' })
})
return buildLockfile(updated)
}
const TEXT_KIT_SOURCE = [
'// INVENTED FOR THIS PAGE. Not a real package. The bodies are harmless stubs.',
'export function slugify(text) {',
" return String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join('-')",
'}',
'',
'export function escapeHtml(text) {',
" return String(text).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')",
'}',
'',
'// The invented advisory LAB-2026-0001 names this function. The stub only',
'// returns its input; there is no flaw here to study.',
'export function renderTemplate(template) {',
' return String(template)',
'}',
'',
].join('\n')
const SOURCES = {
'node_modules/@lab-invented/cms-client/index.mjs': [
'// INVENTED FOR THIS PAGE. A stand-in for a CMS client library.',
"import { escapeHtml } from '@lab-invented/text-kit'",
"import { getJson } from '@lab-invented/http-lite'",
'',
'export async function fetchArticleTitle(baseUrl, id) {',
" const article = await getJson(baseUrl + '/articles/' + encodeURIComponent(id))",
' return escapeHtml(article.title)',
'}',
'',
].join('\n'),
'node_modules/@lab-invented/forms/index.mjs': [
'// INVENTED FOR THIS PAGE. A stand-in for a form helper library.',
"import { slugify } from '@lab-invented/text-kit'",
'',
'export function fieldId(label) {',
" return 'field-' + slugify(label)",
'}',
'',
].join('\n'),
'node_modules/@lab-invented/http-lite/index.mjs': [
'// INVENTED FOR THIS PAGE. A stub that never opens a connection.',
'export async function getJson(address) {',
" return { title: 'stub for ' + address }",
'}',
'',
].join('\n'),
'src/catalogue.mjs': [
"// The invented storefront's own code. It uses one function of text-kit.",
"import { slugify } from '@lab-invented/text-kit'",
'',
'export function productPath(product) {',
" return '/products/' + slugify(product.name)",
'}',
'',
].join('\n'),
'src/contact-form.mjs': [
"import { fieldId } from '@lab-invented/forms'",
'',
'export const emailFieldId = fieldId("Email address")',
'',
].join('\n'),
'limits/dynamic-access.mjs': [
'// Not part of the storefront. Written to show what a text search cannot follow.',
"import * as textKit from '@lab-invented/text-kit'",
'',
'export function runHelper(helperName, input) {',
' return textKit[helperName](input)',
'}',
'',
].join('\n'),
'limits/re-export.mjs': [
"export * from '@lab-invented/text-kit'",
'',
].join('\n'),
'limits/legacy.cjs': [
"const kit = require('@lab-invented/text-kit')",
'module.exports = kit',
'',
].join('\n'),
}
const ADVISORY = {
schema_version: '1.9.2',
id: 'LAB-2026-0001',
modified: '2026-11-10T00:00:00Z',
published: '2026-11-10T00:00:00Z',
summary: 'INVENTED FOR THIS PAGE: renderTemplate in @lab-invented/text-kit mishandles template input',
details: 'An invented advisory used only by this lab. It describes no real package and no real flaw.',
severity: [{ type: 'CVSS_V3', score: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N' }],
affected: [{
package: { ecosystem: 'npm', name: '@lab-invented/text-kit' },
ranges: [{ type: 'SEMVER', events: [{ introduced: '1.5.0' }, { fixed: '2.3.2' }] }],
database_specific: { affected_functions: ['renderTemplate'] },
}],
}
function writeInstalledPackages() {
for (const item of INSTALLED) {
const manifest = { name: item.name, version: item.version, type: 'module', main: 'index.mjs' }
if (item.dependencies) manifest.dependencies = item.dependencies
writeJson(item.location + '/package.json', manifest)
if (item.name === '@lab-invented/text-kit') writeText(item.location + '/index.mjs', TEXT_KIT_SOURCE)
}
}
fs.rmSync(ROOT, { recursive: true, force: true })
writeJson('package.json', ROOT_MANIFEST)
writeText('.npmrc', '@lab-invented:registry=' + REGISTRY + '\n')
writeJson('package-lock.json', buildLockfile(INSTALLED))
writeJson('careless-lock.json', buildCarelessLockfile())
writeJson('after-update-lock.json', buildAfterUpdateLockfile())
writeJson('advisories/LAB-2026-0001.json', ADVISORY)
writeInstalledPackages()
for (const relativePath of Object.keys(SOURCES)) writeText(relativePath, SOURCES[relativePath])
console.log('fixture written: ' + fs.readdirSync(ROOT).sort().join(', '))
==== File 2 of 6: advisory.mjs ====
// advisory.mjs: reads one advisory in the OSV format and answers two
// questions for the lab: which versions of a package it covers, and which
// function names it lists. The function list is this lab's own field inside
// database_specific, which OSV leaves to each database to define.
import fs from 'node:fs'
export function readAdvisory(filePath, packageName) {
const advisory = JSON.parse(fs.readFileSync(filePath, 'utf8'))
const affected = (advisory.affected || []).filter((item) => item.package && item.package.name === packageName)
const functions = []
for (const item of affected) {
const listed = (item.database_specific && item.database_specific.affected_functions) || []
for (const name of listed) functions.push(name)
}
return { id: advisory.id, affected: affected, functions: functions }
}
// Plain MAJOR.MINOR.PATCH only. Returns null for anything else, such as a
// pre-release tag, so the caller can say it could not compare.
function parseVersion(text) {
if (text === '0') return [0, 0, 0]
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 a = parseVersion(left)
const b = parseVersion(right)
if (!a || !b) return null
for (let index = 0; index < 3; index++) {
if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1
}
return 0
}
// The OSV evaluation for SEMVER ranges, with the events read in the order the
// advisory lists them. Limit events and other range types are not handled.
function isInRange(version, range) {
if (range.type !== 'SEMVER') return 'cannot compare: range type ' + range.type
let vulnerable = false
for (const event of range.events) {
const bound = event.introduced || event.fixed || event.last_affected
if (bound === undefined) return 'cannot compare: unsupported event'
const order = compareVersions(version, bound)
if (order === null) return 'cannot compare: version ' + version
if (event.introduced !== undefined && order >= 0) vulnerable = true
else if (event.fixed !== undefined && order >= 0) vulnerable = false
else if (event.last_affected !== undefined && order > 0) vulnerable = false
}
return vulnerable ? 'affected' : 'not affected'
}
export function checkVersion(advisory, version) {
for (const item of advisory.affected) {
if ((item.versions || []).includes(version)) return 'affected'
for (const range of item.ranges || []) {
const verdict = isInRange(version, range)
if (verdict !== 'not affected') return verdict
}
}
return 'not affected'
}
export function describeRanges(advisory) {
const parts = []
for (const item of advisory.affected) {
for (const range of item.ranges || []) {
const events = range.events.map((event) => Object.keys(event)[0] + ' ' + Object.values(event)[0])
parts.push(range.type + ' ' + events.join(', '))
}
}
return parts.join('; ') || 'none'
}
==== File 3 of 6: lockfile-paths.mjs ====
// lockfile-paths.mjs: reads an npm lockfile (lockfileVersion 2 or 3) as JSON.
// For one package name it prints every path from the root project to each
// copy the lockfile records, the range each parent asks for, where the copy
// was resolved from and whether it carries an integrity value. It then checks
// the whole lockfile for entries resolved from a host outside the allow-list
// and entries with no integrity value, and exits with code 1 if it finds any.
//
// It is not npm. It resolves no versions, evaluates no ranges and contacts no
// registry. To find which copy a dependency name points at, it follows the
// lockfile's folder nesting: the dependent's own node_modules folder first,
// then each enclosing package's, then the root's.
//
// Usage: node lockfile-paths.mjs LOCKFILE PACKAGE --allow HOST --advisory FILE
// (repeat --allow for each host; --advisory is optional)
import fs from 'node:fs'
import { readAdvisory, checkVersion, describeRanges } from './advisory.mjs'
function readArguments(argv) {
const options = { lockfile: argv[0], target: argv[1], allowed: [], advisory: null }
for (let index = 2; index < argv.length; index += 2) {
if (argv[index] === '--allow') options.allowed.push(argv[index + 1])
if (argv[index] === '--advisory') options.advisory = argv[index + 1]
}
return options
}
function nameAt(location, entry, lockfile) {
if (location === '') return lockfile.name || '(root)'
if (entry.name) return entry.name
const marker = 'node_modules/'
return location.slice(location.lastIndexOf(marker) + marker.length)
}
function parentFolder(location) {
const index = location.lastIndexOf('/node_modules/')
return index === -1 ? '' : location.slice(0, index)
}
// The copy a dependency name points at, found by folder nesting.
function findCopy(packages, fromLocation, dependencyName) {
let folder = fromLocation
while (true) {
const prefix = folder === '' ? '' : folder + '/'
const candidate = prefix + 'node_modules/' + dependencyName
if (packages[candidate]) return candidate
if (folder === '') return null
folder = parentFolder(folder)
}
}
function listEdges(location, entry) {
const groups = [entry.dependencies, entry.optionalDependencies, entry.peerDependencies]
if (location === '') groups.push(entry.devDependencies)
const edges = []
for (const group of groups) {
for (const name of Object.keys(group || {})) edges.push({ name: name, range: group[name] })
}
return edges
}
// Depth-first walk from the root. A path is a list of hops; a location is
// never visited twice on one path, so a cycle in the lockfile cannot loop.
function findPaths(lockfile, target, missing) {
const packages = lockfile.packages
const found = []
function walk(location, hops) {
for (const edge of listEdges(location, packages[location])) {
const copy = findCopy(packages, location, edge.name)
if (!copy) {
missing.add(edge.name + ' ' + edge.range + ', wanted by ' + nameAt(location, packages[location], lockfile))
continue
}
if (hops.some((hop) => hop.location === copy)) continue
const next = hops.concat([{ location: copy, name: edge.name, version: packages[copy].version, range: edge.range }])
if (edge.name === target) found.push(next)
walk(copy, next)
}
}
walk('', [])
return found
}
function describeResolved(entry, allowed) {
if (!entry.resolved) return { text: 'none recorded', allowed: false }
try {
const address = new URL(entry.resolved)
const isAllowed = address.protocol === 'https:' && allowed.includes(address.hostname)
return { text: address.protocol + '//' + address.hostname, allowed: isAllowed }
} catch (error) {
return { text: 'not a URL: ' + entry.resolved, allowed: false }
}
}
function describeIntegrity(entry) {
if (!entry.integrity) return 'missing'
return entry.integrity.split('-')[0] + ' present'
}
// One line per hop, so each parent and the range it asks for can be read.
function formatPath(rootLabel, hops, number) {
const kind = hops.length === 1 ? 'direct' : 'transitive, through ' + hops[0].name
const lines = [' path ' + number + ', ' + kind + ':', ' ' + rootLabel]
let parentName = 'root'
for (const hop of hops) {
lines.push(' > ' + hop.name + '@' + hop.version + ' (' + parentName + ' wants ' + hop.range + ')')
parentName = hop.name
}
return lines.join('\n')
}
function printCopies(lockfile, options, paths, advisory) {
const packages = lockfile.packages
const rootLabel = nameAt('', packages[''], lockfile) + '@' + packages[''].version
const locations = Object.keys(packages).filter((location) => location !== '' && nameAt(location, packages[location], lockfile) === options.target)
locations.forEach((location, index) => {
const entry = packages[location]
const resolved = describeResolved(entry, options.allowed)
console.log('')
console.log('COPY ' + (index + 1) + ': ' + location)
let versionLine = ' version ' + entry.version
if (advisory) versionLine += ' | ' + advisory.id + ': ' + checkVersion(advisory, entry.version)
console.log(versionLine)
console.log(' resolved: ' + (entry.resolved || 'none recorded'))
console.log(' host allowed: ' + (resolved.allowed ? 'yes' : 'NO') + ' | integrity: ' + describeIntegrity(entry) + ' | install script flag: ' + (entry.hasInstallScript ? 'yes' : 'no'))
const own = paths.filter((hops) => hops[hops.length - 1].location === location).sort((a, b) => a.length - b.length)
console.log(' paths from the root (' + own.length + '):')
own.forEach((hops, pathIndex) => console.log(formatPath(rootLabel, hops, pathIndex + 1)))
})
return locations.length
}
function checkWholeLockfile(lockfile, allowed) {
const outside = []
const noIntegrity = []
for (const location of Object.keys(lockfile.packages)) {
const entry = lockfile.packages[location]
if (location === '' || entry.link) continue
const resolved = describeResolved(entry, allowed)
if (!resolved.allowed) outside.push(location + ' (' + resolved.text + ')')
if (!entry.integrity) noIntegrity.push(location)
}
return { outside: outside, noIntegrity: noIntegrity }
}
function printList(title, items) {
console.log(title + ': ' + (items.length === 0 ? 'none' : items.length))
for (const item of items) console.log(' ' + item)
}
function main() {
const options = readArguments(process.argv.slice(2))
const lockfile = JSON.parse(fs.readFileSync(options.lockfile, 'utf8'))
if (!lockfile.packages || lockfile.lockfileVersion < 2) {
console.log('This script reads lockfileVersion 2 or 3, which have a packages section.')
process.exit(2)
}
const advisory = options.advisory ? readAdvisory(options.advisory, options.target) : null
console.log('LOCKFILE PATHS: ' + options.target)
console.log('Lockfile: ' + options.lockfile + ' (lockfileVersion ' + lockfile.lockfileVersion + ', ' + Object.keys(lockfile.packages).length + ' entries including the root)')
console.log('Allowed hosts: ' + options.allowed.join(', '))
if (advisory) console.log('Advisory: ' + advisory.id + ' (' + describeRanges(advisory) + ')')
const missing = new Set()
const paths = findPaths(lockfile, options.target, missing)
const copies = printCopies(lockfile, options, paths, advisory)
if (copies === 0) console.log('\nNo copy of ' + options.target + ' in this lockfile.')
const whole = checkWholeLockfile(lockfile, options.allowed)
console.log('')
console.log('WHOLE-LOCKFILE CHECKS')
printList('Entries resolved from outside the allow-list', whole.outside)
printList('Entries without an integrity value', whole.noIntegrity)
printList('Dependencies named but not found in the lockfile', Array.from(missing))
const problems = whole.outside.length + whole.noIntegrity.length + missing.size
console.log('Result: ' + (problems === 0 ? 'no problems found' : problems + ' problem(s) found'))
process.exitCode = problems === 0 ? 0 : 1
}
main()
==== File 4 of 6: reachability.mjs ====
// reachability.mjs: a text search, not a proof. It reads one installed
// package's entry file as text to list the names it exports, then reads
// every JavaScript file under a source folder as text and reports which of
// those names the files import by name. Any import it cannot reduce to named
// imports (a namespace import, a default import, a re-export, require(), a
// dynamic import() or any other mention of the package name) is listed as
// unresolved, because a text search cannot tell what such code calls.
//
// It does not run the code, follow calls between functions, read other
// packages that use this one, or see code loaded at run time.
//
// Usage: node reachability.mjs PACKAGE-FOLDER SOURCE-FOLDER ADVISORY-FILE
import fs from 'node:fs'
import path from 'node:path'
import { readAdvisory } from './advisory.mjs'
const SOURCE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']
function shown(filePath) {
return path.relative(process.cwd(), filePath).split(path.sep).join('/')
}
function escapeForRegExp(text) {
return text.replace(/[.*+?^()|{}\\/]/g, (character) => '\\' + character)
}
function readExports(packageFolder) {
const manifest = JSON.parse(fs.readFileSync(path.join(packageFolder, 'package.json'), 'utf8'))
const entryFile = path.join(packageFolder, manifest.main || 'index.js')
const text = fs.readFileSync(entryFile, 'utf8')
const names = new Set()
for (const match of text.matchAll(/export\s+(?:async\s+)?function\s*\*?\s*(\w+)/g)) names.add(match[1])
for (const match of text.matchAll(/export\s+(?:const|let|var|class)\s+(\w+)/g)) names.add(match[1])
for (const match of text.matchAll(/export\s*\{([^}]*)\}(?!\s*from)/g)) {
for (const part of match[1].split(',')) {
const name = part.trim().split(/\s+as\s+/).pop()
if (name) names.add(name)
}
}
if (/export\s+default\b/.test(text)) names.add('default')
const reexports = /export\s*\*\s*from/.test(text)
return { manifest: manifest, entryFile: entryFile, names: Array.from(names).sort(), reexports: reexports }
}
function listSourceFiles(folder) {
const files = []
for (const item of fs.readdirSync(folder, { withFileTypes: true })) {
const itemPath = path.join(folder, item.name)
if (item.isDirectory() && item.name !== 'node_modules') files.push(...listSourceFiles(itemPath))
if (item.isFile() && SOURCE_EXTENSIONS.includes(path.extname(item.name))) files.push(itemPath)
}
return files.sort()
}
function lineAt(text, index) {
return text.slice(0, index).split('\n').length
}
function scanFile(filePath, packageName, named, unresolved) {
const text = fs.readFileSync(filePath, 'utf8')
const quoted = "['\"]" + escapeForRegExp(packageName) + "(?:/[^'\"]*)?['\"]"
const kinds = [
{ label: 'named import', pattern: new RegExp('import\\s*\\{([^}]*)\\}\\s*from\\s*' + quoted, 'g') },
{ label: 'namespace import', pattern: new RegExp('import\\s*\\*\\s*as\\s+\\w+\\s+from\\s*' + quoted, 'g') },
{ label: 'default import', pattern: new RegExp('import\\s+\\w+\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*' + quoted, 'g') },
{ label: 're-export', pattern: new RegExp('export\\s*(?:\\*|\\{[^}]*\\})\\s*(?:as\\s+\\w+\\s*)?from\\s*' + quoted, 'g') },
{ label: 'require() call', pattern: new RegExp('require\\s*\\(\\s*' + quoted + '\\s*\\)', 'g') },
{ label: 'dynamic import()', pattern: new RegExp('import\\s*\\(\\s*' + quoted + '\\s*\\)', 'g') },
]
const covered = []
for (const kind of kinds) {
for (const match of text.matchAll(kind.pattern)) {
covered.push([match.index, match.index + match[0].length])
const where = shown(filePath) + ':' + lineAt(text, match.index)
if (kind.label !== 'named import') {
unresolved.push(where + ' ' + kind.label)
continue
}
for (const part of match[1].split(',')) {
const importedName = part.trim().split(/\s+as\s+/)[0]
if (!importedName) continue
if (!named.has(importedName)) named.set(importedName, [])
named.get(importedName).push(where)
}
}
}
for (const match of text.matchAll(new RegExp(quoted, 'g'))) {
const inside = covered.some((span) => match.index >= span[0] && match.index < span[1])
if (!inside) unresolved.push(shown(filePath) + ':' + lineAt(text, match.index) + ' other mention of the package name')
}
}
function main() {
const packageFolder = process.argv[2]
const sourceFolder = process.argv[3]
const exported = readExports(packageFolder)
const packageName = exported.manifest.name
const advisory = readAdvisory(process.argv[4], packageName)
const files = listSourceFiles(sourceFolder)
const named = new Map()
const unresolved = []
for (const filePath of files) scanFile(filePath, packageName, named, unresolved)
console.log('REACHABILITY BY TEXT: ' + packageName)
console.log('Exports read from: ' + shown(exported.entryFile) + ' (version ' + exported.manifest.version + ')')
console.log('Exported names found: ' + exported.names.join(', '))
if (exported.reexports) console.log('The entry file re-exports another module, so this list is incomplete.')
console.log('Advisory ' + advisory.id + ' lists: ' + (advisory.functions.join(', ') || 'no function names'))
console.log('Files scanned under ' + shown(sourceFolder) + ': ' + files.length)
for (const filePath of files) console.log(' ' + shown(filePath))
console.log('')
console.log('Exported name imported by name in')
for (const name of exported.names) {
const places = named.get(name) || []
const flag = advisory.functions.includes(name) ? ' (listed in the advisory)' : ''
console.log(' ' + name.padEnd(16) + (places.join(', ') || 'not imported by name') + flag)
}
console.log('')
console.log('Imports this check cannot follow by text: ' + (unresolved.length === 0 ? 'none' : unresolved.length))
for (const item of unresolved) console.log(' ' + item)
const advisoryNamed = advisory.functions.some((name) => named.has(name))
let result = 'an advisory function is imported by name'
if (!advisoryNamed && unresolved.length > 0) result = 'no advisory function imported by name, but some imports cannot be followed by text'
if (!advisoryNamed && unresolved.length === 0) result = 'no advisory function imported by name in the files scanned'
console.log('Result: ' + result)
}
main()
==== File 5 of 6: lockfile-diff.mjs ====
// lockfile-diff.mjs: compares two npm lockfiles read as JSON and prints, for
// each package location, what changed: added, removed, or a different
// version, resolved address or integrity value. It does not run npm.
//
// Usage: node lockfile-diff.mjs OLD-LOCKFILE NEW-LOCKFILE
import fs from 'node:fs'
const FIELDS = ['version', 'resolved', 'integrity']
function readPackages(filePath) {
return JSON.parse(fs.readFileSync(filePath, 'utf8')).packages || {}
}
// Integrity values are long, so only their start is shown.
function shorten(field, value) {
if (value === undefined) return '(none)'
if (field !== 'integrity') return value
return value.slice(0, 20) + '...'
}
function main() {
const before = readPackages(process.argv[2])
const after = readPackages(process.argv[3])
const locations = Array.from(new Set(Object.keys(before).concat(Object.keys(after)))).sort()
let changes = 0
console.log('LOCKFILE DIFF: ' + process.argv[2] + ' -> ' + process.argv[3])
for (const location of locations) {
const label = location === '' ? '(root)' : location
if (!before[location]) { console.log('ADDED ' + label + ' ' + after[location].version); changes++; continue }
if (!after[location]) { console.log('REMOVED ' + label + ' ' + before[location].version); changes++; continue }
for (const field of FIELDS) {
if (before[location][field] === after[location][field]) continue
console.log('CHANGED ' + label + ' ' + field + ': ' + shorten(field, before[location][field]) + ' -> ' + shorten(field, after[location][field]))
changes++
}
}
console.log('Changes: ' + changes)
}
main()
==== File 6 of 6: lockfile.test.mjs ====
// lockfile.test.mjs: a regression test for the lockfile itself, for Node's
// built-in test runner. It fails when an entry has no sha512 integrity value
// or was resolved from anything other than an https address on an allowed
// host. Set LOCKFILE to the lockfile to check and ALLOWED_HOSTS to a
// comma-separated list of hosts.
import test from 'node:test'
import assert from 'node:assert/strict'
import fs from 'node:fs'
const lockfilePath = process.env.LOCKFILE || 'fixture/package-lock.json'
const allowedHosts = (process.env.ALLOWED_HOSTS || 'registry.lab.test').split(',')
const lockfile = JSON.parse(fs.readFileSync(lockfilePath, 'utf8'))
test('the lockfile has a packages section (lockfileVersion 2 or 3)', () => {
assert.ok(lockfile.lockfileVersion >= 2, 'lockfileVersion is ' + lockfile.lockfileVersion)
assert.equal(typeof lockfile.packages, 'object')
})
for (const [location, entry] of Object.entries(lockfile.packages || {})) {
if (location === '' || entry.link) continue
test(location + ': sha512 integrity value recorded', () => {
assert.ok(String(entry.integrity || '').startsWith('sha512-'), 'integrity is ' + (entry.integrity || 'missing'))
})
test(location + ': resolved over https from an allowed host', () => {
assert.ok(entry.resolved, 'resolved is missing')
const address = new URL(entry.resolved)
assert.equal(address.protocol, 'https:')
assert.ok(allowedHosts.includes(address.hostname), 'host is ' + address.hostname)
})
}
==== RUN IT ====
node make-fixture.mjs
(cd fixture && npm ls @lab-invented/text-kit)
(cd fixture && npm explain @lab-invented/text-kit)
node lockfile-paths.mjs fixture/package-lock.json @lab-invented/text-kit --allow registry.lab.test --advisory fixture/advisories/LAB-2026-0001.json
node lockfile-diff.mjs fixture/package-lock.json fixture/careless-lock.json
node lockfile-paths.mjs fixture/careless-lock.json @lab-invented/text-kit --allow registry.lab.test --advisory fixture/advisories/LAB-2026-0001.json
node reachability.mjs fixture/node_modules/@lab-invented/text-kit fixture/src fixture/advisories/LAB-2026-0001.json
node reachability.mjs fixture/node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit fixture/node_modules/@lab-invented/cms-client fixture/advisories/LAB-2026-0001.json
node reachability.mjs fixture/node_modules/@lab-invented/text-kit fixture/limits fixture/advisories/LAB-2026-0001.json
node lockfile-diff.mjs fixture/package-lock.json fixture/after-update-lock.json
node lockfile-paths.mjs fixture/after-update-lock.json @lab-invented/text-kit --allow registry.lab.test --advisory fixture/advisories/LAB-2026-0001.json
node --test lockfile.test.mjs
LOCKFILE=fixture/careless-lock.json node --test lockfile.test.mjs
LOCKFILE=fixture/after-update-lock.json node --test lockfile.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. Lines that showed a local file path were cut, and each cut is marked where it was made.
==== OUTPUT OF node make-fixture.mjs (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
fixture written: .npmrc, advisories, after-update-lock.json, careless-lock.json, limits, node_modules, package-lock.json, package.json, src
exit code: 0
==== fixture/package-lock.json, as make-fixture.mjs wrote it ====
{
"name": "lab-storefront",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "lab-storefront",
"version": "1.0.0",
"dependencies": {
"@lab-invented/cms-client": "^4.0.0",
"@lab-invented/forms": "^3.0.0",
"@lab-invented/text-kit": "^2.1.0"
}
},
"node_modules/@lab-invented/cms-client": {
"version": "4.2.1",
"resolved": "https://registry.lab.test/@lab-invented/cms-client/-/cms-client-4.2.1.tgz",
"integrity": "sha512-5EZkrl35+3D1O7UfiIN9yWBjVgnb+d5ws+nifg4O+IPSI0o5ETKptIsZM/CKYjrOujjxRBcbeMAqfi1k5L3HNQ==",
"dependencies": {
"@lab-invented/http-lite": "^1.0.0",
"@lab-invented/text-kit": "~1.8.0"
}
},
"node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit": {
"version": "1.8.4",
"resolved": "https://registry.lab.test/@lab-invented/text-kit/-/text-kit-1.8.4.tgz",
"integrity": "sha512-529KGzc2YNatRWXrZKxhz6E1OPoTWJRwepCMMNQMZGJwIWD36yyUJAn1aa/PGO8kX7lsBmmCzKQm3+QNe+BFQw=="
},
"node_modules/@lab-invented/forms": {
"version": "3.1.0",
"resolved": "https://registry.lab.test/@lab-invented/forms/-/forms-3.1.0.tgz",
"integrity": "sha512-ROIk+W+mgQSfPNZS5f/7vE70pH19YoNYrv3TSJoWmDPS7RmI7pNsHSqMsveAMfhsXAjPBAOk+1VMROuN/veaVQ==",
"dependencies": {
"@lab-invented/text-kit": "^2.0.0"
}
},
"node_modules/@lab-invented/http-lite": {
"version": "1.4.2",
"resolved": "https://registry.lab.test/@lab-invented/http-lite/-/http-lite-1.4.2.tgz",
"integrity": "sha512-tZ2NUPIl/6MCuL53E+Y1okcd0N4Tt7J+ACaGSXTr/A0J8pKDntmYtwn5M4Hirq8AZNRQoa+o/SaRCMrx3AKAJg=="
},
"node_modules/@lab-invented/text-kit": {
"version": "2.3.0",
"resolved": "https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.0.tgz",
"integrity": "sha512-JzgcPk0OAX8FvZ60lmSKz0TH8jaqZiO/7KENn6YZ+4qBbgEvI3DVE13BBbsuSMOPTIjMgzbci3xI6IXhUHc59Q=="
}
}
}
==== fixture/advisories/LAB-2026-0001.json (invented) ====
{
"schema_version": "1.9.2",
"id": "LAB-2026-0001",
"modified": "2026-11-10T00:00:00Z",
"published": "2026-11-10T00:00:00Z",
"summary": "INVENTED FOR THIS PAGE: renderTemplate in @lab-invented/text-kit mishandles template input",
"details": "An invented advisory used only by this lab. It describes no real package and no real flaw.",
"severity": [
{
"type": "CVSS_V3",
"score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N"
}
],
"affected": [
{
"package": {
"ecosystem": "npm",
"name": "@lab-invented/text-kit"
},
"ranges": [
{
"type": "SEMVER",
"events": [
{
"introduced": "1.5.0"
},
{
"fixed": "2.3.2"
}
]
}
],
"database_specific": {
"affected_functions": [
"renderTemplate"
]
}
}
]
}
==== OUTPUT OF npm ls @lab-invented/text-kit (run inside fixture) (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
(line cut here: it showed a local file path)
├─┬ @lab-invented/cms-client@4.2.1
│ └── @lab-invented/text-kit@1.8.4
├─┬ @lab-invented/forms@3.1.0
│ └── @lab-invented/text-kit@2.3.0 deduped
└── @lab-invented/text-kit@2.3.0
exit code: 0
==== OUTPUT OF npm explain @lab-invented/text-kit (run inside fixture) (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
@lab-invented/text-kit@2.3.0
node_modules/@lab-invented/text-kit
@lab-invented/text-kit@"^2.1.0" from the root project
@lab-invented/text-kit@"^2.0.0" from @lab-invented/forms@3.1.0
node_modules/@lab-invented/forms
@lab-invented/forms@"^3.0.0" from the root project
@lab-invented/text-kit@1.8.4
node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit
@lab-invented/text-kit@"~1.8.0" from @lab-invented/cms-client@4.2.1
node_modules/@lab-invented/cms-client
@lab-invented/cms-client@"^4.0.0" from the root project
exit code: 0
==== OUTPUT OF lockfile-paths.mjs on the careful lockfile (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
LOCKFILE PATHS: @lab-invented/text-kit
Lockfile: fixture/package-lock.json (lockfileVersion 3, 6 entries including the root)
Allowed hosts: registry.lab.test
Advisory: LAB-2026-0001 (SEMVER introduced 1.5.0, fixed 2.3.2)
COPY 1: node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit
version 1.8.4 | LAB-2026-0001: affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-1.8.4.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (1):
path 1, transitive, through @lab-invented/cms-client:
lab-storefront@1.0.0
> @lab-invented/cms-client@4.2.1 (root wants ^4.0.0)
> @lab-invented/text-kit@1.8.4 (@lab-invented/cms-client wants ~1.8.0)
COPY 2: node_modules/@lab-invented/text-kit
version 2.3.0 | LAB-2026-0001: affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.0.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (2):
path 1, direct:
lab-storefront@1.0.0
> @lab-invented/text-kit@2.3.0 (root wants ^2.1.0)
path 2, transitive, through @lab-invented/forms:
lab-storefront@1.0.0
> @lab-invented/forms@3.1.0 (root wants ^3.0.0)
> @lab-invented/text-kit@2.3.0 (@lab-invented/forms wants ^2.0.0)
WHOLE-LOCKFILE CHECKS
Entries resolved from outside the allow-list: none
Entries without an integrity value: none
Dependencies named but not found in the lockfile: none
Result: no problems found
exit code: 0
==== OUTPUT OF lockfile-diff.mjs: what the careless lockfile changes (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
LOCKFILE DIFF: fixture/package-lock.json -> fixture/careless-lock.json
CHANGED node_modules/@lab-invented/forms resolved: https://registry.lab.test/@lab-invented/forms/-/forms-3.1.0.tgz -> https://packages.unexpected.example/@lab-invented/forms/-/forms-3.1.0.tgz
CHANGED node_modules/@lab-invented/http-lite integrity: sha512-tZ2NUPIl/6MCu... -> (none)
Changes: 2
exit code: 0
==== OUTPUT OF lockfile-paths.mjs on the careless lockfile (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
LOCKFILE PATHS: @lab-invented/text-kit
Lockfile: fixture/careless-lock.json (lockfileVersion 3, 6 entries including the root)
Allowed hosts: registry.lab.test
Advisory: LAB-2026-0001 (SEMVER introduced 1.5.0, fixed 2.3.2)
COPY 1: node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit
version 1.8.4 | LAB-2026-0001: affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-1.8.4.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (1):
path 1, transitive, through @lab-invented/cms-client:
lab-storefront@1.0.0
> @lab-invented/cms-client@4.2.1 (root wants ^4.0.0)
> @lab-invented/text-kit@1.8.4 (@lab-invented/cms-client wants ~1.8.0)
COPY 2: node_modules/@lab-invented/text-kit
version 2.3.0 | LAB-2026-0001: affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.0.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (2):
path 1, direct:
lab-storefront@1.0.0
> @lab-invented/text-kit@2.3.0 (root wants ^2.1.0)
path 2, transitive, through @lab-invented/forms:
lab-storefront@1.0.0
> @lab-invented/forms@3.1.0 (root wants ^3.0.0)
> @lab-invented/text-kit@2.3.0 (@lab-invented/forms wants ^2.0.0)
WHOLE-LOCKFILE CHECKS
Entries resolved from outside the allow-list: 1
node_modules/@lab-invented/forms (https://packages.unexpected.example)
Entries without an integrity value: 1
node_modules/@lab-invented/http-lite
Dependencies named but not found in the lockfile: none
Result: 2 problem(s) found
exit code: 1
==== OUTPUT OF reachability.mjs on the storefront's own source (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
REACHABILITY BY TEXT: @lab-invented/text-kit
Exports read from: fixture/node_modules/@lab-invented/text-kit/index.mjs (version 2.3.0)
Exported names found: escapeHtml, renderTemplate, slugify
Advisory LAB-2026-0001 lists: renderTemplate
Files scanned under fixture/src: 2
fixture/src/catalogue.mjs
fixture/src/contact-form.mjs
Exported name imported by name in
escapeHtml not imported by name
renderTemplate not imported by name (listed in the advisory)
slugify fixture/src/catalogue.mjs:2
Imports this check cannot follow by text: none
Result: no advisory function imported by name in the files scanned
exit code: 0
==== OUTPUT OF reachability.mjs on cms-client's installed folder (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
REACHABILITY BY TEXT: @lab-invented/text-kit
Exports read from: fixture/node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit/index.mjs (version 1.8.4)
Exported names found: escapeHtml, renderTemplate, slugify
Advisory LAB-2026-0001 lists: renderTemplate
Files scanned under fixture/node_modules/@lab-invented/cms-client: 1
fixture/node_modules/@lab-invented/cms-client/index.mjs
Exported name imported by name in
escapeHtml fixture/node_modules/@lab-invented/cms-client/index.mjs:2
renderTemplate not imported by name (listed in the advisory)
slugify not imported by name
Imports this check cannot follow by text: none
Result: no advisory function imported by name in the files scanned
exit code: 0
==== OUTPUT OF reachability.mjs on the limits folder (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
REACHABILITY BY TEXT: @lab-invented/text-kit
Exports read from: fixture/node_modules/@lab-invented/text-kit/index.mjs (version 2.3.0)
Exported names found: escapeHtml, renderTemplate, slugify
Advisory LAB-2026-0001 lists: renderTemplate
Files scanned under fixture/limits: 3
fixture/limits/dynamic-access.mjs
fixture/limits/legacy.cjs
fixture/limits/re-export.mjs
Exported name imported by name in
escapeHtml not imported by name
renderTemplate not imported by name (listed in the advisory)
slugify not imported by name
Imports this check cannot follow by text: 3
fixture/limits/dynamic-access.mjs:2 namespace import
fixture/limits/legacy.cjs:1 require() call
fixture/limits/re-export.mjs:1 re-export
Result: no advisory function imported by name, but some imports cannot be followed by text
exit code: 0
==== OUTPUT OF lockfile-diff.mjs: the update in row 1 (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
LOCKFILE DIFF: fixture/package-lock.json -> fixture/after-update-lock.json
CHANGED node_modules/@lab-invented/text-kit version: 2.3.0 -> 2.3.2
CHANGED node_modules/@lab-invented/text-kit resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.0.tgz -> https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.2.tgz
CHANGED node_modules/@lab-invented/text-kit integrity: sha512-JzgcPk0OAX8Fv... -> sha512-bfR3nRrLOsVmJ...
Changes: 3
exit code: 0
==== OUTPUT OF lockfile-paths.mjs after the update (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
LOCKFILE PATHS: @lab-invented/text-kit
Lockfile: fixture/after-update-lock.json (lockfileVersion 3, 6 entries including the root)
Allowed hosts: registry.lab.test
Advisory: LAB-2026-0001 (SEMVER introduced 1.5.0, fixed 2.3.2)
COPY 1: node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit
version 1.8.4 | LAB-2026-0001: affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-1.8.4.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (1):
path 1, transitive, through @lab-invented/cms-client:
lab-storefront@1.0.0
> @lab-invented/cms-client@4.2.1 (root wants ^4.0.0)
> @lab-invented/text-kit@1.8.4 (@lab-invented/cms-client wants ~1.8.0)
COPY 2: node_modules/@lab-invented/text-kit
version 2.3.2 | LAB-2026-0001: not affected
resolved: https://registry.lab.test/@lab-invented/text-kit/-/text-kit-2.3.2.tgz
host allowed: yes | integrity: sha512 present | install script flag: no
paths from the root (2):
path 1, direct:
lab-storefront@1.0.0
> @lab-invented/text-kit@2.3.2 (root wants ^2.1.0)
path 2, transitive, through @lab-invented/forms:
lab-storefront@1.0.0
> @lab-invented/forms@3.1.0 (root wants ^3.0.0)
> @lab-invented/text-kit@2.3.2 (@lab-invented/forms wants ^2.0.0)
WHOLE-LOCKFILE CHECKS
Entries resolved from outside the allow-list: none
Entries without an integrity value: none
Dependencies named but not found in the lockfile: none
Result: no problems found
exit code: 0
==== OUTPUT OF node --test lockfile.test.mjs (careful lockfile) (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
✔ the lockfile has a packages section (lockfileVersion 2 or 3) (0.730458ms)
✔ node_modules/@lab-invented/cms-client: sha512 integrity value recorded (0.059583ms)
✔ node_modules/@lab-invented/cms-client: resolved over https from an allowed host (0.055292ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.035458ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.0455ms)
✔ node_modules/@lab-invented/forms: sha512 integrity value recorded (0.03525ms)
✔ node_modules/@lab-invented/forms: resolved over https from an allowed host (0.040625ms)
✔ node_modules/@lab-invented/http-lite: sha512 integrity value recorded (0.0325ms)
✔ node_modules/@lab-invented/http-lite: resolved over https from an allowed host (0.055458ms)
✔ node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.083792ms)
✔ node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.09ms)
ℹ tests 11
ℹ suites 0
ℹ pass 11
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 90.878375
exit code: 0
==== OUTPUT OF node --test lockfile.test.mjs with LOCKFILE=fixture/careless-lock.json (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
✔ the lockfile has a packages section (lockfileVersion 2 or 3) (0.679875ms)
✔ node_modules/@lab-invented/cms-client: sha512 integrity value recorded (0.0585ms)
✔ node_modules/@lab-invented/cms-client: resolved over https from an allowed host (0.051875ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.035833ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.043042ms)
✔ node_modules/@lab-invented/forms: sha512 integrity value recorded (0.031791ms)
✖ node_modules/@lab-invented/forms: resolved over https from an allowed host (0.348958ms)
✖ node_modules/@lab-invented/http-lite: sha512 integrity value recorded (0.048708ms)
✔ node_modules/@lab-invented/http-lite: resolved over https from an allowed host (0.048542ms)
✔ node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.0775ms)
✔ node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.0685ms)
ℹ tests 11
ℹ suites 0
ℹ pass 9
ℹ fail 2
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 81.397708
✖ failing tests:
test at lockfile.test.mjs:24:3
✖ node_modules/@lab-invented/forms: resolved over https from an allowed host (0.348958ms)
AssertionError [ERR_ASSERTION]: host is packages.unexpected.example
(line cut here: it showed a local file path)
at Test.runInAsyncScope (node:async_hooks:226:14)
at Test.run (node:internal/test_runner/test:1201:25)
at Test.processPendingSubtests (node:internal/test_runner/test:831:18)
at Test.postRun (node:internal/test_runner/test:1330:19)
at Test.run (node:internal/test_runner/test:1258:12)
at async Test.processPendingSubtests (node:internal/test_runner/test:831:7) {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: false,
expected: true,
operator: '==',
diff: 'simple'
}
test at lockfile.test.mjs:21:3
✖ node_modules/@lab-invented/http-lite: sha512 integrity value recorded (0.048708ms)
AssertionError [ERR_ASSERTION]: integrity is missing
(line cut here: it showed a local file path)
at Test.runInAsyncScope (node:async_hooks:226:14)
at Test.run (node:internal/test_runner/test:1201:25)
at Test.processPendingSubtests (node:internal/test_runner/test:831:18)
at Test.postRun (node:internal/test_runner/test:1330:19)
at Test.run (node:internal/test_runner/test:1258:12)
at async Test.processPendingSubtests (node:internal/test_runner/test:831:7) {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: false,
expected: true,
operator: '==',
diff: 'simple'
}
exit code: 1
==== OUTPUT OF node --test lockfile.test.mjs with LOCKFILE=fixture/after-update-lock.json (Node.js v26.0.0, npm 11.12.1, macOS 27.2.1 (arm64)) ====
✔ the lockfile has a packages section (lockfileVersion 2 or 3) (0.730625ms)
✔ node_modules/@lab-invented/cms-client: sha512 integrity value recorded (0.055834ms)
✔ node_modules/@lab-invented/cms-client: resolved over https from an allowed host (0.055459ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.034875ms)
✔ node_modules/@lab-invented/cms-client/node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.045333ms)
✔ node_modules/@lab-invented/forms: sha512 integrity value recorded (0.037333ms)
✔ node_modules/@lab-invented/forms: resolved over https from an allowed host (0.038417ms)
✔ node_modules/@lab-invented/http-lite: sha512 integrity value recorded (0.030125ms)
✔ node_modules/@lab-invented/http-lite: resolved over https from an allowed host (0.056209ms)
✔ node_modules/@lab-invented/text-kit: sha512 integrity value recorded (0.075792ms)
✔ node_modules/@lab-invented/text-kit: resolved over https from an allowed host (0.414292ms)
ℹ tests 11
ℹ suites 0
ℹ pass 11
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 84.731875
exit code: 0
==== READING THE OUTPUT ====
In the npm ls output, the text library appears under the form library marked deduped: it is the same 2.3.0 copy the root uses. npm explain answers the reverse question: for each installed copy, which packages asked for it and with which range, up to the root project.
lockfile-paths.mjs prints the same chains from the lockfile alone, adds the resolved host and integrity check for each copy, and checks the advisory's range against each installed version. After the update, the top-level copy reads "not affected" and the nested copy still reads "affected", which is why row 2 needs its own decision.
The careless lockfile has two faults, shown by lockfile-diff.mjs: one entry resolved from a host nobody configured, and one entry with no integrity value. lockfile-paths.mjs reports both and exits with code 1, and the regression test fails on exactly those two checks.
The limits run shows what the reachability search cannot do: a namespace import used with a computed name, a require() call and a re-export are each reported as an import it cannot follow, rather than counted as safe.
==== WHAT WAS NOT TESTED ====
The lab ran on macOS only. It did not run npm install, npm ci, npm update or npm audit, because each of those needs a registry; the after-update lockfile was written by make-fixture.mjs to show the shape of the change, not produced by npm. It reads lockfileVersion 2 and 3 files only, and it was run against lockfileVersion 3. Workspaces, link entries, git dependencies, bundled dependencies, peer dependency conflicts and pre-release versions were not tested. The reachability search was tried on ES module and CommonJS files written for the lab, not on bundled or minified code.
==== USING IT ON YOUR OWN PROJECT ====
1. Run lockfile-paths.mjs against your own package-lock.json, with --allow for each registry host your project should use, and fill A2 to A4 from its output.
2. Add lockfile.test.mjs to your test suite with ALLOWED_HOSTS set to the same hosts, so a lockfile change that adds an unexpected host or drops an integrity value fails a build.
3. For an advisory that names a function, run reachability.mjs on your source folder, then on the installed folder of each package that the lockfile shows loading the affected copy. Treat every "cannot follow" line as unknown until someone reads that code.
4. Keep each output with the worksheet row it supports, with the date it was run.What software composition analysis is
Software composition analysis (SCA) is the work of listing the third-party components an application is built from and checking each one against what is known about it.
OWASP treats it as a narrower case of component analysis, which its Component Analysis page defines as the process of identifying potential areas of risk from the use of third-party and open-source software and hardware components. A software-only subset with limited scope, the page says, is commonly referred to as Software Composition Analysis.
It also names the starting point: an accurate inventory of all third-party and open source components, without which the other factors become impractical to determine with high confidence.
OWASP Top 10:2025 covers the same work under A03 Software Supply Chain Failures. Its prevention list includes tracking not just your direct dependencies but their transitive dependencies, continuously monitoring sources like CVE, NVD and OSV for vulnerabilities in the components you use, and using software composition analysis, software supply chain or security-focused SBOM tools to automate the process.
Listing and matching are the half of the job a tool can do. Deciding what a match means for your site is the other half. Yarn's documentation for its audit command puts it plainly: the reports it pulls from the npm registry may or may not be relevant to your actual program, because not all vulnerabilities affect all code paths.
This guide is about that second half: reading each match against how your own code uses the package, and keeping a record of the answer.
Two neighbouring subjects have their own guides. A deliberately malicious release, a look-alike package or an install script that runs on your build machine is a supply chain attack, and the supply chain attacks guide covers how those reach a site and what to do first. The software bill of materials (SBOM), the formal inventory format, has its own planned guide; this page works from the lockfile you already have.
Direct and transitive dependencies
A dependency is any package your application needs in order to build or run.
The ones your team chose are named in package.json, and those are your direct dependencies. Each of them has its own package.json with its own list, and the packages on those lists are transitive dependencies of your application: installed because something you chose asked for them, and so on down.
OWASP's Component Analysis page defines a transitive dependency as the case where an application depends directly on a component and that component depends on another, and notes that each transitive dependency's risk is inherited by every component and application that relies on it. OWASP's A03 lists not carefully tracking the versions of all components, including nested (transitive) dependencies, among the signs that you are likely vulnerable.
A site built on a framework runs the framework, the libraries it installs and the libraries those install, with your own code on top. OWASP's Component Analysis page states the consequence: by using open source components, organisations ultimately take responsibility for code they did not write. You can see the scale for your own project by comparing the dependencies named in package.json with the number of entries in package-lock.json.
Two npm commands show the structure. npm ls prints installed versions as a tree, and given a package name it limits the output to the paths that lead to that package; npm's documentation notes that this is the logical dependency tree, not the physical layout of node_modules. npm explain answers the reverse question by printing the chain of dependencies causing a given package to be installed.
The same package can be installed more than once at different versions, and npm's documentation suggests passing npm explain a folder path to find out exactly why a dependency is being duplicated to satisfy conflicting version requirements.
The lab on this page shows that case. Its invented storefront depends on a text library directly, and also through a form library and a CMS client. npm explain reports one copy at 2.3.0 serving the storefront and the form library, and a second copy at 1.8.4 nested under the CMS client, which asks for ~1.8.0.
An advisory against that library is therefore two questions, one for each copy. The planned Node.js security guide covers the runtime itself, including which release lines are supported.
The npm behaviour this page quotes comes from npm's documentation for CLI version 12.2.2, which the documentation marked as the latest version when it was read. The lab on this page ran on npm 11.12.1, the version installed on the machine that ran it.
What a lockfile fixes in place, and why installs should follow it
package.json can name version ranges rather than exact versions. npm's documentation on semantic versioning lists the update types a package can accept from its dependencies, each with several ways to write it: patch releases (1.0, 1.0.x or ~1.0.4), minor releases (1, 1.x or ^1.0.4) and major releases (* or x).
The lockfile records what those ranges resolved to. npm's documentation says package-lock.json describes the exact tree that was generated, so that subsequent installs can generate identical trees regardless of intermediate dependency updates, and that it is intended to be committed.
For a package fetched from the registry, its entry records the version, a resolved field giving the place the package was actually resolved from (a URL to a tarball) and an integrity field holding a sha512 or sha1 Subresource Integrity string for the artifact unpacked there.
An entry flagged as a link carries no other fields, because the link target has its own entry. The same documentation gives lockfileVersion 3 as the format used by npm v9 and above.
A lockfile protects only the installs that follow it. npm's documentation for npm install says that when it is run without arguments, it uses the exact versions in package-lock.json while they satisfy the ranges in package.json, and resolves new versions and updates the lockfile when they do not. npm's documentation says npm ci is meant to be used in automated environments such as test platforms, continuous integration and deployment, or any situation where you want to make sure you are doing a clean install of your dependencies.
It needs an existing lockfile, exits with an error instead of updating it when the dependencies in the lockfile do not match package.json, and never writes to either file. pnpm has a frozen-lockfile install, which its documentation makes the default in CI when a lockfile is present.
Read the lockfile for where code came from, not only for versions. Two checks are cheap to automate, and both are this page's own advice: every resolved address should point at a registry host on a short allow-list, and every entry fetched from a registry should carry an integrity value.
The regression test in the lab fails on either fault. One detail from npm's documentation matters here: it calls registry.npmjs.org in a lockfile a magic value meaning the currently configured registry.
This page reads that as a caution: the host written in the file is not always where npm fetches from, so your registry configuration is part of the evidence.
Other package managers have their own form of this control. pip's hash-checking mode uses hashes embedded in a requirements file to protect against remote tampering and network issues. Its documentation says that by default, when at least one requirement has hashes, hashes become required for all requirements, and that in this mode hashes are required for all dependencies too.
Since version 26.2, a --no-require-hashes flag disables that mechanism, and hashes are then verified only for requirements where they are provided.
Reading lockfile changes for signs of a deliberate compromise, such as a new install script, belongs to the supply chain attacks guide, and hardening the pipeline that runs the install belongs to the CI/CD security guide.
Dependency confusion is a configuration problem
pip's documentation describes dependency confusion as a class of security issue in which an attacker publishes a package with the same name as your private package to a public index, which may then be chosen instead of yours. npm's threats page describes the same pattern, says npm is not able to detect dependency confusion attacks, and strongly encourages scoped packages.
Whether it can happen to you comes down to configuration: how each package manager is told where each name lives.
In npm, the control is the scope. npm's scope documentation says each npm user or organisation has its own scope and only you can add packages in your scope. A scope can be associated with a separate registry, at login or with npm config, after which any npm install for a package with that scope requests it from that registry instead, and a scope only ever points to one registry.
This page's advice follows from that: publish private packages under a scope you own, map that scope to your private registry, and leave no private package under an unscoped name.
pip works differently. Its install documentation says it looks for packages on the package index, in the local file system and in any additional repositories given with --find-links or --extra-index-url, with no priority between them: all are checked and the best match by version number is selected.
The same page warns that using --extra-index-url to search for packages which are not in the main repository, such as private packages, is unsafe.
Composer 2 takes the opposite default. Its documentation on repository priorities says Composer looks a package up in the topmost repository and moves to the next only if that one does not contain it, and that all repositories are canonical in this way by default in Composer 2.x.
Its own example is a private repository that is not canonical: if someone publishes foo/bar 2.999 to packagist.org, Composer picks it over a private 2.4.3 because the version is higher. Composer 1.x treated all repositories as non-canonical.
ASVS 5.0 sets the expectation as requirement 15.2.4, at Level 3: third-party components and all of their transitive dependencies are included from the expected repository, whether internally owned or an external source, with no risk of a dependency confusion attack. GitHub says the malware advisories in its Advisory Database are mostly about this kind of substitution, and that users whose dependencies are appropriately scoped should not be affected.
The lockfile shows whether the configuration held: a resolved address on an unexpected host is what the lab's lockfile-paths.mjs and regression test report.
One more setting cuts the other way. npm's audit documentation says that for its bulk advisory request, npm sends the name and list of versions of each package in the tree to the default configured registry, and that npm versions 5 and 6 scrubbed packages with a slash in their name to avoid leaking the names of potentially private packages, a behaviour removed as of version 7.
If your private package names are sensitive in themselves, check which registry npm audit talks to. The tokens a build uses to reach a private registry are secrets like any other, and the secrets exposure guide covers finding and rotating exposed ones. What a substituted package does once it runs is a matter for the supply chain attacks guide.
How to read an advisory against your own use of the package
An advisory is a statement about versions, and sometimes about functions.
GitHub's Advisory Database documentation says its advisories are published as JSON files in the Open Source Vulnerability (OSV) format, and that a vulnerability advisory contains the range of released package versions where the problem exists and the earliest version where it was fixed. An advisory may include the description, severity, affected package, package ecosystem, affected versions and patched versions, impact, and optional information such as references, workarounds and credits.
In the OSV schema, affected versions are a timeline of events of four types: introduced, fixed, last_affected and limit. The schema says limit events, which set an upper limit on a range, are typically not necessary for describing numbered (linear) version ranges and should not be used for them.
The schema strongly recommends fixed over last_affected where possible: fixed identifies the version that contains the fix, while last_affected opens up the possibility of false negatives. It leaves two fields for others to define: ecosystem_specific, defined by the package ecosystem, and database_specific, defined by the database the record came from.
Its example is the Go ecosystem, which records in ecosystem_specific the affected functions, the modules the packages were found in, and a severity on the Go project's own scale.
Read each advisory in four passes. Together they fill columns A5 and A7 to A9 of the worksheet, and the order is this page's advice:
- The affected range and the fixed version, taken from the version fields rather than from the summary text. Check every installed copy against the range, not only the first one npm ls prints.
- The affected function or feature, where the advisory names one. Where it names none, treat the whole package as in use until you know otherwise.
- Severity as published: the CVSS version, the vector and the score. FIRST's CVSS specifications say the vector string should be displayed with the score. Copy both, as this page's advice.
- Exploit evidence: whether the advisory reports exploitation, whether it carries a CVE ID that CISA's KEV catalogue could list, and any EPSS score.
What npm audit reports
npm's audit command submits a description of your project's dependencies to the default registry and asks for a report of known vulnerabilities. npm's page on audit reports lists the fields as severity, description, package, patched in, dependency of, path and more info, and defines severity as determined by the impact and exploitability of the vulnerability in its most common use case.
Your use may not be the most common one, which is why the severity column is never the whole row.
npm also reports what it calls meta-vulnerabilities: a dependency that is vulnerable by virtue of depending on vulnerable versions of another package. By npm's own example, if foo is vulnerable in the range >=1.0.2 <2.0.0 and bar depends on foo@^1.1.0, then that version of bar can only be installed by installing a vulnerable version of foo.
In the lab, the CMS client asks for ~1.8.0 of a library whose whole 1.x line from 1.5.0 is affected, so it fits that definition.
Why severity alone does not set the order of work
Severity describes the flaw in general; priority depends on how you use it.
FIRST's CVSS v3.1 specification says the Base Score reflects a vulnerability's intrinsic characteristics and assumes the reasonable worst-case impact across different deployed environments, and that consumers should supplement it with Temporal and Environmental scores specific to their use of the vulnerable product.
Version 4.0 asks consumers to enrich Base metrics with Threat and Environmental values in the same way, notes that product maintainers and the NVD typically provide only Base scores, labelled CVSS-B, and says that for prioritisation, a score's usefulness is directly proportional to the CVSS metrics used to generate it.
GitHub's Advisory Database supports both versions, and where GitHub obtains a CVE it uses the CVSS version the maintainer assigned.
Exploit evidence answers a different question. CISA adds a vulnerability to its KEV catalogue on three criteria: an assigned CVE ID, reliable evidence that it has been actively exploited in the wild, and a clear remediation action such as a vendor-provided update.
CISA is explicit that exploitability, meaning how easily an attacker could take advantage of a flaw, is not a criterion for inclusion, and that the public availability of a proof of concept does not automatically indicate the vulnerability has been or will be exploited.
Because a CVE ID is the first criterion, an advisory without one cannot be in the catalogue, so the absence of a KEV listing on such an advisory tells you nothing about exploitation.
EPSS, from FIRST, estimates the probability that a published CVE will be exploited in the wild in the next 30 days, and GitHub shows EPSS scores for advisories containing CVEs that have EPSS data. FIRST's guidance on using EPSS says the score is not a severity score and not a complete risk score, and that EPSS does not know what is in your environment.
It warns against treating a low score as a declaration that a vulnerability is safe to ignore, and against multiplying an EPSS score by a CVSS score to produce a combined risk score, which it says has no interpretable meaning.
As a general rule of thumb, it says to treat a vulnerability on the KEV list as actively exploited and prioritise it accordingly, regardless of its EPSS score.
FIRST describes three checks that turn a population-level EPSS score into something specific to your organisation: presence, reachability and consequence. In FIRST's words, a vulnerability present in your environment is only exploitable if the conditions for exploitation exist and are achievable by an attacker, and network exposure, authentication requirements and compensating controls already in place all determine whether a high score translates into real exposure.
This page uses a narrower reading of its own for dependencies: presence is the lockfile entry for each copy, reachability is whether code that loads that copy calls the affected function, and consequence is what that code handles.
A function that is called may still be out of an attacker's reach, so the narrower check answers only part of FIRST's question.
The worksheet has a column for the first two; the third is your judgement about your own site. The vulnerability assessment guide covers CVSS, KEV and EPSS for findings in general.
Deciding what to update first
Start with deadlines.
ASVS 5.0 requirement 15.1.1, at Level 1, asks for application documentation that defines risk-based remediation time frames for third-party component versions with vulnerabilities and for updating libraries in general, and requirement 15.2.1, also Level 1, asks that the application only contains components which have not breached those time frames. With the time frames written down, the order below, which is this page's advice, decides what comes first within them:
- Any affected copy whose vulnerability is on the KEV list, or whose advisory reports exploitation, where the affected function is reached or reach is unknown.
- Any affected copy whose function is reached, or whose reach is unknown, in code that handles input from outside: requests, uploads, webhooks or content from a CMS.
- Any affected copy whose fixed version already sits inside every range on its path. These updates are cheap, so batch them into the same change rather than ranking them.
- Everything else, inside the documented time frames, with a written decision for anything that will wait.
Two cautions from OWASP
OWASP's A03 lists not fixing or upgrading the underlying platform, frameworks and dependencies in a risk-based, timely fashion among the signs you are likely vulnerable, and says this commonly happens where patching is a monthly or quarterly task under change control.
The same list includes developers not testing the compatibility of updated, upgraded or patched libraries. An update that breaks checkout is not a fix, so the order assumes your tests run on every dependency change.
Letting a tool open the pull requests
GitHub's documentation says Dependabot security updates check whether a vulnerable dependency can be upgraded to a fixed version without disrupting the dependency graph, then raise a pull request to update it to the minimum version that includes the patch. Dependabot shows an alert for every vulnerable dependency in the full dependency graph, but triggers security updates only for dependencies specified in a manifest or lock file, and GitHub's Advisory Database documentation adds that Dependabot does not create alerts for unreviewed advisories.
Renovate's documentation says it can read GitHub's vulnerability alerts and raise fix pull requests, and that its vulnerabilityFixStrategy defaults to the lowest version with a fix. Whichever tool opens the pull request, the reachability column and the decision stay with your team.
Updating a vulnerable package several levels down
When the affected copy is a transitive dependency, the fix has to fit every range between your package.json and that copy.
Work through the options in order of how much they change, starting with the smallest.
If every parent's range already allows the fixed version, npm update can move it. npm's documentation says npm update respects the semver constraints of both your package and its dependencies, and by default does not update the ranges of direct dependencies in package.json.
It also says npm prioritises having a single version of a package in the tree rather than two when that single version can satisfy the semver requirements of multiple dependencies.
npm audit fix runs a full npm install under the hood. Its documentation says that where remediations do not require changes to dependency ranges, all vulnerable packages are updated to a version without an advisory or meta-vulnerability posted against it.
Where the chain of meta-vulnerabilities reaches the root project and cannot be updated without changing its ranges, npm audit fix requires --force, which allows installs outside your stated range, including SemVer-major changes. npm's description of --force adds that if you don't have a clear idea of what you want to do, it is strongly recommended that you do not use it.
If a parent's range blocks the fix, look for a release of that parent whose range allows it. GitHub's documentation says that for npm, Dependabot raises a pull request to update an explicitly defined dependency to a secure version, which may mean updating the parent dependency or dependencies, or removing a sub-dependency the parent no longer needs.
OWASP's Component Analysis page gives the reason to prefer this route: any change to a transitive dependency can potentially break the code that depends on it, so it is most impactful to focus on identifying the direct dependency fix.
The same page says API changes can be expected between major versions of a component, but are rare between minor versions and patches. This page's advice follows from that: treat a parent update that crosses a major version as a code change, not a version bump.
When no parent release fits yet, the overrides field in your root package.json can replace a version anywhere in the tree. npm's documentation names replacing the version of a dependency with a known security issue as one of its uses, and lets you scope an override to a single parent, such as the text library only where the CMS client asks for it.
Overrides are only considered in the root package.json, and you may not set one for a package you depend on directly unless the dependency and the override share the exact same spec.
Forcing a new major version under a parent written for the old one can break at run time, so treat the override as code and test it.
Each package manager's own documentation describes its tools for this job, and they do not behave the same way.
- pnpm:pnpm why shows every package that depends on a given one, as a reverse dependency tree. pnpm's audit documentation suggests pnpm update first, then overrides to force versions that are not vulnerable, and pnpm audit --fix adds those overrides to pnpm-workspace.yaml. It notes that the registry's response does not include CVE identifiers, so advisories are identified by their GHSA ID.
- Yarn:yarn why prints the reasons a package appears in the dependency tree. yarn npm audit checks only the active workspace's direct dependencies by default, and -R (--recursive) extends it to transitive ones. The resolutions field forces a specific version and can only be set at the root of the project.
- Composer:composer audit checks installed packages against security advisories, and its --direct option limits the audit to packages the root package requires directly, skipping transitive dependencies; --locked audits from composer.lock instead of the vendor folder. composer depends, also called why, shows which packages depend on a given one.
- Renovate:its OSV-based vulnerability alerts, flagged as experimental, cover direct dependencies only, with uv projects as the one exception its documentation names.
Recording a decision not to update yet
Sometimes the right call is to wait: the fix needs a parent's next major release, the affected function is not reached, or the change needs testing you cannot finish yet.
A decision to wait is still a decision, and it needs the same evidence as an update.
The Vulnerability Exploitability eXchange (VEX) vocabulary gives such decisions a shared form. CISA's Minimum Requirements for VEX, published in April 2023, says a VEX statement conveys a single status for a single vulnerability and one or more products, and limits that status to four values: not_affected, affected, fixed and under_investigation.
A not_affected statement should provide a justification, and must provide an impact statement explaining how or why if it does not. The justifications are 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 says it does not represent official CISA policy and does not impose or mandate compliance. The SBOM guide, when it is published, covers VEX documents themselves; this page borrows only the vocabulary.
The justification that fits an unreached function is Vulnerable_code_not_in_execute_path, which the document describes as vulnerable code that cannot be executed due to the way the product uses it, typically because the product includes the vulnerable code but does not call or otherwise use it.
That is a claim about behaviour, so the record has to show how the team knows. The worked decision in the worksheet treats it this way, as this page's advice:
- The evidence is named: which files were searched, by what method, against which versions, on which date.
- The limits are written down: a text search misses calls made through computed names, generated or bundled code, and packages it was not pointed at.
- One named person makes the decision and another approves it.
- Triggers reopen it: a new version of the parent, a revised advisory, a new CVE alias or KEV listing, a new feature that uses the affected code, or the review date.
- The update is still planned, as this page's advice. In the VEX document, not_affected means no remediation or mitigation is required for the listed product; taking the fix on the normal release plan anyway gives the decision an end.
While the evidence is still coming in
under_investigation is the honest status while the evidence is gathered; the document expects it to change once the investigation has reached a conclusion. Once a decision is made, package managers let you silence the advisory: pnpm's audit.ignore setting for vulnerabilities that do not affect your project, Yarn's npmAuditIgnoreAdvisories option, and Composer's config.policy.advisories.ignore-id list, which takes advisory IDs and can record a reason for each.
Composer's configuration chapter marks the older audit.ignore key as deprecated in favour of that list, and says audit.ignore is ignored entirely once config.policy.advisories is set. Tie each ignore entry to its written record, so the silence ends when the decision does.
Proving the update took
A merged pull request is a claim that the vulnerable copy is gone.
Four pieces of evidence check it, and each is cheap to collect. Asking for all four is this page's advice:
- The lockfile diff. npm lists greater visibility of tree changes through readable source control diffs among the lockfile's purposes. The diff should show the affected copy's version, resolved address and integrity value changing, and nothing you did not expect.
- A clean install that followed the lockfile. npm ci removes any existing node_modules folder before it installs, and exits with an error if the dependencies in the lockfile do not match those in package.json. This page reads a passing npm ci on the build runner as evidence that the committed lockfile is the one being built.
- The installed version. npm ls or npm explain on the built tree shows which copies are present. Check every copy the worksheet listed: in the lab, the update moved the top-level copy to 2.3.2 and left the copy under the CMS client at 1.8.4.
- A repeat of the scan that raised the advisory. By default, npm audit exits with a non-zero code if any vulnerability is found, and its documentation says --audit-level does not filter the report output but only changes the failure threshold. Read the report, not just the exit code.
Keep the evidence with the row
Store the four with the worksheet row they close. If the same advisory appears in a later scan, the record shows whether the fix regressed, a second copy was missed, or the advisory itself changed its range.
What ASVS 5.0 and the OWASP Top 10 ask for
Two OWASP documents set out what to expect of the process, each in its own words.
OWASP says that, as a vendor-neutral nonprofit, it does not certify any vendors, verifiers or software. A report against these requirements is evidence for your own decision or a customer's, not a certificate.
- ASVS 5.0 requirement 15.1.1 (Level 1): application documentation defines risk-based remediation time frames for third-party component versions with vulnerabilities and for updating libraries in general.
- Requirement 15.1.2 (Level 2): 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.
- Requirement 15.1.4 (Level 3): application documentation highlights third-party libraries considered to be risky components. The chapter gives libraries that are poorly maintained, unsupported, at the end-of-life stage or with a history of significant vulnerabilities as examples.
- Requirement 15.2.1 (Level 1): the application only contains components which have not breached the documented update and remediation time frames.
- Requirement 15.2.4 (Level 3): third-party components and all of their transitive dependencies are included from the expected repository, with no risk of a dependency confusion attack.
- OWASP Top 10:2025 A03: its prevention list includes tracking transitive dependencies, removing unused dependencies, continuously monitoring sources like CVE, NVD and OSV for vulnerabilities in the components you use, and only obtaining components from official (trusted) sources over secure links. It also says to deliberately choose which version of a dependency you use and upgrade only when there is need.
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 worksheet and lab on this page are for your own team to keep between reviews.
Dependencies come into Clever Ops work as part of reviewing an application. A secure code review reads the lockfile against package.json, checks new packages and versions against published advisories, and reads what runs on its own at install, build or deploy time. 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.
Your developers, your agency or a Clever Ops security fix sprint under a separate statement of work can make the updates. 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
Software composition analysis lists the third-party components an application is built from and checks each one against what is known about it, such as published advisories. OWASP describes it as the software-only, limited-scope subset of component analysis, which it defines as identifying potential areas of risk from the use of third-party and open-source components. Deciding whether a match matters for your own code is the part the worksheet on this page is for.
A vulnerability in a package your application did not choose directly but installs because one of its dependencies asked for it. npm explain shows the chain from your package.json to that package, with the range each parent asks for. Whether npm update can fix it depends on whether every range on that chain allows the fixed version.
Where the fix fits the existing ranges, npm's documentation says npm audit fix updates the vulnerable packages. Where a chain of meta-vulnerabilities reaches your package.json and cannot be fixed without changing ranges, it needs --force, which can install SemVer-major changes, and npm strongly recommends against --force unless you have a clear idea of what you want to do. Updating the parent or setting an override are the other routes.
Make each private package name resolvable only from your own registry. In npm, publish private packages under a scope you own and associate that scope with your registry; npm says a scope only ever points to one registry. In pip, do not use --extra-index-url for private packages, which pip's documentation calls unsafe. In Composer 2, repositories are canonical by default. Then check the lockfile: every resolved host should be one you expect.
Plan to, but the urgency changes. If the fix fits your existing ranges, update anyway, because it is cheaper than the record. If it needs a parent's major upgrade, a not_affected decision with the justification Vulnerable_code_not_in_execute_path, the evidence behind it and the triggers that reopen it lets the update follow your normal release plan. A text search is evidence, not proof, so the record says what was searched and what it could not see.
It is part of one. It records the exact versions, where each package was resolved from and an integrity value for what was unpacked. It only protects installs that follow it, such as npm ci, which exits with an error rather than rewriting the lockfile when package.json disagrees. A regression test that checks resolved hosts and integrity values turns the file into something a build can fail on.
No. Clever Ops does not monitor dependencies or sell a scanning subscription. A secure code review reads the lockfile against package.json and checks packages and versions against published advisories for the build reviewed. The worksheet on this page is for your team to keep 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.