npm-vulnerability-analysis

NPM Vulnerability Analysis Skill

Prerequisites

• WebSearch tool available
• Internet connection
• Node.js environment (version 22 or higher)

Input

User provides:

• Package Name (required): The name of the npm package to analyze (e.g., "lodash", "fastify")
• Version Range (optional): Specific versions or version range to analyze.
  • English: "4.17.10-4.17.21", "latest 10"
  • Chinese: "latest 10", "4.17.10 to 4.17.21"
  • Defaults to "latest 10"
• Generate Report (optional): Whether to generate a detailed markdown, CSV, and HTML report, defaults to true.
• Report Output Path (optional): Directory path to save the generated report files (Markdown, CSV, HTML). Defaults to the reports directory in the project root (automatically created if missing).

Overview

This skill enables comprehensive security analysis of npm packages across different versions, helping identify safe version ranges, track vulnerability trends, and make informed dependency decisions. It supports npm, pnpm, and yarn package managers and provides tools for scanning, analysis, and reporting. It also supports both English and Chinese input for version ranges.

Best Practices for AI Agent

When acting as an AI agent using this skill, follow these guidelines to ensure consistent and high-quality results:

1. Prefer scripts/index.js: Always start with the main entry point scripts/index.js for standard analysis tasks. It handles the complete workflow: scanning, analysis, and report generation (Markdown, HTML, CSV).

   • Do not create custom scripts that replicate this logic unless the user has a specific requirement that cannot be met by the existing tools.
   • Do not manually call analyze_version_range.js or data_aggregator.js individually if scripts/index.js can satisfy the request.

2. Verify Report Generation: After running the analysis, verify that the expected report files (HTML, CSV, Markdown) have been generated in the specified output directory.

   • If reports are missing, check if the --no-report flag was accidentally used or if the workflow was interrupted.

3. Use Absolute Paths: When specifying output directories or file paths, always use absolute paths to avoid ambiguity.

4. Leverage Existing Tools: If you need to perform a sub-task (e.g., just scanning one version), use the specialized scripts (scripts/scan_version.js) instead of writing new code to run npm audit.

Quick Start

Recommended: One-Step Analysis

Use the master script to scan versions and generate reports in one go.

# Analyze latest 10 versions of lodash and generate reports
node scripts/index.js lodash --range "latest 10"

# Analyze specific versions
node scripts/index.js express --range "4.17.10,4.17.21" --output ./reports

Advanced: Individual Scripts

Basic Package Version Scan

# Scan a specific package version
node scripts/scan_version.js lodash 4.17.21 npm

# Scan with different package manager
node scripts/scan_version.js express 4.18.0 pnpm

Analyze Multiple Versions

# Analyze specific versions
node scripts/analyze_version_range.js lodash --versions 4.17.10,4.17.11,4.17.21

# Analyze latest 10 versions
node scripts/analyze_version_range.js react --latest 10

# Analyze all available versions
node scripts/analyze_version_range.js express --all

Generate Comprehensive Report

# Aggregate data and generate report
node scripts/data_aggregator.js aggregate scan_results.json
node scripts/data_aggregator.js report markdown

Core Workflows

1. Single Version Vulnerability Check

Use this when you need to check the security status of a specific package version.

Steps:

1. Use scan_version.js to scan the specific version
2. Parse vulnerability counts by severity
3. Evaluate against your risk thresholds
4. Make upgrade/downgrade decisions

Example:

import { scanPackageVersion } from './scripts/scan_version.js';

const result = await scanPackageVersion("lodash", "4.17.21", "npm");
if (!result.error) {
    const vulns = result.vulnerabilities;
    if (vulns.critical === 0 && vulns.high === 0) {
        console.log("Version is safe for production use");
    }
}

2. Version Range Analysis

Use this when you need to find the safest version among multiple options.

Steps:

1. Collect available versions or specify versions to analyze
2. Scan each version using analyze_version_range.js
3. Identify safe version ranges based on thresholds
4. Select the optimal version considering features and security

Example Command:

node scripts/analyze_version_range.js lodash \
  --versions 4.17.10,4.17.11,4.17.19,4.17.20,4.17.21 \
  --thresholds 0,0,1,3 \
  --manager npm

3. Trend Analysis Across Versions

Use this to understand how vulnerabilities evolve over package releases.

Steps:

1. Scan multiple consecutive versions
2. Use data_aggregator.js to analyze trends
3. Identify patterns (improving, worsening, stable)
4. Make predictions about future version security

4. Package Manager Comparison

Use this to compare vulnerability results across different package managers.

Steps:

1. Run audits with npm, pnpm, and yarn
2. Use package_manager_adapter.js to compare results
3. Identify discrepancies and choose most reliable manager
4. Document differences for team awareness

Example:

node scripts/package_manager_adapter.js compare lodash 4.17.21

Script Reference

scan_version.js

Scans a specific package version for vulnerabilities.

Usage:

node scripts/scan_version.js <package-name> <package-version> [package-manager] [--save]

Examples:

