NPM SCA Scanner

A Docker-based security scanner that analyzes npm package dependencies for vulnerabilities and enriches them with CVE information from GitHub Advisory Database.

Features

• Scans package-lock.json files for security vulnerabilities
• Enriches vulnerability data with CVE information from GitHub Advisory API
• Provides detailed dependency graphs and fix suggestions
• Outputs structured JSON results
• Lightweight Alpine-based Docker image with minimal dependencies
• Separate production and development environments for security optimization

Prerequisites

• Docker installed on your system
• A package-lock.json file in your project directory
• (Optional) GitHub Personal Access Token for enhanced API access

Quick Start

1. Build the Docker image:

   docker build -t npm-sca-scanner .

2. Run the scanner:

   # Navigate to your project directory with package-lock.json
   cd /path/to/your/project
   
   # Run the scanner
   docker run --rm -v $(pwd):/app/scan npm-sca-scanner

3. View results:

   cat scan_results.json

Usage with GitHub Token (Recommended)

To avoid API rate limits and get enhanced vulnerability information:

1. Set up GitHub token:

   export GH_TOKEN=your_github_token_here

2. Run with token:

   docker run --rm -v $(pwd):/app/scan -e GH_TOKEN npm-sca-scanner

Output

The scanner generates scan_results.json containing:

• CVE identifiers
• Package names and versions
• Vulnerability descriptions
• Dependency graphs
• Fix suggestions

GitHub Token Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token with public_repo scope
3. Export the token: export GH_TOKEN=your_token

Docker Command Options

# Basic scan
docker run --rm -v $(pwd):/app/scan npm-sca-scanner

# With GitHub token
docker run --rm -v $(pwd):/app/scan -e GH_TOKEN npm-sca-scanner

# Interactive mode (for debugging)
docker run --rm -it -v $(pwd):/app/scan -e GH_TOKEN npm-sca-scanner

Development

Requirements Files

The project uses separate requirements files for different environments:

• requirements-prod.txt - Minimal production dependencies (3 packages)

  • Used by Docker for lean, secure container images
  • Contains only: requests, python-dotenv, semantic_version

• requirements-dev.txt - Development dependencies (13 packages)

  • Includes production dependencies plus testing tools
  • Contains pytest and all transitive dependencies

Setup development environment:

# Install all development dependencies
pip install -r requirements-dev.txt

Testing

The project includes comprehensive tests covering three key dependency scenarios:

1. Direct Dependencies - Packages listed directly in package.json
2. Transitive Dependencies - Sub-dependencies with proper dependency chains
3. Multiple Introduction Paths - Packages introduced via multiple dependency routes

Run tests:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test
pytest tests/test_dependencies.py::test_direct_dependencies

Project Structure

npm_sca_scanner/
├── main.py                    # Main scanner logic
├── functions.py               # Core functions (CVE lookup, version matching)
├── entrypoint.sh             # Docker entrypoint script
├── requirements-prod.txt     # Production dependencies
├── requirements-dev.txt      # Development dependencies
├── tests/                    # Test suite
│   ├── test_dependencies.py  # Dependency scenario tests
│   ├── test_npm_results.json # Mock npm audit data
│   └── test_scan_results.json # Mock scanner output
└── Dockerfile               # Production Docker image

Security

Container Security Scan

The Docker image has been optimized for security and scanned with Trivy:

Report Summary
┌─────────────────────────┬────────────┬─────────────────┬─────────┐
│         Target          │    Type    │ Vulnerabilities │ Secrets │
├─────────────────────────┼────────────┼─────────────────┼─────────┤
│ npm-sca-scanner         │   alpine   │        0        │    -    │
├─────────────────────────┼────────────┼─────────────────┼─────────┤
│ Python packages         │ python-pkg │        0        │    -    │
└─────────────────────────┴────────────┴─────────────────┴─────────┘

✅ No security vulnerabilities detected

The production image contains only essential dependencies:

• requests - GitHub API communication
• python-dotenv - Environment variable handling
• semantic_version - Version range matching

Requirements

• Project must contain a valid package-lock.json file
• Docker must have access to the internet for API calls