Upgrade note. Six changes can affect an existing setup.
- Node 22.13.0 or later on the 22.x line, or 23.4.0 and later, is now required. The offline advisory database uses the SQLite driver built into Node.js instead of
better-sqlite3, so installs with scripts disabled now work and there is no native module to build.- A scan that finds nothing to parse, with no lockfile and no exact-pinned
package.json, now exits 3 instead of 0, with or without--fail-on. Pass--allow-empty, or set the Action'sallow-emptyinput, to keep the old behaviour.cve-lite --report <dir>with no project path is refused, since the folder after--reportwas being read as the report directory and the wrong folder scanned. Use--report=<dir>, or put the project path first.- Some CycloneDX ratings come out lower, because a severity no longer carries over from one advisory to another advisory for the same package.
- The first scan after upgrading runs with a cold OSV cache, because the cache format changed.
- A known malicious package now fails
--fail-onat any level, including the default.
Added
- A GitLab CI/CD template. One
includeline in.gitlab-ci.ymladds acve-lite-scanjob, with inputs named like the GitHub Action's (fail-on,prod-only,sbom,offline,ca-certand others). It scans one project, set withpath, and publishes the JSON report and an SBOM as job artifacts, including when findings fail the job. See the new GitLab CI/CD docs page. --sbomaccepts several formats in one run, comma-separated or by repeating the flag (--sbom cyclonedx,spdx,--cdx --sbom spdx), and writes one file per format with a shared timestamp. A single output file or standard output is refused when more than one format is requested.- CycloneDX and SPDX SBOMs record the advisory database behind the scan: whether it ran offline, when the local database was last synced, and where it came from. Output is unchanged when no such metadata is available.
- EXPERIMENTAL:
--pythonscans pinnedrequirements.txtfiles (name==version) against OSV's PyPI data. Python findings are reported but never change the exit code, and Python is refused with--sbomand--offline. Pinned lines carrying an environment marker are scanned whatever the marker says, with a note counting them. Unpinned or unsupported lines, and included files (-r,-c) that were not scanned, mark the scan partial. Nothing changes without the flag.
Changed
- Offline scans and advisory database commands work with npm install scripts disabled. They use the SQLite driver bundled with Node.js and read existing databases unchanged. Node 22 marks its SQLite API experimental.
- A scan that finds nothing to parse exits 3, which now also means "nothing to scan". JSON modes give the reason on standard error, and the terminal adds a hint about
--allow-empty. The Action's pull request comparison treats an empty base branch as having no findings. cve-lite --report <dir>with no project path is refused with guidance to use--report=<dir>or to put the project path first.--report ./out .,. --report ./outand--report=<dir>all still work.- A known malicious package (a MAL- advisory) fails
--fail-onat any level, including the default, on single and multi-folder scans, and the gate line names it. It used to score as unknown severity and pass every threshold exceptlowwhile the output said to remove it. Runs without--fail-onare unchanged. - Lockfile selection follows one ordered list per package manager. When a project holds both npm lockfiles, the notice now explains that npm reads
npm-shrinkwrap.jsonfirst. - Bun lockfile parsing stops expanding a package's dependency paths once it already holds the per-package path limit, which did a large amount of work on wide graphs for no change in output.
- Contributors can claim an issue by commenting
/assign-me; the claim is confirmed by replying with local test output within two days. - Pull requests are checked against the contribution rules (a linked issue, an author who claimed or opened it, at most five open pull requests each) and get a comment when they do not meet them.
Security
- Package names, advisory summaries, warnings and table cells are cleaned of terminal escape codes, control characters and CI workflow command markers (
::error::,##[) before they are printed, so a crafted lockfile name or advisory text can no longer send commands to GitHub Actions or Azure Pipelines or rewrite the terminal. A fix whose name or version carries such a marker is withheld with the reason. Some output wording changes: triage hints use a·bullet, and the compactFix:text is reworded. - Local advisory databases, including one passed with
--offline-db, are opened with SQLite'strusted_schemaoff, so a crafted database file cannot run functions from triggers or views. - Resolved URLs from lockfiles drop embedded credentials and token query parameters before they reach SBOMs or terminal output.
Fixed
- OSV batch queries follow OSV's paged results, so a large scan no longer silently drops the advisories past the first page.
- Offline scans match advisories that list explicit affected versions with no ranges, so a known malicious package is reported and fails the gate instead of scanning clean. An older local database is upgraded when opened, with a note on how to refresh it.
- A failed advisory detail lookup is retried, and if it still fails a cached copy of the details is used and disclosed with its age in the terminal, HTML, JSON and SARIF, without marking the scan incomplete. Under
--incomplete-policy errorsuch a scan fails with the reason, including--ratchetruns. - A
--fail-onrun where some advisories could not be evaluated, for example after a rate-limited detail lookup, prints how many and points at--incomplete-policy error, including when the finding is accepted by a baseline. The exit code under the default policy is unchanged. - A nested project's lockfile is chosen by the same rules as the root's: the
packageManagerfield first, then precedence, with shrinkwrap beforepackage-lock.json. Every run decides multi-folder mode the same way, the lockfile notice names the nested folder, and the debug bundle reports "multiple" on multi-folder runs. - npm v1 lockfiles keep each dependency's resolved URL, so the registry and alias checks that rely on it work on them too.
- Single-project pnpm v5 and v6 lockfiles without an
importersblock map their root dependencies, so within-range commands no longer carry a pointless--recursive. - In a Bun workspace, install commands for a member run from the member's folder (
bun add --cwd '<member>'), since Bun 1.3 rejects or ignores--filteronbun add. A package declared at the root and in a member gets a plainbun addfor the root followed by the member command, and--fixruns the same. - A validated chain upgrade of a dev-only parent prints its dev flag (
-D, or--devon Bun) in the per-finding command and the target's command, matching the fix plan. The JSON runnable command, SPDX and CycloneDX are corrected too. - When a parent already allows the fixed version, the JSON, HTML, SARIF, CycloneDX and SPDX recommendation names the project's package manager (
pnpm install,yarn install,bun install) instead of alwaysnpm install. - When
--fixfails, the package manager's error code (npmERESOLVE, pnpmERR_PNPM_..., Yarn's last code) is reported with a command to rerun for full details, without echoing raw output that could carry tokens, registry hosts or local paths. - The compact view no longer says vulnerabilities were found and then shows none when every finding is medium or low; it falls back to the most severe ones, up to the usual limit.
- CycloneDX SBOMs keep every advisory for a package. Identifiers are chosen per advisory, so a CVE alias on one advisory no longer hides an independent advisory without one, and each advisory carries its own severity and recommendation. When advisories share a CVE, the entry keeps the highest known severity.
- SARIF rule help for an advisory with several affected windows shows the window that matches the installed version and its fix, instead of always the first window.
- SARIF locations for a Bun project point at
bun.lockrather than the unsupported binarybun.lockb. --check-licenseson pnpm, Yarn and Bun projects reads the license of the installed version rather than the latest release, soua-parser-js@1.0.41(MIT) no longer gets an AGPL finding. Missing version metadata reports LC002 instead of borrowing another release's license.--check-licenseswith--prod-onlyon npm projects no longer reports dev-only packages, on single and multi-folder scans.--check-licensesreports EPL, EUPL, OSL, CDDL and CPL licenses as copyleft (LC001), including lowercase and compound expressions.- When OA010 raises a vulnerable caret override floor it keeps the caret's ceiling, so
^0.2.0becomes>=0.2.5 <0.3.0-0rather than>=0.2.5 <1.0.0, which admitted later minor releases. - OA009 no longer treats a parent's upper bound (
<2.0.0,<=1.5.0) as a floor, so it stops calling an override redundant when no parent guarantees the version. - OA008 checks override floors written as
npm:aliases, which it used to skip as invalid ranges. - The OA010 message lists each vulnerable version once instead of once per advisory.
overrides --fixfor OA005 removes only the flagged nested pin instead of the whole outer override, and npm's"."self-pin is no longer reported as an undeclared dependency.overrides --ruleaccepts rule IDs in any case and stops with a clear error listing the valid rules when given an unknown one.- Fix pull requests opened by
--create-prand the Action show package names as code, so a scoped name such as@babel/coreno longer notifies the GitHub account or organisation it resembles. --min-severityrejects values that are not a severity level. An unknown value such asmoderatesilently fell back to critical and hid every lower finding.--search-depthrejects values that are not whole numbers;0still means root only.--base,advisories sync --ca-certand theadvisoriescommands'--outputstop with a clear error when the value is missing or another flag is given in its place.--report=with an empty value is refused instead of writing to an unnamed path.cve-lite advisorieswith no subcommand or an unknown one stops with a clear error listing the valid subcommands, instead of trying to scan a folder namedadvisories.advisories syncrefuses-as its output path, and its progress reaches the total even when withdrawn or unusable records are skipped.- A bad
--audit-logpath orCVE_LITE_AUDIT_LOGvalue prints one line naming the source, the path and the reason instead of a stack trace, and missing parent folders for the log file are created.
Tests
- CI validates the SPDX SBOM with the official spdx-tools validator.
- A manual script checks PEP 440 version ordering against Python's
packaginglibrary on real PyPI advisories. It is kept outside the build and the npm package.
Docs
- The docs say which dependency metadata is sent to OSV during an online scan.
- The website navigation fits on one row on laptop-width screens, with a Resources menu.
Validation
- npm test
- npm run build
Contributors
- @vianmangal, who wrote the GitLab CI template, the move to Node's built-in SQLite, OSV pagination, offline matching of malicious package records, CycloneDX advisory and severity fixes, license version and copyleft fixes, the OA010 caret ceiling fix, and the
--reportand--baseguards - @Nachiket-Roy, who wrote multi-format
--sbom, SBOM advisory database metadata, output sanitising against workflow command injection, the SQLitetrusted_schemahardening, the compact-view fallback and the--fail-onnotice for unevaluated advisories - @muntasir-396
- @bhushan4work, who wrote the experimental
--pythonscanning, Bun workspace member commands and the SARIF affected-window fix - @prx-my, who wrote the
/assign-meand pull request rules workflows, the OA005 fix and the Bun path cap, and cleared the test type-check backlog - @coder-Yash886, who wrote the resolved-URL credential stripping
- @shryssssss-maker
- @alex-powell
- @luojiyin1987
- @ahmed-sherif-hassona
- @adarshswaminath
- @sarthakdev143-lite
- @costajohnt
- @sarankumar1325
- @ahmetkurtbm
- @Thijs226, co-author of the empty-scan exit code change