npm-audit-guard

A powerful CLI tool for npm security audits with blacklist functionality, progress bar, and JUnit XML reports for CI/CD integration.

✨ Features

• 🔍 Security Scanning: Runs npm audit and groups vulnerabilities by severity level
• 🚫 Blacklist Function: Ignore known packages and display them separately
• ⚡ Progress Bar: Visual feedback during the audit process
• 📊 JUnit XML Reports: Perfect for Jenkins, GitLab CI, and other CI/CD systems
• ⚙️ Config File Support: Configuration via .auditguardrc.json file
• 🎨 Colored Output: Clear, color-coded terminal output
• 🔄 Flexible Options: Scan with or without dev dependencies

📦 Installation

Global

npm install -g npm-audit-guard

Local (per project)

npm install --save-dev npm-audit-guard

🚀 Usage

Initialize Config File

Create a .auditguardrc.json config file in your project:

audit-guard init

This creates a default config file that you can customize with your blacklist and settings.

Basic Scan

Standard scan without dev dependencies:

audit-guard

or with npx:

npx npm-audit-guard

With Dev Dependencies

audit-guard --dev

With Blacklist

Option 1: Using config file (recommended for multiple packages)

# Create config file once
audit-guard init

# Edit .auditguardrc.json and add your packages to the blacklist array
# Then just run:
audit-guard

Option 2: Command line (quick one-time use)

audit-guard --blacklist="axios,lodash,moment"

JUnit XML Report

# Standard output (./audit-results.xml)
audit-guard --junit

# Custom output path
audit-guard --junit --output="./test-results/security-audit.xml"

Important: The JUnit XML also includes blacklist warnings as failures!
If a package is on the blacklist but has no security issues, this will be reported as a failure in Jenkins/CI.
This helps keep your blacklist clean.

Combined

audit-guard --dev --blacklist="old-package,legacy-dep" --junit --output="./reports/audit.xml"

📋 Example Output

Running security audit... [████████████████████] 100%

Security Audit Results:

Critical:
- axios (>=0.8.1 <0.21.2)
- lodash (>=1.0.0 <4.17.21)

High:
- express (>=4.0.0 <4.17.3)

Moderate:
- moment (>=2.0.0 <2.29.2)

Low:
(none)

Ignored:
- old-package (high)
- legacy-dep (moderate)

Warning: Following blacklisted packages have no security issues: another-package

Total vulnerabilities found: 4 (excluding ignored)

⚙️ Configuration

Config File (.auditguardrc.json)

You can create a config file to persist your audit settings. The file is automatically loaded if it exists in your project directory.

Option 1: Using the init command (recommended)

audit-guard init

This creates a .auditguardrc.json file with default settings that you can customize.

Option 2: Manual creation

Create a .auditguardrc.json file in your project root:

{
  "blacklist": [
    "package-name-1",
    "package-name-2",
    "old-legacy-package"
  ],
  "includeDev": false
}

How it works:

• ✅ The config file is automatically detected and loaded - no extra command needed
• ✅ Run audit-guard and it will use your blacklist from the config file
• ⚠️ CLI parameters override config file settings (e.g., --blacklist on command line takes priority)

CLI Commands & Options

Commands:

Options:

🔄 CI/CD Integration

Jenkins

pipeline {
    agent any
    stages {
        stage('Security Audit') {
            steps {
                sh 'npx npm-audit-guard --junit --output="./test-results/audit.xml"'
            }
            post {
                always {
                    junit 'test-results/audit.xml'
                }
            }
        }
    }
}

GitLab CI

security_audit:
  script:
    - npx npm-audit-guard --junit --output="audit-results.xml"
  artifacts:
    when: always
    reports:
      junit: audit-results.xml

GitHub Actions

name: Security Audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npx npm-audit-guard --junit --output="audit-results.xml"
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: audit-results
          path: audit-results.xml

📊 Exit Codes

📄 Requirements

• Node.js >= 16.0.0
• npm >= 7.0.0

📝 License

MIT License - see LICENSE file for details.