npm-security-analyzer

A command-line tool to generate template content for analyzing suspicious npm packages, designed specifically for use with GitHub Copilot.

Overview

This tool generates template files to help security researchers analyze potentially malicious npm packages with GitHub Copilot by:

• Creating standardized template files for vulnerability reports
• Providing example suspicious code patterns and their explanations
• Generating comprehensive security advisory templates
• Setting up the perfect environment for GitHub Copilot to assist with analysis

The tool is specifically designed to work with GitHub Copilot to help analyze and explain security vulnerabilities without actually executing potentially malicious code.

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