Merge pull request #80 from sonukapoor/feature/issue-77-readme-offline-support

[Enhancement] Make offline advisory DB support prominent in the README

Author: sonukapoor

README.md

@@ -27,6 +27,29 @@
 
 **CVE Lite CLI** helps developers scan their projects for known package vulnerabilities without signing up for an expensive platform. It is built for the moment right before release, when you want a clear answer, a practical fix plan, and a tool you can actually afford to use.
 
+## New: Offline advisory DB support
+
+CVE Lite CLI now supports a local advisory database workflow for teams that cannot allow runtime outbound advisory API calls.
+
+That means you can:
+
+- sync advisory data ahead of time
+- scan projects fully offline
+- use the tool in restricted, enterprise, or air-gapped environments more easily
+
+Example offline workflow:
+
+```bash
+# Build the local advisory database
+cve-lite advisories sync
+
+# Scan using the default local advisory DB
+cve-lite /path/to/project --offline
+
+# Or scan using a specific local advisory DB file
+cve-lite /path/to/project --offline-db /path/to/advisories.db
+```
+
 ## Quick start
 
 Install globally:
@@ -74,6 +97,15 @@ cve-lite /path/to/project --sarif --output reports/scan.sarif
 
 # Use a custom advisory endpoint
 cve-lite /path/to/project --osv-url https://security.company.internal/osv
+
+# Build the local advisory DB for offline scans
+cve-lite advisories sync
+
+# Scan with zero runtime advisory API calls
+cve-lite /path/to/project --offline
+
+# Use a specific local advisory DB file
+cve-lite /path/to/project --offline-db /path/to/advisories.db
 ```
 
 ## What it looks like
@@ -145,6 +177,7 @@ The project emphasizes:
 - direct vs transitive visibility
 - top-priority fixes and a suggested remediation plan
 - JSON and SARIF output for automation
+- offline scanning through a local advisory database
 - configurable advisory endpoint support via `--osv-url` for internal proxies or mirrors
 - a small, reviewable runtime footprint
 
@@ -166,19 +199,73 @@ This section is here to make the scope clear. CVE Lite CLI aims to complement th
 
 ## Network behavior and privacy
 
-CVE Lite CLI is a local-first scanner. It parses dependency information locally, uses local caching to reduce repeated lookups, and in standard mode queries OSV for advisory data needed for matching.
+CVE Lite CLI is a local-first scanner. It parses dependency information locally, uses local caching to reduce repeated lookups, and in standard mode queries OSV for advisory data needed for matching. It also now supports a local advisory database workflow for offline scans with zero runtime advisory API calls.
 
 It 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).
 
-### Planned support for stricter environments
+### Offline workflow
+
+For teams in controlled or restricted environments, the intended model is:
+
+1. sync advisory data into a local database
+2. distribute that database as needed
+3. scan projects using the local DB instead of runtime OSV API calls
+
+Sync the local advisory database:
+
+```bash
+cve-lite advisories sync
+```
+
+Write the advisory database to a specific path:
+
+```bash
+cve-lite advisories sync --output /path/to/advisories.db
+```
+
+Scan using the default local advisory DB:
+
+```bash
+cve-lite . --offline
+```
+
+Scan using an explicit local advisory DB file:
 
-Support for stricter network-controlled environments is planned on the roadmap, including:
+```bash
+cve-lite . --offline-db /path/to/advisories.db
+```
+
+Keep the local advisory DB fresh with a scheduled job when needed. For example, teams can run a cron job, CI job, or other scheduler to refresh the advisory DB periodically:
+
+```bash
+cve-lite advisories sync --output /path/to/advisories.db
+```
+
+That helps ensure offline scans continue using current advisory data without requiring developers to remember to refresh the DB manually every time.
+
+Standard online mode remains available when you want live OSV-backed scans:
+
+```bash
+cve-lite . --osv-url https://security.company.internal/osv
+```
+
+### Advisory DB freshness
+
+The local advisory DB is only as current as the last successful sync.
+
+For now, the recommended model is:
 
-- offline scanning mode with zero outbound calls
-- custom advisory endpoint support for internal mirrors or proxies
-- local advisory database input for controlled or air-gapped workflows
+- sync the advisory DB on a schedule using cron, CI, or another automation system
+- distribute the refreshed DB where needed
+- run offline scans against that updated DB
+
+A future improvement is to add built-in advisory DB freshness metadata, such as:
+
+- last sync timestamp reporting
+- a TTL-style warning when the DB is older than a recommended threshold
+- clearer CLI guidance when a local advisory DB should be refreshed
 
 ## Detecting malicious package incidents
 
@@ -209,6 +296,7 @@ CVE Lite CLI is designed as a **local-first, metadata-only** scanner. Unlike tra
 * **Lockfile-Driven Accuracy:** By parsing `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`, the tool avoids the "it works on my machine" discrepancy. It scans the *exact* dependency tree that will be deployed.
 * **Intelligent Triage:** The Analysis engine utilizes the lockfile's graph structure to distinguish between dependencies you manage directly and those brought in by third-party packages (transitive). This allows for a "Fix the Root" strategy rather than chasing individual nested vulnerabilities.
 * **Performance Optimization:** A local TTL (Time-To-Live) cache stores advisory results. This ensures that subsequent scans—common in iterative development or CI/CD retry loops—are near-instant and respect external API rate limits.
+* **Offline-Capable Advisory Flow:** Advisory data can be synced into a local SQLite database and reused for offline scans with zero runtime advisory API calls.
 * **Standards-Based Output:** Results are natively available in **SARIF (Static Analysis Results Interchange Format)** and **JSON**, ensuring compatibility with modern DevSecOps dashboards and IDE integrations.
 
 ## What makes it stand out
@@ -225,6 +313,8 @@ CVE Lite CLI is designed as a **local-first, metadata-only** scanner. Unlike tra
   It is intended for developers and teams who want useful security checks without paying for a large commercial product.
 - **local-first**  
   It reads your project locally and uses package/version matching against OSV advisories.
+- **offline-capable**
+  It can sync and scan against a local advisory database for zero-runtime-network workflows.
 - **release-focused**  
   It is especially useful before a release, in CI, or during final dependency cleanup.
 
@@ -289,15 +379,26 @@ cve-lite /path/to/project --sarif --output reports/scan.sarif
 
 The CLI can be used in CI/CD pipelines and can fail builds based on severity thresholds.
 
-### 9. Local cache
+### 9. Offline advisory DB support
+
+The CLI can sync the official OSV npm advisory dump into a local SQLite advisory database and scan against it later with zero runtime advisory API calls.
+
+That makes it more practical for:
+
+- enterprise environments
+- restricted CI systems
+- air-gapped workflows
+- teams that want explicit local advisory control
+
+### 10. Local cache
 
 It caches advisory detail results locally so repeated scans are faster and make fewer repeated requests.
 
-### 10. Clear final scan status
+### 11. Clear final scan status
 
 At the end of each run, CVE Lite CLI prints a short final status line so users immediately know whether the scan was clean or whether they should start with the priority fixes above.
 
-### 11. Small runtime footprint
+### 12. Small runtime footprint
 
 This project intentionally keeps runtime dependencies minimal to reduce attack surface and keep the tool easier to review.
 
@@ -308,6 +409,8 @@ CVE Lite CLI is intentionally designed with a very small dependency surface.
 **Runtime dependencies**
 - `yaml`
 - `yarn-lockfile`
+- `better-sqlite3`
+- `fflate`
 
 **Development dependencies**
 - `@types/node`
@@ -326,13 +429,21 @@ CVE Lite CLI is a good fit for:
 - teams that want a lightweight dependency scan in CI
 - developers who want a second opinion alongside other tools
 - OSS maintainers who need a practical scan before publishing
+- teams that need offline or controlled-network dependency scanning
 
 ## Supported workflows
 
 ### Local development
 
 Run it before a release, during dependency cleanup, or after a major package upgrade.
 
+For offline-capable local workflows:
+
+```bash
+cve-lite advisories sync
+cve-lite . --offline
+```
+
 ### CI/CD
 
 This repository also uses CVE Lite CLI in its own GitHub Actions workflow to scan itself as part of CI. See [`self-scan.yml`](https://github.com/sonukapoor/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
@@ -359,6 +470,13 @@ Use JSON output for custom reporting:
 cve-lite . --json > cve-lite-report.json
 ```
 
