🛡️ Supply Chain Inspector

A standalone, zero-dependency Node.js script for supply chain security analysis of npm dependencies. Queries public security APIs for every package and delivers a formatted terminal report and a shareable standalone HTML report — with no install step required.

Features

Vulnerability scanning via OSV.dev — known CVEs and security advisories, severity-ranked (Critical / High / Medium / Low)
CISA KEV cross-reference — automatically checks every discovered CVE against the CISA Known Exploited Vulnerabilities catalog, highlighting packages with actively exploited vulnerabilities in a dedicated alert section (CLI and HTML), with vendor, product, due date, required action, and ransomware campaign flag
Project health scoring via OpenSSF Scorecard — 10+ automated checks covering code review, branch protection, signed releases, and more
Install-script detection — flags packages that run preinstall, postinstall, prepare, and other lifecycle hooks (a common malware vector)
Publisher history — tracks who published each version to spot account takeovers
Version history — configurable look-back window for detecting dormancy, publish bursts, or suspicious major jumps
Transitive dependency support — optionally scan every resolved package in package-lock.json, not just direct dependencies
Lockfile-aware — auto-detects package-lock.json for exact pinned versions instead of resolving from semver ranges
File cache — API responses are cached to disk with stale-while-revalidate semantics (npm: 24 h, OSV: 12 h, Scorecard: 48 h, CISA KEV: 48 h) so repeated runs are fast and network-friendly. Stale data is served instantly while a background refresh updates the cache for the next invocation. TTLs are configurable via --ttl-npm, --ttl-osv, --ttl-scorecard, --ttl-kev.
In-flight deduplication — concurrent workers that request the same package or repo share one HTTP request instead of firing duplicates
Zero dependencies — uses Node.js 18+ built-in fetch; nothing to install

Quick Start

# Run directly via npx — no install needed
npx supply-chain-inspector path/to/package.json

# Inspect a single npm package directly (no package.json needed)
npx supply-chain-inspector lodash-es
npx supply-chain-inspector @nx/jest

# Or use a URL to a remote package.json
npx supply-chain-inspector https://raw.githubusercontent.com/angular/angular/refs/heads/main/package.json

# Or install globally once to get the short "sci" alias
npm install -g supply-chain-inspector
sci path/to/package.json

# Or clone/copy the script and run it locally
npx supply-chain-inspector path/to/package.json

Typical output:

Supply Chain Inspector
Package: my-app 1.0.0
Source:  /home/user/my-app/package.json
Lockfile: /home/user/my-app/package-lock.json (312 resolved versions)
Cache:    /home/user/my-app/.cache

Inspecting 14 package(s) — concurrency: 5

  → express  (^4.18.2)
  → lodash   (^4.17.21)
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SUPPLY CHAIN REPORT  ·  [email protected]  ·  14 package(s)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  PACKAGE           VERSION     VULNS          SCORECARD        SCRIPTS
  ─────────────────────────────────────────────────────────────────────────────
  express           4.18.3      0              ████████░░ 7.8   ─
  lodash            4.17.21     1 high         ██████░░░░ 5.2   ─
  ...

Usage

# Via npx (no install required)
npx supply-chain-inspector <path/to/package.json|url|npm-package> [options]

# Via short alias (requires: npm install -g supply-chain-inspector)
sci <path/to/package.json|url|npm-package> [options]

# Or if running the script directly
npx supply-chain-inspector <path/to/package.json|url|npm-package> [options]

Input can be:

npm package name — inspect a single package directly: lodash-es, @nx/jest, [email protected]
Local file path: package.json or path/to/package.json
Remote URL: https://raw.githubusercontent.com/user/repo/refs/heads/main/package.json

When an npm package name is provided (not a file path or URL), the tool inspects that single package directly against the npm registry. Supports scoped (@scope/name) and versioned (name@version) specs. All CLI options (--json, --html, --graph, --no-scorecard, etc.) work in this mode.

Note: When using a remote URL, the lockfile (package-lock.json) is automatically fetched from the same directory. You can also explicitly specify a lockfile URL using --lockfile=<url>.

If package-lock.json is missing for a remote URL, the tool falls back to npm-registry resolution. When --include-transitive is enabled, the CLI also checks for a sibling pnpm-lock.yaml and prints a clear note when it is detected but not supported for transitive resolution.

Options

Dependency Scope

By default only dependencies (production) are scanned.