# Basic scan
node scripts/scan_version.js lodash 4.17.21 npm

# Scan with pnpm and save results
node scripts/scan_version.js express 4.18.0 pnpm --save

# Scan with yarn
node scripts/scan_version.js react 18.2.0 yarn

Output: JSON with vulnerability counts by severity and raw audit data.

analyze_version_range.js

Analyzes vulnerabilities across multiple versions and identifies safe ranges.

Usage:

node scripts/analyze_version_range.js <package-name> [options]

Options:

• --versions v1,v2,v3: Comma-separated list of versions
• --latest N: Analyze N latest versions
• --all: Analyze all available versions
• --manager npm|pnpm|yarn: Package manager to use
• --thresholds c,h,m,l: Vulnerability thresholds (default: 0,0,1,3)

Examples:

# Analyze specific versions
node scripts/analyze_version_range.js lodash --versions 4.17.10,4.17.11,4.17.21

# Analyze latest 5 versions with custom thresholds
node scripts/analyze_version_range.js express --latest 5 --thresholds 0,0,0,5

# Analyze all versions with pnpm
node scripts/analyze_version_range.js react --all --manager pnpm

package_manager_adapter.js

Provides unified interface for different package managers and compares their results.

Usage:

node scripts/package_manager_adapter.js <command> [options]

Commands:

• info <manager>: Get package manager information
• versions <pkg> <manager>: Get available versions
• compare <pkg> <version>: Compare audit results
• audit <pkg> <version> <manager>: Run single audit

Examples:

# Get npm information
node scripts/package_manager_adapter.js info npm

# Get available versions for lodash
node scripts/package_manager_adapter.js versions lodash npm

# Compare audit results across managers
node scripts/package_manager_adapter.js compare lodash 4.17.21

# Run single audit
node scripts/package_manager_adapter.js audit express 4.18.0 yarn

data_aggregator.js

Aggregates vulnerability data and generates comprehensive reports to the output path.

Usage:

node scripts/data_aggregator.js <command> [options]

Commands:

• aggregate <file1> [file2...]: Aggregate data from JSON files
• summary: Generate summary statistics
• trends: Analyze vulnerability trends
• patterns: Identify risk patterns
• report <format>: Generate report (json, csv, markdown)
• viz-data: Export visualization data

Examples:

# Aggregate multiple scan files
node scripts/data_aggregator.js aggregate scan1.json scan2.json scan3.json

# Generate markdown report
node scripts/data_aggregator.js report markdown

# Export data for visualization
node scripts/data_aggregator.js viz-data

Reference Documentation

For detailed information, consult these reference files:

1. NPM Audit Output Format

File: references/npm_audit_format.md

• Understanding npm audit JSON structure
• Parsing vulnerability counts
• Handling different npm versions (v6 vs v7+)
• Package manager output differences

When to read: When you need to parse or understand raw audit output.

2. Package Manager Comparison

File: references/package_manager_comparison.md

• Command differences between npm, pnpm, yarn
• Output format variations
• Performance characteristics
• Best practices for each manager

When to read: When comparing results across package managers or troubleshooting audit issues.

3. Vulnerability Severity Levels

File: references/vulnerability_severity.md

• Understanding critical, high, moderate, low, info levels
• Risk assessment frameworks
• Threshold recommendations
• Decision-making guidelines

When to read: When evaluating risk levels or setting security thresholds.

4. Version Range Syntax

File: references/version_range_syntax.md

• Semantic versioning (SemVer) parsing
• Version range syntax and comparators
• Vulnerability range interpretation
• Safe version range detection algorithms

When to read: When working with version ranges or parsing vulnerability advisories.

Asset Templates

Sample Reports and Templates

Location: assets/

1. Sample Vulnerability Report (sample_vulnerability_report.json)

   • Complete example of analysis output
   • Shows all data fields and structure
   • Useful for understanding expected output format

2. Report Template (report_template.md)

   • Markdown template for vulnerability reports
   • Placeholder-based structure
   • Can be filled with actual data

3. Visualization Template (visualization_template.html)

   • Interactive HTML/Chart.js visualization
   • Charts for severity distribution, trends, version analysis
   • Responsive design for different devices

4. Data Export Template (data_export_template.csv)

   • CSV format for data export
   • Standardized column structure
   • Compatible with spreadsheet software

Common Use Cases

Use Case 1: Choosing a Safe Package Version

Scenario: A team needs to select a secure version of a critical dependency.

Workflow:

1. Identify the package and required feature set
2. Scan available versions with scan_version.js
3. Analyze results with analyze_version_range.js
4. Identify safe version ranges
5. Select version balancing security and features
6. Generate report for team review

Use Case 2: Security Audit of Existing Project

Scenario: Conducting a security audit of an existing project's dependencies.

Workflow:

1. Extract current dependency versions from package.json
2. Scan each dependency with current version
3. Identify vulnerable dependencies
4. Find safe upgrade paths for each
5. Generate comprehensive audit report
6. Create upgrade plan with risk assessment