Skip to main content

Ratcheting Mode

When adopting CVE Lite CLI as a hard CI gate on a codebase that already has vulnerabilities, --fail-on will block every PR until all pre-existing issues are resolved. That is rarely realistic on a production codebase.

Ratcheting lets you accept the current state and only fail on findings introduced above that baseline. Existing vulnerabilities are tracked but do not block - they get cleaned up gradually. Once you fix one, the baseline drops and can never go back up.

Setup​

Run once locally to snapshot the current findings:

cve-lite . --ratchet

This creates .cve-lite/baseline.json in your project root. A missing baseline accepts no debt, so this first run still applies the --fail-on gate (default critical): it exits 1 if any finding is at or above the threshold, and 0 otherwise. That keeps a fresh CI checkout without a committed baseline from passing silently. Commit the file so your whole team and CI share the same baseline; from then on, only findings above it fail.

git add .cve-lite/baseline.json
git commit -m "chore: establish vulnerability baseline"

Multi-folder / workspace projects​

When there is no root lockfile and CVE Lite scans nested packages (multi-folder mode), --ratchet writes a per-subfolder baseline — each scanned folder gets its own .cve-lite/baseline.json. That matches scanning a folder on its own (cve-lite packages/api --ratchet), so a baseline stays valid whether the folder is scanned alone or as part of the monorepo.

cve-lite . --ratchet
# packages/api/.cve-lite/baseline.json
# packages/web/.cve-lite/baseline.json
git add '**/.cve-lite/baseline.json'

Subsequent multi-folder scans with an existing per-folder baseline suppress known findings in that folder. --ratchet again gates each folder independently and fails if any folder has findings above its baseline. A folder with no baseline yet is saved and gated by --fail-on, the same as the single-folder first run.

How it works in CI​

No flag changes needed. Once the baseline file exists, every scan automatically suppresses known findings:

cve-lite . --fail-on high

Pre-existing findings are hidden. Only new findings - things introduced above the baseline - trigger failure. Your existing CI commands work exactly as before.

Output​

When all findings are suppressed:

✓ Scan complete. No known vulnerabilities found.

No new findings above baseline - 7 existing findings suppressed

When new findings appear:

3 new findings above baseline - 7 existing findings suppressed

Updating the baseline​

After fixing some vulnerabilities, reset the baseline by running --ratchet again:

cve-lite . --ratchet
git add .cve-lite/baseline.json
git commit -m "chore: update vulnerability baseline"

Because the baseline is committed to git, every update is tracked and reversible.

Ignoring the baseline​

To run a full scan without suppression, delete or rename .cve-lite/baseline.json. No flag needed. The file's presence is what activates ratcheting.

How matching works​

A finding is suppressed if every advisory ID on that name@version combination was present when the baseline was saved. If a package gains a new advisory ID not in the baseline, that finding surfaces as new - even if the package version itself was already baselined.

This means:

  • Same package, same version, same advisory - suppressed
  • Same package, same version, new advisory - surfaces as new
  • New package not in baseline at all - surfaces as new

See also​