auditclean 0.1.0

Cut npm audit down to what matters — production, high-severity, fixable vulnerabilities only. Zero dependencies.

auditclean

npm audit cries wolf. auditclean tells you what to actually fix. A typical audit report is ~80% noise — dev-only CVEs that never ship, transitive advisories with no available fix, low-severity findings buried under two screens of red text. auditclean keeps only what's actionable: production dependencies, at or above a severity threshold, with a fix available. Zero dependencies.

pip install auditclean
auditclean

auditclean — 2 of 47 advisories need action (≥ high, production, fixable)

  ● critical  lodash    <=4.17.20   Prototype Pollution in lodash    → npm audit fix
  ● high      minimist  <1.2.6      Prototype Pollution in minimist  → upgrade minimist to 1.2.8

45 hidden (below high · dev-only · no fix). See everything: auditclean --all

Why

npm audit was famously called "broken by design": it reports every advisory in your entire dependency tree, including ones in build tooling that never reach production and ones with no fix you can apply. The result is alert fatigue — a wall of output you learn to || true past in CI, which is exactly how a real critical slips through.

The existing alternatives want a config file (audit-filter), interactive prompts (npm-audit-resolver), or an account (a SaaS scanner). auditclean wants nothing: run it, get the short list.

How it works

By default it runs npm audit --omit=dev --json for you (so you only see production vulnerabilities), then filters to high+ severity with a fix:

auditclean                      # run audit, show prod high+ fixable
auditclean --level critical     # only critical
auditclean --all                # show everything (low+, dev, unfixable), just cleaned up

You can also feed it a report you already have:

npm audit --json | auditclean
npm audit --omit=dev --json | auditclean   # prod-only on piped input

It understands both npm audit JSON schemas — v2 (npm 7+, vulnerabilities) and v1 (npm 6, advisories) — and normalizes the fix advice, including isSemVerMajor upgrades flagged as (breaking).

In CI

auditclean exits non-zero only when something actionable is left after filtering, so it gates on signal instead of noise:

# fails the build only on production, high+, fixable vulnerabilities
- run: npx auditclean

Exit code	Meaning
0	nothing actionable at the threshold
1	actionable vulnerabilities found
2	error (npm missing, unparseable input)

Options

--level <sev>         minimum severity: low | moderate | high | critical (default: high)
--include-unfixable   also show vulns with no fix available
--include-dev         also include devDependencies (when reading piped full JSON)
--all                 shorthand for --level low --include-unfixable --include-dev
--format text|json    output format (default: text)
-v, --version
-h, --help

--format json emits { format, level, total, actionable, hidden, counts, vulnerabilities } for programmatic use.

Notes

• Production filtering comes from running npm audit --omit=dev. If you pipe a full npm audit --json, the npm 7+ schema doesn't tag dev per-vuln — pipe npm audit --omit=dev --json to get the same result on stdin.
• Zero dependencies. It shells out to your npm and parses JSON with the standard library. Nothing to install, nothing to audit.

Also available for Node

npx auditclean

Same filtering, same flags, same exit codes — auditclean on npm.

Note: this Python package shells out to your installed npm to read the audit report, so Node/npm must be on PATH. It's handy in Python-based CI that audits a Node sub-project.

License

MIT