+Use an offline local advisory DB in controlled environments:
+
+```bash
+cve-lite advisories sync --output ./.cache/advisories.db
+cve-lite . --offline-db ./.cache/advisories.db --json > cve-lite-report.json
+```
+
 ## Comparison with other tools
 
 CVE Lite CLI is not trying to be everything for everyone. It is designed to be one of the easiest and most actionable vulnerability scanners for JavaScript and TypeScript developers who want fast release-time checks without the cost and complexity of a full security platform.
@@ -376,6 +494,7 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
 - support for **npm**, **pnpm**, and **Yarn** lockfiles
 - **SARIF** and **JSON** output for CI and automation
 - a **lightweight**, **security-conscious** dependency footprint
+- **offline local advisory DB support** for controlled environments
 - a **developer-friendly** option for teams that want useful **CVE scanning without paying for a larger commercial product**
 
 ### At a glance
@@ -451,6 +570,7 @@ To keep the project honest, here is what it does **not** do in the current versi
 - it does not scan container images, binaries, secrets, or IaC
 - it does not replace a full application security program
 - it is currently focused on JS/TS dependency scanning
+- local advisory sync performance will need continued optimization as the advisory dataset grows
 
 ## Positioning
 
@@ -471,6 +591,7 @@ CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remed
 * **Official GitHub Action:** Create a dedicated Action for one-line setup in CI/CD pipelines.
 * **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
 * **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
+* **Workflow Integration Guidance:** Expand official workflow patterns for local scripts, hooks, CI, and offline developer adoption.
 
 ### Phase 3: Maturity & Compliance (Long-Term)
 * **Standardized SBOM Support:** Add the ability to export findings as an **SBOM (Software Bill of Materials)** in CycloneDX or SPDX formats.