cve-lite-cli 1.5.2 → 1.5.4

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
@@ -4,166 +4,111 @@
4
4
  [![CI](https://img.shields.io/github/actions/workflow/status/sonukapoor/cve-lite-cli/ci.yml?branch=main)](https://github.com/sonukapoor/cve-lite-cli/actions)
5
5
  [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-CVE%20Lite%20CLI-blue)](https://github.com/marketplace/actions/cve-lite-cli)
6
6
  [![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
7
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
7
8
 
8
9
  <div align="center">
9
10
  <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
10
11
 
11
12
  <h1>CVE Lite CLI</h1>
12
- <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects, with offline support for restricted environments.</p>
13
+ <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Clear direct vs transitive visibility.</p>
13
14
 
14
- <strong>Scan. Prioritize. Fix.</strong>
15
+ <strong>Scan. Understand. Fix.</strong>
16
+
17
+ <br/>
18
+
19
+ <table>
20
+ <tr>
21
+ <td align="center" width="33%"><p>🆓</p><strong>Free to use</strong><br/><sub>No account, no subscription,<br/>no cloud required</sub></td>
22
+ <td align="center" width="33%"><p>🏠</p><strong>Runs locally</strong><br/><sub>Scans your lockfile on your machine.<br/>Nothing leaves your environment</sub></td>
23
+ <td align="center" width="33%"><p>⚡</p><strong>Fast</strong><br/><sub>Results in seconds. Local cache keeps<br/>rescans near-instant</sub></td>
24
+ </tr>
25
+ </table>
26
+
27
+ <br/>
15
28
 
16
29
  <p>
17
30
  <a href="#quick-start">Quick Start</a> •
18
- <a href="#new-here-start-here">New Here? Start Here</a> •
19
- <a href="#features">Features</a> •
20
31
  <a href="#usage">Usage</a> •
32
+ <a href="#what-it-looks-like">Screenshots</a> •
33
+ <a href="docs/comparison.md">Compare</a> •
34
+ <a href="docs/roadmap.md">Roadmap</a> •
21
35
  <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
22
36
  </p>
23
-
24
37
  </div>
25
38
 
26
39
  ---
27
40
 
28
- ## Contents
29
-
30
- <table>
31
- <tr>
32
- <td valign="top">
33
- <strong>Overview</strong><br/>
34
- <a href="#what-is-cve-lite-cli">What is CVE Lite CLI</a><br/>
35
- <a href="#new-here-start-here">New here? Start here</a><br/>
36
- <a href="#new-offline-advisory-db-support">Offline advisory DB support</a><br/>
37
- <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
38
- <a href="docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop case study</a><br/>
39
- <a href="docs/case-studies/nestjs.md">NestJS case study</a><br/>
40
- <a href="docs/fix-mode.md">Fix mode guide (--fix)</a><br/>
41
- <a href="docs/how-to-read-verbose-output.md">How to read verbose output</a><br/>
42
- <a href="#what-it-looks-like">What it looks like</a><br/>
43
- <a href="#why-this-tool-exists">Why this tool exists</a><br/>
44
- <a href="#project-scope-and-differentiation">Project scope and differentiation</a>
45
- </td>
46
- <td valign="top">
47
- <strong>Usage</strong><br/>
48
- <a href="#quick-start">Quick start</a><br/>
49
- <a href="#usage">Usage</a><br/>
50
- <a href="#workflow-modes">Workflow modes</a><br/>
51
- <a href="#network-behavior-and-privacy">Network behavior and privacy</a><br/>
52
- <a href="#features">Features</a><br/>
53
- <a href="#supported-workflows">Supported workflows</a>
54
- </td>
55
- <td valign="top">
56
- <strong>CI and Offline</strong><br/>
57
- <a href="#dependency-footprint">Dependency footprint</a><br/>
58
- <a href="#example-use-cases">Example use cases</a><br/>
59
- <a href="#recommended-workflow-patterns">Recommended workflow patterns</a><br/>
60
- <a href="#comparison-with-other-tools">Comparison with other tools</a><br/>
61
- <a href="#current-limitations">Current limitations</a><br/>
62
- <a href="#positioning">Positioning</a>
63
- </td>
64
- <td valign="top">
65
- <strong>Project</strong><br/>
66
- <a href="#roadmap">Roadmap</a><br/>
67
- <a href="#contributing">Contributing</a><br/>
68
- <a href="#community-and-support">Community and support</a><br/>
69
- <a href="#license">License</a>
70
- </td>
71
- </tr>
72
- </table>
73
-
74
- ## What is CVE Lite CLI
75
-
76
- **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.
77
-
78
- It is designed to be:
79
-
80
- - developer-friendly in day-to-day workflows
81
- - local-first and transparent about network behavior
82
- - usable in enterprise and restricted-network environments
83
- - capable of zero-runtime-network scans through a local advisory database
84
-
85
- For real-world remediation examples, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
86
- If you are new to verbose mode, use the [How to read verbose output guide](docs/how-to-read-verbose-output.md).
87
- If you want automatic direct remediation, use the [Fix mode guide](docs/fix-mode.md).
88
-
89
- ## New here? Start here
90
-
91
- If the verbose output feels dense at first, start with the [How to read verbose output guide](docs/how-to-read-verbose-output.md).
92
-
93
- 1. run one scan on a real project with `npx cve-lite-cli /path/to/project --verbose`
94
- 2. review direct vs transitive findings and the `Copy And Run These Fix Commands` section (direct command groups apply to manifest-declared dependencies)
95
- 3. compare the output with your current scanner workflow
96
- 4. check a real walkthrough:
97
- - [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md)
98
- - [NestJS case study](docs/case-studies/nestjs.md)
99
- 5. use the [How to read verbose output guide](docs/how-to-read-verbose-output.md) to convert scan sections into next steps
100
-
101
- If CVE Lite CLI helps your release workflow, a GitHub star helps more developers discover it: [Star CVE Lite CLI](https://github.com/sonukapoor/cve-lite-cli).
102
-
103
- If you want to shape the roadmap, open an issue with feedback on:
104
-
105
- - whether the direct vs transitive split is useful in practice
106
- - where remediation guidance is still missing
107
- - what increases or decreases trust in a CLI security tool
108
- - what would make frontend-heavy CI workflows smoother
109
-
110
- ## New: Offline advisory DB support
111
-
112
- CVE Lite CLI now supports a local advisory database workflow for teams that cannot allow runtime outbound advisory API calls.
113
-
114
- That means you can:
41
+ ## Quick start
115
42
 
116
- - sync advisory data ahead of time
117
- - scan projects fully offline
118
- - use the tool in restricted, enterprise, or air-gapped environments more easily
43
+ ```bash
44
+ npm install -g cve-lite-cli
45
+ cve-lite /path/to/project
46
+ ```
119
47
 
120
- Example offline workflow:
48
+ Or one-off with `npx`:
121
49
 
122
50
  ```bash
123
- # Build the local advisory database
124
- cve-lite advisories sync
51
+ npx cve-lite-cli /path/to/project
52
+ ```
125
53
 
126
- # Scan using the default local advisory DB
127
- cve-lite /path/to/project --offline
54
+ ## What is CVE Lite CLI
128
55
 
129
- # Or scan using a specific local advisory DB file
130
- cve-lite /path/to/project --offline-db /path/to/advisories.db
131
- ```
56
+ CVE Lite CLI scans JavaScript and TypeScript projects for known dependency vulnerabilities and tells you what to fix first. It reads your lockfile locally, queries [OSV](https://osv.dev) for advisory data, and produces a practical remediation plan — not just a list of advisory IDs.
132
57
 
133
- ## Why offline mode matters
58
+ It is built for the moment right before release: fast, local-first, and honest about what it does and does not do.
134
59
 
135
- 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.
60
+ **Key differentiators:**
136
61
 
137
- Offline advisory DB support makes CVE Lite CLI more practical for:
62
+ - **Copy-and-run fix commands** — turns findings into package-manager-aware `npm install`, `pnpm add`, or `yarn add` commands you can run immediately
63
+ - **Direct vs transitive visibility** — shows whether the risk comes from something you installed directly or a nested dependency
64
+ - **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, useful for enterprise and restricted-network environments
65
+ - **No account required** — no sign-up, no cloud dashboard, no source code upload
66
+ - **Small dependency footprint** — only four runtime dependencies, intentionally kept minimal for a security tool
138
67
 
139
- - enterprise environments with strict network controls
140
- - regulated teams that need explicit advisory data handling
141
- - internal CI systems that should not depend on public runtime API access
142
- - air-gapped or partially connected workflows
68
+ ## How it compares
143
69
 
144
- This is one of the most important differentiators in the project today because it improves both trust and adoptability, not just convenience.
70
+ | Capability | CVE Lite CLI | npm audit | OSV-Scanner | Snyk CLI | Socket CLI |
71
+ |---|:---:|:---:|:---:|:---:|:---:|
72
+ | JS/TS lockfile scanning | ✅ | ✅ | ✅ | ✅ | ✅ |
73
+ | npm + pnpm + Yarn support | ✅ | ❌ | ✅ | ✅ | ✅ |
74
+ | No account required | ✅ | ✅ | ✅ | ❌ | ❌ |
75
+ | **Free to use** | ✅ | ✅ | ✅ | ❌ | ❌ |
76
+ | Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
77
+ | Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
78
+ | Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
79
+ | JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
80
+ | Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
145
81
 
146
- The project also ships a reusable first-party GitHub Action, now available on the [GitHub Marketplace](https://github.com/marketplace/actions/cve-lite-cli), for teams that want a low-friction CI integration path.
82
+ <sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
147
83
 
148
- ## Quick start
84
+ For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
85
+
86
+ ## What it looks like
149
87
 
150
- Install globally:
88
+ Default output on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop):
151
89
 
152
90
  ```bash
153
- npm install -g cve-lite-cli
91
+ git clone https://github.com/juice-shop/juice-shop.git
92
+ cd juice-shop
93
+ cve-lite .
154
94
  ```
155
95
 
156
- Then run:
96
+ <p align="center">
97
+ <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png">
98
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output" width="600"/>
99
+ </a>
100
+ </p>
157
101
 
158
- ```bash
159
- cve-lite /path/to/project
160
- ```
102
+ Verbose output — includes the `Copy And Run These Fix Commands` section:
161
103
 
162
- Or run it one-off with `npx`:
104
+ <p align="center">
105
+ <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-1.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-1.png" alt="Verbose output part 1" width="280"/></a>
106
+ <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-2.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-2.png" alt="Verbose output part 2" width="280"/></a>
107
+ <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-3.png"><img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-3.png" alt="Verbose output part 3" width="280"/></a>
108
+ </p>
109
+ <p align="center"><sub>Click any screenshot to enlarge</sub></p>
163
110
 
164
- ```bash
165
- npx cve-lite-cli /path/to/project
166
- ```
111
+ For a section-by-section walkthrough, see [How to read verbose output](docs/how-to-read-verbose-output.md).
167
112
 
168
113
  ## Usage
169
114
 
@@ -174,17 +119,16 @@ cve-lite /path/to/project
174
119
  # Show all findings
175
120
  cve-lite /path/to/project --all
176
121
 
177
- # Focus only on urgent findings
122
+ # Focus on urgent findings only
178
123
  cve-lite /path/to/project --min-severity high
179
124
 
180
- # Show full detailed output, fix plan, paths, and full table
181
- # Recommended for CI logs when you want full context
125
+ # Full output: fix plan, paths, and complete table
182
126
  cve-lite /path/to/project --verbose
183
127
 
184
128
  # Apply validated direct dependency fixes and rescan
185
129
  cve-lite /path/to/project --fix
186
130
 
187
- # Limit the scan to production dependencies where supported by the lockfile
131
+ # Production dependencies only (where supported by the lockfile)
188
132
  cve-lite /path/to/project --prod-only
189
133
 
190
134
  # Fail a build on high severity and above
@@ -193,13 +137,7 @@ cve-lite /path/to/project --fail-on high
193
137
  # JSON output
194
138
  cve-lite /path/to/project --json
195
139
 
196
- # Use a custom advisory endpoint
197
- cve-lite /path/to/project --osv-url https://security.company.internal/osv
198
-
199
- # Show the CLI version
200
- cve-lite --version
201
-
202
- # Build the local advisory DB for offline scans
140
+ # Sync the local advisory DB for offline scans
203
141
  cve-lite advisories sync
204
142
 
205
143
  # Scan with zero runtime advisory API calls
@@ -207,766 +145,147 @@ cve-lite /path/to/project --offline
207
145
 
208
146
  # Use a specific local advisory DB file
209
147
  cve-lite /path/to/project --offline-db /path/to/advisories.db
148
+
149
+ # Use a custom advisory endpoint
150
+ cve-lite /path/to/project --osv-url https://security.company.internal/osv
151
+
152
+ # Show version
153
+ cve-lite --version
210
154
  ```
211
155
 
212
156
  ## Auto-fix mode (`--fix`)
213
157
 
214
- `--fix` is designed to speed up remediation without overpromising safety.
158
+ `--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.
215
159
 
216
- In v1, `--fix`:
160
+ In the current version it:
217
161
  - applies only direct dependency fixes with a validated lowest known non-vulnerable target
218
- - uses your project’s package manager (`npm install`, `pnpm add`, or `yarn add`)
162
+ - uses `npm install`, `pnpm add`, or `yarn add` based on your lockfile
219
163
  - rescans automatically after applying fixes
220
- - prints a concise summary of applied fixes, skipped findings, and remaining findings
221
-
222
- In v1, `--fix` does not:
223
- - auto-apply transitive overrides/resolutions
224
- - guarantee compatibility with your application code
225
- - perform exploitability or runtime reachability analysis
226
-
227
- Example:
164
+ - does **not** auto-apply transitive overrides or guarantee application compatibility
228
165
 
229
166
  ```bash
230
167
  npx cve-lite-cli /path/to/project --fix
231
168
  ```
232
169
 
233
- For output details and interpretation, see [Fix mode guide](docs/fix-mode.md).
234
-
235
- ## Workflow modes
236
-
237
- CVE Lite CLI now supports three clear advisory workflows:
170
+ See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
238
171
 
239
- ### 1. Standard online scan
172
+ ## Offline support
240
173
 
241
- Use the default OSV-backed mode when runtime advisory API access is acceptable:
242
-
243
- ```bash
244
- cve-lite /path/to/project
245
- ```
246
-
247
- ### 2. Advisory DB sync
248
-
249
- Build or refresh the local advisory database ahead of time:
174
+ For teams in enterprise, restricted-network, or air-gapped environments:
250
175
 
251
176
  ```bash
177
+ # Sync advisory data locally
252
178
  cve-lite advisories sync
253
- ```
254
-
255
- ### 3. Offline local DB scan
256
-
257
- Scan against the local advisory DB with zero runtime advisory API calls:
258
-
259
- ```bash
260
- cve-lite /path/to/project --offline
261
- ```
262
-
263
- ## What it looks like
264
-
265
- CVE Lite CLI produces a clean, summary-first console view by default, designed for fast triage before release.
266
-
267
- The default output is designed to stay concise while still surfacing the most important next step, including package-manager-aware fix commands when confident targets exist.
268
-
269
- The most important section to look for in the output is:
270
-
271
- ```text
272
- 🛠 Copy And Run These Fix Commands
273
- ```
274
179
 
275
- That is one of the clearest differentiators in CVE Lite CLI. Instead of only showing advisories and severity counts, the tool tries to turn findings into concrete commands developers can copy and run immediately for manifest-declared direct dependencies, while still showing parent-upgrade guidance for transitive issues when available.
276
-
277
- For example, the tool can now suggest a concrete next command such as:
278
-
279
- ```bash
280
- npm install jsonwebtoken@4.2.2 express-jwt@2.1.0 sanitize-html@2.17.2
180
+ # Scan with no runtime API calls
181
+ cve-lite . --offline
281
182
  ```
282
183
 
283
- The exact command adapts to the dependency file used for the scan, so `package-lock.json`, `pnpm-lock.yaml`, and `yarn.lock` can each produce a package-manager-specific suggestion.
284
-
285
- For deeper investigation, running with `--verbose` provides the fuller remediation context, including the `Copy And Run These Fix Commands` section, dependency paths, parent upgrade guidance for transitive issues when available, a complete fix plan, skipped-item context for unresolved urgent findings, and a detailed table view.
286
-
287
- That is the core idea: install it, point it at your project, and immediately get a practical dependency fix plan instead of a wall of raw advisories.
184
+ Syncing ~217,065 advisory records runs in under 9 seconds after bulk SQLite ingestion optimizations — roughly **9.9x faster** than the initial implementation.
288
185
 
289
- That local loop matters a lot in practice. In the NestJS case study, one dependency path required several `tar` upgrades in sequence as the dependency graph changed after each install. If a team only relied on pipeline scanners, they would likely:
186
+ See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
290
187
 
291
- 1. upgrade `tar`
292
- 2. push a branch
293
- 3. wait for CI or a scheduled scanner to report back
294
- 4. learn they need to upgrade `tar` again
295
- 5. repeat the full cycle
188
+ ## CI integration
296
189
 
297
- That kind of branch-and-pipeline remediation can easily burn hours or days for one CVE path, and in slower teams it can stretch into weeks. CVE Lite CLI brings that feedback loop down to a local scan-fix-rescan workflow that can happen in the same session, and its local caching keeps consecutive rescans extremely fast instead of redoing the same advisory lookups from scratch each time.
298
-
299
- The final status line also gives the scan a clear ending, which makes terminal use and screenshots easier to read.
300
-
301
- See the example below using OWASP Juice Shop for real output samples.
302
-
303
- For real-world case studies, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
304
- For a section-by-section walkthrough of the terminal output, see [How to read verbose output](docs/how-to-read-verbose-output.md).
305
-
306
- If you maintain an open-source JavaScript or TypeScript project and want CVE Lite CLI evaluated on it, open an issue and share the repository. Strong candidates may be turned into future public case studies.
190
+ The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
307
191
 
308
- ## Example: Scanning OWASP Juice Shop (Real Output)
309
-
310
- CVE Lite CLI can be used against real-world vulnerable applications such as the OWASP Juice Shop.
311
-
312
- OWASP [Juice Shop](https://github.com/juice-shop/juice-shop) is a deliberately insecure JavaScript application widely used for security training and testing. Running CVE Lite CLI against it provides a realistic example of how the tool behaves on a dependency tree with known vulnerabilities.
313
-
314
- To try this yourself:
315
-
316
- Example:
317
-
318
- ```bash
319
- git clone https://github.com/juice-shop/juice-shop.git
320
- cd juice-shop
321
- cve-lite .
192
+ ```yaml
193
+ - uses: sonukapoor/cve-lite-cli@v1
194
+ with:
195
+ verbose: "true"
196
+ fail-on: high
322
197
  ```
323
198
 
324
- <p align="center">
325
- <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
326
- </p>
327
-
328
- Verbose examples:
329
-
330
- Look for the `Copy And Run These Fix Commands` section in the screenshots below. That is the part of the output that turns findings into direct remediation steps.
331
-
332
- <p align="center">
333
- <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"/>
334
- <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"/>
335
- <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"/>
336
- </p>
337
-
338
- ## Why this tool exists
339
-
340
- A lot of developers want a practical dependency scan right before release, but they do not want the cost, complexity, or friction of a larger platform just to answer a simple question:
341
-
342
- **Do we have known vulnerable packages in this project, and what should we fix first?**
199
+ CVE Lite CLI also uses itself in CI to scan its own dependencies. See [`self-scan.yml`](https://github.com/sonukapoor/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
343
200
 
344
- CVE Lite CLI is built for that workflow.
345
-
346
- It focuses on being:
347
-
348
- - fast
349
- - local-first
350
- - easy to understand
351
- - useful in CI
352
- - honest about what it does and does not do
353
-
354
- ## Project scope and differentiation
355
-
356
- CVE Lite CLI is intentionally focused.
357
-
358
- It is built for JavaScript and TypeScript dependency scanning, especially in the workflows where developers want a fast local check before release or a simple CI gate during dependency review.
359
-
360
- The project emphasizes:
361
-
362
- - npm, pnpm, and Yarn lockfile support
363
- - direct vs transitive visibility
364
- - top-priority fixes and a suggested dependency remediation plan
365
- - JSON output for automation
366
- - offline scanning through a local advisory database
367
- - configurable advisory endpoint support via `--osv-url` for internal proxies or mirrors
368
- - a small, reviewable runtime footprint
369
-
370
- That narrow scope is deliberate. CVE Lite CLI is not trying to be a full application security platform or a broad multi-surface scanner. It is trying to be a lightweight, understandable, developer-first tool for teams that want practical vulnerability scanning without extra cost or complexity.
201
+ For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
371
202
 
372
203
  ## Relationship to similar OWASP projects
373
204
 
374
- CVE Lite CLI is not trying to replace broader OWASP security tooling.
375
-
376
- Its role is narrower and workflow-focused:
377
-
378
- - focused on JavaScript and TypeScript dependency scanning
379
- - designed for fast local checks and simple CI release gates
380
- - centered on direct vs transitive visibility
381
- - built to highlight top-priority fixes and a suggested dependency remediation plan
382
- - intentionally lightweight in runtime footprint and setup
205
+ CVE Lite CLI is intentionally narrower than the broader OWASP security tooling ecosystem. Its role is workflow-focused: fast local checks and simple CI release gates for JavaScript and TypeScript dependency scanning.
383
206
 
384
207
  The closest OWASP comparisons are:
385
208
 
386
- - **OWASP Dependency-Check**
387
- A broader dependency analysis tool that covers many ecosystems and use cases beyond the lockfile-first JavaScript/TypeScript workflow emphasized here.
388
-
389
- - **OWASP dep-scan**
390
- A broader dependency and security analysis tool with wider language and environment coverage than this project is trying to provide.
391
-
392
- - **OWASP Dependency-Track**
393
- More SBOM- and platform-oriented, with a different operational model than a lightweight local CLI focused on developer checks close to release time.
394
-
395
- CVE Lite CLI is intentionally narrower: it is JavaScript/TypeScript focused, lockfile-first, local-first, designed for fast local checks and simple CI gates, and built to surface direct vs transitive visibility, top-priority fixes, suggested remediation guidance, offline advisory DB workflows, and a small, reviewable runtime footprint.
396
-
397
- This section is here to make the scope clear. CVE Lite CLI is meant to complement the broader OWASP ecosystem by serving a practical developer workflow close to release time.
398
-
399
- 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.
400
-
401
- ## Network behavior and privacy
402
-
403
- 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.
404
-
405
- It does not require a hosted account, cloud dashboard, or source code upload.
406
-
407
- For the full explanation, see [Network Behavior and Privacy](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/network-and-privacy.md).
408
-
409
- ### Offline workflow
410
-
411
- For teams in controlled or restricted environments, the intended model is:
412
-
413
- 1. sync advisory data into a local database
414
- 2. distribute that database as needed
415
- 3. scan projects using the local DB instead of runtime OSV API calls
416
-
417
- Sync the local advisory database:
418
-
419
- ```bash
420
- cve-lite advisories sync
421
- ```
422
-
423
- 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.
424
-
425
- Write the advisory database to a specific path:
426
-
427
- ```bash
428
- cve-lite advisories sync --output /path/to/advisories.db
429
- ```
430
-
431
- Scan using the default local advisory DB:
432
-
433
- ```bash
434
- cve-lite . --offline
435
- ```
436
-
437
- Scan using an explicit local advisory DB file:
438
-
439
- ```bash
440
- cve-lite . --offline-db /path/to/advisories.db
441
- ```
442
-
443
- 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:
444
-
445
- ```bash
446
- cve-lite advisories sync --output /path/to/advisories.db
447
- ```
448
-
449
- That helps ensure offline scans continue using current advisory data without requiring developers to remember to refresh the DB manually every time.
450
-
451
- Standard online mode remains available when you want live OSV-backed scans:
452
-
453
- ```bash
454
- cve-lite . --osv-url https://security.company.internal/osv
455
- ```
456
-
457
- ### Advisory DB freshness
209
+ - **OWASP Dependency-Check** — broader ecosystem coverage, different operational model
210
+ - **OWASP dep-scan** — wider language and environment coverage
211
+ - **OWASP Dependency-Track** — SBOM- and platform-oriented, not a local developer CLI
458
212
 
459
- The local advisory DB is only as current as the last successful sync.
213
+ CVE Lite CLI complements these tools by serving a practical developer workflow close to release time: lockfile-first, local-first, remediation-focused, and offline-capable. It is vendor-neutral and does not require any commercial platform.
460
214
 
461
- Offline scans now report advisory DB freshness and warn when the local DB appears stale or is missing sync metadata.
215
+ ## Real-world case studies
462
216
 
463
- The recommended model is:
217
+ - [OWASP Juice Shop](docs/case-studies/owasp-juice-shop.md) — scanning a deliberately vulnerable application with known dependency issues
218
+ - [NestJS](docs/case-studies/nestjs.md) — working through a real transitive dependency remediation sequence
464
219
 
465
- - sync the advisory DB on a schedule using cron, CI, or another automation system
466
- - distribute the refreshed DB where needed
467
- - run offline scans against that updated DB
468
-
469
- This helps keep offline scan results current without requiring developers to manually track advisory update cadence.
470
-
471
- ## Detecting malicious package incidents
472
-
473
- CVE Lite CLI can help detect malicious package incidents and supply-chain compromises **once the affected versions are represented in OSV or equivalent advisory data available through the configured advisory endpoint**.
474
-
475
- In practice, that means the tool can catch incidents such as a compromised npm package **when the exact malicious version appears in your lockfile** and the advisory data has already been published and indexed. This makes the tool useful for real-world release checks after a malicious package disclosure becomes known.
476
-
477
- It is important to be precise about the current scope:
478
-
479
- - CVE Lite CLI is **advisory-driven**, not a behavioral malware detector
480
- - it does **not** perform static malware analysis on package contents
481
- - it does **not** detect a package compromise before advisory intelligence exists for it
482
- - it works best with lockfiles because they capture the exact resolved version that was actually installed
483
-
484
- So the practical model is: **local lockfile scan + advisory matching**. When malicious versions are published to OSV or mirrored through a compatible internal endpoint, CVE Lite CLI can flag those exact versions during a scan.
485
-
486
- If a malicious package was installed and executed, upgrading or removing the dependency may not be sufficient on its own; teams should treat that as a potential security incident and follow their incident-response process.
487
-
488
- ## How it works
489
-
490
- ### Architectural Philosophy
491
- 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.
492
-
493
- <p align="center">
494
- <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
495
- </p>
496
-
497
- ### Workflow Specifications
498
- * **Trust Boundary & Privacy:** The scan is non-intrusive. Only package names and exact versions are extracted. No source code, environment variables, or proprietary logic is ever transmitted to the external OSV (Open Source Vulnerability) API.
499
- * **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.
500
- * **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.
501
- * **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.
502
- * **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.
503
- * **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.
504
-
505
- ## What makes it stand out
506
-
507
- - **fast, low-friction workflow**
508
- Run it locally against a project without adopting a large security platform.
509
- - **practical dependency remediation guidance**
510
- It does not stop at raw advisory output. It highlights top-priority fixes, suggests a dependency fix plan, and generates package-manager-aware commands developers can copy and run when confident upgrade targets exist. When advisory and registry data allow, it recommends the lowest known non-vulnerable version and shows transparent scan/exclusion counts for checked package versions.
511
- - **direct vs transitive visibility**
512
- The output makes it easier to see whether the risk comes from something you installed directly or from a nested package.
513
- - **developer-first**
514
- It is optimized for developers working with npm, pnpm, and Yarn lockfiles.
515
- - **budget-friendly**
516
- It is intended for developers and teams who want useful security checks without paying for a large commercial product.
517
- - **local-first**
518
- It reads your project locally and uses package/version matching against OSV advisories.
519
- - **offline-capable**
520
- It can sync and scan against a local advisory database for zero-runtime-network workflows.
521
- - **enterprise-friendly network model**
522
- Teams can control when advisory data is synced and where offline scans run, which is valuable in restricted environments.
523
- - **release-focused**
524
- It is especially useful before a release, in CI, or during final dependency cleanup.
525
-
526
- ## Features
527
-
528
- ### 1. Lockfile-based scanning
529
-
530
- CVE Lite CLI scans resolved dependency versions from:
531
-
532
- - `package-lock.json`
533
- - `pnpm-lock.yaml`
534
- - `yarn.lock`
535
-
536
- It also supports a limited `package.json` fallback for exact pinned direct dependencies.
537
-
538
- ### 2. Clear vulnerability output
539
-
540
- Instead of only showing advisory IDs, the CLI reports:
541
-
542
- - package name and version
543
- - severity
544
- - direct vs transitive relationship
545
- - fixed-version hint when available
546
- - advisory IDs
547
- - dependency path hints
548
- - recommended parent upgrade for transitive issues when available
549
-
550
- By default, the CLI now presents a cleaner summary-first view, with `--verbose` available for the full detailed output.
551
-
552
- ### 3. Copy-and-run fix commands
553
-
554
- This is one of the most important parts of the CLI output.
555
-
556
- When confident upgrade targets exist, CVE Lite CLI shows a dedicated `Copy And Run These Fix Commands` section so developers can move straight from findings to action.
557
-
558
- The commands are:
559
-
560
- - package-manager-aware
561
- - grouped by severity and fix type
562
- - designed to be copied directly from the terminal
563
- - direct command groups are limited to dependencies declared in the scanned root manifest
564
- - shown before the deeper remediation detail in verbose mode
565
- - when enough advisory data exists, targeted to the lowest known non-vulnerable version with transparent version-scan counts in verbose output
566
-
567
- In practice, this helps avoid repeated install-and-rescan loops.
568
- Example: if advisory metadata suggests `tar@7.5.3`, CVE Lite CLI validates that target against known advisory ranges. If `7.5.3` is still known vulnerable, it checks the next published versions (`7.5.4`, `7.5.5`, and so on) until it finds the lowest known non-vulnerable version. The verbose output then shows how many versions were scanned and how many were excluded as still known vulnerable.
569
-
570
- In the NestJS walkthrough, that validation flow scanned 22 package versions for a `tar` remediation path and excluded 21 as still known vulnerable before selecting the lowest known non-vulnerable target (see the [NestJS case study](docs/case-studies/nestjs.md)).
571
-
572
- This gives developers a more direct remediation path instead of repeatedly upgrading, rescanning, and discovering that the next version is still affected. In slower CI-only workflows, that trial-and-error cycle can otherwise take much longer.
573
-
574
- ### 4. Top priority fixes
575
-
576
- The CLI highlights the most important issues first, so developers can focus on the findings most likely to matter immediately.
577
-
578
- ### 5. Suggested fix plan
579
-
580
- CVE Lite CLI organizes likely dependency remediation work into a practical sequence, such as:
581
-
582
- - direct critical and high issues first
583
- - urgent transitive issues next
584
- - medium direct cleanup after that
585
- - duplicated vulnerable packages to consolidate
586
-
587
- ### 6. Parent package hints for transitive issues
588
-
589
- For transitive vulnerabilities, CVE Lite CLI can show the dependency path and, when it can determine one reliably, recommend the parent package upgrade to make. That makes the output more actionable than simply saying a nested package is vulnerable.
590
-
591
- ### 7. JSON output
592
-
593
- Structured JSON output makes it easier to integrate with scripts, logs, or pipeline artifacts.
594
-
595
- ### 8. CI-friendly behavior
596
-
597
- The CLI can be used in CI/CD pipelines and can fail builds based on severity thresholds.
598
-
599
- ### 9. Offline advisory DB support
600
-
601
- 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.
602
-
603
- That makes it more practical for:
604
-
605
- - enterprise environments
606
- - restricted CI systems
607
- - air-gapped workflows
608
- - teams that want explicit local advisory control
609
-
610
- ### 10. Local cache
611
-
612
- It caches advisory detail results locally so repeated scans are faster and make fewer repeated requests.
613
-
614
- ### 11. Clear final scan status
615
-
616
- 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.
617
-
618
- ### 12. Small runtime footprint
619
-
620
- This project intentionally keeps runtime dependencies minimal to reduce attack surface and keep the tool easier to review.
621
-
622
- ## Dependency footprint
623
-
624
- CVE Lite CLI is intentionally designed with a very small dependency surface.
625
-
626
- **Runtime dependencies**
627
- - `yaml`
628
- - `yarn-lockfile`
629
- - `better-sqlite3`
630
- - `fflate`
631
-
632
- **Development dependencies**
633
- - `@types/node`
634
- - `tsx`
635
- - `typescript`
636
-
637
- This is a deliberate design choice. Because CVE Lite CLI is itself a security-oriented tool, we want to minimize unnecessary third-party packages and keep the runtime as small and reviewable as possible.
220
+ If you maintain an open-source JavaScript or TypeScript project and want CVE Lite CLI evaluated on it, open an issue and share the repository. Strong candidates may be turned into future public case studies.
638
221
 
639
- ## Example use cases
222
+ ## Who uses it
640
223
 
641
224
  CVE Lite CLI is a good fit for:
642
225
 
643
- - independent developers shipping side projects
644
- - startups watching every tool budget
645
- - consultants doing release checks for client projects
646
- - teams that want a lightweight dependency scan in CI
647
- - developers who want a second opinion alongside other tools
648
- - OSS maintainers who need a practical scan before publishing
649
- - teams that need offline or controlled-network dependency scanning
650
- - security-conscious organizations that need clear advisory data control
651
-
652
- ## Supported workflows
653
-
654
- ### Local development
655
-
656
- Run it before a release, during dependency cleanup, or after a major package upgrade.
657
-
658
- For offline-capable local workflows:
659
-
660
- ```bash
661
- cve-lite advisories sync
662
- cve-lite . --offline
663
- ```
664
-
665
- ### CI/CD
666
-
667
- 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).
668
-
669
- Use the reusable first-party GitHub Action in another repository:
670
-
671
- ```yaml
672
- name: Dependency Scan
673
-
674
- on:
675
- pull_request:
676
- push:
677
- branches: [main]
678
-
679
- jobs:
680
- cve-lite:
681
- runs-on: ubuntu-latest
682
- steps:
683
- - uses: actions/checkout@v4
684
- - uses: sonukapoor/cve-lite-cli@v1
685
- with:
686
- verbose: "true"
687
- fail-on: high
688
- ```
689
-
690
- For an offline GitHub Actions workflow that refreshes the advisory DB first:
691
-
692
- ```yaml
693
- name: Offline Dependency Scan
694
-
695
- on:
696
- pull_request:
697
-
698
- jobs:
699
- cve-lite:
700
- runs-on: ubuntu-latest
701
- steps:
702
- - uses: actions/checkout@v4
703
- - uses: sonukapoor/cve-lite-cli@v1
704
- with:
705
- sync-advisories: "true"
706
- offline: "true"
707
- offline-db: ./.cache/cve-lite/advisories.db
708
- verbose: "true"
709
- fail-on: high
710
- ```
711
-
712
- For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, detailed table output, and suggested fix commands when a scan fails.
713
-
714
- Use it as a release gate in CI:
226
+ - **Independent developers and OSS maintainers** — quick pre-release check without any platform overhead
227
+ - **Startups and small teams** — lightweight CI gate at no cost
228
+ - **Consultants** — run a scan on a client project in seconds, with a clear fix plan to hand over
229
+ - **Enterprise teams with restricted networks** — offline advisory DB workflow removes the need for runtime outbound calls during scans
230
+ - **Teams running npm, pnpm, and Yarn** — unified scanning across all three package managers in one tool
715
231
 
716
- ```bash
717
- cve-lite . --verbose --fail-on high
718
- ```
719
-
720
- ### Scripted automation
721
-
722
- Use JSON output for custom reporting:
723
-
724
- ```bash
725
- cve-lite . --json > cve-lite-report.json
726
- ```
727
-
728
- Use an offline local advisory DB in controlled environments:
729
-
730
- ```bash
731
- cve-lite advisories sync --output ./.cache/advisories.db
732
- cve-lite . --offline-db ./.cache/advisories.db --json > cve-lite-report.json
733
- ```
232
+ See the [CI and Workflow Integration guide](docs/ci-integration.md) for concrete patterns across these scenarios.
734
233
 
735
- ## Recommended workflow patterns
736
-
737
- 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.
738
-
739
- The recommended pattern is:
740
-
741
- 1. choose a scan command that matches your environment
742
- 2. wire it into scripts, hooks, CI, or scheduled refresh jobs
743
- 3. keep the behavior explicit so developers and security reviewers can see exactly when scans run and whether network access is involved
744
-
745
- ### Package scripts
746
-
747
- Add a simple script to the consuming project so developers have a memorable command:
748
-
749
- ```json
750
- {
751
- "scripts": {
752
- "security:scan": "cve-lite .",
753
- "security:scan:offline": "cve-lite . --offline"
754
- }
755
- }
756
- ```
757
-
758
- This is the best default for most teams because it is visible, easy to document, and easy to reuse in local development and CI.
759
-
760
- ### Opt-in postinstall usage
234
+ ## Current limitations
761
235
 
762
- 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.
236
+ - does not detect malicious packages before they appear in advisory data
237
+ - does not perform behavioral malware detection or package content analysis
238
+ - does not prove exploitability or verify runtime reachability
239
+ - does not scan container images, binaries, secrets, or IaC
240
+ - does not replace a full application security program
241
+ - currently focused on JS/TS dependency scanning
242
+ - local advisory sync performance will need continued optimization as the advisory dataset grows
763
243
 
764
- For example:
244
+ ## Dependency footprint
765
245
 
766
- ```json
767
- {
768
- "scripts": {
769
- "postinstall": "cve-lite . --offline || true"
770
- }
771
- }
772
- ```
246
+ **Runtime:** `yaml` · `yarn-lockfile` · `better-sqlite3` · `fflate`
773
247
 
774
- Why this is opt-in:
248
+ **Dev only:** `@types/node` · `tsx` · `typescript`
775
249
 
776
- - install hooks should be visible to the team using them
777
- - controlled environments often prefer offline scanning for install-time checks
778
- - explicit project scripts are easier to review, tune, and disable than implicit package behavior
250
+ This is intentional. Because CVE Lite CLI is a security-oriented tool, runtime dependencies are kept minimal and reviewable.
779
251
 
780
- ### Git hooks
252
+ ## Roadmap
781
253
 
782
- For teams that want a lightweight local gate before code leaves a workstation, a git hook can be a good fit:
254
+ See [roadmap.md](docs/roadmap.md) for the full plan. Phases 1 and 2 are complete. Phase 3 (ecosystem coverage: Bun, Deno, parser improvements) is in progress.
783
255
 
784
- ```bash
785
- cve-lite . --fail-on high
786
- ```
256
+ ## Troubleshooting
787
257
 
788
- This works well in `pre-push` or another team-approved hook if you want to catch high-severity dependency issues before changes are shared.
258
+ See [troubleshooting.md](docs/troubleshooting.md) for common issues: no lockfile found, zero results, slow advisory sync, offline DB errors, `--fix` skipping findings, and CI failures.
789
259
 
790
- ### CI pipelines
260
+ ## Parser coverage
791
261
 
792
- For CI, a strong baseline is:
262
+ See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats, selection priority, the `package.json` fallback, and known edge cases including monorepos and private registries.
793
263
 
794
- ```bash
795
- cve-lite . --verbose --fail-on high
796
- ```
264
+ ## Contributing
797
265
 
798
- For controlled or restricted environments, sync the advisory DB separately and then scan offline:
266
+ Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
799
267
 
800
- ```bash
801
- cve-lite advisories sync --output ./.cache/advisories.db
802
- cve-lite . --offline-db ./.cache/advisories.db --verbose --fail-on high
803
- ```
268
+ See [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
804
269
 
805
- ### Scheduled advisory DB refresh
270
+ ## Add a badge to your project
806
271
 
807
- If you use offline mode, keep the advisory DB fresh with a scheduler such as cron, CI, or an internal automation system:
272
+ If you use CVE Lite CLI in your project, add this badge to your README:
808
273
 
809
- ```bash
810
- cve-lite advisories sync --output /path/to/advisories.db
274
+ ```markdown
275
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
811
276
  ```
812
277
 
813
- This keeps offline scans current without forcing every developer machine or build runner to make live advisory API calls during the scan itself.
814
-
815
- ## Comparison with other tools
816
-
817
- 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.
818
-
819
- ### Where CVE Lite CLI stands out
820
-
821
- Compared with other tools in this space, CVE Lite CLI focuses on:
822
-
823
- - **free to use**
824
- - **fast to run**
825
- - **easy to understand**
826
- - **practical dependency remediation guidance** instead of just raw advisory dumps
827
- - **clear direct vs transitive visibility**
828
- - **top priority fixes** and a suggested fix plan
829
- - support for **npm**, **pnpm**, and **Yarn** lockfiles
830
- - **SARIF** and **JSON** output for CI and automation
831
- - a **lightweight**, **security-conscious** dependency footprint
832
- - **offline local advisory DB support** for controlled environments
833
- - a **developer-friendly** option for teams that want useful **CVE scanning without paying for a larger commercial product**
834
-
835
- ### At a glance
836
-
837
- | Tool | Best at | Ecosystem scope | Lockfile support | Dependency remediation guidance | Auto-fix support | JSON/SARIF | Best fit |
838
- |---|---|---|---|---|---|---|---|
839
- | **CVE Lite CLI** | Fast, developer-friendly pre-release CVE scanning | Focused on JS/TS | npm, pnpm, Yarn | **Dependency fix guidance** | **Yes (scoped `--fix` for validated direct dependencies in v1)** | **Yes** | Developers and small teams who want a free, practical release-time check |
840
- | `npm audit` | Built-in npm auditing | npm-centric | npm | Basic remediation info | Yes (`npm audit fix`) | Limited compared to dedicated scanner workflows | Teams already living fully inside npm |
841
- | OSV-Scanner | Broad multi-ecosystem scanning | Broad | Many ecosystems and lockfiles | More general-purpose | Yes (guided remediation, experimental) | Strong machine-readable workflows | Teams needing wider ecosystem coverage |
842
- | Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Yes (CLI + platform-driven fix/PR workflows) | Strong | Teams adopting a larger security platform |
843
- | Socket CLI | Broader package and supply-chain risk visibility | Broad | Multi-ecosystem/package-risk focus | Strong for package risk workflows | Varies by product/workflow | Strong | Teams that want more than CVE scanning alone |
844
-
845
- ### Offline support at a glance
846
-
847
- | Tool | Local advisory DB workflow | Zero runtime advisory API calls |
848
- |---|---|---|
849
- | **CVE Lite CLI** | **Yes** | **Yes** |
850
- | `npm audit` | No built-in local advisory DB workflow | No |
851
- | OSV-Scanner | Depends on broader workflow setup rather than the local DB pattern emphasized here | Varies by setup |
852
- | Snyk CLI | Not the primary workflow emphasis | Varies by product/workflow |
853
- | Socket CLI | Not the primary workflow emphasis | Varies by product/workflow |
854
-
855
- ### CVE Lite CLI vs npm audit
856
-
857
- `npm audit` is the built-in default for npm users, which makes it convenient when your workflow is entirely npm-based.
858
-
859
- CVE Lite CLI stands out when you want:
860
-
861
- - support across npm, pnpm, and Yarn lockfiles
862
- - cleaner, more guided console output
863
- - priority fixes and a suggested remediation plan
864
- - a more focused pre-release scanning experience for JS/TS teams
865
-
866
- ### CVE Lite CLI vs OSV-Scanner
867
-
868
- OSV-Scanner supports many ecosystems and lockfile types, which makes it broader overall.
869
-
870
- CVE Lite CLI stands out when you want:
871
-
872
- - a narrower, easier-to-understand tool built specifically around JS/TS dependency workflows
873
- - remediation-first output instead of a more general multi-ecosystem scanner experience
874
- - a more approachable local workflow for everyday developers
875
- - a more explicit local advisory DB workflow for offline or restricted environments
876
-
877
- ### CVE Lite CLI vs Snyk CLI
878
-
879
- Snyk CLI is part of a much broader commercial platform with wider enterprise coverage.
880
-
881
- CVE Lite CLI stands out when you want:
882
-
883
- - a simpler and lighter dependency CVE workflow
884
- - an affordable option for small teams, startups, consultants, and independent developers
885
- - a focused tool for lockfile-based release checks without adopting a larger platform
886
- - a more explicit offline scanning model with local advisory DB control
887
-
888
- ### CVE Lite CLI vs Socket CLI
889
-
890
- Socket CLI goes beyond CVEs into broader package and supply-chain risk signals.
891
-
892
- CVE Lite CLI stands out when you want:
893
-
894
- - a focused dependency vulnerability scanner
895
- - a straightforward answer to “what should I fix before release?”
896
- - readable output centered on known vulnerability findings and practical next steps
897
-
898
- ### Best fit
899
-
900
- CVE Lite CLI is best for:
901
-
902
- - developers shipping JavaScript or TypeScript applications
903
- - teams that want a lightweight release gate
904
- - maintainers who want actionable vulnerability output without heavy platform overhead
905
- - users who care about simplicity, readability, and fast adoption
906
-
907
- If your goal is a practical developer-first CVE scan right before release, CVE Lite CLI is designed to be one of the most approachable options in that workflow.
908
-
909
- ## Current limitations
910
-
911
- To keep the project honest, here is what it does **not** do in the current version:
912
-
913
- - it does not detect malicious packages before they are represented in advisory data
914
- - it does not perform behavioral malware detection or package content analysis
915
- - it does not prove exploitability
916
- - it does not verify runtime reachability
917
- - it does not scan container images, binaries, secrets, or IaC
918
- - it does not replace a full application security program
919
- - it is currently focused on JS/TS dependency scanning
920
- - local advisory sync performance will need continued optimization as the advisory dataset grows
921
-
922
- ## Positioning
923
-
924
- CVE Lite CLI is best described as:
925
-
926
- **A fast, developer-friendly dependency vulnerability scanner for JavaScript and TypeScript projects, built for teams that want actionable results without the cost and complexity of a full security platform.**
927
-
928
- ## Roadmap
929
-
930
- CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remediation engine.
931
-
932
- ### Phase 1: Advanced Remediation Intelligence (Short-Term)
933
- * **Executable Fix-Plan:** Move from suggesting a plan to generating executable commands (e.g., `npm install package@version`) to resolve direct vulnerabilities.
934
- * **Transitive Parent Mapping:** Enhance output to explicitly map the dependency path from the root to the vulnerable nested package, making manual triage effortless.
935
- * **Deduplication Analysis:** Identify instances where multiple versions of the same vulnerable package exist and suggest a single version for consolidation.
936
-
937
- ### Phase 2: Ecosystem & Integration (Mid-Term)
938
- * **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
939
- * **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
940
- * **Workflow Integration Guidance:** Expand official workflow patterns for local scripts, hooks, CI, and offline developer adoption.
941
-
942
- ### Phase 3: Maturity & Compliance (Long-Term)
943
- * **Standardized SBOM Support:** Add the ability to export findings as an **SBOM (Software Bill of Materials)** in CycloneDX or SPDX formats.
944
- * **Community Plugin System:** Decouple the scanner logic to allow community-contributed data sources and custom security rules.
945
-
946
- ## Contributing
947
-
948
- This project is being shaped around real-world developer usability. Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
949
-
950
- To get started, see [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md).
278
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
951
279
 
952
280
  ## Community and support
953
281
 
954
- CVE Lite CLI is being shaped in public and feedback is welcome.
955
-
956
- If you run into a bug, want to suggest an improvement, or have a lockfile edge case that the tool should handle better, please open an issue in the repository.
957
-
958
- Helpful feedback includes:
282
+ For bug reports and feature requests: [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues)
959
283
 
960
- - reproducible bug reports
961
- - real-world lockfile edge cases
962
- - ideas for clearer output and remediation guidance
963
- - CI usage examples
964
- - JSON and SARIF workflow feedback
965
- - comparison feedback based on real usage
284
+ Helpful feedback includes reproducible bug reports, real-world lockfile edge cases, ideas for clearer output and remediation guidance, and CI or JSON workflow examples.
966
285
 
967
- As the project grows, contribution and security guidance will be expanded further in dedicated project docs.
286
+ For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
968
287
 
969
- For bug reports and feature requests, please use [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues). For contribution guidance, see [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md). For security-related reporting, see [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md).
288
+ If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/sonukapoor/cve-lite-cli) helps more developers find it.
970
289
 
971
290
  ## License
972
291
 
package/dist/index.js CHANGED
@@ -14,6 +14,7 @@ import { chalk } from "./utils/chalk.js";
14
14
  import { createSpinner } from "./output/spinner.js";
15
15
  import { buildSuggestedFixCommandPlan } from "./remediation/fix-commands.js";
16
16
  import { getCliVersion } from "./utils/version-info.js";
17
+ import { isLikelyBlockedAdvisoryRequestError } from "./utils/network.js";
17
18
  import { logInfo, logWarn, printCacheSummary, serializeFinding } from "./output/formatters.js";
18
19
  import { printSummary, printActionSummary, printPriorityFixes, printFixPlan, printSuggestedFixCommands, printSuggestedFixCommandSkips, printCoverage, printSkippedDependencies, printGroupSummary, printTable, printPathHints, printFinalStatus, printCompactOutput } from "./output/printers.js";
19
20
  let parsedArgs = null;
@@ -224,7 +225,13 @@ if (parsedArgs) {
224
225
  return;
225
226
  }
226
227
  main().catch((error) => {
227
- console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
228
+ const errorMessage = error instanceof Error ? error.message : String(error);
229
+ console.error(chalk.red(`Error: ${errorMessage}`));
230
+ if (isLikelyBlockedAdvisoryRequestError(errorMessage)) {
231
+ console.error(chalk.yellow("Hint: Outbound access to the OSV API may be blocked or restricted in this environment."));
232
+ console.error(chalk.gray("If that is expected, build the advisory DB on a machine with OSV access, then scan here with `--offline` or `--offline-db /path/to/advisories.db`."));
233
+ console.error(chalk.gray("Command to build the DB on a network-allowed machine: `cve-lite advisories sync --output /path/to/advisories.db`"));
234
+ }
228
235
  process.exit(1);
229
236
  });
230
237
  }
@@ -19,12 +19,21 @@ export function inferSeverity(vuln) {
19
19
  }
20
20
  const db = vuln.database_specific;
21
21
  const dbSeverity = String(db?.severity ?? "").toLowerCase();
22
+ // OSV uses "MODERATE" where our label is "medium".
23
+ if (dbSeverity === "moderate")
24
+ return "medium";
22
25
  if (["critical", "high", "medium", "low"].includes(dbSeverity)) {
23
26
  return dbSeverity;
24
27
  }
25
28
  return "unknown";
26
29
  }
27
30
  function severityFromScore(score) {
31
+ // CVSS vector strings (e.g. "CVSS:3.1/AV:N/...") are not numerical scores.
32
+ // Extracting the first number would yield the CVSS version (3.1), not the base
33
+ // score — causing every CVSS_V3 advisory to be misclassified as "low".
34
+ // Return unknown so the caller falls through to database_specific.severity.
35
+ if (String(score).startsWith("CVSS:"))
36
+ return "unknown";
28
37
  const match = String(score).match(/([0-9]+(?:\.[0-9]+)?)/);
29
38
  if (!match)
30
39
  return "unknown";
@@ -130,7 +130,8 @@ export function printSuggestedFixCommands(findings, scanInput) {
130
130
  for (const section of plan.sections) {
131
131
  console.log("");
132
132
  console.log(colorFixSectionTitle(section.severity, section.title));
133
- if (section.kind === "direct" || section.kind === "direct-adjusted") {
133
+ const hasDirectTargets = section.targets.some(t => t.kind === "direct");
134
+ if (section.kind === "direct" || section.kind === "direct-adjusted" || (section.kind === "urgent" && hasDirectTargets)) {
134
135
  const validationSummary = summarizeAdjustedValidation(section.targets);
135
136
  const remainingNotes = [];
136
137
  printDirectTargetsTable(section.targets, remainingNotes, validationSummary, sharedDirectTableWidths);
@@ -149,7 +150,10 @@ export function printSuggestedFixCommandSkips(findings, scanInput) {
149
150
  if (!plan || plan.skipped.length === 0)
150
151
  return;
151
152
  const unpublishable = plan.skipped.filter(skipped => skipped.reason.includes("not published on npm"));
152
- const remaining = plan.skipped.filter(skipped => !skipped.reason.includes("not published on npm"));
153
+ // Only surface direct-dependency skips here. Transitive findings without an
154
+ // auto-fix path are already covered by the fix plan step 2 ("Review these urgent
155
+ // transitive issues"), so repeating them here creates confusing duplication.
156
+ const remaining = plan.skipped.filter(skipped => !skipped.reason.includes("not published on npm") && skipped.relationship === "direct");
153
157
  if (unpublishable.length > 0) {
154
158
  console.log("");
155
159
  console.log(chalk.gray("Unpublishable fixed-version hints:"));
@@ -162,7 +166,7 @@ export function printSuggestedFixCommandSkips(findings, scanInput) {
162
166
  }
163
167
  if (remaining.length > 0) {
164
168
  console.log("");
165
- console.log(chalk.gray("Not included automatically:"));
169
+ console.log(chalk.gray("No auto-fix command available for these direct dependencies:"));
166
170
  for (const skipped of remaining.slice(0, 5)) {
167
171
  console.log(`- ${skipped.package}@${skipped.version}: ${skipped.reason}`);
168
172
  }
@@ -0,0 +1,33 @@
1
+ export function isLikelyBlockedAdvisoryRequestError(message) {
2
+ if (!message.includes("OSV")) {
3
+ return false;
4
+ }
5
+ const normalized = message.toLowerCase();
6
+ const finalCause = normalized.split(":").pop()?.trim() ?? normalized;
7
+ const blockedIndicators = [
8
+ "access denied",
9
+ "blocked",
10
+ "body timeout",
11
+ "connection refused",
12
+ "eai_again",
13
+ "econnrefused",
14
+ "econnreset",
15
+ "enotfound",
16
+ "etimedout",
17
+ "fetch failed",
18
+ "forbidden",
19
+ "gateway timeout",
20
+ "host unreachable",
21
+ "network unavailable",
22
+ "proxy",
23
+ "socket hang up",
24
+ "timed out",
25
+ "timeout",
26
+ "tunneling socket",
27
+ "unable to verify the first certificate",
28
+ ];
29
+ if (blockedIndicators.some(indicator => finalCause.includes(indicator))) {
30
+ return true;
31
+ }
32
+ return /^(401|403|407|408|429|451|502|503|504)\b/.test(finalCause);
33
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cve-lite-cli",
3
- "version": "1.5.2",
3
+ "version": "1.5.4",
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": {