npm-security-analyzer

npm-security-analyzer

A command-line tool to analyze suspicious npm packages for security vulnerabilities, designed to work with GitHub Copilot.

Overview

This tool helps security researchers analyze potentially malicious npm packages by:

• Downloading packages without executing install scripts
• Extracting package contents safely
• Scanning code for known malicious patterns
• Comparing with legitimate package versions
• Generating detailed analysis reports in JSON and Markdown formats

It's specifically designed to work well with GitHub Copilot to help analyze and explain security vulnerabilities.

Installation

# Install globally
npm install -g npm-security-analyzer

# Or run with npx
npx npm-security-analyzer

Usage

Basic Usage

npm-security-analyzer --issue <issue-number> --repo <repo>

Example

# Analyze an npm package mentioned in a GitHub security issue
npm-security-analyzer --issue 15035 --repo github/octoscan-results

# Specify custom patterns to search for
npm-security-analyzer --patterns "eval(" "base64" "process.env" --output ./my-analysis

Options

Options:
  -V, --version            output the version number
  -i, --issue <number>     GitHub issue number containing the vulnerability report
  -r, --repo <repo>        GitHub repository path (default: "github/octoscan-results")
  -p, --patterns <patterns...>  Suspicious patterns to search for
  -o, --output <directory>  Directory to save analysis results (default: ~/security-reports)
  -v, --verbose            Enable verbose output
  -h, --help               display help for command

Using with GitHub Copilot

For the best experience with GitHub Copilot, use this prompt:

Execute an npm security analysis using npm-security-analyzer:

1. Analyze the vulnerability report:
   npm-security-analyzer --issue <issue> --repo <repo> --output ./analysis-results

2. Once complete, review the JSON report at ./analysis-results/analysis_*.json and the human-readable Markdown file at ./analysis-results/analysis_*.md, then provide:
   - A summary of detected vulnerabilities
   - Technical explanation of the exploit mechanism
   - Code snippets of suspicious patterns found (highlight the malicious portions)
   - Probable attack vectors and potential impact
   - Recommended mitigation steps

3. Compare the compromised package with the legitimate version
4. Provide a detailed risk assessment
5. Generate a comprehensive security advisory in human-readable Markdown format that explains the vulnerability in clear terms for both technical and non-technical audiences

Output

The tool generates several outputs in the specified directory:

• analysis_<timestamp>.json - Complete JSON report with technical details
• analysis_<timestamp>.md - Human-readable Markdown summary with vulnerability explanations
• package_contents/ - Extracted package files for inspection
• diffs/ - Diffs between legitimate and suspicious versions (if available)
• human_report_<timestamp>.md - Comprehensive human-readable explanation of findings suitable for sharing with both technical and non-technical stakeholders

License

MIT