audit-explain

Make npm security audits understandable — explains vulnerabilities in plain English with interactive fixes.

Overview

audit-explain is an intelligent CLI tool that transforms npm security audits into clear, actionable guidance for developers. Instead of cryptic vulnerability IDs and technical jargon, it provides:

✅ Plain English explanations of each vulnerability ✅ Dependency tree visualization showing how you're affected ✅ Interactive prompts to apply fixes one-by-one ✅ Beautiful, color-coded output ✅ Markdown reports for documentation

Installation

Global Install

npm install -g audit-explain
audit-explain

Local Install

npm install --save-dev audit-explain
npx audit-explain

Via npx (No Installation)

npx audit-explain

Requirements

• Node.js 18.0.0 or higher
• npm 6.0.0 or higher

Usage

Basic Usage

# Interactive mode - prompts for each vulnerability
audit-explain

# Show only high/critical severity
audit-explain --severity high

# Auto-fix all vulnerabilities
audit-explain --fix-all

# Generate report without fixing
audit-explain --report-only

CLI Options

  -h, --help                  Show help message
  -v, --version              Show version
  --fix-all                   Automatically apply all available fixes
  --severity <level>         Filter by severity: critical, high, moderate, low
  --report-only              Generate markdown report without fixing
  --json                      Output results as JSON

How It Works

Step 1: Scan Your Dependencies

$ audit-explain

Runs npm audit --json and parses the results.

Step 2: Understand Each Vulnerability

For each vulnerability, you'll see:

 1/3 - 🔴 HIGH SEVERITY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Package: lodash
Vulnerability: Prototype Pollution
CVE: CVE-2019-10744

📖 What this means:
An attacker could modify JavaScript object prototypes, 
affecting all objects in your application.

🔍 How you're affected:
  ├─ [email protected]
  │  └─ [email protected]
  │     └─ [email protected] ⚠️

💡 The fix:
Update lodash to version 4.17.21 or higher

? Apply this fix? (Y/n/skip all)

Step 3: Choose How to Fix

For each vulnerability, you can:

• Yes: Apply the fix immediately
• No: Skip this fix
• Skip all: Stop interactive mode

Step 4: Review the Report

A markdown report is generated at ./audit-report.md with:

• Summary of all vulnerabilities
• Detailed explanations for each
• Fix results and status
• References and CVEs

Features

🎯 Plain English Explanations

Instead of cryptic vulnerability descriptions, audit-explain translates security concepts:

| Technical | Plain English | |-----------|---------------| | "Prototype Pollution" | "An attacker could modify JavaScript object prototypes" | | "ReDoS" | "A specially crafted input could cause regex to run forever" | | "Path Traversal" | "An attacker could access files outside your app's directory" |

📊 Dependency Tree Visualization

See exactly where each vulnerable package appears in your dependency tree:

Your Project
└─ [email protected]
   └─ [email protected]
      └─ [email protected] ⚠️

🔧 Interactive Fixing

Apply fixes interactively for each vulnerability, or auto-fix them all at once.

📝 Markdown Reports

Generate professional reports for your team:

# NPM Audit Report
Generated: 2024-02-14T10:30:45.123Z

## Summary
- **Total Packages:** 487
- **Vulnerabilities Found:** 3
  - 🔴 **High:** 1
  - 🟡 **Moderate:** 1
  - 🟢 **Low:** 1

## Vulnerabilities
### 1. Prototype Pollution
**Severity:** high
**Package:** lodash
**CVE:** CVE-2019-10744
...

🎨 Beautiful Output

Color-coded severity levels and emoji indicators make it easy to spot critical issues.

Configuration

Create an optional audit-explain.config.json in your project root:

{
  "severity": "high",
  "interactiveMode": true,
  "reportPath": "./audit-report.md",
  "excludeDevDeps": false,
  "autoFixAll": false
}

Examples

Example 1: Quick Interactive Audit

$ audit-explain
✓ Scanned 487 packages
⚠ Found 3 vulnerabilities (1 high, 2 moderate)

# ... displays vulnerabilities and prompts to fix each one

Example 2: Auto-fix All

$ audit-explain --fix-all
✓ Scanned 487 packages
⚠ Found 3 vulnerabilities
Fixing lodash... ✓
Fixing express... ✓
Fixing debug... ✓
Report generated: audit-report.md

Example 3: Report Only

$ audit-explain --report-only
✓ Scanned 487 packages
⚠ Found 3 vulnerabilities
Generating report...
Report generated: audit-report.md

Example 4: High Severity Only

$ audit-explain --severity high
✓ Scanned 487 packages
⚠ Found 1 high-severity vulnerability

# ... only shows high severity vulnerabilities

Supported Vulnerability Types

audit-explain includes plain English explanations for:

• Prototype Pollution — Modifying JavaScript prototypes
• Remote Code Execution (RCE) — Arbitrary code execution
• SQL Injection — Database query manipulation
• Cross-Site Scripting (XSS) — Browser script injection
• Denial of Service (DoS) — Service unavailability attacks
• Path Traversal — Unauthorized file access
• Authentication Bypass — Circumventing security checks
• Regular Expression DoS (ReDoS) — Regex-based attacks
• XML External Entity (XXE) — XML parsing attacks
• Insecure Deserialization — Object manipulation attacks
• Cryptographic Weakness — Weak encryption
• Information Disclosure — Sensitive data exposure
• And more...

For unknown vulnerability types, audit-explain shows the raw description and provides helpful guidance.

Troubleshooting

"Failed to run npm audit"

Ensure you're in a Node.js project with a package.json file:

npm init
npm install audit-explain
audit-explain

"No fix is currently available"

Some vulnerabilities don't have fixes from the package maintainers yet. Options:

1. Wait for a fix release
2. File an issue with the package author
3. Use an alternative package

Dependencies are conflicting

When a fix introduces breaking changes, npm may refuse to install it. Options:

1. Review the changelog of the fixed version
2. Update your code if needed
3. Skip the fix for now

API Usage

You can also use audit-explain as a library in your own tools:

import {
  runAudit,
  explainVulnerabilities,
  buildDependencyPath,
  generateReport,
} from 'audit-explain';

// Run audit
const auditResult = await runAudit();

// Explain vulnerabilities
const explained = explainVulnerabilities(auditResult.vulnerabilities);

// Get dependency path
explained.forEach((vuln) => {
  const depPath = buildDependencyPath(vuln);
  console.log(depPath);
});

// Generate report
generateReport(auditResult, explained);

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Support

• 🐛 Report bugs
• 💬 Discussions
• 📚 Documentation

Related Tools

• npm audit — Official npm vulnerability scanner
• snyk — Comprehensive security platform
• OWASP Top 10 — Security best practices

Made with ❤️ for developers who care about security.