Skip to content

docs: add vulnerability data sources section to how-it-works #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sonukapoor merged 1 commit into from
May 15, 2026
Merged

docs: add vulnerability data sources section to how-it-works #355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 0 additions & 100 deletions src/docs/network-and-privacy.md
View file
Open in desktop

This file was deleted.

13 changes: 12 additions & 1 deletion website/docs/how-it-works.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,19 @@ CVE Lite CLI is a **local-first, metadata-only** scanner. It operates directly w
<img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
</p>

## Vulnerability data sources

CVE Lite CLI queries the [OSV API](https://osv.dev) (`api.osv.dev`), an open vulnerability aggregator maintained by Google. OSV is the only external query target — not because other databases are ignored, but because OSV already aggregates the databases that matter for npm packages.

**Why not NVD directly?** NVD's API does not support queries by package ecosystem. It uses CPE (Common Platform Enumeration) identifiers, which are vendor/product strings that don't map cleanly to npm package names. In practice, npm CVEs are reviewed and assigned version ranges by the GitHub Advisory Database (GHSA) before they reach NVD — so GHSA is the authoritative source for npm vulnerability data.

**Why not GHSA directly?** GHSA is a first-class data source inside OSV. OSV ingests GHSA advisories directly, so querying GHSA separately returns the same data. This was verified by comparing OSV and GHSA API results for the same package: the vast majority of vulnerability IDs returned by OSV for npm packages are GHSA IDs, and OSV includes GHSA as a first-class source for the npm ecosystem.

**Freshness:** There is a short window — typically minutes — between GHSA publishing an advisory and OSV reflecting it. If you need the freshest results immediately after a known disclosure, run with `--no-cache` to bypass the local query cache and query OSV directly — though note that the OSV ingestion window is a separate delay that `--no-cache` cannot overcome.

## Contents

- [Vulnerability data sources](#vulnerability-data-sources)
- [Trust boundary and privacy](#trust-boundary-and-privacy)
- [Lockfile-driven accuracy](#lockfile-driven-accuracy)
- [Direct vs transitive triage](#direct-vs-transitive-triage)
Expand All @@ -24,7 +35,7 @@ The scan is non-intrusive. Only package names and exact resolved versions are ex

CVE Lite CLI does not require a hosted account, cloud dashboard, or source code upload.

For the full explanation, see [Network Behavior and Privacy](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/network-and-privacy.md).
For the full explanation, see [Security Assurance Case](security-assurance-case.md).

---

Expand Down