NPM Vulnerability Scanner Suite

Standalone tools for auditing NPM package vulnerabilities and comparing reports over time. Zero dependencies required.

Overview

This suite provides two complementary tools:

Tool	Purpose
npm-vuln-scanner.js	Scans any npm project for security vulnerabilities
compare-reports.js	Compares two vulnerability reports to track changes

Both scripts are completely standalone — no npm install needed. They use only Node.js built-in modules.

---

Prerequisites

• Node.js 18+ (required for native fetch() API)

Check your version:

node --version

---

1. Vulnerability Scanner

npm-vuln-scanner.js — Scan any npm project for security vulnerabilities.

Features

• 🔍 Scans any project directory (doesn't contaminate target project)
• 📊 Queries OSV database for CVEs, CVSS scores, and fix versions
• ⚠️ Flags vulnerabilities with known public exploits
• 🔗 Shows full dependency chains (e.g., root → express → body-parser)
• 🏷️ Distinguishes direct vs transitive dependencies
• 📅 Reports when each vulnerability was published
• ⚡ Parallel OSV requests with rate limiting
• 🎨 Grouped Markdown output by severity

Usage

# Basic scan of current directory
node npm-vuln-scanner.js

# Scan specific project
node npm-vuln-scanner.js /path/to/project

# Filter to critical/high only
node npm-vuln-scanner.js /path/to/project --severity critical,high

# Only direct dependencies
node npm-vuln-scanner.js /path/to/project --only-direct

# Exclude devDependencies (faster for production scans)
node npm-vuln-scanner.js /path/to/project --exclude-dev

# Custom output directory
node npm-vuln-scanner.js /path/to/project --output-dir ./reports

# Faster OSV fetching
node npm-vuln-scanner.js /path/to/project --concurrency 10

Output Files

File	Description
VULNERABILITY_REPORT.md	Human-readable report with severity groups
VULNERABILITY_REPORT.csv	Machine-readable data for further analysis

Report Columns

Column	Description
Package	Vulnerable package name
Parent Dependency	Immediate parent in dependency tree
Full Chain	Complete path from root to vulnerable package
Severity	critical / high / moderate / low / info
CVE	CVE identifier from OSV
GHSA	GitHub Security Advisory ID
CVSS Score	Numerical severity (0-10)
Affected Version	Version ranges that are vulnerable
Fix Version	Patched version(s) available
Has Exploit	⚠️ Warning if public exploits exist
Published	Date vulnerability was disclosed
Dependency Type	Direct or Transitive

---

2. Report Comparator

compare-reports.js — Compare two vulnerability reports to see what changed.

Features

• 📈 Tracks fixed, remaining, and newly introduced vulnerabilities
• 🔢 Net change calculation
• 🚨 Exit code 2 if new critical vulnerabilities found (CI-friendly)
• 📊 Severity breakdown for each category

Usage

# Compare old and new reports
node compare-reports.js VULNERABILITY_REPORT_old.csv VULNERABILITY_REPORT.csv

# With output directory
node compare-reports.js old.csv new.csv --output-dir ./comparisons

# In CI pipeline (fails if new critical issues)
node compare-reports.js old.csv new.csv || echo "Critical vulnerabilities detected!"

Output Files

File	Description
VULNERABILITY_COMPARISON.md	Side-by-side comparison with summaries
VULNERABILITY_COMPARISON.csv	Combined data with ChangeStatus column

Comparison Report Sections

• Executive Summary — Totals, net change, high-level metrics
• ✅ Fixed — Vulnerabilities that were resolved
• ⚠️ Remaining — Vulnerabilities still present from old scan
• 🔴 Newly Introduced — Vulnerabilities that appeared in new scan

Exit Codes

Code	Meaning
0	Success, no new critical issues
1	Error (file not found, parse error, etc.)
2	New critical vulnerabilities detected

---

Typical Workflow

1. Initial Scan

# Save as baseline
node npm-vuln-scanner.js /path/to/project
cp VULNERABILITY_REPORT.csv VULNERABILITY_REPORT_baseline.csv

2. After Updates

# Re-scan after npm update
node npm-vuln-scanner.js /path/to/project

# Compare to baseline
node compare-reports.js VULNERABILITY_REPORT_baseline.csv VULNERABILITY_REPORT.csv

3. CI Integration

# Store last known good report
node npm-vuln-scanner.js .
node compare-reports.js known-good.csv VULNERABILITY_REPORT.csv
# Exit code 2 breaks the build if new critical issues found

---

How It Works

Scanner Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│  package.json   │────▶│   npm audit  │────▶│   Audit     │
│  package-lock   │     │  (in target  │     │   JSON      │
│  (target proj)  │     │   directory) │     │             │
└─────────────────┘     └──────────────┘     └──────┬──────┘
                                                      │
                              ┌───────────────────────┘
                              ▼
                       ┌──────────────┐
                       │  Extract     │
                       │Vulnerabilities│
                       └──────┬───────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐    ┌──────────┐    ┌──────────┐
        │  CVE     │    │  CVSS    │    │  Fix     │
        │  Lookup  │    │  Score   │    │  Version │
        │  (OSV)   │    │  (OSV)   │    │  (OSV)   │
        └──────────┘    └──────────┘    └──────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │   Generate   │
                       │   Reports    │
                       │  (MD + CSV)  │
                       └──────────────┘

Comparison Logic

Vulnerabilities are matched by Package Name + GHSA ID, ensuring accurate tracking even if severity scores change over time.

---

Limitations

• OSV API Dependency: Requires internet connection; rate limited
• Node 18+ Required: Uses native fetch() API
• npm audit Limitations: Inherits any false positives/negatives from npm's audit
• semver Approximation: Minimal inlined semver handles common patterns but may not cover all edge cases

---

Troubleshooting

"package-lock.json not found"

Run npm install in the target project first.

"npm audit failed"

Ensure the target project has a valid package.json and node_modules.

Empty reports

Check that the project actually has dependencies with npm ls.

OSV timeouts

Reduce concurrency: --concurrency 2

---

License

These scripts are provided as-is for security auditing purposes. Use at your own risk.