diff --git a/README.md b/README.md index 8d78333..7961939 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ No account. No configuration. No source code leaves your machine. - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, designed for enterprise and air-gapped environments - **Interactive HTML report** — generate a self-contained dashboard with severity cards, a searchable findings table, and copy-ready fix commands (`--report`) - **Auto-fix mode** — apply validated direct dependency fixes and rescan automatically (`--fix`) -- **Override hygiene checks** — audit npm/pnpm/yarn/bun `overrides` and `resolutions` for orphaned targets, floating tags, surpassed pins, ineffective nested overrides, and platform-binary coupling (`cve-lite overrides`, rules `OA001`-`OA008`) +- **Override hygiene checks** — audit npm/pnpm/yarn/bun `overrides` and `resolutions` for orphaned targets, floating tags, surpassed pins, ineffective nested overrides, and platform-binary coupling (`--check-overrides`, rules `OA001`-`OA008`) - **CI-ready** — `--fail-on high` exits non-zero on findings at or above a severity threshold; a first-party [GitHub Action](https://github.com/marketplace/actions/cve-lite-cli) is available on the Marketplace; `--sarif` writes SARIF 2.1.0 output for direct upload to GitHub Code Scanning; `--cdx` writes a CycloneDX 1.4 SBOM for Dependency-Track and compliance artifacts; `--json` integrates with SIEM tools and dashboards - **Minimal footprint** — four runtime dependencies, intentionally kept small for a security tool @@ -313,10 +313,10 @@ cve-lite /path/to/project --verbose cve-lite /path/to/project --fix # Audit override hygiene (OA001-OA008) across npm/pnpm/yarn/bun -cve-lite overrides /path/to/project +cve-lite /path/to/project --check-overrides # Audit and auto-clean stale or ineffective overrides -cve-lite overrides /path/to/project --fix +cve-lite /path/to/project --check-overrides --fix # Production dependencies only (where supported by the lockfile) cve-lite /path/to/project --prod-only @@ -393,7 +393,7 @@ For a deeper explanation of how the CLI chooses direct upgrades, parent upgrades ## Override hygiene (`overrides`) -`overrides` and `resolutions` are powerful, but they rot. A pin you added to dodge a CVE last year can outlive its target, drift behind upstream, or quietly stop taking effect after a refactor, leaving a vulnerable copy still nested under a parent dependency. `cve-lite overrides [path]` audits that hygiene across npm, pnpm, yarn, and bun, reporting eight classes of problem (`OA001`-`OA008`): +`overrides` and `resolutions` are powerful, but they rot. A pin you added to dodge a CVE last year can outlive its target, drift behind upstream, or quietly stop taking effect after a refactor, leaving a vulnerable copy still nested under a parent dependency. `--check-overrides` audits that hygiene across npm, pnpm, yarn, and bun, reporting eight classes of problem (`OA001`-`OA008`): | Rule | What it catches | |---|---| @@ -408,22 +408,22 @@ For a deeper explanation of how the CLI chooses direct upgrades, parent upgrades ```bash # Audit, severity-grouped terminal output -cve-lite overrides /path/to/project +cve-lite /path/to/project --check-overrides # Structured JSON findings -cve-lite overrides /path/to/project --json +cve-lite /path/to/project --check-overrides --json # Apply RFC 6902 patches for fixable findings -cve-lite overrides /path/to/project --fix +cve-lite /path/to/project --check-overrides --fix # Scope a run (or a fix) to a single rule -cve-lite overrides /path/to/project --rule OA001 +cve-lite /path/to/project --check-overrides --rule OA001 # Enable the OA007 registry drift check (opt-in network) -cve-lite overrides /path/to/project --check-network +cve-lite /path/to/project --check-overrides --check-network # Stream an NDJSON change-control log of every detection and fix -cve-lite overrides /path/to/project --audit-log ./override-audit.ndjson +cve-lite /path/to/project --check-overrides --audit-log ./override-audit.ndjson ``` `--fix` applies fixes as RFC 6902 patches to `package.json`. A chokepoint guard means a fix can only remove, repin, move, or relocate an existing override; it can never invent a new override key. Suggest-only findings (OA004 cross-major, OA005.d/.e, all of OA008) and "proposed" fixes (the OA006 relocate floor) carry no auto-applied patch and are surfaced as recommendations. `--fail-on ` sets the minimum severity that makes the command exit non-zero (default: `critical`). diff --git a/website/docs/override-hygiene/index.md b/website/docs/override-hygiene/index.md index 03110e0..b138b53 100644 --- a/website/docs/override-hygiene/index.md +++ b/website/docs/override-hygiene/index.md @@ -7,7 +7,7 @@ description: Find and fix stale, broken, and dangerous dependency overrides acro Dependency overrides are security patches you apply manually when a vulnerable transitive package is not yet fixed upstream. They work - but they accumulate debt silently over time. The package gets updated, the CVE gets fixed, the override stays. Or worse: the override was never effective to begin with, and your project has been exposed the entire time without knowing it. -`cve-lite overrides` audits your override declarations against 8 rules and tells you exactly which ones are stale, broken, misplaced, or failing to take effect on disk. +`cve-lite . --check-overrides` audits your override declarations against 8 rules and tells you exactly which ones are stale, broken, misplaced, or failing to take effect on disk. --- @@ -15,22 +15,22 @@ Dependency overrides are security patches you apply manually when a vulnerable t ```bash # Scan current directory -cve-lite overrides . +cve-lite . --check-overrides # Scan a specific project -cve-lite overrides /path/to/project +cve-lite /path/to/project --check-overrides # JSON output for CI -cve-lite overrides . --json +cve-lite . --check-overrides --json # Include network checks (required for OA007) -cve-lite overrides . --check-network +cve-lite . --check-overrides --check-network # Auto-fix all fixable findings -cve-lite overrides . --fix +cve-lite . --check-overrides --fix # Fix a specific rule -cve-lite overrides . --fix --rule OA001 +cve-lite . --check-overrides --fix --rule OA001 ``` --- @@ -104,7 +104,7 @@ Most findings can be fixed automatically. `--fix` applies RFC 6902 JSON patches ```bash # Fail CI on any critical or high finding -cve-lite overrides . --fail-on high +cve-lite . --check-overrides --fail-on high # Run as part of the regular CVE scan cve-lite . --check-overrides --fail-on high @@ -113,7 +113,7 @@ cve-lite . --check-overrides --fail-on high Log every detection and fix event for compliance audit trails: ```bash -cve-lite overrides . --fix --audit-log ./override-audit.ndjson +cve-lite . --check-overrides --fix --audit-log ./override-audit.ndjson ``` --- @@ -122,9 +122,9 @@ cve-lite overrides . --fix --audit-log ./override-audit.ndjson Most dependency security tools read `package.json` statically and stop there. They see the override entry and assume it is working. -`cve-lite overrides` cross-checks overrides against the resolved lockfile and the installed `node_modules` tree - which is the only way to catch OA001 (orphaned), OA003 (wrong section), OA008 (still on disk despite floor), and OA006 (parent-coupling failure). +`cve-lite . --check-overrides` cross-checks overrides against the resolved lockfile and the installed `node_modules` tree - which is the only way to catch OA001 (orphaned), OA003 (wrong section), OA008 (still on disk despite floor), and OA006 (parent-coupling failure). -| Capability | cve-lite overrides | npm audit | OSV-Scanner | Snyk CLI | Socket CLI | +| Capability | --check-overrides | npm audit | OSV-Scanner | Snyk CLI | Socket CLI | |---|---|---|---|---|---| | Detect orphaned overrides (OA001) | ✅ | ❌ | ❌ | ❌ | ❌ | | Detect wrong-section overrides (OA003) | ✅ | ❌ | ❌ | ❌ | ❌ | diff --git a/website/docs/override-hygiene/oa001.md b/website/docs/override-hygiene/oa001.md index 90ef3bb..c32ba86 100644 --- a/website/docs/override-hygiene/oa001.md +++ b/website/docs/override-hygiene/oa001.md @@ -46,7 +46,7 @@ HIGH (1) ## Fix ```bash -cve-lite overrides . --fix --rule OA001 +cve-lite . --check-overrides --fix --rule OA001 ``` `--fix` removes the entry with a single RFC 6902 `remove` patch. Re-run `npm install` (or `pnpm install`, `yarn`) to confirm the cleanup took effect. diff --git a/website/docs/override-hygiene/oa002.md b/website/docs/override-hygiene/oa002.md index c28610b..ea0dba7 100644 --- a/website/docs/override-hygiene/oa002.md +++ b/website/docs/override-hygiene/oa002.md @@ -51,7 +51,7 @@ MEDIUM (1) ## Fix ```bash -cve-lite overrides . --fix --rule OA002 +cve-lite . --check-overrides --fix --rule OA002 ``` `--fix` replaces the floating tag with `>=` - a floor that encodes "at least this version for security" while letting the resolver pick newer compatible versions on future installs. diff --git a/website/docs/override-hygiene/oa003.md b/website/docs/override-hygiene/oa003.md index 4d1a8e2..e028ddb 100644 --- a/website/docs/override-hygiene/oa003.md +++ b/website/docs/override-hygiene/oa003.md @@ -79,7 +79,7 @@ OA003 is the single highest-impact category of override hygiene problem in the w ## Fix ```bash -cve-lite overrides . --fix --rule OA003 +cve-lite . --check-overrides --fix --rule OA003 ``` `--fix` applies a RFC 6902 `move` patch, relocating the override to the correct section. Re-run `npm install` (or `pnpm install`, `yarn`) afterward to apply the override at install time. diff --git a/website/docs/override-hygiene/oa004.md b/website/docs/override-hygiene/oa004.md index da760bd..4abfc19 100644 --- a/website/docs/override-hygiene/oa004.md +++ b/website/docs/override-hygiene/oa004.md @@ -41,7 +41,7 @@ LOW (1) ## Fix ```bash -cve-lite overrides . --fix --rule OA004 +cve-lite . --check-overrides --fix --rule OA004 ``` For same-major findings, `--fix` removes the override entry - the installed version already satisfies the security intent. diff --git a/website/docs/override-hygiene/oa005.md b/website/docs/override-hygiene/oa005.md index 3f19f76..7c583dd 100644 --- a/website/docs/override-hygiene/oa005.md +++ b/website/docs/override-hygiene/oa005.md @@ -71,7 +71,7 @@ CRITICAL (1) ## Fix ```bash -cve-lite overrides . --fix --rule OA005 +cve-lite . --check-overrides --fix --rule OA005 ``` `--fix` applies `remove` patches for OA005.a, OA005.b, and OA005.c. OA005.d and OA005.e are suggest-only - flattening a nested override is a scope decision that requires manual review. diff --git a/website/docs/override-hygiene/oa006.md b/website/docs/override-hygiene/oa006.md index b1410e2..3be21d0 100644 --- a/website/docs/override-hygiene/oa006.md +++ b/website/docs/override-hygiene/oa006.md @@ -82,10 +82,10 @@ Override the parent instead of the binary: ``` ```bash -cve-lite overrides . --fix --rule OA006 +cve-lite . --check-overrides --fix --rule OA006 rm -rf node_modules package-lock.json npm install -cve-lite overrides . +cve-lite . --check-overrides ``` `--fix` surfaces a recommendation rather than applying it automatically. If the parent already has an override, it repins that to a `>=` floor; if not, it relocates - retires the binary override and adds a parent dependency floor (an upgrade path), never a new override key. Because the floor is inferred from the installed tree, it is surfaced for review rather than auto-applied. diff --git a/website/docs/override-hygiene/oa007.md b/website/docs/override-hygiene/oa007.md index 0ad2318..3b540ca 100644 --- a/website/docs/override-hygiene/oa007.md +++ b/website/docs/override-hygiene/oa007.md @@ -14,7 +14,7 @@ This rule is OA002's companion. OA002 catches floating tags statically ("this ta This rule requires a network check and is opt-in: ```bash -cve-lite overrides . --check-network +cve-lite . --check-overrides --check-network ``` --- @@ -52,7 +52,7 @@ LOW (1) ## Fix ```bash -cve-lite overrides . --fix --rule OA007 --check-network +cve-lite . --check-overrides --fix --rule OA007 --check-network ``` `--fix` replaces the floating tag with `>=`, pinning the floor to the current registry version. diff --git a/website/docs/override-hygiene/oa008.md b/website/docs/override-hygiene/oa008.md index 5ceaac2..b1fb233 100644 --- a/website/docs/override-hygiene/oa008.md +++ b/website/docs/override-hygiene/oa008.md @@ -85,7 +85,7 @@ npm ls @esbuild/linux-x64 rm -rf node_modules package-lock.json && npm install # 4. Confirm the finding is gone -cve-lite overrides . +cve-lite . --check-overrides ``` See [OA006](./oa006.md) for the parent-override pattern. OA008 and OA006 often appear together on the same package - OA006 catches the structural cause, OA008 confirms the vulnerable copy on disk. diff --git a/website/docs/workflow-integration.md b/website/docs/workflow-integration.md index 4caa9a2..5c30ad8 100644 --- a/website/docs/workflow-integration.md +++ b/website/docs/workflow-integration.md @@ -206,7 +206,7 @@ Add it as a separate step in GitHub Actions: run: npx cve-lite-cli . --fail-on high --sarif - name: Override hygiene - run: npx cve-lite-cli overrides . --fail-on high + run: npx cve-lite-cli . --check-overrides --fail-on high ``` See the [Override Hygiene Auditing guide](./override-hygiene/index.md) for all 8 rules, auto-fix behavior, and audit logging.