Flag	Description
`--include-dev`	Also inspect `devDependencies`
`--include-peer`	Also inspect `peerDependencies`
`--include-optional`	Also inspect `optionalDependencies`
`--include-transitive`	Also inspect every transitive package resolved in `package-lock.json`, deduplicated by `name@version`. Packages already present as direct deps are skipped. Requires a lockfile.

Version History

--version-history=<N>    Versions to keep per package (default: 10, min: 2)

Value	What it enables
`2`	Downgrade / major-jump detection only
`5`	+ Rapid publish burst + dormancy detection
`10`	+ Cadence baseline (recommended)
`20+`	Broader history, larger JSON output

Data Collection

Flag	Description
`--concurrency=<N>`	Max parallel package fetches (default: `5`)
`--verbose`	Show per-package fetch/progress logs (`→ package` and `✓ package@version`). By default these lines are hidden to reduce noise.
`--lockfile=<path\|url>`	Path or URL to `package-lock.json` (auto-detected next to `package.json` if omitted; for remote URLs, auto-detects `package-lock.json` in same directory)
`--no-scorecard`	Skip OpenSSF Scorecard lookups (faster, useful offline)
`--no-vulns`	Skip OSV.dev vulnerability lookups
`--no-kev`	Skip the CISA KEV cross-reference (also skipped automatically when `--no-vulns` is set, since there are no CVEs to match)

Cache

Flag	Description
`--cache-dir=<path>`	Directory for cached API responses (default: `.cache/` next to the script)
`--no-cache`	Disable file cache; always fetch live data

Cache uses stale-while-revalidate: within the soft TTL the entry is a fresh hit (no network). Past the soft TTL but within the hard TTL, stale data is served instantly and a background refresh updates the cache file for the next run. Past the hard TTL the entry is expired and a fresh fetch blocks as usual.

Source	Hard TTL	Soft TTL	Rationale
npm Registry	24 h	6 h	Metadata rarely changes within hours
OSV.dev	12 h	2 h	Vulnerability data is stable within hours
OpenSSF Scorecard	48 h	12 h	Scores are recomputed weekly by OpenSSF
CISA KEV	48 h	12 h	Catalog is updated weekly

TTLs can be overridden per data source (values in hours):

Flag	Description
`--ttl-npm=<hours>`	npm registry hard TTL (default: 24). Soft TTL derived as 25% of hard.
`--ttl-osv=<hours>`	OSV.dev hard TTL (default: 12)
`--ttl-scorecard=<hours>`	Scorecard hard TTL (default: 48)
`--ttl-kev=<hours>`	CISA KEV hard TTL (default: 48)

Report

Flag	Description
`--findings`	Show per-package findings detail below the summary table. By default only the table is shown; a one-line hint indicates how many packages have signals.
`--fail-on=<level>`	Exit with code 1 if vulnerabilities at or above the specified severity are found. Valid levels: `low`, `medium`, `high`, `critical` (default: `critical`). When set to `low`, any vulnerability will cause a failure. When set to `critical`, only critical vulnerabilities trigger a failure.
`--fail-licenses=<licenses>`	Exit with code 1 if any dependency uses a restricted (copyleft) license. Accepts a comma-separated list: `GPL,AGPL,LGPL`. Normalizes automatically: `GPL-3.0-or-later` → `GPL-3.0` → `GPL`. Works independently of `--fail-on`.
`--no-kev`	Skip the CISA KEV cross-reference entirely. Without this flag, any KEV match always causes exit code 1, regardless of `--fail-on` level — see KEV Alert.

Output

Flag	Description
`--json`	Print the full result array as JSON to stdout
`--output=<path>`	Write JSON to a file (implies `--json`)
`--html[=<path>]`	Write a fully standalone HTML security report to a file (no server or internet connection required to view). Defaults to `report.html` when no path is given.
`--graph[=<path>]`	Write a standalone vis-network dependency graph report to a file. Graph root is `name@version` when available (falls back to `name`, then `package.json`), with scope nodes (`dependencies`, `devDependencies`, etc.) and package child nodes. Defaults to `graph-report.html` when no path is given.
`--graph-no-dev`	In npm-package graph mode (e.g. `npx supply-chain-inspector vite --graph`), hide `devDependencies` in the graph. By default all scopes are included.

Color

Set NO_COLOR=1 in the environment to disable ANSI colors. Colors are also automatically disabled when stderr is not a TTY (e.g. piped output).

Output Modes

The formatted report always goes to stderr. stdout is reserved exclusively for JSON so you can pipe cleanly.

# Report only
npx supply-chain-inspector package.json

