pnpm-audit-hook

A pnpm hook that audits dependencies for vulnerabilities before packages are downloaded. It queries the GitHub Advisory Database for vulnerabilities and optionally enriches severity data from NVD, blocking installs when critical or high severity issues are found.

Installation

From npm/pnpm (Easiest)

# Install the package
pnpm add -D pnpm-audit-hook

# Run setup to create .pnpmfile.cjs in your project
pnpm exec pnpm-audit-setup

That's it! Every pnpm install will now audit packages for vulnerabilities.

Global Setup (All Projects)

To enable for all pnpm projects on your machine:

# Install globally
pnpm add -g pnpm-audit-hook

# Create global hooks directory
mkdir -p ~/.pnpm-hooks
cp $(pnpm root -g)/pnpm-audit-hook/dist ~/.pnpm-hooks/ -r
cp $(pnpm root -g)/pnpm-audit-hook/.pnpmfile.cjs ~/.pnpm-hooks/

# Configure pnpm to use global hooks
pnpm config set global-pnpmfile ~/.pnpm-hooks/.pnpmfile.cjs

Manual Setup

git clone https://github.com/asx8678/pnpm-audit-hook.git
cd pnpm-audit-hook
pnpm install && pnpm run build

# Copy to your project
cp -r dist /path/to/your/project/
cp .pnpmfile.cjs /path/to/your/project/

Quick Test

pnpm add lodash              # Safe - installs normally
pnpm add event-stream@3.3.6  # Vulnerable - blocked!

If vulnerabilities are found, install fails before any packages are downloaded.

Configuration

Create .pnpm-audit.yaml in your project root:

policy:
  block:
    - critical
    - high
  warn:
    - medium
    - low
    - unknown
  allowlist:
    - id: CVE-2024-12345
      reason: "False positive"
    - package: legacy-lib
      expires: "2025-06-01"

sources:
  github: true
  nvd: true

performance:
  timeoutMs: 15000

cache:
  ttlSeconds: 3600

All fields are optional. Set any source to false to disable it.

Configuration Constraints

The following validation rules are applied to configuration values:

Invalid values are silently replaced with defaults to ensure safe operation.

Vulnerability Sources

GitHub Advisory is the primary vulnerability source. NVD provides additional severity metadata but does not add new vulnerability entries.

Allowlist

Suppress specific vulnerabilities or packages:

policy:
  allowlist:
    - id: CVE-2024-12345
      reason: "False positive for our use case"
    - package: legacy-lib
      reason: "Accepted risk"
      expires: "2025-06-01"

• id - CVE or GHSA identifier to ignore (case-insensitive)
• package - Package name to ignore entirely (case-insensitive)
• If both id and package are set, both must match (scoped allowlist)
• reason - Why it's allowed (for audit trail)
• expires - ISO date when the allowlist entry expires

Environment Variables

How It Works

1. pnpm resolves the full dependency graph
2. .pnpmfile.cjs hook runs afterAllResolved() before downloads
3. The hook queries GitHub Advisory (and optionally NVD for severity enrichment)
4. Findings are deduplicated and checked against the severity policy
5. If any blocking vulnerabilities exist, pnpm aborts the install

Note: The .pnpmfile.cjs file must be in your workspace root directory.

CI/CD Integration

GitHub Actions

name: Install with Audit
on: [push, pull_request]

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NVD_API_KEY: ${{ secrets.NVD_API_KEY }}

The hook runs automatically during pnpm install and will fail the job if blocking vulnerabilities are found.

Static Vulnerability Database

The hook includes a bundled database of historical vulnerabilities (2020-2025) that enables faster audits and reduced API calls.

How It Works

• Historical vulnerabilities (before the cutoff date) are served from the bundled static database
• New vulnerabilities (after the cutoff date) are fetched from live APIs
• This hybrid approach provides offline capability for historical data while ensuring fresh data for recent disclosures

Benefits

• Faster audits: No API calls needed for known historical vulnerabilities
• Reduced API calls: Only new vulnerabilities require network requests
• Offline capability: Historical vulnerability checks work without internet access
• Rate limit friendly: Minimizes API usage against GitHub and NVD

Configuration

Enable or disable the static baseline in .pnpm-audit.yaml:

staticBaseline:
  enabled: true
  cutoffDate: "2025-12-31"
  dataPath: "node_modules/pnpm-audit-hook/dist/static-db/data"  # optional custom path

• enabled - Whether to use the static database (default: true)
• cutoffDate - Vulnerabilities published before this date use the static database (must be valid ISO format, not in future)
• dataPath - Optional custom path to static data directory (default: bundled data)

Updating the Database

Update the bundled vulnerability database monthly to capture new disclosures:

# Full rebuild of the vulnerability database
pnpm run update-vuln-db

# Incremental update (faster, adds only new vulnerabilities)
pnpm run update-vuln-db:incremental

After updating, rebuild and commit the changes:

pnpm run build
git add src/static-db/data/ dist/static-db/data/
git commit -m "chore: update vulnerability database"

Update Workflow

1. Run pnpm run update-vuln-db:incremental monthly
2. Optionally extend cutoffDate in your config to include newer static data
3. Commit the updated data/ directory to your repository

Local Development with pnpm

Setup

git clone https://github.com/asx8678/pnpm-audit-hook.git
cd pnpm-audit-hook
pnpm install
pnpm run build

Test in Another Project (pnpm link)

# In pnpm-audit-hook directory
pnpm link --global

# In your target project
pnpm link --global pnpm-audit-hook

# Copy the hook file to your project root
cp node_modules/pnpm-audit-hook/.pnpmfile.cjs .

# Edit .pnpmfile.cjs to point to linked package
# Change: path.join(__dirname, 'dist', 'index.js')
# To:     path.join(__dirname, 'node_modules', 'pnpm-audit-hook', 'dist', 'index.js')

# Test it
pnpm add lodash

Test Directly in This Repo

The .pnpmfile.cjs already points to ./dist, so you can test directly:

pnpm run build
pnpm add lodash              # Safe package
pnpm add event-stream@3.3.6  # Vulnerable - should be blocked

Development Workflow

# Make changes to src/
pnpm run build

# Run tests
pnpm test

# Test the hook manually
pnpm add some-package

Unlink After Testing

# In your target project
pnpm unlink pnpm-audit-hook
rm .pnpmfile.cjs

# In pnpm-audit-hook directory
pnpm unlink --global

Build

pnpm install
pnpm run build