Metadata-Version: 2.4
Name: auditclean
Version: 0.1.0
Summary: Cut npm audit down to what matters — production, high-severity, fixable vulnerabilities only. Zero dependencies.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/auditclean-py
Project-URL: Repository, https://github.com/jjdoor/auditclean-py
Project-URL: Issues, https://github.com/jjdoor/auditclean-py/issues
Keywords: npm-audit,audit,security,vulnerabilities,cve,noise,cli,ci,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.

```bash
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"](https://overreacted.io/npm-audit-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**:

```bash
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:

```bash
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:

```yaml
# 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

```bash
npx auditclean
```

Same filtering, same flags, same exit codes — [auditclean on npm](https://github.com/jjdoor/auditclean).

> 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
