🛡️ 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)
• 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 (npm: 6 h, OSV: 6 h, Scorecard: 24 h) so repeated runs are fast and network-friendly
• 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

Requirements

• Node.js 18 or later (uses native fetch)
• No npm install required — the script is fully self-contained, or use npx to run it directly from the registry

Quick Start

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

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

# Or install as a dev dependency and run via npx
npm install --save-dev supply-chain-inspector
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> [options]

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

# Or as a local dev dependency
npx supply-chain-inspector <path/to/package.json> [options]

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 TTLs are fixed and not configurable. Delete cache files manually to force an early refresh:

Report

Output

Exit Code / CI Gate

By default the script exits with 0 regardless of findings. The flags below turn it into a hard gate that fails with exit code 1 when vulnerabilities at or above the chosen severity are found — suitable for CI pipelines, pre-commit hooks, and lint-staged.

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 — clean terminal view, no JSON noise
npx supply-chain-inspector package.json

# Report on stderr + JSON on stdout — pipe JSON to another tool
npx supply-chain-inspector package.json --json

# Report on stderr + JSON saved to a file — review both independently
npx supply-chain-inspector package.json --output=results.json

# Write a standalone HTML report — open report.html in any browser
npx supply-chain-inspector package.json --html=report.html

# HTML report + JSON side by side (useful for both humans and tooling)
npx supply-chain-inspector package.json --html=report.html --output=results.json

# Suppress the report, get only JSON (useful for scripting)
npx supply-chain-inspector package.json --json 2>/dev/null

# Pipe JSON straight into an AI tool
npx supply-chain-inspector package.json --json | llm "analyze these deps"

Common Recipes

# Scan all dependency groups, save JSON for later AI analysis
npx supply-chain-inspector package.json \
  --include-dev --include-peer \
  --output=scan.json

# Generate an HTML report for easy sharing with your team
npx supply-chain-inspector package.json --html=report.html

# Full scan with HTML report, JSON data, and findings detail
npx supply-chain-inspector package.json \
  --include-dev --include-peer \
  --output=scan.json --html=report.html --findings

# Full deep scan — all groups, all transitive deps, with findings detail
npx supply-chain-inspector package.json \
  --include-dev --include-peer --include-optional --include-transitive \
  --findings

# Quick scan — skip Scorecard (no outbound calls to api.scorecard.dev)
npx supply-chain-inspector package.json --no-scorecard

# High concurrency for large lockfiles (mind API rate limits)
npx supply-chain-inspector package.json --concurrency=10

# CI-friendly: plain text, no color, output to log file
NO_COLOR=1 npx supply-chain-inspector package.json 2>&1 | tee security-report.txt

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

# Share a single cache across multiple projects to avoid redundant API calls
npx supply-chain-inspector package.json --cache-dir=~/.supply-chain-cache

# Inspect only production deps with narrow version history (fastest)
npx supply-chain-inspector package.json --version-history=2 --no-scorecard

Security Signals

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

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 three sources are public and unauthenticated — no API tokens required.

Pre-commit Hooks / lint-staged

--fail-on / --ci make the script a drop-in lint-staged linter. lint-staged automatically appends the staged file path to the command, which aligns perfectly with the script's positional <path/to/package.json> argument.

Setup

npm install --save-dev husky lint-staged
npx husky init

.lintstagedrc.json

{
  "package.json": "supply-chain-inspector --ci --include-dev"
}

Or inline inside package.json:

{
  "lint-staged": {
    "package.json": "supply-chain-inspector --ci --include-dev"
  }
}

.husky/pre-commit

#!/usr/bin/env sh
npx lint-staged

How it works

1. You stage a package.json change (new dependency, version bump, etc.).
2. On git commit, husky runs lint-staged.
3. lint-staged calls supply-chain-inspector --ci --include-dev <staged-package.json>.
4. The script inspects all dependencies, prints the full report to stderr, then checks the vulnerability totals.
5. Critical CVEs found → exits 1 → commit is blocked with a summary line showing the counts (critical:N high:N medium:N low:N).
6. No issues at the threshold → exits 0 → commit proceeds normally.

Adjust the threshold to suit your policy:

Tip: Pass --no-cache if you want lint-staged to always fetch live data rather than serving cached results from a previous run.

CI Integration

Use --fail-on (or --ci) to make the scan a hard gate in your pipeline. Pipe stderr to your log system and upload the JSON / HTML artifacts for later review.

# GitHub Actions — fail the build on critical CVEs, upload artefacts
- name: Supply chain scan
  run: |
    NO_COLOR=1 npx supply-chain-inspector package.json \
      --ci \
      --include-dev \
      --findings \
      --output=supply-chain.json \
      --html=supply-chain.html \
      2>&1 | tee supply-chain-report.txt

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

For a non-blocking advisory run (report only, never fails the build), omit --ci / --fail-on:

- name: Supply chain audit (advisory)
  run: |
    NO_COLOR=1 npx supply-chain-inspector package.json \
      --findings \
      --output=supply-chain.json \
      2>&1 | tee supply-chain-report.txt

License

See LICENSE.