🛡️ 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  ·  my-app@1.0.0  ·  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, react@18.2.0
• 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.

Version History

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

Data Collection

Cache

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.

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

Report

Output

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/core@17.0.0

# 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:

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

Data Sources

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
──────────────────────────────────────────────────────────────────────────────────────────

  ● systeminformation@5.3.0  [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

  ● mongo-express@0.53.0  [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:

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.