# NPM Vulnerability Analysis

> Comprehensive vulnerability analysis for npm packages across different versions. Use when Claude needs to: (1) Analyze security vulnerabilities for specific package versions, (2) Compare vulnerability counts across multiple versions of the same package, (3) Identify safe version ranges based on vulnerability thresholds, (4) Track vulnerability trends over version releases, (5) Work with npm, pnpm, or yarn package managers for audit analysis, or (6) Generate vulnerability reports and recommendations for dependency management.

- Skill: `konata9/npm-vulnerability-analysis` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add konata9/npm-vulnerability-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konata9/npm-vulnerability-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: konata9 (https://skillmd.com/u/konata9)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konata9/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: "最新 10" (latest 10), "4.17.10 到 4.17.21" (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.

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:**
```javascript
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:**
```bash
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:**
```bash
node scripts/package_manager_adapter.js compare lodash 4.17.21
```

## Script Reference

### scan_version.js
Scans a specific package version for vulnerabilities.

**Usage:**
```bash
node scripts/scan_version.js <package-name> <package-version> [package-manager] [--save]
```

**Examples:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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