vuln-guardian

Scan a Node.js project for known dependency vulnerabilities (npm audit) and auto-fix the safe ones — as a CLI, a library, or a daily GitHub Actions job.

Why not just run npm audit fix daily?

You can, and under the hood that's exactly what this does. vuln-guardian adds three things on top: a severity gate for CI (fail the build only on high/critical, ignore low-severity noise), a daily-schedule generator (there's no way for a published npm package to keep running after npm install finishes, so "every day" has to live somewhere — CI cron is the standard place, same mechanism Dependabot uses), and a safe-by-default fix mode (npm audit fix only; --force, which can bump major versions and break your build, is opt-in).

Install

npm install --save-dev vuln-guardian
# or run without installing:
npx vuln-guardian scan

CLI

vuln-guardian scan

Runs npm audit and prints/writes a Markdown report.

vuln-guardian scan --dir . --report report.md --fail-on high

• --fail-on <severity> — exit non-zero if a vulnerability at or above this severity (info|low|moderate|high|critical) is found. Useful for CI gates.

vuln-guardian fix

Applies npm audit fix (non-breaking fixes only, by default) and reports what changed.

vuln-guardian fix --dir . --report fix-report.md
vuln-guardian fix --force   # allow major version bumps — may break your build

vuln-guardian ci

The one-shot command for automation: scans, applies safe fixes, writes a report, and fails (exit code 1) if high/critical vulnerabilities remain after fixing.

vuln-guardian ci --report vuln-guardian-report.md --fail-on high

vuln-guardian init-workflow

Writes a GitHub Actions workflow that runs daily, applies safe fixes, opens a pull request with the changes, and fails the run if high/critical vulnerabilities remain unresolved.

vuln-guardian init-workflow
# writes .github/workflows/vuln-guardian.yml

Options: --cron '0 6 * * *' (UTC), --base-branch main, --node-version 20, --out <path>.

The generated workflow needs contents: write and pull-requests: write permissions (already set) and uses peter-evans/create-pull-request to open the PR — no extra secrets required beyond the default GITHUB_TOKEN.

vuln-guardian daemon

For self-hosted setups (a server or container that stays running) instead of CI: runs the same scan-and-fix cycle on a cron schedule inside a long-lived Node process.

vuln-guardian daemon --cron '0 3 * * *' --dir . --report report.md

Library API

import { scan, fix, meetsThreshold, scanToMarkdown } from 'vuln-guardian';

const result = await scan('./my-project');
console.log(scanToMarkdown(result));

if (meetsThreshold(result.summary, 'high')) {
  const fixed = await fix('./my-project'); // safe fixes only
  console.log(`Fixed ${fixed.fixedCount}, ${fixed.remainingCount} remain`);
}

How "safe" fixing works

vuln-guardian fix runs npm audit fix without --force, so it only applies changes npm considers non-breaking (patch/minor bumps within your existing semver ranges). Vulnerabilities that require a major version bump are left for a human — or for --force, which you should treat as "review the diff before merging," not "fire and forget."

Limitations

• Wraps npm audit, so it inherits its coverage (the npm/GitHub Advisory Database) and its blind spots — it does not run its own vulnerability scan.
• Only supports npm (not yarn/pnpm) for now.
• --force fixes can change major versions and break your code; always review the resulting diff / PR before merging.