feat(overrides): override-hygiene subsystem (cve-lite overrides + --check-overrides) by alamb-hex · Pull Request #718 · OWASP/cve-lite-cli

alamb-hex · 2026-06-20T00:33:48Z

Closes #717

Adds an override-hygiene subsystem that audits npm overrides / pnpm.overrides / yarn resolutions for problems that CVE remediation alone never catches. Contributed from @hexaxia-labs/override-audit-cli (Aaron Lamb), co-developed with Sonu Kapoor. Opening this PR is MIT-license consent per CONTRIBUTING.md.

What it adds

cve-lite overrides [path] runs eight detectors (OA001-OA008): orphaned target, floating tag, misplaced section, surpassed pin, ineffective nested, parent-binary coupling, registry drift, and on-disk materialized vulnerable copy. Each finding links to a rule doc under docs/rules/.
cve-lite [path] --check-overrides runs the same audit during a normal scan and threads findings to terminal / --json / --sarif / --report output.
--fix closes the loop: an applied override fix re-runs OA001 + OA008 against the patched target to confirm it took (new exit code 2 only on an override-fix verify failure). The fix hook never creates new override keys; it removes, repins, or relocates existing ones.
Opt-in audit log via --audit-log <path> / CVE_LITE_AUDIT_LOG (NDJSON change-control stream). No-op when unused.
Docs: docs/rules/OA001-OA008, docs/audit-log.md, docs/api/overrides.md.

Additive by design

No change to the default scan path or its exit behavior. The only surface a non-override user can observe is opt-in: the overrides subcommand, the --check-overrides flag, --audit-log, exit code 2 (override --fix verify failure only), and a SARIF sibling toolComponent that appears only when override findings exist (the CVE component/results are unchanged otherwise).

Verification

Staged on current main (no rebase needed). npm run build and npx tsc --noEmit clean.
827 tests / 81 suites green.
CI gains two steps: the test-hygiene gate, and an advisory-DB sync before tests (the override e2e suite scans with --offline).

Notes

A small, unrelated CLI fix (erroring on a mistyped command instead of silently scanning and exiting 0) is intentionally kept out of this PR and will follow as its own focused PR.

… --check-overrides) Contributes the override-hygiene auditor from @hexaxia-labs/override-audit-cli (Aaron Lamb), co-developed with Sonu Kapoor. It audits npm / pnpm.overrides / yarn resolutions for hygiene problems that CVE remediation alone never catches. - `cve-lite overrides [path]` runs eight detectors (OA001-OA008): orphaned target, floating tag, misplaced section, surpassed pin, ineffective nested, parent-binary coupling, registry drift, and on-disk materialized vulnerable copy. - `cve-lite [path] --check-overrides` runs the same audit during a regular scan and threads findings to terminal / JSON / SARIF / HTML output. - `--fix` closes the loop: an applied override fix re-runs OA001 + OA008 against the patched target to confirm it took (new exit code 2 on verify failure). The fix hook never creates new override keys; it removes, repins, or relocates existing ones. - Opt-in project audit log via `--audit-log <path>` / CVE_LITE_AUDIT_LOG (NDJSON). - Docs: docs/rules/OA001-OA008, docs/audit-log.md, docs/api/overrides.md. Additive for existing CVE users: the default scan exit behavior is unchanged, and SARIF adds a sibling toolComponent only when override findings are present. Staged on main HEAD (0c16544). 827 tests / 81 suites green.

sonukapoor

Really solid foundation - the subsystem architecture is clean, the chokepoint guard is the right safety invariant for a tool that auto-patches project files, and the test coverage is thorough. A few things need attention before this merges.

The main one: the fix hook runs on every --fix scan regardless of whether --check-overrides was passed. That contradicts the "additive by design" contract in the PR description - any user running cve-lite . --fix will silently get a full OA audit and potentially have their package.json patched without knowing it. Details in the inline comments.

The audit log also has a double-open on the overrides command path and a missing close() before process.exit(2). The SARIF output is missing the toolComponent.index linkage required by SARIF 2.1.0 §3.27.7. The HTML report renders an "Override hygiene" section on every scan even when override checking was never requested. The rest is minor - details inline.

- Gate the --fix override hygiene hook on --check-overrides so `cve-lite . --fix` never audits or patches package.json overrides unasked (additive contract). README auto-fix section updated to match. - Pass the index-level audit-log handle into runOverrides instead of opening a second handle to the same --audit-log file on the overrides command path. - Emit scan.finished and close the audit log before process.exit(2) on the override-verify failure path (was leaking the FD and dropping scan.finished). - SARIF: add rule.toolComponent.index to override results (SARIF 2.1.0 3.27.7) so GitHub Code Scanning / Multitool link OA001-OA008 to the extension; version the override extension component from getCliVersion() instead of a "1.0.0" literal. - HTML report: render nothing when override hygiene was not requested (undefined), vs the "no findings" panel for an empty result set. - fixer: refuse a move into an already-occupied destination instead of silently overwriting it (the chokepoint guard only catches key-set growth, not clobber). - terminal: "applyable patch" -> "autofix available". Tests: +5 (hook-gating contract, SARIF rule ref + version, HTML omit, move guard); 2 updated. 832 green.

alamb-hex · 2026-06-20T01:52:42Z

@sonukapoor all eight points are addressed in 2ca5b05 — replies inline on each thread, README aligned with the gated --fix behavior, full suite green at 832 (+5 tests). Ready for another look whenever you have a minute.