# Report (stderr) + JSON (stdout)
npx supply-chain-inspector package.json --json

# Save JSON to file (implies --json)
npx supply-chain-inspector package.json --output=results.json

# HTML report (default: report.html)
npx supply-chain-inspector package.json --html

# Graph report (default: graph-report.html)
npx supply-chain-inspector package.json --graph

# In npm-package graph mode, hide devDependencies
npx supply-chain-inspector vite --graph --graph-no-dev

# HTML + JSON side by side
npx supply-chain-inspector package.json --html=report.html --output=results.json

# JSON only (suppress report)
npx supply-chain-inspector package.json --json 2>/dev/null

Common Recipes

# Inspect a single npm package
npx supply-chain-inspector lodash-es

# Inspect a scoped package with a pinned version
npx supply-chain-inspector @angular/[email protected]

# Full app scan (direct + dev + peer)
npx supply-chain-inspector package.json \
  --include-dev --include-peer \
  --output=scan.json

# HTML report (default filename)
npx supply-chain-inspector package.json --html

# Dependency graph report
npx supply-chain-inspector package.json --graph

# Remote package.json (auto-detects remote lockfile)
npx supply-chain-inspector https://raw.githubusercontent.com/angular/angular/refs/heads/main/package.json

# Inspect remote package.json with explicit remote lockfile URL
npx supply-chain-inspector https://raw.githubusercontent.com/user/repo/main/package.json \
  --lockfile=https://raw.githubusercontent.com/user/repo/main/package-lock.json

# Include transitive dependencies (requires lockfile)
npx supply-chain-inspector https://raw.githubusercontent.com/user/repo/main/package.json \
  --include-transitive --findings

# Show detailed per-package fetch/progress logs
npx supply-chain-inspector package.json --verbose

# Deep scan (all scopes + transitive + findings)
npx supply-chain-inspector package.json \
  --include-dev --include-peer --include-optional --include-transitive \
  --findings

# Faster scan (skip Scorecard)
npx supply-chain-inspector package.json --no-scorecard

# CI fail on high or critical vulnerabilities
npx supply-chain-inspector package.json --fail-on=high

# CI fail on restricted licenses (fixture example)
npx supply-chain-inspector https://raw.githubusercontent.com/DenysVuika/supply-chain-inspector/main/assets/test-license-package.json --fail-licenses="GPL,AGPL,LGPL"

# Force fresh data, bypassing any cached responses
npx supply-chain-inspector package.json --no-cache

# Use a shared cache directory for multiple projects
npx supply-chain-inspector package.json --cache-dir=~/.supply-chain-cache

# Extend cache TTLs for a CI environment (hours)
npx supply-chain-inspector package.json --ttl-npm=48 --ttl-osv=24

You can combine these patterns as needed (for example: --html --output --findings).

Security Signals

The --findings flag expands details for any package that triggers one or more of the following signals:

Signal	Meaning
`vulns`	One or more known CVEs or advisories from OSV.dev
`scripts`	Package declares lifecycle scripts (`preinstall`, `postinstall`, `prepare`, etc.)
`low_scorecard`	OpenSSF Scorecard score below 5 / 10
`very_recent`	Package version was published fewer than 48 hours ago
`no_repo`	No source repository URL found in the npm registry entry
`not_found`	Package could not be found on the npm registry at all

Separately from the per-package findings, a KEV alert section is shown at the bottom of the report (above the footer totals in the CLI; above the Findings section in the HTML report) whenever one or more discovered CVEs appear in the CISA Known Exploited Vulnerabilities catalog. Each KEV match shows:

Package name and version
CVE ID and severity badge
Vendor / product as listed by CISA
Date the CVE was added to the catalog and the remediation due date
Required action text from CISA
A ransomware campaign flag when applicable
Direct link to the CISA KEV catalog

JSON Output Structure

Each element of the output array represents one inspected package:

{
  "name": "express",
  "versionSpec": "^4.18.2",
  "resolvedVersion": "4.18.3",
  "lockfileVersion": "4.18.3",
  "scope": "dependencies",
  "ecosystem": "npm",
  "sourceRepository": "https://github.com/expressjs/express",
  "notFound": false,
  "collectedAt": "2025-01-15T10:23:00.000Z",

  "registry": {
    "name": "express",
    "publishedHoursAgo": 2160,
    "publisher": "dougwilson",
    "hasInstallScripts": false,
    "repository": "https://github.com/expressjs/express",
    "homepage": "https://expressjs.com",
    "license": "MIT",
    "directDependencies": 30,
    "dependencyCount": 30,
    "devDependencyCount": 14,
    "peerDependencyCount": 0,
    "unpackedSize": 210000,
    "integrity": "sha512-...",
    "tarball": "https://registry.npmjs.org/express/-/express-4.18.3.tgz",
    "maintainers": ["dougwilson", "wesleytodd"]
  },

  "versionHistory": [
    { "version": "4.18.3", "date": "2024-03-01T00:00:00.000Z" },
    { "version": "4.18.2", "date": "2022-10-08T00:00:00.000Z" }
  ],

  "publisherHistory": [
    { "version": "4.18.3", "publisher": "wesleytodd" },
    { "version": "4.18.2", "publisher": "dougwilson" }
  ],

  "vulnerabilities": {
    "summary": {
      "total": 0,
      "critical": 0,
      "high": 0,
      "medium": 0,
      "low": 0,
      "unknown": 0
    },
    "list": [],
    "error": null
  },

  "scorecard": {
    "score": 7.8,
    "repoChecked": "github.com/expressjs/express",
    "checks": [
      { "name": "Code-Review", "score": 10, "reason": "all changesets reviewed" },
      { "name": "Branch-Protection", "score": 8, "reason": "..." }
    ],
    "signals": {
      "maintained": 10,
      "codeReview": 10,
      "vulnerabilities": 10,
      "signedReleases": -1,
      "branchProtection": 8,
      "securityPolicy": 9,
      "dangerousWorkflow": 10,
      "binaryArtifacts": 10,
      "pinned": 2,
      "ciTests": 9
    },
    "error": null
  }
}

Field Reference

