cve-lite-cli 1.8.0 โ†’ 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,16 +1,22 @@
1
1
 
2
+ [![OWASP Incubator Project](https://img.shields.io/badge/OWASP-Incubator%20Project-48A646?logo=owasp)](https://owasp.org/cve-lite-cli)
2
3
  [![npm version](https://img.shields.io/npm/v/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
3
4
  [![npm downloads](https://img.shields.io/npm/dm/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
4
- [![CI](https://img.shields.io/github/actions/workflow/status/sonukapoor/cve-lite-cli/ci.yml?branch=main)](https://github.com/sonukapoor/cve-lite-cli/actions)
5
+ [![CI](https://img.shields.io/github/actions/workflow/status/OWASP/cve-lite-cli/ci.yml?branch=main)](https://github.com/OWASP/cve-lite-cli/actions)
5
6
  [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-CVE%20Lite%20CLI-blue)](https://github.com/marketplace/actions/cve-lite-cli)
6
- [![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
7
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
7
+ [![License](https://img.shields.io/github/license/OWASP/cve-lite-cli)](https://github.com/OWASP/cve-lite-cli/blob/main/LICENSE)
8
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
8
9
 
9
10
  <div align="center">
10
- <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
11
+ <a href="https://owasp.org/cve-lite-cli">
12
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/logos-combined.svg" alt="CVE Lite CLI โ€” An OWASP Foundation Project" width="500"/>
13
+ </a>
11
14
 
12
15
  <h1>CVE Lite CLI</h1>
13
- <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Clear direct vs transitive visibility.</p>
16
+
17
+ **๐Ÿ† Officially recognized as an [OWASP Incubator Project](https://owasp.org/cve-lite-cli)**
18
+
19
+ <p>Vulnerability scanning that belongs in your terminal โ€” not your CI pipeline.<br/>Scan your lockfile, get copy-and-run fix commands, and ship clean code.</p>
14
20
 
15
21
  <strong>Scan. Understand. Fix.</strong>
16
22
 
@@ -30,14 +36,33 @@
30
36
  <a href="#quick-start">Quick Start</a> โ€ข
31
37
  <a href="#usage">Usage</a> โ€ข
32
38
  <a href="#what-it-looks-like">Screenshots</a> โ€ข
39
+ <a href="docs/html-report.md">HTML Report</a> โ€ข
33
40
  <a href="docs/comparison.md">Compare</a> โ€ข
34
41
  <a href="docs/roadmap.md">Roadmap</a> โ€ข
35
- <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
42
+ <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
36
43
  </p>
37
44
  </div>
38
45
 
39
46
  ---
40
47
 
48
+ ## The problem with how security scanning works today
49
+
50
+ Most security tooling is designed around pipelines, not people.
51
+
52
+ Dependabot files PRs you'll get to eventually. CI scanners block merges hours after the fact. Security dashboards surface a list of CVE IDs with no clear path to resolving them. By the time a developer is looking at a scan result, the code has already been reviewed and is waiting to ship.
53
+
54
+ The feedback loop is too slow to be useful, and too noisy to be trusted. Developers learn to ignore it.
55
+
56
+ There is also a more fundamental problem: these tools tell you what is vulnerable. Very few tell you what to actually do about it. The result is a gap between detection and remediation that security teams paper over with manual triage, and developers experience as alert fatigue.
57
+
58
+ ## A different model
59
+
60
+ CVE Lite CLI is built around a different idea: **vulnerability scanning belongs at the developer's terminal, not at the end of a pipeline.**
61
+
62
+ It reads your lockfile locally, queries [OSV](https://osv.dev) for advisory data, and produces a concrete remediation plan โ€” not a list of identifiers. You get copy-and-run `npm install`, `pnpm add`, `yarn add`, or `bun add` commands scoped to your package manager. You see exactly which packages are directly installed versus pulled in transitively. You can scan with no internet connection in restricted-network environments.
63
+
64
+ The tool is designed for the moment right before you push: fast, honest, and actionable.
65
+
41
66
  ## Quick start
42
67
 
43
68
  ```bash
@@ -51,19 +76,75 @@ Or one-off with `npx`:
51
76
  npx cve-lite-cli /path/to/project
52
77
  ```
53
78
 
54
- ## What is CVE Lite CLI
79
+ No account. No configuration. No source code leaves your machine.
80
+
81
+ ## What it does
82
+
83
+ - **Produces copy-and-run fix commands** โ€” every finding comes with a package-manager-aware install command you can run immediately
84
+ - **Distinguishes direct from transitive risk** โ€” shows whether the vulnerability is in something you installed or buried three levels deep in a dependency chain
85
+ - **Usage-aware reachability** โ€” optionally uses static analysis to detect whether vulnerable packages are actually imported in your code, cutting noise with `--usage` and `--only-used`
86
+ - **Offline advisory DB** โ€” sync advisory data ahead of time and scan with zero runtime API calls, designed for enterprise and air-gapped environments
87
+ - **Interactive HTML report** โ€” generate a self-contained dashboard with severity cards, a searchable findings table, and copy-ready fix commands (`--report`)
88
+ - **Auto-fix mode** โ€” apply validated direct dependency fixes and rescan automatically (`--fix`)
89
+ - **CI-ready** โ€” `--fail-on high` exits non-zero on findings at or above a severity threshold; a first-party [GitHub Action](https://github.com/marketplace/actions/cve-lite-cli) is available on the Marketplace
90
+ - **Minimal footprint** โ€” four runtime dependencies, intentionally kept small for a security tool
91
+
92
+ ## What it looks like
93
+
94
+ <table>
95
+ <tr>
96
+ <th align="center">Terminal output</th>
97
+ <th align="center">HTML dashboard (<code>--report</code>)</th>
98
+ </tr>
99
+ <tr>
100
+ <td align="center">
101
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png">
102
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI terminal output" width="440"/>
103
+ </a>
104
+ </td>
105
+ <td align="center">
106
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png">
107
+ <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png" alt="CVE Lite CLI HTML dashboard" width="440"/>
108
+ </a>
109
+ </td>
110
+ </tr>
111
+ <tr>
112
+ <td align="center"><sub>Default scan output ยท <a href="docs/how-to-read-verbose-output.md">verbose output guide</a></sub></td>
113
+ <td align="center"><sub>Generated with <code>--report</code> ยท <a href="docs/html-report.md">HTML report guide</a></sub></td>
114
+ </tr>
115
+ </table>
116
+
117
+ <details>
118
+ <summary>Verbose terminal output โ€” includes the full fix plan</summary>
119
+ <p align="center">
120
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-1.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-1.png" alt="Verbose output part 1" width="280"/></a>
121
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-2.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-2.png" alt="Verbose output part 2" width="280"/></a>
122
+ <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-3.png"><img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/verbose-output-3.png" alt="Verbose output part 3" width="280"/></a>
123
+ </p>
124
+ </details>
125
+
126
+ ## Workflow integration
127
+
128
+ CVE Lite CLI fits at every stage of the development workflow, not just CI.
129
+
130
+ **Local development** โ€” run a scan before opening a PR. The default output is fast and minimal. `--verbose` adds the full fix plan with dependency paths and prioritized remediation commands. `--report` opens an interactive HTML dashboard.
55
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
+ **CI pipelines** โ€” use `--fail-on high` to gate builds on severity. JSON output (`--json`) integrates with SIEM, dashboards, and custom automation. SARIF output is on the roadmap for direct integration with GitHub Security.
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
+ **Restricted and enterprise environments** โ€” sync the advisory database ahead of time with `cve-lite advisories sync`, then scan offline with `--offline`. No runtime outbound calls during the scan. Syncing ~217,065 advisory records completes in under 9 seconds.
59
135
 
60
- **Key differentiators:**
136
+ **GitHub Actions** โ€” a first-party action is available on the Marketplace:
61
137
 
62
- - **Copy-and-run fix commands** โ€” turns findings into package-manager-aware `npm install`, `pnpm add`, `yarn add`, or `bun 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
+ ```yaml
139
+ - uses: OWASP/cve-lite-cli@v1
140
+ with:
141
+ verbose: "true"
142
+ fail-on: high
143
+ ```
144
+
145
+ CVE Lite CLI scans its own dependencies in CI. See [`self-scan.yml`](https://github.com/OWASP/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
146
+
147
+ For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
67
148
 
68
149
  ## How it compares
69
150
 
@@ -72,7 +153,8 @@ It is built for the moment right before release: fast, local-first, and honest a
72
153
  | JS/TS lockfile scanning | โœ… | โœ… | โœ… | โœ… | โœ… |
73
154
  | npm + pnpm + Yarn + Bun support | โœ… | โŒ | โœ… | โœ… | โœ… |
74
155
  | No account required | โœ… | โœ… | โœ… | โŒ | โŒ |
75
- | **Free to use** | โœ… | โœ… | โœ… | โŒ | โŒ |
156
+ | Free to use | โœ… | โœ… | โœ… | โŒ | โŒ |
157
+ | Usage-aware reachability scanning | โœ… | โŒ | โŒ | โœ… | โš ๏ธ |
76
158
  | Direct vs transitive visibility | โœ… | โš ๏ธ | โœ… | โœ… | โœ… |
77
159
  | Copy-and-run fix commands | โœ… | โŒ | โŒ | โœ… | โš ๏ธ |
78
160
  | Suggested remediation plan | โœ… | โŒ | โš ๏ธ | โœ… | โš ๏ธ |
@@ -83,32 +165,55 @@ It is built for the moment right before release: fast, local-first, and honest a
83
165
 
84
166
  For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
85
167
 
86
- ## What it looks like
168
+ ## Real-world validation
87
169
 
88
- Default output on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop):
170
+ CVE Lite CLI has been evaluated against real open-source projects to verify that it surfaces meaningful issues โ€” including non-obvious transitive vulnerabilities and complex upgrade paths โ€” not just low-signal advisory matches.
89
171
 
90
- ```bash
91
- git clone https://github.com/juice-shop/juice-shop.git
92
- cd juice-shop
93
- cve-lite .
94
- ```
172
+ - [OWASP Juice Shop](docs/case-studies/owasp-juice-shop.md) โ€” scanning a deliberately vulnerable application with known dependency issues
173
+ - [NestJS](docs/case-studies/nestjs.md) โ€” working through a real transitive dependency remediation sequence across a widely-used Node.js framework
174
+ - [Analog](docs/case-studies/analog.md) โ€” scanning a modern pnpm v9 Angular monorepo (3,367 packages) with unexpected toolchain vulnerabilities
95
175
 
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>
176
+ These are not demos. They are documented scans against real codebases with real findings, recorded before and after applying fix commands.
101
177
 
102
- Verbose output โ€” includes the `Copy And Run These Fix Commands` section:
178
+ 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.
103
179
 
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>
180
+ ## Recognized by OWASP
181
+
182
+ CVE Lite CLI is an [OWASP Incubator Project](https://owasp.org/cve-lite-cli), peer-reviewed and maintained under the Open Web Application Security Project Foundation. Being part of OWASP means:
183
+
184
+ - **Peer-reviewed** by security professionals
185
+ - **Community-driven** development and governance
186
+ - **Vendor-neutral** with no commercial platform required
187
+ - **Open source** with transparent security practices and a minimal dependency footprint
188
+
189
+ **Where it fits in the OWASP ecosystem:**
110
190
 
111
- For a section-by-section walkthrough, see [How to read verbose output](docs/how-to-read-verbose-output.md).
191
+ CVE Lite CLI fills a specific gap โ€” fast, local-first JS/TS dependency scanning close to release time โ€” that broader OWASP tools are not optimized for:
192
+
193
+ | Tool | Focus |
194
+ |---|---|
195
+ | CVE Lite CLI | Lockfile-first, local developer CLI, remediation-focused, JS/TS |
196
+ | OWASP Dependency-Check | Multi-language, SAST-style, broader ecosystem |
197
+ | OWASP dep-scan | Multi-language and environment, SBOM and cloud-native |
198
+ | OWASP Dependency-Track | Platform and SBOM management, not a local CLI |
199
+
200
+ CVE Lite CLI complements these tools. It is not a replacement for continuous monitoring or full SBOM management โ€” it is the fast local check you run before pushing.
201
+
202
+ ## Philosophy
203
+
204
+ Security tooling has optimized heavily for breadth of detection and compliance reporting. That is useful at the platform level. It is the wrong model for the individual developer trying to ship clean code before end of day.
205
+
206
+ Detection without remediation creates work without resolution. A vulnerability report that ends with a list of CVE IDs shifts the burden entirely onto the developer: look up each advisory, figure out which version is safe, work out whether it is a direct or transitive dependency, and construct the right install command by hand. That friction is why security findings go unresolved.
207
+
208
+ CVE Lite CLI is built on the premise that **the closer a security tool is to the developer's natural workflow, the more likely it is to be used** โ€” and that a tool that surfaces a problem alongside the fix is more valuable than one that only surfaces the problem.
209
+
210
+ ## What's next
211
+
212
+ The CLI is the foundation. The model โ€” local-first, actionable, developer-native โ€” extends naturally beyond the terminal.
213
+
214
+ JSON and SARIF outputs make findings consumable by editors, dashboards, and automated workflows today. The next phase of the project is oriented around tighter developer integration: surfacing vulnerabilities at the point of dependency installation, not just at scan time; deeper IDE integration; and team-level visibility without requiring a cloud platform.
215
+
216
+ See [roadmap.md](docs/roadmap.md) for the current plan.
112
217
 
113
218
  ## Usage
114
219
 
@@ -137,6 +242,10 @@ cve-lite /path/to/project --fail-on high
137
242
  # JSON output
138
243
  cve-lite /path/to/project --json
139
244
 
245
+ # Generate an HTML vulnerability dashboard (opens in browser automatically)
246
+ cve-lite /path/to/project --report
247
+ cve-lite /path/to/project --report ./my-report --no-open
248
+
140
249
  # Scan project source files to check if vulnerable dependencies are actually imported
141
250
  cve-lite /path/to/project --usage
142
251
 
@@ -159,6 +268,10 @@ cve-lite /path/to/project --osv-url https://security.company.internal/osv
159
268
  cve-lite --version
160
269
  ```
161
270
 
271
+ ### Why is `--usage` an opt-in flag?
272
+
273
+ CVE Lite CLI is designed to be fast. Scanning a lockfile is nearly instantaneous, whereas running static reachability analysis across thousands of source files takes significantly more time. Static analysis can also produce false negatives when packages are used in build scripts or dynamically imported at runtime. Making `--usage` opt-in ensures the default lockfile scan remains instant and strictly reflects your dependency graph, while giving you the option to aggressively filter out unreachable noise when triaging findings.
274
+
162
275
  ## Auto-fix mode (`--fix`)
163
276
 
164
277
  `--fix` applies validated direct dependency fixes using your project's package manager, then rescans automatically.
@@ -175,6 +288,17 @@ npx cve-lite-cli /path/to/project --fix
175
288
 
176
289
  See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
177
290
 
291
+ ## HTML vulnerability report (`--report`)
292
+
293
+ Generate a self-contained HTML dashboard from any scan โ€” severity cards, an interactive findings table with search, copy-ready fix commands, and breaking-change indicators on upgrades โ€” all written to a local directory and opened automatically in your browser.
294
+
295
+ ```bash
296
+ cve-lite /path/to/project --report
297
+ cve-lite /path/to/project --report ./my-report --no-open
298
+ ```
299
+
300
+ See the [HTML Report guide](docs/html-report.md) for the full option reference and output details.
301
+
178
302
  ## Offline support
179
303
 
180
304
  For teams in enterprise, restricted-network, or air-gapped environments:
@@ -191,41 +315,6 @@ Syncing ~217,065 advisory records runs in under 9 seconds after bulk SQLite inge
191
315
 
192
316
  See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
193
317
 
194
- ## CI integration
195
-
196
- The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
197
-
198
- ```yaml
199
- - uses: sonukapoor/cve-lite-cli@v1
200
- with:
201
- verbose: "true"
202
- fail-on: high
203
- ```
204
-
205
- 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).
206
-
207
- For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
208
-
209
- ## Relationship to similar OWASP projects
210
-
211
- 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.
212
-
213
- The closest OWASP comparisons are:
214
-
215
- - **OWASP Dependency-Check** โ€” broader ecosystem coverage, different operational model
216
- - **OWASP dep-scan** โ€” wider language and environment coverage
217
- - **OWASP Dependency-Track** โ€” SBOM- and platform-oriented, not a local developer CLI
218
-
219
- 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.
220
-
221
- ## Real-world case studies
222
-
223
- - [OWASP Juice Shop](docs/case-studies/owasp-juice-shop.md) โ€” scanning a deliberately vulnerable application with known dependency issues
224
- - [NestJS](docs/case-studies/nestjs.md) โ€” working through a real transitive dependency remediation sequence
225
- - [Analog](docs/case-studies/analog.md) โ€” scanning a modern pnpm v9 Angular monorepo (3,367 packages) with unexpected toolchain vulnerabilities
226
-
227
- 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.
228
-
229
318
  ## Who uses it
230
319
 
231
320
  CVE Lite CLI is a good fit for:
@@ -272,27 +361,31 @@ See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats
272
361
 
273
362
  Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
274
363
 
275
- See [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
364
+ See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
276
365
 
277
366
  ## Add a badge to your project
278
367
 
279
368
  If you use CVE Lite CLI in your project, add this badge to your README:
280
369
 
281
370
  ```markdown
282
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
371
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
283
372
  ```
284
373
 
285
- [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
374
+ [![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
286
375
 
287
376
  ## Community and support
288
377
 
289
- For bug reports and feature requests: [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues)
378
+ For bug reports and feature requests: [GitHub Issues](https://github.com/OWASP/cve-lite-cli/issues)
290
379
 
291
380
  Helpful feedback includes reproducible bug reports, real-world lockfile edge cases, ideas for clearer output and remediation guidance, and CI or JSON workflow examples.
292
381
 
293
- For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
382
+ For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md)
383
+
384
+ If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/OWASP/cve-lite-cli) helps more developers find it.
385
+
386
+ ---
294
387
 
295
- If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/sonukapoor/cve-lite-cli) helps more developers find it.
388
+ *Most tools tell you what's wrong. CVE Lite CLI tells you what to run.*
296
389
 
297
390
  ## License
298
391
 
package/dist/cli/args.js CHANGED
@@ -138,6 +138,25 @@ export function parseArgs(argv) {
138
138
  options.usage = true;
139
139
  continue;
140
140
  }
141
+ if (arg === "--report") {
142
+ const next = argv[i + 1];
143
+ if (next !== undefined && !next.startsWith("-")) {
144
+ options.report = next;
145
+ i++;
146
+ }
147
+ else {
148
+ options.report = true;
149
+ }
150
+ continue;
151
+ }
152
+ if (arg.startsWith("--report=")) {
153
+ options.report = arg.slice("--report=".length);
154
+ continue;
155
+ }
156
+ if (arg === "--no-open") {
157
+ options.noOpen = true;
158
+ continue;
159
+ }
141
160
  if (arg.startsWith("-"))
142
161
  throw new Error(`Unknown option: ${arg}`);
143
162
  if (!projectArg) {
package/dist/cli/help.js CHANGED
@@ -31,6 +31,8 @@ export function printHelp() {
31
31
  "",
32
32
  "Scan options:",
33
33
  " --json Print JSON output",
34
+ " --report [dir] Generate an HTML report in [dir] (default: ./cve-report)",
35
+ " --no-open Don't auto-open the report in the browser",
34
36
  " --fix Apply validated direct dependency fixes and rescan",
35
37
  " --osv-url <url> Use a custom OSV-compatible advisory endpoint",
36
38
  " --verbose Show detailed output with fix plan, paths, and full table",
package/dist/index.js CHANGED
@@ -17,6 +17,7 @@ import { scanProjectForPackageUsage } from "./usage/scanner.js";
17
17
  import { getCliVersion } from "./utils/version-info.js";
18
18
  import { isLikelyBlockedAdvisoryRequestError } from "./utils/network.js";
19
19
  import { logInfo, logWarn, printCacheSummary, serializeFinding, sortFindingsForOutput } from "./output/formatters.js";
20
+ import { buildReportData, writeHtmlReport } from "./output/html-reporter.js";
20
21
  import { printSummary, printActionSummary, printPriorityFixes, printFixPlan, printSuggestedFixCommands, printSuggestedFixCommandSkips, printCoverage, printSkippedDependencies, printGroupSummary, printTable, printPathHints, printFinalStatus, printCompactOutput } from "./output/printers.js";
21
22
  let parsedArgs = null;
22
23
  try {
@@ -87,6 +88,9 @@ if (parsedArgs) {
87
88
  if (options.fix && options.json) {
88
89
  throw new Error("--fix cannot be used with --json");
89
90
  }
91
+ if (options.report && options.json) {
92
+ throw new Error("--report cannot be used with --json");
93
+ }
90
94
  let advisorySourceLine;
91
95
  let advisoryDbFreshnessLine = null;
92
96
  let advisoryDbWarning = null;
@@ -220,6 +224,26 @@ if (parsedArgs) {
220
224
  // Simplified output - cleaner, focused view
221
225
  printCompactOutput(scanState.sorted, scanInput);
222
226
  }
227
+ if (options.report) {
228
+ const outputDir = path.resolve(typeof options.report === "string" ? options.report : "./cve-report");
229
+ const reportData = buildReportData({
230
+ projectPath,
231
+ cliVersion,
232
+ packageManager: scanInput.source,
233
+ lockfileSource: scanInput.filePath ? path.basename(scanInput.filePath) : scanInput.source,
234
+ packageCount: packages.length,
235
+ findings: scanState.sorted,
236
+ suggestedFixCommands: scanState.suggestedFixCommands,
237
+ notes: [...scanInput.notes, ...scanState.coverage],
238
+ warnings: scanInput.warnings,
239
+ });
240
+ const { reportPath } = await writeHtmlReport({
241
+ outputDir,
242
+ data: reportData,
243
+ autoOpen: !options.noOpen,
244
+ });
245
+ console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
246
+ }
223
247
  const failLevel = normalizeSeverity(options.failOn);
224
248
  const shouldFail = scanState.sorted.some(f => severityOrder[f.severity] >= severityOrder[failLevel]);
225
249
  process.exit(shouldFail ? 1 : 0);
@@ -2,6 +2,7 @@ import { chalk } from "../utils/chalk.js";
2
2
  import { severityOrder } from "../constants.js";
3
3
  import { loadCache } from "../osv/cache.js";
4
4
  import { inferSeverity } from "../osv/severity.js";
5
+ import { getPrimaryParent } from "../utils/finding.js";
5
6
  export function formatSeverityLabel(severity) {
6
7
  const lower = severity.toLowerCase();
7
8
  if (lower === "critical")
@@ -23,12 +24,6 @@ export function formatRelationshipLabel(value) {
23
24
  return chalk.yellow(value);
24
25
  return chalk.gray(value);
25
26
  }
26
- export function getPrimaryParent(finding) {
27
- const firstPath = finding.dependencyPaths?.[0];
28
- if (!firstPath || firstPath.length < 3)
29
- return null;
30
- return firstPath[1] ?? null;
31
- }
32
27
  export function getRecommendedAction(finding) {
33
28
  if (finding.relationship === "direct" && finding.firstFixedVersion) {
34
29
  return `Upgrade ${finding.pkg.name} to ${finding.firstFixedVersion}+ in this project.`;
@@ -41,13 +36,13 @@ export function getRecommendedAction(finding) {
41
36
  }
42
37
  const parent = getPrimaryParent(finding);
43
38
  if (parent && finding.firstFixedVersion) {
44
- return `Review ${parent}; aim for a version that resolves ${finding.pkg.name} to ${finding.firstFixedVersion}+`;
39
+ return `Upgrade ${parent} โ€” no safe version was identified automatically. Check for a release that resolves ${finding.pkg.name} to ${finding.firstFixedVersion}+.`;
45
40
  }
46
41
  if (parent) {
47
42
  return `Review ${parent}; it currently pulls in vulnerable ${finding.pkg.name}.`;
48
43
  }
49
44
  if (finding.firstFixedVersion) {
50
- return `Upgrade the parent dependency chain so ${finding.pkg.name} resolves to ${finding.firstFixedVersion}+`;
45
+ return `No dependency path found for ${finding.pkg.name}. Inspect your lockfile to identify which package pulls it in.`;
51
46
  }
52
47
  return `Inspect the dependency path for ${finding.pkg.name} and choose the safest upgrade path.`;
53
48
  }
@@ -94,8 +89,12 @@ export function summarizeNextAction(finding) {
94
89
  if (finding.recommendedParentUpgrade) {
95
90
  return `Upgrade ${finding.recommendedParentUpgrade.package} ${finding.recommendedParentUpgrade.currentVersion} -> ${finding.recommendedParentUpgrade.targetVersion}.`;
96
91
  }
92
+ const parent = getPrimaryParent(finding);
93
+ if (parent && finding.firstFixedVersion) {
94
+ return `Upgrade ${parent} โ€” no safe version identified. Find a release resolving ${finding.pkg.name} to ${finding.firstFixedVersion}+.`;
95
+ }
97
96
  if (finding.firstFixedVersion) {
98
- return `Upgrade the parent dependency chain so it resolves ${finding.pkg.name} to ${finding.firstFixedVersion}+`;
97
+ return `No dependency path found for ${finding.pkg.name}. Check your lockfile for which package pulls it in.`;
99
98
  }
100
99
  return `Inspect the parent dependency chain for ${finding.pkg.name} and choose the safest available upgrade.`;
101
100
  }