#1) The installed-tree walker skipped `.pnpm` along with other dotfiles, so in a strict pnpm layout every transitive-only package (the real copies live under .pnpm/<name>@<ver>/node_modules/<name>) was invisible. installedCopies came back empty for those packages, which: - false-positived OA006 (overrideWonOnDisk saw 0 copies -> "override not confirmed on disk") on the canonical next->postcss pattern, and - blinded OA008's materialization check to genuinely below-floor copies in the store (false negative). Descend into the virtual store and dedupe by realpath so a package reachable both via a top-level symlink and via the store is counted once. Closes #1.

#3) --ratchet unconditionally re-saved the current findings as the baseline and exited 0, so a newly introduced vulnerability was silently absorbed into a fresh baseline - a ratcheted CI job could never fail on a regression. Add ratchetOutcome(): with no baseline, save (unchanged); with an existing baseline, gate - report findings not in the baseline and exit 1 without overwriting. Matches the documented "if baseline exists, only fail on new findings." Closes #3.

sonukapoor

All 8 requested changes are correctly addressed - thank you for the thorough fixes. One new issue crept in with the ratchet rewrite: the three --ratchet exit paths don't call auditLogHandle.close(). Same pattern as the process.exit(2) fix you just landed - detail inline. Everything else looks good.

sonukapoor · 2026-06-20T12:31:28Z

+          if (options.checkOverrides) {
+            console.log(chalk.gray("Note: override hygiene (--check-overrides) is not part of the ratchet baseline; run `cve-lite overrides` to audit overrides."));
+          }
+          process.exit(0);


The three --ratchet exit paths here (lines 532, 540, 549) skip auditLogHandle.close() and the scan.finished emit. Same issue as the process.exit(2) path you fixed - the audit log FD is leaked and the log is missing the terminal event. Each of the three exits needs the same treatment:

auditLogHandle.emit({ ts: new Date().toISOString(), type: "scan.finished", schemaVersion: 1, durationMs: Date.now() - scanStartTime, findingsCount: scanState.sorted.length, exitCode: 0 }); auditLogHandle.close(); process.exit(0);

(exitCode: 1 for the new-findings branch at line 549.)

Fixed in 87835ae. All three ratchet exit paths (baseline saved, no new findings, new findings) now emit scan.finished with the correct exitCode (0/0/1) and call auditLogHandle.close() before process.exit, matching the process.exit(2) pattern. Full suite green.

… ratchet exit paths The ratchet gate (#3 fix) added three process.exit() sites that skipped the scan.finished emit and auditLogHandle.close(), leaking the FD and dropping the terminal audit-log event - the same defect class as the process.exit(2) fix. Each ratchet exit (baseline saved, no new findings, new findings) now emits scan.finished with the right exitCode and closes the handle before exiting.

alamb-hex · 2026-06-20T15:47:14Z

@sonukapoor ratchet audit-log leak fixed in 87835ae - all three exit paths now emit scan.finished + close() before exiting (same pattern as the exit(2) fix). Suite green. Ready for another look.

alamb-hex · 2026-06-20T15:56:00Z

@sonukapoor one structural question before you re-review: the --ratchet gate fix is actually independent of override hygiene. It fixes a pre-existing bug in upstream's ratchet feature (with an existing baseline, --ratchet re-saved instead of gating, so CI never failed on a new finding) and touches only index.ts / utils/baseline.ts / baseline.test.ts - no override code. The audit-log teardown fix I just pushed (87835ae) only patches that rewrite's exit paths.

Both are the two tip commits on the branch, so they're cleanly separable. I'm happy to pull them into their own focused PR to keep this one purely the override-hygiene subsystem - or leave them here since you've already reviewed the rewrite. Whichever you prefer for review and merge.

I've filed the underlying bug as #721 so it's tracked on its own regardless of which way you want the fix to land.

sonukapoor

All issues resolved - the ratchet exit paths are correctly fixed across all three sites, consistent with the process.exit(2) pattern from the prior commit. Happy to keep the ratchet gate fix here given it was surfaced during this review and is already tracked under #721. Merging.

sonukapoor · 2026-06-20T16:32:34Z

Merged - thank you @alamb-hex! Outstanding contribution.

alamb-hex mentioned this pull request Jun 20, 2026

fix(cli): error on a mistyped command instead of silently scanning and exiting 0 #719

Merged

sonukapoor requested changes Jun 20, 2026

View reviewed changes

alamb-hex added 2 commits June 20, 2026 02:59

sonukapoor requested changes Jun 20, 2026

View reviewed changes

alamb-hex mentioned this pull request Jun 20, 2026

--ratchet always overwrites an existing baseline; never fails on new findings (CI gate is ineffective) #721

Closed

sonukapoor approved these changes Jun 20, 2026

View reviewed changes

sonukapoor merged commit b8cba84 into OWASP:main Jun 20, 2026
6 checks passed

Uh oh!

Conversation

alamb-hex commented Jun 20, 2026

What it adds

Additive by design

Verification

Notes

Uh oh!

sonukapoor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alamb-hex commented Jun 20, 2026

Uh oh!

sonukapoor left a comment

Choose a reason for hiding this comment

Uh oh!

sonukapoor Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

alamb-hex Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

alamb-hex commented Jun 20, 2026

Uh oh!

alamb-hex commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonukapoor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonukapoor commented Jun 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alamb-hex commented Jun 20, 2026 •

edited

Loading