Field	Description
`name`	Package name as it appears in `package.json`
`versionSpec`	The version range or tag from `package.json` (e.g. `^4.18.2`)
`resolvedVersion`	The actual version that was inspected (from lockfile or registry)
`lockfileVersion`	The version pinned in `package-lock.json`, if available
`scope`	Which dependency group this came from (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`, `transitive`, `direct` when inspecting a single npm package)
`notFound`	`true` if the package could not be found on the npm registry
`collectedAt`	ISO 8601 timestamp of when the data was collected
`registry.hasInstallScripts`	`true` if the package declares any lifecycle scripts
`registry.publishedHoursAgo`	How many hours ago the resolved version was published
`versionHistory`	Last N versions with publish dates (N set by `--version-history`)
`publisherHistory`	Who published each of the last N versions
`vulnerabilities.summary`	Counts by severity from OSV.dev
`vulnerabilities.list`	Full advisory details including CVE IDs, aliases, and affected ranges
`scorecard.score`	Aggregate OpenSSF Scorecard score out of 10 (null if unavailable)
`scorecard.signals`	Individual check scores (−1 = not applicable)

Data Sources

Source	URL	Data provided
npm Registry	`https://registry.npmjs.org`	Package metadata, version history, maintainers, install scripts, tarball integrity
OSV.dev	`https://api.osv.dev/v1/query`	Known CVEs and security advisories
OpenSSF Scorecard	`https://api.scorecard.dev`	Project health (17 automated checks)
CISA KEV	`https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json`	Confirmed actively exploited vulnerabilities

All four sources are public and unauthenticated — no API tokens required.

KEV Alert

After all packages have been scanned, Supply Chain Inspector cross-references every discovered CVE (including OSV aliases such as GHSA-*) against the CISA Known Exploited Vulnerabilities (KEV) catalog. The KEV catalog lists vulnerabilities confirmed by CISA to be actively exploited in the wild, often with a federal remediation due date.

When matches are found:

CLI — a bright-red ▲ KNOWN EXPLOITED VULNERABILITIES banner is printed below the Findings section with per-match detail and a direct link to the catalog. The footer chip also shows ▲ N KEV matches.
HTML report — a dedicated red alert card section appears above Findings, with a grid of metadata per match (vendor, product, dates, required action, ransomware flag).

A ready-made test fixture is included at assets/test-kev-package.json — it pins known-vulnerable versions of several packages so you can reproduce KEV matches locally:

npx supply-chain-inspector https://raw.githubusercontent.com/DenysVuika/supply-chain-inspector/main/assets/test-kev-package.json

Example CLI output when matches exist:

──────────────────────────────────────────────────────────────────────────────────────────
  ▲ KNOWN EXPLOITED VULNERABILITIES (CISA KEV)  ·  2 matches with actively exploited CVEs
──────────────────────────────────────────────────────────────────────────────────────────

  ● [email protected]  [MEDIUM  ]  GHSA-2m8v-572m-ff2v
    Command Injection Vulnerability
    Vendor / Product:  Npm package — System Information Library for Node.JS
    Added to KEV:      2022-01-18  ·  Due: 2022-02-01
    Required action:   Apply updates per vendor instructions.
    https://www.cisa.gov/known-exploited-vulnerabilities-catalog

  ● [email protected]  [MEDIUM  ]  GHSA-h47j-hc6x-h3qq
    Remote Code Execution Vulnerability in NPM mongo-express
    Vendor / Product:  MongoDB — mongo-express
    Added to KEV:      2021-12-10  ·  Due: 2022-06-10
    Required action:   Apply updates per vendor instructions.
    https://www.cisa.gov/known-exploited-vulnerabilities-catalog

──────────────────────────────────────────────────────────────────────────────────────────

Exit behaviour

KEV matches always cause the script to exit with code 1, independently of --fail-on. This is intentional: a CVE in the KEV catalog has confirmed real-world exploitation right now, making it more urgent than any theoretical severity rating. The two failure paths are complementary and can both fire in the same run:

Condition	Exit code
KEV match(es) found (and `--no-kev` not set)	`1` — always
Vulnerabilities at or above `--fail-on` threshold	`1`
No KEV matches and no `--fail-on` trigger	`0`

Use --no-kev to opt out of KEV hard-failure (e.g. in offline environments or when triaging KEV matches separately). The KEV catalog is cached for 48 hours (soft: 12 h) alongside other API responses.

pre-commit Integration

Supply Chain Inspector can be used as a pre-commit hook so it runs automatically whenever package.json is staged in any repository.

Setup

Add the following to your repository's .pre-commit-config.yaml:

repos:
  - repo: https://github.com/DenysVuika/supply-chain-inspector
    rev: v1.0.0  # replace with the desired tag or commit SHA
    hooks:
      - id: supply-chain-inspector
        args: [--fail-on=high] # Optional: fail the commit if any high or critical vulnerabilities are found (default: critical)

Then install the hooks (if you haven't already):

pre-commit install

How it works

The hook triggers only when package.json is part of the staged files.
pre-commit installs the package via npm into an isolated environment — no global install required.
The package.json path is passed automatically as an argument.
In a monorepo with multiple package.json files, each staged one is scanned independently.

CI Integration

By default, the script exits with code 0 regardless of findings (advisory mode), with two exceptions that always produce exit code 1:

KEV matches — any CVE confirmed in the CISA Known Exploited Vulnerabilities catalog causes an immediate hard failure (bypass with --no-kev).
--fail-on=<level> — exit code 1 when vulnerabilities at or above the specified severity threshold are found.

Both checks are independent and can both fire in the same run, each printing its own failure box before the process exits.

# GitHub Actions example — fail on high/critical vulns AND any KEV match
- name: Supply chain scan
  run: |
    NO_COLOR=1 npx supply-chain-inspector package.json \
      --findings \
      --fail-on=high \
      --output=supply-chain.json \
      --html=supply-chain.html \
      2>&1 | tee supply-chain-report.txt

# To disable the KEV hard-fail (e.g. triaging KEV matches separately):
#   add --no-kev to the command above

- name: Upload scan results
  uses: actions/upload-artifact@v4
  with:
    name: supply-chain
    path: |
      supply-chain-report.txt
      supply-chain.json
      supply-chain.html

License

See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github		.github
assets		assets
src		src
tests		tests
.gitignore		.gitignore
.nvmrc		.nvmrc
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
.releaserc.json		.releaserc.json
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🛡️ Supply Chain Inspector

Features

Quick Start

Usage

Options

Dependency Scope

Version History

Data Collection

Cache

Report

Output

Color

Output Modes

Common Recipes

Security Signals

JSON Output Structure

Field Reference

Data Sources

KEV Alert

Exit behaviour

pre-commit Integration

Setup

How it works

CI Integration

License

About

Uh oh!

Releases 16

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🛡️ Supply Chain Inspector

Features

Quick Start

Usage

Options

Dependency Scope

Version History

Data Collection

Cache

Report

Output

Color

Output Modes

Common Recipes

Security Signals

JSON Output Structure

Field Reference

Data Sources

KEV Alert

Exit behaviour

pre-commit Integration

Setup

How it works

CI Integration

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 16

Contributors

Uh oh!

Languages