onamfc/npm-vulnerability-scanner

A defensive security tool that scans npm packages for vulnerabilities before installation, helping protect your system from compromised packages.

NPM Vulnerability Scanner

A defensive security tool that scans npm packages for vulnerabilities before installation, helping protect your system from compromised packages.

Why Use This Tool?

This scanner allows you to check for known vulnerabilities in npm packages BEFORE running npm install, protecting your system from potentially malicious or compromised packages.

Features

• Scans single package.json files
• Supports npm workspaces (monorepos with multiple package.json files)
• Color-coded vulnerability severity levels
• Detailed vulnerability reports with recommendations
• Returns non-zero exit code when vulnerabilities are found (CI/CD friendly)

Installation

npm install -g @onamfc/npm-vuln-scanner

Or use with npx without installing:

npx @onamfc/npm-vuln-scanner

Usage

Command Line

Scan the current directory:

npm-vuln-scan

Scan a specific directory:

npm-vuln-scan /path/to/project

Programmatic Usage

const { scanPackages } = require('@onamfc/npm-vuln-scanner');

async function checkProject() {
  const { success, results } = await scanPackages('/path/to/project');

  if (!success) {
    console.log('Vulnerabilities found!');
    console.log(results);
  }
}

checkProject();

How It Works

1. Discovers all package.json files in the target directory
2. For workspace projects, finds all workspace package.json files
3. Queries the npm registry audit API for each package
4. Reports vulnerabilities by severity (Critical, High, Moderate, Low)
5. Provides detailed information and remediation recommendations

Vulnerability Severity Levels

• Critical: Immediate action required
• High: Address as soon as possible
• Moderate: Review and plan to address
• Low: Review at your convenience

Exit Codes

• 0: No vulnerabilities found or scan completed successfully
• 1: Vulnerabilities found or scan error

Use in CI/CD

Add to your CI pipeline to prevent deployment of vulnerable dependencies:

- name: Scan for vulnerabilities
  run: npx @onamfc/npm-vuln-scanner

Contributing

This is an open source project. Contributions are welcome!

License

MIT