cve-lite-cli 1.5.1 β 1.5.3
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 +151 -798
- package/dist/cli/args.js +4 -0
- package/dist/cli/help.js +1 -0
- package/dist/index.js +224 -31
- package/dist/osv/severity.js +6 -0
- package/dist/utils/network.js +33 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,159 +4,111 @@
|
|
|
4
4
|
[](https://github.com/sonukapoor/cve-lite-cli/actions)
|
|
5
5
|
[](https://github.com/marketplace/actions/cve-lite-cli)
|
|
6
6
|
[](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
|
|
7
|
+
[](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
|
|
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.
|
|
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
|
-
##
|
|
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="#what-it-looks-like">What it looks like</a><br/>
|
|
41
|
-
<a href="#why-this-tool-exists">Why this tool exists</a><br/>
|
|
42
|
-
<a href="#project-scope-and-differentiation">Project scope and differentiation</a>
|
|
43
|
-
</td>
|
|
44
|
-
<td valign="top">
|
|
45
|
-
<strong>Usage</strong><br/>
|
|
46
|
-
<a href="#quick-start">Quick start</a><br/>
|
|
47
|
-
<a href="#usage">Usage</a><br/>
|
|
48
|
-
<a href="#workflow-modes">Workflow modes</a><br/>
|
|
49
|
-
<a href="#network-behavior-and-privacy">Network behavior and privacy</a><br/>
|
|
50
|
-
<a href="#features">Features</a><br/>
|
|
51
|
-
<a href="#supported-workflows">Supported workflows</a>
|
|
52
|
-
</td>
|
|
53
|
-
<td valign="top">
|
|
54
|
-
<strong>CI and Offline</strong><br/>
|
|
55
|
-
<a href="#dependency-footprint">Dependency footprint</a><br/>
|
|
56
|
-
<a href="#example-use-cases">Example use cases</a><br/>
|
|
57
|
-
<a href="#recommended-workflow-patterns">Recommended workflow patterns</a><br/>
|
|
58
|
-
<a href="#comparison-with-other-tools">Comparison with other tools</a><br/>
|
|
59
|
-
<a href="#current-limitations">Current limitations</a><br/>
|
|
60
|
-
<a href="#positioning">Positioning</a>
|
|
61
|
-
</td>
|
|
62
|
-
<td valign="top">
|
|
63
|
-
<strong>Project</strong><br/>
|
|
64
|
-
<a href="#roadmap">Roadmap</a><br/>
|
|
65
|
-
<a href="#contributing">Contributing</a><br/>
|
|
66
|
-
<a href="#community-and-support">Community and support</a><br/>
|
|
67
|
-
<a href="#license">License</a>
|
|
68
|
-
</td>
|
|
69
|
-
</tr>
|
|
70
|
-
</table>
|
|
71
|
-
|
|
72
|
-
## What is CVE Lite CLI
|
|
73
|
-
|
|
74
|
-
**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.
|
|
75
|
-
|
|
76
|
-
It is designed to be:
|
|
77
|
-
|
|
78
|
-
- developer-friendly in day-to-day workflows
|
|
79
|
-
- local-first and transparent about network behavior
|
|
80
|
-
- usable in enterprise and restricted-network environments
|
|
81
|
-
- capable of zero-runtime-network scans through a local advisory database
|
|
82
|
-
|
|
83
|
-
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).
|
|
84
|
-
|
|
85
|
-
## New here? Start here
|
|
86
|
-
|
|
87
|
-
1. run one scan on a real project with `npx cve-lite-cli /path/to/project --verbose`
|
|
88
|
-
2. review direct vs transitive findings and the `Copy And Run These Fix Commands` section (direct command groups apply to manifest-declared dependencies)
|
|
89
|
-
3. compare the output with your current scanner workflow
|
|
90
|
-
4. check a real walkthrough:
|
|
91
|
-
- [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md)
|
|
92
|
-
- [NestJS case study](docs/case-studies/nestjs.md)
|
|
93
|
-
|
|
94
|
-
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).
|
|
95
|
-
|
|
96
|
-
If you want to shape the roadmap, open an issue with feedback on:
|
|
97
|
-
|
|
98
|
-
- whether the direct vs transitive split is useful in practice
|
|
99
|
-
- where remediation guidance is still missing
|
|
100
|
-
- what increases or decreases trust in a CLI security tool
|
|
101
|
-
- what would make frontend-heavy CI workflows smoother
|
|
102
|
-
|
|
103
|
-
## New: Offline advisory DB support
|
|
104
|
-
|
|
105
|
-
CVE Lite CLI now supports a local advisory database workflow for teams that cannot allow runtime outbound advisory API calls.
|
|
106
|
-
|
|
107
|
-
That means you can:
|
|
41
|
+
## Quick start
|
|
108
42
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
-
|
|
43
|
+
```bash
|
|
44
|
+
npm install -g cve-lite-cli
|
|
45
|
+
cve-lite /path/to/project
|
|
46
|
+
```
|
|
112
47
|
|
|
113
|
-
|
|
48
|
+
Or one-off with `npx`:
|
|
114
49
|
|
|
115
50
|
```bash
|
|
116
|
-
|
|
117
|
-
|
|
51
|
+
npx cve-lite-cli /path/to/project
|
|
52
|
+
```
|
|
118
53
|
|
|
119
|
-
|
|
120
|
-
cve-lite /path/to/project --offline
|
|
54
|
+
## What is CVE Lite CLI
|
|
121
55
|
|
|
122
|
-
|
|
123
|
-
cve-lite /path/to/project --offline-db /path/to/advisories.db
|
|
124
|
-
```
|
|
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.
|
|
125
57
|
|
|
126
|
-
|
|
58
|
+
It is built for the moment right before release: fast, local-first, and honest about what it does and does not do.
|
|
127
59
|
|
|
128
|
-
|
|
60
|
+
**Key differentiators:**
|
|
129
61
|
|
|
130
|
-
|
|
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
|
|
131
67
|
|
|
132
|
-
|
|
133
|
-
- regulated teams that need explicit advisory data handling
|
|
134
|
-
- internal CI systems that should not depend on public runtime API access
|
|
135
|
-
- air-gapped or partially connected workflows
|
|
68
|
+
## How it compares
|
|
136
69
|
|
|
137
|
-
|
|
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 | β
| β | β οΈ | β | β |
|
|
138
81
|
|
|
139
|
-
|
|
82
|
+
<sub>β
= built-in strength Β· β οΈ = partial or workflow-dependent Β· β = not a core strength</sub>
|
|
140
83
|
|
|
141
|
-
|
|
84
|
+
For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
|
|
85
|
+
|
|
86
|
+
## What it looks like
|
|
142
87
|
|
|
143
|
-
|
|
88
|
+
Default output on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop):
|
|
144
89
|
|
|
145
90
|
```bash
|
|
146
|
-
|
|
91
|
+
git clone https://github.com/juice-shop/juice-shop.git
|
|
92
|
+
cd juice-shop
|
|
93
|
+
cve-lite .
|
|
147
94
|
```
|
|
148
95
|
|
|
149
|
-
|
|
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>
|
|
150
101
|
|
|
151
|
-
|
|
152
|
-
cve-lite /path/to/project
|
|
153
|
-
```
|
|
102
|
+
Verbose output β includes the `Copy And Run These Fix Commands` section:
|
|
154
103
|
|
|
155
|
-
|
|
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>
|
|
156
110
|
|
|
157
|
-
|
|
158
|
-
npx cve-lite-cli /path/to/project
|
|
159
|
-
```
|
|
111
|
+
For a section-by-section walkthrough, see [How to read verbose output](docs/how-to-read-verbose-output.md).
|
|
160
112
|
|
|
161
113
|
## Usage
|
|
162
114
|
|
|
@@ -167,14 +119,16 @@ cve-lite /path/to/project
|
|
|
167
119
|
# Show all findings
|
|
168
120
|
cve-lite /path/to/project --all
|
|
169
121
|
|
|
170
|
-
# Focus
|
|
122
|
+
# Focus on urgent findings only
|
|
171
123
|
cve-lite /path/to/project --min-severity high
|
|
172
124
|
|
|
173
|
-
#
|
|
174
|
-
# Recommended for CI logs when you want full context
|
|
125
|
+
# Full output: fix plan, paths, and complete table
|
|
175
126
|
cve-lite /path/to/project --verbose
|
|
176
127
|
|
|
177
|
-
#
|
|
128
|
+
# Apply validated direct dependency fixes and rescan
|
|
129
|
+
cve-lite /path/to/project --fix
|
|
130
|
+
|
|
131
|
+
# Production dependencies only (where supported by the lockfile)
|
|
178
132
|
cve-lite /path/to/project --prod-only
|
|
179
133
|
|
|
180
134
|
# Fail a build on high severity and above
|
|
@@ -183,13 +137,7 @@ cve-lite /path/to/project --fail-on high
|
|
|
183
137
|
# JSON output
|
|
184
138
|
cve-lite /path/to/project --json
|
|
185
139
|
|
|
186
|
-
#
|
|
187
|
-
cve-lite /path/to/project --osv-url https://security.company.internal/osv
|
|
188
|
-
|
|
189
|
-
# Show the CLI version
|
|
190
|
-
cve-lite --version
|
|
191
|
-
|
|
192
|
-
# Build the local advisory DB for offline scans
|
|
140
|
+
# Sync the local advisory DB for offline scans
|
|
193
141
|
cve-lite advisories sync
|
|
194
142
|
|
|
195
143
|
# Scan with zero runtime advisory API calls
|
|
@@ -197,742 +145,147 @@ cve-lite /path/to/project --offline
|
|
|
197
145
|
|
|
198
146
|
# Use a specific local advisory DB file
|
|
199
147
|
cve-lite /path/to/project --offline-db /path/to/advisories.db
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
## Workflow modes
|
|
203
|
-
|
|
204
|
-
CVE Lite CLI now supports three clear advisory workflows:
|
|
205
|
-
|
|
206
|
-
### 1. Standard online scan
|
|
207
|
-
|
|
208
|
-
Use the default OSV-backed mode when runtime advisory API access is acceptable:
|
|
209
|
-
|
|
210
|
-
```bash
|
|
211
|
-
cve-lite /path/to/project
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
### 2. Advisory DB sync
|
|
215
|
-
|
|
216
|
-
Build or refresh the local advisory database ahead of time:
|
|
217
|
-
|
|
218
|
-
```bash
|
|
219
|
-
cve-lite advisories sync
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
### 3. Offline local DB scan
|
|
223
|
-
|
|
224
|
-
Scan against the local advisory DB with zero runtime advisory API calls:
|
|
225
148
|
|
|
226
|
-
|
|
227
|
-
cve-lite /path/to/project --
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
## What it looks like
|
|
231
|
-
|
|
232
|
-
CVE Lite CLI produces a clean, summary-first console view by default, designed for fast triage before release.
|
|
233
|
-
|
|
234
|
-
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.
|
|
235
|
-
|
|
236
|
-
The most important section to look for in the output is:
|
|
237
|
-
|
|
238
|
-
```text
|
|
239
|
-
π Copy And Run These Fix Commands
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
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.
|
|
243
|
-
|
|
244
|
-
For example, the tool can now suggest a concrete next command such as:
|
|
149
|
+
# Use a custom advisory endpoint
|
|
150
|
+
cve-lite /path/to/project --osv-url https://security.company.internal/osv
|
|
245
151
|
|
|
246
|
-
|
|
247
|
-
|
|
152
|
+
# Show version
|
|
153
|
+
cve-lite --version
|
|
248
154
|
```
|
|
249
155
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
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.
|
|
253
|
-
|
|
254
|
-
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.
|
|
255
|
-
|
|
256
|
-
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:
|
|
257
|
-
|
|
258
|
-
1. upgrade `tar`
|
|
259
|
-
2. push a branch
|
|
260
|
-
3. wait for CI or a scheduled scanner to report back
|
|
261
|
-
4. learn they need to upgrade `tar` again
|
|
262
|
-
5. repeat the full cycle
|
|
156
|
+
## Auto-fix mode (`--fix`)
|
|
263
157
|
|
|
264
|
-
|
|
158
|
+
`--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.
|
|
265
159
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
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.
|
|
273
|
-
|
|
274
|
-
## Example: Scanning OWASP Juice Shop (Real Output)
|
|
275
|
-
|
|
276
|
-
CVE Lite CLI can be used against real-world vulnerable applications such as the OWASP Juice Shop.
|
|
277
|
-
|
|
278
|
-
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.
|
|
279
|
-
|
|
280
|
-
To try this yourself:
|
|
281
|
-
|
|
282
|
-
Example:
|
|
160
|
+
In the current version it:
|
|
161
|
+
- applies only direct dependency fixes with a validated lowest known non-vulnerable target
|
|
162
|
+
- uses `npm install`, `pnpm add`, or `yarn add` based on your lockfile
|
|
163
|
+
- rescans automatically after applying fixes
|
|
164
|
+
- does **not** auto-apply transitive overrides or guarantee application compatibility
|
|
283
165
|
|
|
284
166
|
```bash
|
|
285
|
-
|
|
286
|
-
cd juice-shop
|
|
287
|
-
cve-lite .
|
|
167
|
+
npx cve-lite-cli /path/to/project --fix
|
|
288
168
|
```
|
|
289
169
|
|
|
290
|
-
|
|
291
|
-
<img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
|
|
292
|
-
</p>
|
|
293
|
-
|
|
294
|
-
Verbose examples:
|
|
295
|
-
|
|
296
|
-
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.
|
|
297
|
-
|
|
298
|
-
<p align="center">
|
|
299
|
-
<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"/>
|
|
300
|
-
<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"/>
|
|
301
|
-
<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"/>
|
|
302
|
-
</p>
|
|
303
|
-
|
|
304
|
-
## Why this tool exists
|
|
170
|
+
See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
|
|
305
171
|
|
|
306
|
-
|
|
172
|
+
## Offline support
|
|
307
173
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
CVE Lite CLI is built for that workflow.
|
|
311
|
-
|
|
312
|
-
It focuses on being:
|
|
313
|
-
|
|
314
|
-
- fast
|
|
315
|
-
- local-first
|
|
316
|
-
- easy to understand
|
|
317
|
-
- useful in CI
|
|
318
|
-
- honest about what it does and does not do
|
|
319
|
-
|
|
320
|
-
## Project scope and differentiation
|
|
321
|
-
|
|
322
|
-
CVE Lite CLI is intentionally focused.
|
|
323
|
-
|
|
324
|
-
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.
|
|
325
|
-
|
|
326
|
-
The project emphasizes:
|
|
327
|
-
|
|
328
|
-
- npm, pnpm, and Yarn lockfile support
|
|
329
|
-
- direct vs transitive visibility
|
|
330
|
-
- top-priority fixes and a suggested dependency remediation plan
|
|
331
|
-
- JSON output for automation
|
|
332
|
-
- offline scanning through a local advisory database
|
|
333
|
-
- configurable advisory endpoint support via `--osv-url` for internal proxies or mirrors
|
|
334
|
-
- a small, reviewable runtime footprint
|
|
335
|
-
|
|
336
|
-
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.
|
|
337
|
-
|
|
338
|
-
## Relationship to similar OWASP projects
|
|
339
|
-
|
|
340
|
-
CVE Lite CLI is not trying to replace broader OWASP security tooling.
|
|
341
|
-
|
|
342
|
-
Its role is narrower and workflow-focused:
|
|
343
|
-
|
|
344
|
-
- focused on JavaScript and TypeScript dependency scanning
|
|
345
|
-
- designed for fast local checks and simple CI release gates
|
|
346
|
-
- centered on direct vs transitive visibility
|
|
347
|
-
- built to highlight top-priority fixes and a suggested dependency remediation plan
|
|
348
|
-
- intentionally lightweight in runtime footprint and setup
|
|
349
|
-
|
|
350
|
-
The closest OWASP comparisons are:
|
|
351
|
-
|
|
352
|
-
- **OWASP Dependency-Check**
|
|
353
|
-
A broader dependency analysis tool that covers many ecosystems and use cases beyond the lockfile-first JavaScript/TypeScript workflow emphasized here.
|
|
354
|
-
|
|
355
|
-
- **OWASP dep-scan**
|
|
356
|
-
A broader dependency and security analysis tool with wider language and environment coverage than this project is trying to provide.
|
|
357
|
-
|
|
358
|
-
- **OWASP Dependency-Track**
|
|
359
|
-
More SBOM- and platform-oriented, with a different operational model than a lightweight local CLI focused on developer checks close to release time.
|
|
360
|
-
|
|
361
|
-
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.
|
|
362
|
-
|
|
363
|
-
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.
|
|
364
|
-
|
|
365
|
-
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.
|
|
366
|
-
|
|
367
|
-
## Network behavior and privacy
|
|
368
|
-
|
|
369
|
-
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.
|
|
370
|
-
|
|
371
|
-
It does not require a hosted account, cloud dashboard, or source code upload.
|
|
372
|
-
|
|
373
|
-
For the full explanation, see [Network Behavior and Privacy](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/network-and-privacy.md).
|
|
374
|
-
|
|
375
|
-
### Offline workflow
|
|
376
|
-
|
|
377
|
-
For teams in controlled or restricted environments, the intended model is:
|
|
378
|
-
|
|
379
|
-
1. sync advisory data into a local database
|
|
380
|
-
2. distribute that database as needed
|
|
381
|
-
3. scan projects using the local DB instead of runtime OSV API calls
|
|
382
|
-
|
|
383
|
-
Sync the local advisory database:
|
|
174
|
+
For teams in enterprise, restricted-network, or air-gapped environments:
|
|
384
175
|
|
|
385
176
|
```bash
|
|
177
|
+
# Sync advisory data locally
|
|
386
178
|
cve-lite advisories sync
|
|
387
|
-
```
|
|
388
|
-
|
|
389
|
-
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.
|
|
390
|
-
|
|
391
|
-
Write the advisory database to a specific path:
|
|
392
|
-
|
|
393
|
-
```bash
|
|
394
|
-
cve-lite advisories sync --output /path/to/advisories.db
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
Scan using the default local advisory DB:
|
|
398
179
|
|
|
399
|
-
|
|
180
|
+
# Scan with no runtime API calls
|
|
400
181
|
cve-lite . --offline
|
|
401
182
|
```
|
|
402
183
|
|
|
403
|
-
|
|
184
|
+
Syncing ~217,065 advisory records runs in under 9 seconds after bulk SQLite ingestion optimizations β roughly **9.9x faster** than the initial implementation.
|
|
404
185
|
|
|
405
|
-
|
|
406
|
-
cve-lite . --offline-db /path/to/advisories.db
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
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:
|
|
410
|
-
|
|
411
|
-
```bash
|
|
412
|
-
cve-lite advisories sync --output /path/to/advisories.db
|
|
413
|
-
```
|
|
414
|
-
|
|
415
|
-
That helps ensure offline scans continue using current advisory data without requiring developers to remember to refresh the DB manually every time.
|
|
416
|
-
|
|
417
|
-
Standard online mode remains available when you want live OSV-backed scans:
|
|
418
|
-
|
|
419
|
-
```bash
|
|
420
|
-
cve-lite . --osv-url https://security.company.internal/osv
|
|
421
|
-
```
|
|
186
|
+
See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
|
|
422
187
|
|
|
423
|
-
|
|
188
|
+
## CI integration
|
|
424
189
|
|
|
425
|
-
The
|
|
426
|
-
|
|
427
|
-
Offline scans now report advisory DB freshness and warn when the local DB appears stale or is missing sync metadata.
|
|
428
|
-
|
|
429
|
-
The recommended model is:
|
|
430
|
-
|
|
431
|
-
- sync the advisory DB on a schedule using cron, CI, or another automation system
|
|
432
|
-
- distribute the refreshed DB where needed
|
|
433
|
-
- run offline scans against that updated DB
|
|
434
|
-
|
|
435
|
-
This helps keep offline scan results current without requiring developers to manually track advisory update cadence.
|
|
436
|
-
|
|
437
|
-
## Detecting malicious package incidents
|
|
438
|
-
|
|
439
|
-
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**.
|
|
440
|
-
|
|
441
|
-
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.
|
|
442
|
-
|
|
443
|
-
It is important to be precise about the current scope:
|
|
444
|
-
|
|
445
|
-
- CVE Lite CLI is **advisory-driven**, not a behavioral malware detector
|
|
446
|
-
- it does **not** perform static malware analysis on package contents
|
|
447
|
-
- it does **not** detect a package compromise before advisory intelligence exists for it
|
|
448
|
-
- it works best with lockfiles because they capture the exact resolved version that was actually installed
|
|
449
|
-
|
|
450
|
-
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.
|
|
451
|
-
|
|
452
|
-
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.
|
|
453
|
-
|
|
454
|
-
## How it works
|
|
455
|
-
|
|
456
|
-
### Architectural Philosophy
|
|
457
|
-
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.
|
|
458
|
-
|
|
459
|
-
<p align="center">
|
|
460
|
-
<img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
|
|
461
|
-
</p>
|
|
462
|
-
|
|
463
|
-
### Workflow Specifications
|
|
464
|
-
* **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.
|
|
465
|
-
* **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.
|
|
466
|
-
* **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.
|
|
467
|
-
* **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.
|
|
468
|
-
* **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.
|
|
469
|
-
* **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.
|
|
470
|
-
|
|
471
|
-
## What makes it stand out
|
|
472
|
-
|
|
473
|
-
- **fast, low-friction workflow**
|
|
474
|
-
Run it locally against a project without adopting a large security platform.
|
|
475
|
-
- **practical dependency remediation guidance**
|
|
476
|
-
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.
|
|
477
|
-
- **direct vs transitive visibility**
|
|
478
|
-
The output makes it easier to see whether the risk comes from something you installed directly or from a nested package.
|
|
479
|
-
- **developer-first**
|
|
480
|
-
It is optimized for developers working with npm, pnpm, and Yarn lockfiles.
|
|
481
|
-
- **budget-friendly**
|
|
482
|
-
It is intended for developers and teams who want useful security checks without paying for a large commercial product.
|
|
483
|
-
- **local-first**
|
|
484
|
-
It reads your project locally and uses package/version matching against OSV advisories.
|
|
485
|
-
- **offline-capable**
|
|
486
|
-
It can sync and scan against a local advisory database for zero-runtime-network workflows.
|
|
487
|
-
- **enterprise-friendly network model**
|
|
488
|
-
Teams can control when advisory data is synced and where offline scans run, which is valuable in restricted environments.
|
|
489
|
-
- **release-focused**
|
|
490
|
-
It is especially useful before a release, in CI, or during final dependency cleanup.
|
|
491
|
-
|
|
492
|
-
## Features
|
|
493
|
-
|
|
494
|
-
### 1. Lockfile-based scanning
|
|
495
|
-
|
|
496
|
-
CVE Lite CLI scans resolved dependency versions from:
|
|
497
|
-
|
|
498
|
-
- `package-lock.json`
|
|
499
|
-
- `pnpm-lock.yaml`
|
|
500
|
-
- `yarn.lock`
|
|
501
|
-
|
|
502
|
-
It also supports a limited `package.json` fallback for exact pinned direct dependencies.
|
|
503
|
-
|
|
504
|
-
### 2. Clear vulnerability output
|
|
505
|
-
|
|
506
|
-
Instead of only showing advisory IDs, the CLI reports:
|
|
507
|
-
|
|
508
|
-
- package name and version
|
|
509
|
-
- severity
|
|
510
|
-
- direct vs transitive relationship
|
|
511
|
-
- fixed-version hint when available
|
|
512
|
-
- advisory IDs
|
|
513
|
-
- dependency path hints
|
|
514
|
-
- recommended parent upgrade for transitive issues when available
|
|
515
|
-
|
|
516
|
-
By default, the CLI now presents a cleaner summary-first view, with `--verbose` available for the full detailed output.
|
|
517
|
-
|
|
518
|
-
### 3. Copy-and-run fix commands
|
|
519
|
-
|
|
520
|
-
This is one of the most important parts of the CLI output.
|
|
521
|
-
|
|
522
|
-
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.
|
|
523
|
-
|
|
524
|
-
The commands are:
|
|
525
|
-
|
|
526
|
-
- package-manager-aware
|
|
527
|
-
- grouped by severity and fix type
|
|
528
|
-
- designed to be copied directly from the terminal
|
|
529
|
-
- direct command groups are limited to dependencies declared in the scanned root manifest
|
|
530
|
-
- shown before the deeper remediation detail in verbose mode
|
|
531
|
-
- when enough advisory data exists, targeted to the lowest known non-vulnerable version with transparent version-scan counts in verbose output
|
|
532
|
-
|
|
533
|
-
In practice, this helps avoid repeated install-and-rescan loops.
|
|
534
|
-
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.
|
|
535
|
-
|
|
536
|
-
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)).
|
|
537
|
-
|
|
538
|
-
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.
|
|
539
|
-
|
|
540
|
-
### 4. Top priority fixes
|
|
541
|
-
|
|
542
|
-
The CLI highlights the most important issues first, so developers can focus on the findings most likely to matter immediately.
|
|
543
|
-
|
|
544
|
-
### 5. Suggested fix plan
|
|
545
|
-
|
|
546
|
-
CVE Lite CLI organizes likely dependency remediation work into a practical sequence, such as:
|
|
547
|
-
|
|
548
|
-
- direct critical and high issues first
|
|
549
|
-
- urgent transitive issues next
|
|
550
|
-
- medium direct cleanup after that
|
|
551
|
-
- duplicated vulnerable packages to consolidate
|
|
552
|
-
|
|
553
|
-
### 6. Parent package hints for transitive issues
|
|
554
|
-
|
|
555
|
-
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.
|
|
556
|
-
|
|
557
|
-
### 7. JSON output
|
|
558
|
-
|
|
559
|
-
Structured JSON output makes it easier to integrate with scripts, logs, or pipeline artifacts.
|
|
560
|
-
|
|
561
|
-
### 8. CI-friendly behavior
|
|
562
|
-
|
|
563
|
-
The CLI can be used in CI/CD pipelines and can fail builds based on severity thresholds.
|
|
564
|
-
|
|
565
|
-
### 9. Offline advisory DB support
|
|
566
|
-
|
|
567
|
-
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.
|
|
568
|
-
|
|
569
|
-
That makes it more practical for:
|
|
570
|
-
|
|
571
|
-
- enterprise environments
|
|
572
|
-
- restricted CI systems
|
|
573
|
-
- air-gapped workflows
|
|
574
|
-
- teams that want explicit local advisory control
|
|
575
|
-
|
|
576
|
-
### 10. Local cache
|
|
577
|
-
|
|
578
|
-
It caches advisory detail results locally so repeated scans are faster and make fewer repeated requests.
|
|
579
|
-
|
|
580
|
-
### 11. Clear final scan status
|
|
581
|
-
|
|
582
|
-
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.
|
|
583
|
-
|
|
584
|
-
### 12. Small runtime footprint
|
|
585
|
-
|
|
586
|
-
This project intentionally keeps runtime dependencies minimal to reduce attack surface and keep the tool easier to review.
|
|
587
|
-
|
|
588
|
-
## Dependency footprint
|
|
589
|
-
|
|
590
|
-
CVE Lite CLI is intentionally designed with a very small dependency surface.
|
|
591
|
-
|
|
592
|
-
**Runtime dependencies**
|
|
593
|
-
- `yaml`
|
|
594
|
-
- `yarn-lockfile`
|
|
595
|
-
- `better-sqlite3`
|
|
596
|
-
- `fflate`
|
|
597
|
-
|
|
598
|
-
**Development dependencies**
|
|
599
|
-
- `@types/node`
|
|
600
|
-
- `tsx`
|
|
601
|
-
- `typescript`
|
|
602
|
-
|
|
603
|
-
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.
|
|
604
|
-
|
|
605
|
-
## Example use cases
|
|
606
|
-
|
|
607
|
-
CVE Lite CLI is a good fit for:
|
|
608
|
-
|
|
609
|
-
- independent developers shipping side projects
|
|
610
|
-
- startups watching every tool budget
|
|
611
|
-
- consultants doing release checks for client projects
|
|
612
|
-
- teams that want a lightweight dependency scan in CI
|
|
613
|
-
- developers who want a second opinion alongside other tools
|
|
614
|
-
- OSS maintainers who need a practical scan before publishing
|
|
615
|
-
- teams that need offline or controlled-network dependency scanning
|
|
616
|
-
- security-conscious organizations that need clear advisory data control
|
|
617
|
-
|
|
618
|
-
## Supported workflows
|
|
619
|
-
|
|
620
|
-
### Local development
|
|
621
|
-
|
|
622
|
-
Run it before a release, during dependency cleanup, or after a major package upgrade.
|
|
623
|
-
|
|
624
|
-
For offline-capable local workflows:
|
|
625
|
-
|
|
626
|
-
```bash
|
|
627
|
-
cve-lite advisories sync
|
|
628
|
-
cve-lite . --offline
|
|
629
|
-
```
|
|
630
|
-
|
|
631
|
-
### CI/CD
|
|
632
|
-
|
|
633
|
-
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).
|
|
634
|
-
|
|
635
|
-
Use the reusable first-party GitHub Action in another repository:
|
|
190
|
+
The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
|
|
636
191
|
|
|
637
192
|
```yaml
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
push:
|
|
643
|
-
branches: [main]
|
|
644
|
-
|
|
645
|
-
jobs:
|
|
646
|
-
cve-lite:
|
|
647
|
-
runs-on: ubuntu-latest
|
|
648
|
-
steps:
|
|
649
|
-
- uses: actions/checkout@v4
|
|
650
|
-
- uses: sonukapoor/cve-lite-cli@v1
|
|
651
|
-
with:
|
|
652
|
-
verbose: "true"
|
|
653
|
-
fail-on: high
|
|
193
|
+
- uses: sonukapoor/cve-lite-cli@v1
|
|
194
|
+
with:
|
|
195
|
+
verbose: "true"
|
|
196
|
+
fail-on: high
|
|
654
197
|
```
|
|
655
198
|
|
|
656
|
-
|
|
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).
|
|
657
200
|
|
|
658
|
-
|
|
659
|
-
name: Offline Dependency Scan
|
|
660
|
-
|
|
661
|
-
on:
|
|
662
|
-
pull_request:
|
|
663
|
-
|
|
664
|
-
jobs:
|
|
665
|
-
cve-lite:
|
|
666
|
-
runs-on: ubuntu-latest
|
|
667
|
-
steps:
|
|
668
|
-
- uses: actions/checkout@v4
|
|
669
|
-
- uses: sonukapoor/cve-lite-cli@v1
|
|
670
|
-
with:
|
|
671
|
-
sync-advisories: "true"
|
|
672
|
-
offline: "true"
|
|
673
|
-
offline-db: ./.cache/cve-lite/advisories.db
|
|
674
|
-
verbose: "true"
|
|
675
|
-
fail-on: high
|
|
676
|
-
```
|
|
677
|
-
|
|
678
|
-
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.
|
|
679
|
-
|
|
680
|
-
Use it as a release gate in CI:
|
|
681
|
-
|
|
682
|
-
```bash
|
|
683
|
-
cve-lite . --verbose --fail-on high
|
|
684
|
-
```
|
|
685
|
-
|
|
686
|
-
### Scripted automation
|
|
201
|
+
For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
|
|
687
202
|
|
|
688
|
-
|
|
203
|
+
## Relationship to similar OWASP projects
|
|
689
204
|
|
|
690
|
-
|
|
691
|
-
cve-lite . --json > cve-lite-report.json
|
|
692
|
-
```
|
|
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.
|
|
693
206
|
|
|
694
|
-
|
|
207
|
+
The closest OWASP comparisons are:
|
|
695
208
|
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
```
|
|
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
|
|
700
212
|
|
|
701
|
-
|
|
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.
|
|
702
214
|
|
|
703
|
-
|
|
215
|
+
## Real-world case studies
|
|
704
216
|
|
|
705
|
-
|
|
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
|
|
706
219
|
|
|
707
|
-
|
|
708
|
-
2. wire it into scripts, hooks, CI, or scheduled refresh jobs
|
|
709
|
-
3. keep the behavior explicit so developers and security reviewers can see exactly when scans run and whether network access is involved
|
|
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.
|
|
710
221
|
|
|
711
|
-
|
|
222
|
+
## Who uses it
|
|
712
223
|
|
|
713
|
-
|
|
224
|
+
CVE Lite CLI is a good fit for:
|
|
714
225
|
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
}
|
|
721
|
-
}
|
|
722
|
-
```
|
|
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
|
|
723
231
|
|
|
724
|
-
|
|
232
|
+
See the [CI and Workflow Integration guide](docs/ci-integration.md) for concrete patterns across these scenarios.
|
|
725
233
|
|
|
726
|
-
|
|
234
|
+
## Current limitations
|
|
727
235
|
|
|
728
|
-
|
|
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
|
|
729
243
|
|
|
730
|
-
|
|
244
|
+
## Dependency footprint
|
|
731
245
|
|
|
732
|
-
|
|
733
|
-
{
|
|
734
|
-
"scripts": {
|
|
735
|
-
"postinstall": "cve-lite . --offline || true"
|
|
736
|
-
}
|
|
737
|
-
}
|
|
738
|
-
```
|
|
246
|
+
**Runtime:** `yaml` Β· `yarn-lockfile` Β· `better-sqlite3` Β· `fflate`
|
|
739
247
|
|
|
740
|
-
|
|
248
|
+
**Dev only:** `@types/node` Β· `tsx` Β· `typescript`
|
|
741
249
|
|
|
742
|
-
|
|
743
|
-
- controlled environments often prefer offline scanning for install-time checks
|
|
744
|
-
- 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.
|
|
745
251
|
|
|
746
|
-
|
|
252
|
+
## Roadmap
|
|
747
253
|
|
|
748
|
-
|
|
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.
|
|
749
255
|
|
|
750
|
-
|
|
751
|
-
cve-lite . --fail-on high
|
|
752
|
-
```
|
|
256
|
+
## Troubleshooting
|
|
753
257
|
|
|
754
|
-
|
|
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.
|
|
755
259
|
|
|
756
|
-
|
|
260
|
+
## Parser coverage
|
|
757
261
|
|
|
758
|
-
|
|
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.
|
|
759
263
|
|
|
760
|
-
|
|
761
|
-
cve-lite . --verbose --fail-on high
|
|
762
|
-
```
|
|
264
|
+
## Contributing
|
|
763
265
|
|
|
764
|
-
|
|
266
|
+
Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
|
|
765
267
|
|
|
766
|
-
|
|
767
|
-
cve-lite advisories sync --output ./.cache/advisories.db
|
|
768
|
-
cve-lite . --offline-db ./.cache/advisories.db --verbose --fail-on high
|
|
769
|
-
```
|
|
268
|
+
See [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
|
|
770
269
|
|
|
771
|
-
|
|
270
|
+
## Add a badge to your project
|
|
772
271
|
|
|
773
|
-
If you use
|
|
272
|
+
If you use CVE Lite CLI in your project, add this badge to your README:
|
|
774
273
|
|
|
775
|
-
```
|
|
776
|
-
|
|
274
|
+
```markdown
|
|
275
|
+
[](https://github.com/sonukapoor/cve-lite-cli)
|
|
777
276
|
```
|
|
778
277
|
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
## Comparison with other tools
|
|
782
|
-
|
|
783
|
-
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.
|
|
784
|
-
|
|
785
|
-
### Where CVE Lite CLI stands out
|
|
786
|
-
|
|
787
|
-
Compared with other tools in this space, CVE Lite CLI focuses on:
|
|
788
|
-
|
|
789
|
-
- **free to use**
|
|
790
|
-
- **fast to run**
|
|
791
|
-
- **easy to understand**
|
|
792
|
-
- **practical dependency remediation guidance** instead of just raw advisory dumps
|
|
793
|
-
- **clear direct vs transitive visibility**
|
|
794
|
-
- **top priority fixes** and a suggested fix plan
|
|
795
|
-
- support for **npm**, **pnpm**, and **Yarn** lockfiles
|
|
796
|
-
- **SARIF** and **JSON** output for CI and automation
|
|
797
|
-
- a **lightweight**, **security-conscious** dependency footprint
|
|
798
|
-
- **offline local advisory DB support** for controlled environments
|
|
799
|
-
- a **developer-friendly** option for teams that want useful **CVE scanning without paying for a larger commercial product**
|
|
800
|
-
|
|
801
|
-
### At a glance
|
|
802
|
-
|
|
803
|
-
| Tool | Best at | Ecosystem scope | Lockfile support | Dependency remediation guidance | JSON/SARIF | Best fit |
|
|
804
|
-
|---|---|---|---|---|---|---|
|
|
805
|
-
| **CVE Lite CLI** | Fast, developer-friendly pre-release CVE scanning | Focused on JS/TS | npm, pnpm, Yarn | **Dependency fix guidance** | **Yes** | Developers and small teams who want a free, practical release-time check |
|
|
806
|
-
| `npm audit` | Built-in npm auditing | npm-centric | npm | Basic remediation info | Limited compared to dedicated scanner workflows | Teams already living fully inside npm |
|
|
807
|
-
| OSV-Scanner | Broad multi-ecosystem scanning | Broad | Many ecosystems and lockfiles | More general-purpose | Strong machine-readable workflows | Teams needing wider ecosystem coverage |
|
|
808
|
-
| Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Strong | Teams adopting a larger security platform |
|
|
809
|
-
| 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 |
|
|
810
|
-
|
|
811
|
-
### Offline support at a glance
|
|
812
|
-
|
|
813
|
-
| Tool | Local advisory DB workflow | Zero runtime advisory API calls |
|
|
814
|
-
|---|---|---|
|
|
815
|
-
| **CVE Lite CLI** | **Yes** | **Yes** |
|
|
816
|
-
| `npm audit` | No built-in local advisory DB workflow | No |
|
|
817
|
-
| OSV-Scanner | Depends on broader workflow setup rather than the local DB pattern emphasized here | Varies by setup |
|
|
818
|
-
| Snyk CLI | Not the primary workflow emphasis | Varies by product/workflow |
|
|
819
|
-
| Socket CLI | Not the primary workflow emphasis | Varies by product/workflow |
|
|
820
|
-
|
|
821
|
-
### CVE Lite CLI vs npm audit
|
|
822
|
-
|
|
823
|
-
`npm audit` is the built-in default for npm users, which makes it convenient when your workflow is entirely npm-based.
|
|
824
|
-
|
|
825
|
-
CVE Lite CLI stands out when you want:
|
|
826
|
-
|
|
827
|
-
- support across npm, pnpm, and Yarn lockfiles
|
|
828
|
-
- cleaner, more guided console output
|
|
829
|
-
- priority fixes and a suggested remediation plan
|
|
830
|
-
- a more focused pre-release scanning experience for JS/TS teams
|
|
831
|
-
|
|
832
|
-
### CVE Lite CLI vs OSV-Scanner
|
|
833
|
-
|
|
834
|
-
OSV-Scanner supports many ecosystems and lockfile types, which makes it broader overall.
|
|
835
|
-
|
|
836
|
-
CVE Lite CLI stands out when you want:
|
|
837
|
-
|
|
838
|
-
- a narrower, easier-to-understand tool built specifically around JS/TS dependency workflows
|
|
839
|
-
- remediation-first output instead of a more general multi-ecosystem scanner experience
|
|
840
|
-
- a more approachable local workflow for everyday developers
|
|
841
|
-
- a more explicit local advisory DB workflow for offline or restricted environments
|
|
842
|
-
|
|
843
|
-
### CVE Lite CLI vs Snyk CLI
|
|
844
|
-
|
|
845
|
-
Snyk CLI is part of a much broader commercial platform with wider enterprise coverage.
|
|
846
|
-
|
|
847
|
-
CVE Lite CLI stands out when you want:
|
|
848
|
-
|
|
849
|
-
- a simpler and lighter dependency CVE workflow
|
|
850
|
-
- an affordable option for small teams, startups, consultants, and independent developers
|
|
851
|
-
- a focused tool for lockfile-based release checks without adopting a larger platform
|
|
852
|
-
- a more explicit offline scanning model with local advisory DB control
|
|
853
|
-
|
|
854
|
-
### CVE Lite CLI vs Socket CLI
|
|
855
|
-
|
|
856
|
-
Socket CLI goes beyond CVEs into broader package and supply-chain risk signals.
|
|
857
|
-
|
|
858
|
-
CVE Lite CLI stands out when you want:
|
|
859
|
-
|
|
860
|
-
- a focused dependency vulnerability scanner
|
|
861
|
-
- a straightforward answer to βwhat should I fix before release?β
|
|
862
|
-
- readable output centered on known vulnerability findings and practical next steps
|
|
863
|
-
|
|
864
|
-
### Best fit
|
|
865
|
-
|
|
866
|
-
CVE Lite CLI is best for:
|
|
867
|
-
|
|
868
|
-
- developers shipping JavaScript or TypeScript applications
|
|
869
|
-
- teams that want a lightweight release gate
|
|
870
|
-
- maintainers who want actionable vulnerability output without heavy platform overhead
|
|
871
|
-
- users who care about simplicity, readability, and fast adoption
|
|
872
|
-
|
|
873
|
-
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.
|
|
874
|
-
|
|
875
|
-
## Current limitations
|
|
876
|
-
|
|
877
|
-
To keep the project honest, here is what it does **not** do in the current version:
|
|
878
|
-
|
|
879
|
-
- it does not detect malicious packages before they are represented in advisory data
|
|
880
|
-
- it does not perform behavioral malware detection or package content analysis
|
|
881
|
-
- it does not prove exploitability
|
|
882
|
-
- it does not verify runtime reachability
|
|
883
|
-
- it does not scan container images, binaries, secrets, or IaC
|
|
884
|
-
- it does not replace a full application security program
|
|
885
|
-
- it is currently focused on JS/TS dependency scanning
|
|
886
|
-
- local advisory sync performance will need continued optimization as the advisory dataset grows
|
|
887
|
-
|
|
888
|
-
## Positioning
|
|
889
|
-
|
|
890
|
-
CVE Lite CLI is best described as:
|
|
891
|
-
|
|
892
|
-
**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.**
|
|
893
|
-
|
|
894
|
-
## Roadmap
|
|
895
|
-
|
|
896
|
-
CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remediation engine.
|
|
897
|
-
|
|
898
|
-
### Phase 1: Advanced Remediation Intelligence (Short-Term)
|
|
899
|
-
* **Executable Fix-Plan:** Move from suggesting a plan to generating executable commands (e.g., `npm install package@version`) to resolve direct vulnerabilities.
|
|
900
|
-
* **Transitive Parent Mapping:** Enhance output to explicitly map the dependency path from the root to the vulnerable nested package, making manual triage effortless.
|
|
901
|
-
* **Deduplication Analysis:** Identify instances where multiple versions of the same vulnerable package exist and suggest a single version for consolidation.
|
|
902
|
-
|
|
903
|
-
### Phase 2: Ecosystem & Integration (Mid-Term)
|
|
904
|
-
* **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
|
|
905
|
-
* **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
|
|
906
|
-
* **Workflow Integration Guidance:** Expand official workflow patterns for local scripts, hooks, CI, and offline developer adoption.
|
|
907
|
-
|
|
908
|
-
### Phase 3: Maturity & Compliance (Long-Term)
|
|
909
|
-
* **Standardized SBOM Support:** Add the ability to export findings as an **SBOM (Software Bill of Materials)** in CycloneDX or SPDX formats.
|
|
910
|
-
* **Community Plugin System:** Decouple the scanner logic to allow community-contributed data sources and custom security rules.
|
|
911
|
-
|
|
912
|
-
## Contributing
|
|
913
|
-
|
|
914
|
-
This project is being shaped around real-world developer usability. Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
|
|
915
|
-
|
|
916
|
-
To get started, see [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md).
|
|
278
|
+
[](https://github.com/sonukapoor/cve-lite-cli)
|
|
917
279
|
|
|
918
280
|
## Community and support
|
|
919
281
|
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
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.
|
|
923
|
-
|
|
924
|
-
Helpful feedback includes:
|
|
282
|
+
For bug reports and feature requests: [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues)
|
|
925
283
|
|
|
926
|
-
|
|
927
|
-
- real-world lockfile edge cases
|
|
928
|
-
- ideas for clearer output and remediation guidance
|
|
929
|
-
- CI usage examples
|
|
930
|
-
- JSON and SARIF workflow feedback
|
|
931
|
-
- 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.
|
|
932
285
|
|
|
933
|
-
|
|
286
|
+
For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
|
|
934
287
|
|
|
935
|
-
|
|
288
|
+
If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/sonukapoor/cve-lite-cli) helps more developers find it.
|
|
936
289
|
|
|
937
290
|
## License
|
|
938
291
|
|