cve-lite-cli 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,10 +5,10 @@
5
5
  [![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
6
6
 
7
7
  <div align="center">
8
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
8
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
9
9
 
10
10
  <h1>CVE Lite CLI</h1>
11
- <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.</p>
11
+ <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects, with offline support for restricted environments.</p>
12
12
 
13
13
  <strong>Scan. Prioritize. Fix.</strong>
14
14
 
@@ -23,10 +23,58 @@
23
23
 
24
24
  ---
25
25
 
26
+ ## Contents
27
+
28
+ <table>
29
+ <tr>
30
+ <td valign="top">
31
+ <strong>Overview</strong><br/>
32
+ <a href="#what-is-cve-lite-cli">What is CVE Lite CLI</a><br/>
33
+ <a href="#new-offline-advisory-db-support">Offline advisory DB support</a><br/>
34
+ <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
35
+ <a href="#what-it-looks-like">What it looks like</a><br/>
36
+ <a href="#why-this-tool-exists">Why this tool exists</a><br/>
37
+ <a href="#project-scope-and-differentiation">Project scope and differentiation</a>
38
+ </td>
39
+ <td valign="top">
40
+ <strong>Usage</strong><br/>
41
+ <a href="#quick-start">Quick start</a><br/>
42
+ <a href="#usage">Usage</a><br/>
43
+ <a href="#workflow-modes">Workflow modes</a><br/>
44
+ <a href="#network-behavior-and-privacy">Network behavior and privacy</a><br/>
45
+ <a href="#features">Features</a><br/>
46
+ <a href="#supported-workflows">Supported workflows</a>
47
+ </td>
48
+ <td valign="top">
49
+ <strong>CI and Offline</strong><br/>
50
+ <a href="#dependency-footprint">Dependency footprint</a><br/>
51
+ <a href="#example-use-cases">Example use cases</a><br/>
52
+ <a href="#recommended-workflow-patterns">Recommended workflow patterns</a><br/>
53
+ <a href="#comparison-with-other-tools">Comparison with other tools</a><br/>
54
+ <a href="#current-limitations">Current limitations</a><br/>
55
+ <a href="#positioning">Positioning</a>
56
+ </td>
57
+ <td valign="top">
58
+ <strong>Project</strong><br/>
59
+ <a href="#roadmap">Roadmap</a><br/>
60
+ <a href="#contributing">Contributing</a><br/>
61
+ <a href="#community-and-support">Community and support</a><br/>
62
+ <a href="#license">License</a>
63
+ </td>
64
+ </tr>
65
+ </table>
66
+
26
67
  ## What is CVE Lite CLI
27
68
 
28
69
  **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.
29
70
 
71
+ It is designed to be:
72
+
73
+ - developer-friendly in day-to-day workflows
74
+ - local-first and transparent about network behavior
75
+ - usable in enterprise and restricted-network environments
76
+ - capable of zero-runtime-network scans through a local advisory database
77
+
30
78
  ## New: Offline advisory DB support
31
79
 
32
80
  CVE Lite CLI now supports a local advisory database workflow for teams that cannot allow runtime outbound advisory API calls.
@@ -50,6 +98,19 @@ cve-lite /path/to/project --offline
50
98
  cve-lite /path/to/project --offline-db /path/to/advisories.db
51
99
  ```
52
100
 
101
+ ## Why offline mode matters
102
+
103
+ For many teams, “works locally” is not enough. They also need a scanner that can fit into environments where runtime outbound calls are restricted, reviewed closely, or disallowed entirely.
104
+
105
+ Offline advisory DB support makes CVE Lite CLI more practical for:
106
+
107
+ - enterprise environments with strict network controls
108
+ - regulated teams that need explicit advisory data handling
109
+ - internal CI systems that should not depend on public runtime API access
110
+ - air-gapped or partially connected workflows
111
+
112
+ This is one of the most important differentiators in the project today because it improves both trust and adoptability, not just convenience.
113
+
53
114
  ## Quick start
54
115
 
55
116
  Install globally:
@@ -108,6 +169,34 @@ cve-lite /path/to/project --offline
108
169
  cve-lite /path/to/project --offline-db /path/to/advisories.db
109
170
  ```
110
171
 
172
+ ## Workflow modes
173
+
174
+ CVE Lite CLI now supports three clear advisory workflows:
175
+
176
+ ### 1. Standard online scan
177
+
178
+ Use the default OSV-backed mode when runtime advisory API access is acceptable:
179
+
180
+ ```bash
181
+ cve-lite /path/to/project
182
+ ```
183
+
184
+ ### 2. Advisory DB sync
185
+
186
+ Build or refresh the local advisory database ahead of time:
187
+
188
+ ```bash
189
+ cve-lite advisories sync
190
+ ```
191
+
192
+ ### 3. Offline local DB scan
193
+
194
+ Scan against the local advisory DB with zero runtime advisory API calls:
195
+
196
+ ```bash
197
+ cve-lite /path/to/project --offline
198
+ ```
199
+
111
200
  ## What it looks like
112
201
 
113
202
  CVE Lite CLI produces a clean, summary-first console view by default, designed for fast triage before release.
@@ -137,16 +226,16 @@ cve-lite .
137
226
  ```
138
227
 
139
228
  <p align="center">
140
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
229
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
141
230
  </p>
142
231
 
143
232
  Verbose examples:
144
233
 
145
234
  <p align="center">
146
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-1.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
147
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-2.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
148
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-3.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
149
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-4.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
235
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-1.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
236
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-2.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
237
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-3.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
238
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-4.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
150
239
  </p>
151
240
 
152
241
  ## Why this tool exists
@@ -197,6 +286,8 @@ Its role is narrower and workflow-focused:
197
286
 
198
287
  This section is here to make the scope clear. CVE Lite CLI aims to complement the broader security ecosystem by being a practical, low-friction option for JS/TS dependency checks close to release time.
199
288
 
289
+ One of the clearest examples of that focus is offline support: CVE Lite CLI is built to let teams explicitly sync advisory data and then scan locally, instead of forcing every environment to depend on runtime outbound vulnerability API access.
290
+
200
291
  ## Network behavior and privacy
201
292
 
202
293
  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.
@@ -219,6 +310,8 @@ Sync the local advisory database:
219
310
  cve-lite advisories sync
220
311
  ```
221
312
 
313
+ In our local benchmark on the same machine, syncing the OSV npm dump with about `217,065` advisory records improved from `87.53s` to `8.84s` after bulk SQLite ingestion optimizations, or about `9.9x` faster end-to-end. Results will vary by machine and network conditions.
314
+
222
315
  Write the advisory database to a specific path:
223
316
 
224
317
  ```bash
@@ -255,17 +348,15 @@ cve-lite . --osv-url https://security.company.internal/osv
255
348
 
256
349
  The local advisory DB is only as current as the last successful sync.
257
350
 
258
- For now, the recommended model is:
351
+ Offline scans now report advisory DB freshness and warn when the local DB appears stale or is missing sync metadata.
352
+
353
+ The recommended model is:
259
354
 
260
355
  - sync the advisory DB on a schedule using cron, CI, or another automation system
261
356
  - distribute the refreshed DB where needed
262
357
  - run offline scans against that updated DB
263
358
 
264
- A future improvement is to add built-in advisory DB freshness metadata, such as:
265
-
266
- - last sync timestamp reporting
267
- - a TTL-style warning when the DB is older than a recommended threshold
268
- - clearer CLI guidance when a local advisory DB should be refreshed
359
+ This helps keep offline scan results current without requiring developers to manually track advisory update cadence.
269
360
 
270
361
  ## Detecting malicious package incidents
271
362
 
@@ -288,7 +379,7 @@ So the practical model is: **local lockfile scan + advisory matching**. When mal
288
379
  CVE Lite CLI is designed as a **local-first, metadata-only** scanner. Unlike traditional SaaS security platforms that require code uploads or heavy agent installations, this tool operates directly within the developer's environment. It focuses on the "moment of release"—providing a high-speed, low-noise assessment of the dependency tree by analyzing resolved versions in project lockfiles.
289
380
 
290
381
  <p align="center">
291
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
382
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
292
383
  </p>
293
384
 
294
385
  ### Workflow Specifications
@@ -315,6 +406,8 @@ CVE Lite CLI is designed as a **local-first, metadata-only** scanner. Unlike tra
315
406
  It reads your project locally and uses package/version matching against OSV advisories.
316
407
  - **offline-capable**
317
408
  It can sync and scan against a local advisory database for zero-runtime-network workflows.
409
+ - **enterprise-friendly network model**
410
+ Teams can control when advisory data is synced and where offline scans run, which is valuable in restricted environments.
318
411
  - **release-focused**
319
412
  It is especially useful before a release, in CI, or during final dependency cleanup.
320
413
 
@@ -430,6 +523,7 @@ CVE Lite CLI is a good fit for:
430
523
  - developers who want a second opinion alongside other tools
431
524
  - OSS maintainers who need a practical scan before publishing
432
525
  - teams that need offline or controlled-network dependency scanning
526
+ - security-conscious organizations that need clear advisory data control
433
527
 
434
528
  ## Supported workflows
435
529
 
@@ -448,6 +542,49 @@ cve-lite . --offline
448
542
 
449
543
  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).
450
544
 
545
+ Use the reusable first-party GitHub Action in another repository:
546
+
547
+ ```yaml
548
+ name: Dependency Scan
549
+
550
+ on:
551
+ pull_request:
552
+ push:
553
+ branches: [main]
554
+
555
+ jobs:
556
+ cve-lite:
557
+ runs-on: ubuntu-latest
558
+ steps:
559
+ - uses: actions/checkout@v4
560
+ - uses: sonukapoor/cve-lite-cli@v1.1.1
561
+ with:
562
+ verbose: "true"
563
+ fail-on: high
564
+ ```
565
+
566
+ For an offline GitHub Actions workflow that refreshes the advisory DB first:
567
+
568
+ ```yaml
569
+ name: Offline Dependency Scan
570
+
571
+ on:
572
+ pull_request:
573
+
574
+ jobs:
575
+ cve-lite:
576
+ runs-on: ubuntu-latest
577
+ steps:
578
+ - uses: actions/checkout@v4
579
+ - uses: sonukapoor/cve-lite-cli@v1.1.1
580
+ with:
581
+ sync-advisories: "true"
582
+ offline: "true"
583
+ offline-db: ./.cache/cve-lite/advisories.db
584
+ verbose: "true"
585
+ fail-on: high
586
+ ```
587
+
451
588
  For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, and detailed table output when a scan fails.
452
589
 
453
590
  Use it as a release gate in CI:
@@ -477,6 +614,86 @@ cve-lite advisories sync --output ./.cache/advisories.db
477
614
  cve-lite . --offline-db ./.cache/advisories.db --json > cve-lite-report.json
478
615
  ```
479
616
 
617
+ ## Recommended workflow patterns
618
+
619
+ CVE Lite CLI is most useful when teams make it part of an explicit workflow instead of relying on developers to remember a one-off command.
620
+
621
+ The recommended pattern is:
622
+
623
+ 1. choose a scan command that matches your environment
624
+ 2. wire it into scripts, hooks, CI, or scheduled refresh jobs
625
+ 3. keep the behavior explicit so developers and security reviewers can see exactly when scans run and whether network access is involved
626
+
627
+ ### Package scripts
628
+
629
+ Add a simple script to the consuming project so developers have a memorable command:
630
+
631
+ ```json
632
+ {
633
+ "scripts": {
634
+ "security:scan": "cve-lite .",
635
+ "security:scan:offline": "cve-lite . --offline"
636
+ }
637
+ }
638
+ ```
639
+
640
+ This is the best default for most teams because it is visible, easy to document, and easy to reuse in local development and CI.
641
+
642
+ ### Opt-in postinstall usage
643
+
644
+ Some teams want dependency scanning to run immediately after packages are installed. CVE Lite CLI supports that workflow, but it is recommended as an explicit opt-in in the consuming project rather than hidden default behavior in the tool itself.
645
+
646
+ For example:
647
+
648
+ ```json
649
+ {
650
+ "scripts": {
651
+ "postinstall": "cve-lite . --offline || true"
652
+ }
653
+ }
654
+ ```
655
+
656
+ Why this is opt-in:
657
+
658
+ - install hooks should be visible to the team using them
659
+ - controlled environments often prefer offline scanning for install-time checks
660
+ - explicit project scripts are easier to review, tune, and disable than implicit package behavior
661
+
662
+ ### Git hooks
663
+
664
+ For teams that want a lightweight local gate before code leaves a workstation, a git hook can be a good fit:
665
+
666
+ ```bash
667
+ cve-lite . --fail-on high
668
+ ```
669
+
670
+ This works well in `pre-push` or another team-approved hook if you want to catch high-severity dependency issues before changes are shared.
671
+
672
+ ### CI pipelines
673
+
674
+ For CI, a strong baseline is:
675
+
676
+ ```bash
677
+ cve-lite . --verbose --fail-on high
678
+ ```
679
+
680
+ For controlled or restricted environments, sync the advisory DB separately and then scan offline:
681
+
682
+ ```bash
683
+ cve-lite advisories sync --output ./.cache/advisories.db
684
+ cve-lite . --offline-db ./.cache/advisories.db --verbose --fail-on high
685
+ ```
686
+
687
+ ### Scheduled advisory DB refresh
688
+
689
+ If you use offline mode, keep the advisory DB fresh with a scheduler such as cron, CI, or an internal automation system:
690
+
691
+ ```bash
692
+ cve-lite advisories sync --output /path/to/advisories.db
693
+ ```
694
+
695
+ This keeps offline scans current without forcing every developer machine or build runner to make live advisory API calls during the scan itself.
696
+
480
697
  ## Comparison with other tools
481
698
 
482
699
  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.
@@ -507,6 +724,16 @@ Compared with other tools in this space, CVE Lite CLI focuses on:
507
724
  | Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Strong | Teams adopting a larger security platform |
508
725
  | Socket CLI | Broader package and supply-chain risk visibility | Broad | Multi-ecosystem/package-risk focus | Strong for package risk workflows | Strong | Teams that want more than CVE scanning alone |
509
726
 
727
+ ### Offline support at a glance
728
+
729
+ | Tool | Local advisory DB workflow | Zero runtime advisory API calls |
730
+ |---|---|---|
731
+ | **CVE Lite CLI** | **Yes** | **Yes** |
732
+ | `npm audit` | No built-in local advisory DB workflow | No |
733
+ | OSV-Scanner | Depends on broader workflow setup rather than the local DB pattern emphasized here | Varies by setup |
734
+ | Snyk CLI | Not the primary workflow emphasis | Varies by product/workflow |
735
+ | Socket CLI | Not the primary workflow emphasis | Varies by product/workflow |
736
+
510
737
  ### CVE Lite CLI vs npm audit
511
738
 
512
739
  `npm audit` is the built-in default for npm users, which makes it convenient when your workflow is entirely npm-based.
@@ -527,6 +754,7 @@ CVE Lite CLI stands out when you want:
527
754
  - a narrower, easier-to-understand tool built specifically around JS/TS dependency workflows
528
755
  - remediation-first output instead of a more general multi-ecosystem scanner experience
529
756
  - a more approachable local workflow for everyday developers
757
+ - a more explicit local advisory DB workflow for offline or restricted environments
530
758
 
531
759
  ### CVE Lite CLI vs Snyk CLI
532
760
 
@@ -537,6 +765,7 @@ CVE Lite CLI stands out when you want:
537
765
  - a simpler and lighter dependency CVE workflow
538
766
  - an affordable option for small teams, startups, consultants, and independent developers
539
767
  - a focused tool for lockfile-based release checks without adopting a larger platform
768
+ - a more explicit offline scanning model with local advisory DB control
540
769
 
541
770
  ### CVE Lite CLI vs Socket CLI
542
771
 
@@ -588,7 +817,6 @@ CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remed
588
817
  * **Deduplication Analysis:** Identify instances where multiple versions of the same vulnerable package exist and suggest a single version for consolidation.
589
818
 
590
819
  ### Phase 2: Ecosystem & Integration (Mid-Term)
591
- * **Official GitHub Action:** Create a dedicated Action for one-line setup in CI/CD pipelines.
592
820
  * **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
593
821
  * **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
594
822
  * **Workflow Integration Guidance:** Expand official workflow patterns for local scripts, hooks, CI, and offline developer adoption.
@@ -26,10 +26,23 @@ const SCHEMA_SQL = `
26
26
 
27
27
  CREATE INDEX IF NOT EXISTS idx_advisory_packages_advisory
28
28
  ON advisory_packages (advisory_id);
29
+
30
+ CREATE TABLE IF NOT EXISTS advisory_db_metadata (
31
+ id INTEGER PRIMARY KEY CHECK (id = 1),
32
+ last_sync_at TEXT,
33
+ source_url TEXT
34
+ );
29
35
  `;
30
36
  export class LocalAdvisoryDatabase {
31
37
  dbPath;
32
38
  db;
39
+ upsertAdvisoryStatement;
40
+ deleteRangesStatement;
41
+ insertRangeStatement;
42
+ setMetadataStatement;
43
+ getMetadataStatement;
44
+ getVulnerabilityStatement;
45
+ findMatchingIdsStatement;
33
46
  constructor(dbPath, options) {
34
47
  this.dbPath = dbPath;
35
48
  const readonly = !!options?.readonly;
@@ -39,15 +52,7 @@ export class LocalAdvisoryDatabase {
39
52
  this.db = new Database(dbPath, readonly ? { readonly: true, fileMustExist: true } : undefined);
40
53
  this.db.pragma("foreign_keys = ON");
41
54
  this.db.exec(SCHEMA_SQL);
42
- }
43
- close() {
44
- this.db.close();
45
- }
46
- upsertVulnerability(vuln) {
47
- const advisoryRows = deriveAdvisoryPackageRows(vuln);
48
- const advisoryJson = JSON.stringify(vuln);
49
- const aliasesJson = JSON.stringify(vuln.aliases ?? []);
50
- const upsertAdvisory = this.db.prepare(`
55
+ this.upsertAdvisoryStatement = this.db.prepare(`
51
56
  INSERT INTO advisories (id, modified_at, aliases_json, summary, osv_json)
52
57
  VALUES (@id, @modified_at, @aliases_json, @summary, @osv_json)
53
58
  ON CONFLICT(id) DO UPDATE SET
@@ -56,11 +61,11 @@ export class LocalAdvisoryDatabase {
56
61
  summary = excluded.summary,
57
62
  osv_json = excluded.osv_json
58
63
  `);
59
- const deleteRanges = this.db.prepare(`
64
+ this.deleteRangesStatement = this.db.prepare(`
60
65
  DELETE FROM advisory_packages
61
66
  WHERE advisory_id = ?
62
67
  `);
63
- const insertRange = this.db.prepare(`
68
+ this.insertRangeStatement = this.db.prepare(`
64
69
  INSERT INTO advisory_packages (
65
70
  advisory_id,
66
71
  ecosystem,
@@ -77,27 +82,77 @@ export class LocalAdvisoryDatabase {
77
82
  @last_affected
78
83
  )
79
84
  `);
80
- const transaction = this.db.transaction(() => {
81
- upsertAdvisory.run({
82
- id: vuln.id,
83
- modified_at: null,
84
- aliases_json: aliasesJson,
85
- summary: vuln.summary ?? null,
86
- osv_json: advisoryJson,
87
- });
88
- deleteRanges.run(vuln.id);
89
- for (const row of advisoryRows) {
90
- insertRange.run(row);
85
+ this.setMetadataStatement = this.db.prepare(`
86
+ INSERT INTO advisory_db_metadata (id, last_sync_at, source_url)
87
+ VALUES (1, @last_sync_at, @source_url)
88
+ ON CONFLICT(id) DO UPDATE SET
89
+ last_sync_at = excluded.last_sync_at,
90
+ source_url = excluded.source_url
91
+ `);
92
+ this.getMetadataStatement = this.db.prepare(`
93
+ SELECT last_sync_at, source_url
94
+ FROM advisory_db_metadata
95
+ WHERE id = 1
96
+ `);
97
+ this.getVulnerabilityStatement = this.db.prepare(`
98
+ SELECT osv_json
99
+ FROM advisories
100
+ WHERE id = ?
101
+ `);
102
+ this.findMatchingIdsStatement = this.db.prepare(`
103
+ SELECT advisory_id, introduced, fixed, last_affected
104
+ FROM advisory_packages
105
+ WHERE ecosystem = ? AND package_name = ?
106
+ `);
107
+ }
108
+ close() {
109
+ this.db.close();
110
+ }
111
+ setMetadata(metadata) {
112
+ this.setMetadataStatement.run({
113
+ last_sync_at: metadata.lastSyncAt,
114
+ source_url: metadata.sourceUrl,
115
+ });
116
+ }
117
+ getMetadata() {
118
+ const row = this.getMetadataStatement.get();
119
+ return {
120
+ lastSyncAt: row?.last_sync_at ?? null,
121
+ sourceUrl: row?.source_url ?? null,
122
+ };
123
+ }
124
+ upsertVulnerability(vuln) {
125
+ const transaction = this.db.transaction((item) => {
126
+ this.upsertVulnerabilityInternal(item);
127
+ });
128
+ transaction(vuln);
129
+ }
130
+ bulkUpsertVulnerabilities(vulns) {
131
+ const transaction = this.db.transaction((items) => {
132
+ for (const item of items) {
133
+ this.upsertVulnerabilityInternal(item);
91
134
  }
92
135
  });
93
- transaction();
136
+ transaction([...vulns]);
137
+ }
138
+ upsertVulnerabilityInternal(vuln) {
139
+ const advisoryRows = deriveAdvisoryPackageRows(vuln);
140
+ const advisoryJson = JSON.stringify(vuln);
141
+ const aliasesJson = JSON.stringify(vuln.aliases ?? []);
142
+ this.upsertAdvisoryStatement.run({
143
+ id: vuln.id,
144
+ modified_at: null,
145
+ aliases_json: aliasesJson,
146
+ summary: vuln.summary ?? null,
147
+ osv_json: advisoryJson,
148
+ });
149
+ this.deleteRangesStatement.run(vuln.id);
150
+ for (const row of advisoryRows) {
151
+ this.insertRangeStatement.run(row);
152
+ }
94
153
  }
95
154
  getVulnerability(id) {
96
- const row = this.db.prepare(`
97
- SELECT osv_json
98
- FROM advisories
99
- WHERE id = ?
100
- `).get(id);
155
+ const row = this.getVulnerabilityStatement.get(id);
101
156
  if (!row)
102
157
  return null;
103
158
  return JSON.parse(row.osv_json);
@@ -106,11 +161,7 @@ export class LocalAdvisoryDatabase {
106
161
  if (!looksLikeVersion(pkg.version)) {
107
162
  return [];
108
163
  }
109
- const rows = this.db.prepare(`
110
- SELECT advisory_id, introduced, fixed, last_affected
111
- FROM advisory_packages
112
- WHERE ecosystem = ? AND package_name = ?
113
- `).all(pkg.ecosystem, pkg.name);
164
+ const rows = this.findMatchingIdsStatement.all(pkg.ecosystem, pkg.name);
114
165
  const ids = new Set();
115
166
  for (const row of rows) {
116
167
  if (versionMatchesRange(pkg.version, row)) {
@@ -4,6 +4,7 @@ import path from "node:path";
4
4
  import { unzipSync } from "fflate";
5
5
  import { LocalAdvisoryDatabase } from "./local-db.js";
6
6
  const DEFAULT_OSV_NPM_DUMP_URL = "https://storage.googleapis.com/osv-vulnerabilities/npm/all.zip";
7
+ export const ADVISORY_DB_STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
7
8
  export function getDefaultAdvisoryDbPath(outputPath) {
8
9
  if (outputPath) {
9
10
  return path.resolve(outputPath);
@@ -55,7 +56,7 @@ export async function syncOsvAdvisories(options = {}) {
55
56
  });
56
57
  await yieldToEventLoop();
57
58
  const archiveEntries = unzipSync(zippedBytes);
58
- const advisoryEntries = Object.keys(archiveEntries).filter(entryName => entryName.endsWith(".json"));
59
+ const advisoryEntries = Object.entries(archiveEntries).filter(([entryName]) => entryName.endsWith(".json"));
59
60
  onProgress?.({
60
61
  phase: "extract",
61
62
  totalEntries: Object.keys(archiveEntries).length,
@@ -65,18 +66,16 @@ export async function syncOsvAdvisories(options = {}) {
65
66
  await yieldToEventLoop();
66
67
  const db = new LocalAdvisoryDatabase(dbPath);
67
68
  try {
69
+ const parsedVulns = [];
68
70
  let advisoryCount = 0;
69
71
  const progressInterval = 250;
70
- for (const [entryName, bytes] of Object.entries(archiveEntries)) {
71
- if (!entryName.endsWith(".json")) {
72
- continue;
73
- }
72
+ for (const [, bytes] of advisoryEntries) {
74
73
  const text = Buffer.from(bytes).toString("utf8");
75
74
  const vuln = JSON.parse(text);
76
75
  if (!vuln.id) {
77
76
  continue;
78
77
  }
79
- db.upsertVulnerability(vuln);
78
+ parsedVulns.push(vuln);
80
79
  advisoryCount += 1;
81
80
  if (advisoryCount === 1 ||
82
81
  advisoryCount % progressInterval === 0 ||
@@ -90,6 +89,11 @@ export async function syncOsvAdvisories(options = {}) {
90
89
  await yieldToEventLoop();
91
90
  }
92
91
  }
92
+ db.bulkUpsertVulnerabilities(parsedVulns);
93
+ db.setMetadata({
94
+ lastSyncAt: new Date().toISOString(),
95
+ sourceUrl,
96
+ });
93
97
  onProgress?.({
94
98
  phase: "complete",
95
99
  advisoryCount,
package/dist/index.js CHANGED
@@ -62,6 +62,8 @@ async function main() {
62
62
  }
63
63
  }
64
64
  let advisorySourceLine;
65
+ let advisoryDbFreshnessLine = null;
66
+ let advisoryDbWarning = null;
65
67
  try {
66
68
  const advisorySource = createAdvisorySource({
67
69
  osvUrl: options.osvUrl,
@@ -69,6 +71,15 @@ async function main() {
69
71
  offlineDb: options.offlineDb,
70
72
  });
71
73
  advisorySourceLine = advisorySource.sourceLabel;
74
+ if (advisorySource.offline) {
75
+ const metadata = advisorySource.advisoryDbMetadata;
76
+ advisoryDbFreshnessLine = formatAdvisoryDbFreshness(metadata?.lastSyncAt ?? null);
77
+ if (advisorySource.advisoryDbIsStale) {
78
+ advisoryDbWarning = metadata?.lastSyncAt
79
+ ? "The local advisory DB appears stale. Re-run `cve-lite advisories sync` to refresh it."
80
+ : "The local advisory DB has no recorded sync timestamp. Re-run `cve-lite advisories sync` to refresh it.";
81
+ }
82
+ }
72
83
  advisorySource.cleanup();
73
84
  }
74
85
  catch (error) {
@@ -81,6 +92,12 @@ async function main() {
81
92
  console.log(chalk.gray("Offline mode:") + " " + chalk.yellow("enabled") + " " + chalk.gray("(no external advisory calls will be made)"));
82
93
  }
83
94
  console.log(`${chalk.gray("Advisory source:")} ${formatAdvisorySourceLine(advisorySourceLine)}`);
95
+ if (advisoryDbFreshnessLine) {
96
+ console.log(`${chalk.gray("Advisory DB freshness:")} ${advisoryDbFreshnessLine}`);
97
+ }
98
+ if (advisoryDbWarning) {
99
+ logWarn(advisoryDbWarning, options);
100
+ }
84
101
  const scanInput = loadPackages(projectPath, !!options.prodOnly, searchDepth);
85
102
  const packages = scanInput.packages;
86
103
  logInfo(`Parsed ${packages.length} package${packages.length === 1 ? "" : "s"} from ${scanInput.source}${scanInput.filePath ? ` (${path.relative(projectPath, scanInput.filePath) || path.basename(scanInput.filePath)})` : ""}`, options);
@@ -155,3 +172,32 @@ function formatAdvisorySourceLine(sourceLabel) {
155
172
  }
156
173
  return `${match[1]} (${chalk.cyan(match[2])})`;
157
174
  }
175
+ function formatAdvisoryDbFreshness(lastSyncAt) {
176
+ if (!lastSyncAt) {
177
+ return chalk.yellow("unknown");
178
+ }
179
+ const timestamp = Date.parse(lastSyncAt);
180
+ if (Number.isNaN(timestamp)) {
181
+ return chalk.yellow("unknown");
182
+ }
183
+ return `${relativeAge(timestamp)} ${chalk.gray(`(${lastSyncAt})`)}`;
184
+ }
185
+ function relativeAge(timestamp) {
186
+ const deltaMs = Math.max(0, Date.now() - timestamp);
187
+ const minute = 60 * 1000;
188
+ const hour = 60 * minute;
189
+ const day = 24 * hour;
190
+ if (deltaMs < minute) {
191
+ return "just synced";
192
+ }
193
+ if (deltaMs < hour) {
194
+ const minutes = Math.floor(deltaMs / minute);
195
+ return `synced ${minutes} minute${minutes === 1 ? "" : "s"} ago`;
196
+ }
197
+ if (deltaMs < day) {
198
+ const hours = Math.floor(deltaMs / hour);
199
+ return `synced ${hours} hour${hours === 1 ? "" : "s"} ago`;
200
+ }
201
+ const days = Math.floor(deltaMs / day);
202
+ return `synced ${days} day${days === 1 ? "" : "s"} ago`;
203
+ }
package/dist/scanner.js CHANGED
@@ -6,7 +6,7 @@ import { createSpinner } from "./output/spinner.js";
6
6
  import { OsvAdvisorySource } from "./advisory/osv-advisory-source.js";
7
7
  import { LocalAdvisorySource } from "./advisory/local-advisory-source.js";
8
8
  import { LocalAdvisoryDatabase } from "./advisory/local-db.js";
9
- import { getDefaultAdvisoryDbPath } from "./advisory/osv-sync.js";
9
+ import { ADVISORY_DB_STALE_AFTER_MS, getDefaultAdvisoryDbPath } from "./advisory/osv-sync.js";
10
10
  import { resolveRecommendedParentUpgrade } from "./remediation/parent-upgrade.js";
11
11
  export function createAdvisorySource(options) {
12
12
  const offline = !!options?.offline || !!options?.offlineDb;
@@ -17,6 +17,8 @@ export function createAdvisorySource(options) {
17
17
  advisorySource: new LocalAdvisorySource(db),
18
18
  offline: true,
19
19
  sourceLabel: `local advisory database (${dbPath})`,
20
+ advisoryDbMetadata: db.getMetadata(),
21
+ advisoryDbIsStale: isAdvisoryDbStale(db.getMetadata()),
20
22
  cleanup: () => db.close(),
21
23
  };
22
24
  }
@@ -26,6 +28,8 @@ export function createAdvisorySource(options) {
26
28
  sourceLabel: options?.osvUrl
27
29
  ? `custom OSV endpoint (${options.osvUrl})`
28
30
  : "OSV (https://api.osv.dev)",
31
+ advisoryDbMetadata: null,
32
+ advisoryDbIsStale: false,
29
33
  cleanup: () => { },
30
34
  };
31
35
  }
@@ -193,6 +197,16 @@ export async function scanPackages(packages, batchSize, options) {
193
197
  sourceContext.cleanup();
194
198
  }
195
199
  }
200
+ function isAdvisoryDbStale(metadata) {
201
+ if (!metadata.lastSyncAt) {
202
+ return true;
203
+ }
204
+ const timestamp = Date.parse(metadata.lastSyncAt);
205
+ if (Number.isNaN(timestamp)) {
206
+ return true;
207
+ }
208
+ return Date.now() - timestamp > ADVISORY_DB_STALE_AFTER_MS;
209
+ }
196
210
  function classifyRelationship(paths) {
197
211
  if (paths.length === 0)
198
212
  return "unknown";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cve-lite-cli",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Developer-friendly CLI for scanning JS/TS projects for dependency vulnerabilities using local lockfiles and OSV",
5
5
  "type": "module",
6
6
  "bin": {