From 5a56810eedf7f99ac59c7cc711edb5c9d1682bd0 Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Fri, 15 May 2026 12:00:00 -0400 Subject: [PATCH] docs: add vulnerability data sources section and remove redundant network-privacy doc Closes #354 --- src/docs/network-and-privacy.md | 100 -------------------------------- website/docs/how-it-works.md | 13 ++++- 2 files changed, 12 insertions(+), 101 deletions(-) delete mode 100644 src/docs/network-and-privacy.md diff --git a/src/docs/network-and-privacy.md b/src/docs/network-and-privacy.md deleted file mode 100644 index 42fc5c3..0000000 --- a/src/docs/network-and-privacy.md +++ /dev/null @@ -1,100 +0,0 @@ -# Network Behavior and Privacy - -CVE Lite CLI is a local-first dependency vulnerability scanner for JavaScript and TypeScript projects. This document explains what it does locally, when it makes external calls, and how it supports stricter environments today. - -## Overview - -CVE Lite CLI scans project dependency data on the machine where you run it. It is intended for developers and teams who want a practical vulnerability check close to release time, without adopting a larger hosted security platform. - -The tool does not require a hosted account or external dashboard. - -## What happens locally - -When you run CVE Lite CLI, the following work happens locally: - -- reading supported lockfiles -- extracting dependency package information -- classifying findings as direct or transitive -- prioritizing fix candidates -- generating CLI or JSON output -- using local cache data where available - -This local-first design keeps the workflow simple and helps teams understand what the tool is doing. - -## External calls in standard mode - -In its standard mode, CVE Lite CLI queries OSV for advisory data used in vulnerability matching. - -This means the scanner may make outbound network requests during a scan in order to retrieve vulnerability information for the dependencies it is checking. - -## Current outbound destination - -In standard mode, CVE Lite CLI retrieves advisory data from OSV over HTTPS. - -Current base URL: -- https://api.osv.dev/ - -This is the default public advisory service used by the tool today. - -## What is not uploaded - -CVE Lite CLI is not designed as a source-code upload service. - -- application source code is not uploaded -- the tool does not require a hosted dashboard -- the tool does not require a user account - -## Local cache behavior - -CVE Lite CLI uses local caching to reduce repeated advisory lookups and improve scan speed. - -This helps keep repeat scans fast and reduces unnecessary network activity. - -## Why this documentation exists - -Some teams, especially in enterprise, regulated, or restricted CI environments, need to understand exactly when a tool makes outbound calls. - -This document exists to make that behavior explicit and reviewable. - -## Support for stricter environments - -CVE Lite CLI already supports multiple patterns for teams with stricter network controls. - -### Offline mode - -Offline scans can run with zero outbound advisory API calls by using a local advisory database. - -Example workflow: - - cve-lite advisories sync - cve-lite . --offline - -Or with an explicit DB path: - - cve-lite advisories sync --output /path/to/advisories.db - cve-lite . --offline-db /path/to/advisories.db - -### Custom advisory endpoint support - -Organizations can route standard online advisory lookups through an internal proxy or mirrored service with `--osv-url`. - -Example workflow: - - cve-lite . --osv-url https://security.company.internal/osv - -### Advisory DB freshness - -Offline scans report advisory DB freshness and warn when the local DB appears stale or is missing sync metadata. - -This makes the tradeoff explicit: - -- offline scans avoid runtime advisory API calls -- advisory data is only as current as the last successful sync - -### Operational model - -For many teams, the recommended model is: - -- sync advisory data on a schedule from a connected environment -- distribute the local advisory DB where needed -- run offline scans in controlled developer, CI, or restricted-network environments diff --git a/website/docs/how-it-works.md b/website/docs/how-it-works.md index 455c93a..3ea279b 100644 --- a/website/docs/how-it-works.md +++ b/website/docs/how-it-works.md @@ -6,8 +6,19 @@ CVE Lite CLI is a **local-first, metadata-only** scanner. It operates directly w CVE Lite CLI Workflow

+## 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) @@ -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). ---