DEV Community

Prashant Gupta
Prashant Gupta

Posted on

NPM Vulnerability Report

#npm #vulnerabilities #monitoring

NPM Vulnerability Report

An automated security scanning tool that identifies frontend applications in GitHub repositories and performs npm audit to detect vulnerabilities in Node.js dependencies.

Overview

This solution scans multiple GitHub repositories to identify frontend applications (those containing package.json) and automatically runs npm audit to generate vulnerability reports. Results are organized by project and repository for easy review and remediation.

Features

  • Multi-Repository Scanning: Processes multiple GitHub repositories from a configuration file
  • Frontend Detection: Automatically identifies repositories containing Node.js/npm projects
  • Automated Vulnerability Scanning: Runs npm audit using Docker containers
  • Organized Reporting: Generates structured audit reports per project and repository
  • Branch Support: Checks both master and main branches
  • Email Notifications: Sends scan results via email (requires Notification module)

Prerequisites

  • Python 3.13+
  • Docker installed and running
  • Git command line tools
  • GitHub token (optional, for higher API rate limits)
  • Node.js Docker image (node:24-alpine)

Setup

1. Environment Configuration 

# Set GitHub token for API access (optional but recommended)
export GITHUB_TOKEN="your_github_token_here"
Enter fullscreen mode Exit fullscreen mode

2. Repository Configuration

Create repositories.json with your project structure:

{
  "project-name": {
    "repositories": [
      "https://github.com/owner/frontend-repo.git",
      "https://github.com/owner/another-repo.git"
    ]
  },
  "another-project": {
    "repositories": [
      "https://github.com/org/web-app.git"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Dependencies 

# Install required Python packages
pip install requests
Enter fullscreen mode Exit fullscreen mode

Usage

Basic Scan 

python github-repositories-scan.py
Enter fullscreen mode Exit fullscreen mode

Output Structure 

npm-vulnerability-report/
├── projects/
│   ├── project-name/
│   │   ├── frontend-repo_npm-audit.json
│   │   └── another-repo_npm-audit.json
│   └── another-project/
│       └── web-app_npm-audit.json
├── screenshots/
│   ├── email-report-sample.png
│   ├── vulnerability-dashboard.png
│   └── scan-results.png
├── repositories.json
└── github-repositories-scan.py
Enter fullscreen mode Exit fullscreen mode

How It Works

  1. Repository Discovery: Reads project configuration from repositories.json
  2. Frontend Detection: Uses GitHub API to check for package.json and package-lock.json
  3. Repository Cloning: Temporarily clones repositories containing frontend code
  4. Dependency Installation: Runs npm install if package-lock.json is missing
  5. Vulnerability Scanning: Executes npm audit --json in Docker container
  6. Report Generation: Saves audit results as JSON files organized by project
  7. Cleanup: Removes temporary files and directories

Configuration Options

Docker Image

Default: node:24-alpine

  • Modify docker_image variable in the script for different Node.js versions

Branch Detection

Default: ['master', 'main']

  • Add additional branches to the branches list as needed

API Endpoints

  • GitHub API: https://api.github.com
  • Supports public repositories by default
  • Private repositories require a valid GitHub token

Security Considerations

  • Token Management: Store GitHub tokens securely using environment variables
  • Docker Security: Ensure Docker daemon is properly secured
  • Temporary Files: Script automatically cleans up cloned repositories
  • API Rate Limits: Use GitHub token to avoid rate limiting

Troubleshooting

Common Issues

No GitHub Token Warning

No GitHub token found. API calls will be rate-limited.
Enter fullscreen mode Exit fullscreen mode
  • Set GITHUB_TOKEN environment variable for higher API limits

Docker Permission Errors

docker: permission denied
Enter fullscreen mode Exit fullscreen mode
  • Ensure the user is in the Docker group or runs with appropriate permissions

Git Clone Failures

Git clone failed: authentication required
Enter fullscreen mode Exit fullscreen mode
  • Verify repository URLs and access permissions
  • Check if repositories are public or require authentication

Missing package.json

package.json not found in cloned repo
Enter fullscreen mode Exit fullscreen mode
  • Repository may not be a frontend application
  • Check if package.json exists in a different branch or subdirectory

Integration

CI/CD Pipeline Integration 

# Example Jenkins/GitHub Actions step
- name: Run NPM Vulnerability Scan
  run: |
    export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
    python github-repositories-scan.py
Enter fullscreen mode Exit fullscreen mode

Automated Reporting

The script includes email notification capability through the Notification module—Configure email settings to receive scan results automatically.

Screenshots

Email Vulnerability Report Sample

Email NPM Vulnerability Report

Scan Results

NPM Scan Results

Output Format

Audit results are saved as JSON files containing:

  • Vulnerability details and severity levels
  • Affected packages and versions
  • Recommended fixes and updates
  • Dependency tree information

Contributing

  1. Follow the established directory structure
  2. Update this README for any new features
  3. Test with sample repositories before deployment
  4. Ensure Docker compatibility across environments

GitHub Link

https://github.com/prashantgupta123/devops-automation/tree/main/npm-vulnerability-report

Security Note: This tool performs automated vulnerability scanning. Always review audit results and apply security patches promptly. Never commit actual GitHub tokens or sensitive credentials to version control.

Top comments (0)