cve-guard-npm

cve-guard-npm is a lifecycle hook guard for npm installs. It automatically scans package install targets for OSV/CVE vulnerabilities before install and audits the resulting dependency tree after install.

Features

• Pre-install CVE scanning for packages requested with npm install
• Interactive warnings and confirmation when vulnerabilities are detected
• Post-install audit report using npm audit --json
• Beautiful terminal experience with chalk, boxen, cli-table3, gradient-string, and ora
• Works without changing normal npm commands after one-time setup
• Graceful error handling for offline, malformed input, unsupported npm usage, and audit failures
• Bonus reputation details for packages: weekly downloads, publish date, maintainers count

Installation

npm install --save-dev cve-guard-npm

One-time Setup

Add lifecycle scripts to your package.json:

{
  "scripts": {
    "preinstall": "cve-guard-npm preinstall",
    "postinstall": "cve-guard-npm postinstall"
  }
}

After setup, every future npm install call will trigger the CVE guard automatically.

Usage

Normal install

npm install express

This will automatically run the preinstall CVE scan for express, prompt if vulnerabilities exist, and run npm audit --json after install.

Preinstall flow

If the package scan detects issues, you will see a report and a prompt like:

Continue installation? (y/n):

If you choose n, the install aborts safely.

Postinstall flow

After install completes, the package runs npm audit --json and prints a summary report for detected vulnerabilities.

Example Output

Preinstall

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CVE PRE-INSTALL CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Package: lodash
  • Weekly downloads: 23,000,000
  • Last publish date: 2024-12-05
  • Maintainers: 4

┌───────────┬────────────┬──────────────────────────────────────────────────────────┐
│ Severity  │ CVE / GHSA │ Summary                                                  │
├───────────┼────────────┼──────────────────────────────────────────────────────────┤
│ HIGH      │ GHSA-xxxx  │ Prototype Pollution                                       │
└───────────┴────────────┴──────────────────────────────────────────────────────────┘

Continue installation? (y/n): n

❌ Installation aborted by user.

Postinstall

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DEPENDENCY SECURITY REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌───────────┬───────┐
│ Severity  │ Count │
├───────────┼───────┤
│ CRITICAL  │ 1     │
│ HIGH      │ 2     │
│ MODERATE  │ 5     │
│ LOW       │ 1     │
└───────────┴───────┘

Affected Packages:

┌──────────────────────────┬──────────┬──────────────────────────────┐
│ Package@Version          │ Severity │ Identifier                   │
├──────────────────────────┼──────────┼──────────────────────────────┤
│ [email protected]           │ high     │ GHSA-xxxx                    │
└──────────────────────────┴──────────┴──────────────────────────────┘

Architecture Overview

• bin/cli.js - executable entrypoint for cve-guard-npm
• lib/preinstall.js - pre-install lifecycle hook logic
• lib/postinstall.js - post-install audit reporting
• lib/osv.js - reusable OSV API integration with retry and timeout support
• lib/audit.js - npm audit execution and JSON parsing
• lib/formatter.js - CLI output formatting and tables
• lib/logger.js - rich boxed headers and log helpers
• lib/prompt.js - interactive confirmation helper
• lib/utils.js - npm argv parsing, package normalization, and package.json helpers
• lib/constants.js - shared configuration values and mappings

Screenshots

Roadmap

• [ ] Add support for lockfile-aware package resolution
• [ ] Add optional CI-only enforcement mode
• [ ] Add config file support for ignore rules
• [ ] Add support for Yarn and pnpm lifecycle flows
• [ ] Add package metadata caching to reduce network traffic

Contributing

1. Fork the repository
2. Create a branch for your feature or fix
3. Submit a pull request with tests and documentation

Please follow the existing code style and keep features modular.

License

MIT