cve-lite-cli 1.5.2 → 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 +145 -826
- package/dist/index.js +8 -1
- package/dist/osv/severity.js +6 -0
- package/dist/utils/network.js +33 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,166 +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="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
|
-
|
|
117
|
-
|
|
118
|
-
-
|
|
43
|
+
```bash
|
|
44
|
+
npm install -g cve-lite-cli
|
|
45
|
+
cve-lite /path/to/project
|
|
46
|
+
```
|
|
119
47
|
|
|
120
|
-
|
|
48
|
+
Or one-off with `npx`:
|
|
121
49
|
|
|
122
50
|
```bash
|
|
123
|
-
|
|
124
|
-
|
|
51
|
+
npx cve-lite-cli /path/to/project
|
|
52
|
+
```
|
|
125
53
|
|
|
126
|
-
|
|
127
|
-
cve-lite /path/to/project --offline
|
|
54
|
+
## What is CVE Lite CLI
|
|
128
55
|
|
|
129
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
+
**Key differentiators:**
|
|
136
61
|
|
|
137
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
82
|
+
<sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
|
|
147
83
|
|
|
148
|
-
|
|
84
|
+
For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
|
|
85
|
+
|
|
86
|
+
## What it looks like
|
|
149
87
|
|
|
150
|
-
|
|
88
|
+
Default output on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop):
|
|
151
89
|
|
|
152
90
|
```bash
|
|
153
|
-
|
|
91
|
+
git clone https://github.com/juice-shop/juice-shop.git
|
|
92
|
+
cd juice-shop
|
|
93
|
+
cve-lite .
|
|
154
94
|
```
|
|
155
95
|
|
|
156
|
-
|
|
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
|
-
|
|
159
|
-
cve-lite /path/to/project
|
|
160
|
-
```
|
|
102
|
+
Verbose output — includes the `Copy And Run These Fix Commands` section:
|
|
161
103
|
|
|
162
|
-
|
|
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
|
-
|
|
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
|
|
122
|
+
# Focus on urgent findings only
|
|
178
123
|
cve-lite /path/to/project --min-severity high
|
|
179
124
|
|
|
180
|
-
#
|
|
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
|
-
#
|
|
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
|
-
#
|
|
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`
|
|
158
|
+
`--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.
|
|
215
159
|
|
|
216
|
-
In
|
|
160
|
+
In the current version it:
|
|
217
161
|
- applies only direct dependency fixes with a validated lowest known non-vulnerable target
|
|
218
|
-
- uses
|
|
162
|
+
- uses `npm install`, `pnpm add`, or `yarn add` based on your lockfile
|
|
219
163
|
- rescans automatically after applying fixes
|
|
220
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
172
|
+
## Offline support
|
|
240
173
|
|
|
241
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
215
|
+
## Real-world case studies
|
|
462
216
|
|
|
463
|
-
|
|
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
|
-
-
|
|
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
|
-
##
|
|
222
|
+
## Who uses it
|
|
640
223
|
|
|
641
224
|
CVE Lite CLI is a good fit for:
|
|
642
225
|
|
|
643
|
-
-
|
|
644
|
-
-
|
|
645
|
-
-
|
|
646
|
-
- teams
|
|
647
|
-
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
244
|
+
## Dependency footprint
|
|
765
245
|
|
|
766
|
-
|
|
767
|
-
{
|
|
768
|
-
"scripts": {
|
|
769
|
-
"postinstall": "cve-lite . --offline || true"
|
|
770
|
-
}
|
|
771
|
-
}
|
|
772
|
-
```
|
|
246
|
+
**Runtime:** `yaml` · `yarn-lockfile` · `better-sqlite3` · `fflate`
|
|
773
247
|
|
|
774
|
-
|
|
248
|
+
**Dev only:** `@types/node` · `tsx` · `typescript`
|
|
775
249
|
|
|
776
|
-
|
|
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
|
-
|
|
252
|
+
## Roadmap
|
|
781
253
|
|
|
782
|
-
|
|
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
|
-
|
|
785
|
-
cve-lite . --fail-on high
|
|
786
|
-
```
|
|
256
|
+
## Troubleshooting
|
|
787
257
|
|
|
788
|
-
|
|
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
|
-
|
|
260
|
+
## Parser coverage
|
|
791
261
|
|
|
792
|
-
|
|
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
|
-
|
|
795
|
-
cve-lite . --verbose --fail-on high
|
|
796
|
-
```
|
|
264
|
+
## Contributing
|
|
797
265
|
|
|
798
|
-
|
|
266
|
+
Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
|
|
799
267
|
|
|
800
|
-
|
|
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
|
-
|
|
270
|
+
## Add a badge to your project
|
|
806
271
|
|
|
807
|
-
If you use
|
|
272
|
+
If you use CVE Lite CLI in your project, add this badge to your README:
|
|
808
273
|
|
|
809
|
-
```
|
|
810
|
-
|
|
274
|
+
```markdown
|
|
275
|
+
[](https://github.com/sonukapoor/cve-lite-cli)
|
|
811
276
|
```
|
|
812
277
|
|
|
813
|
-
|
|
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
|
+
[](https://github.com/sonukapoor/cve-lite-cli)
|
|
951
279
|
|
|
952
280
|
## Community and support
|
|
953
281
|
|
|
954
|
-
|
|
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
|
-
|
|
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
|
-
|
|
286
|
+
For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
|
|
968
287
|
|
|
969
|
-
|
|
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
|
-
|
|
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
|
}
|
package/dist/osv/severity.js
CHANGED
|
@@ -25,6 +25,12 @@ export function inferSeverity(vuln) {
|
|
|
25
25
|
return "unknown";
|
|
26
26
|
}
|
|
27
27
|
function severityFromScore(score) {
|
|
28
|
+
// CVSS vector strings (e.g. "CVSS:3.1/AV:N/...") are not numerical scores.
|
|
29
|
+
// Extracting the first number would yield the CVSS version (3.1), not the base
|
|
30
|
+
// score — causing every CVSS_V3 advisory to be misclassified as "low".
|
|
31
|
+
// Return unknown so the caller falls through to database_specific.severity.
|
|
32
|
+
if (String(score).startsWith("CVSS:"))
|
|
33
|
+
return "unknown";
|
|
28
34
|
const match = String(score).match(/([0-9]+(?:\.[0-9]+)?)/);
|
|
29
35
|
if (!match)
|
|
30
36
|
return "unknown";
|
|
@@ -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
|
+
}
|