cve-lite-cli 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,23 @@
1
- # CVE Lite CLI
1
+ <div align="center">
2
+ <img src="./assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
2
3
 
3
- Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.
4
+ <h1>CVE Lite CLI</h1>
5
+ <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.</p>
6
+
7
+ <strong>Scan. Prioritize. Fix.</strong>
8
+
9
+ <p>
10
+ <a href="#quick-start">Quick Start</a> •
11
+ <a href="#features">Features</a> •
12
+ <a href="#usage">Usage</a> •
13
+ <a href="CONTRIBUTING.md">Contributing</a>
14
+ </p>
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## What is CVE Lite CLI
4
21
 
5
22
  **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.
6
23
 
@@ -24,7 +41,7 @@ Or run it one-off with `npx`:
24
41
  npx cve-lite-cli /path/to/project
25
42
  ```
26
43
 
27
- Common examples:
44
+ ## Usage
28
45
 
29
46
  ```bash
30
47
  # Basic scan
@@ -36,6 +53,10 @@ cve-lite /path/to/project --all
36
53
  # Focus only on urgent findings
37
54
  cve-lite /path/to/project --min-severity high
38
55
 
56
+ # Show full detailed output, fix plan, paths, and full table
57
+ # Recommended for CI logs when you want full context
58
+ cve-lite /path/to/project --verbose
59
+
39
60
  # Fail a build on high severity and above
40
61
  cve-lite /path/to/project --fail-on high
41
62
 
@@ -48,15 +69,45 @@ cve-lite /path/to/project --sarif --output reports/scan.sarif
48
69
 
49
70
  ## What it looks like
50
71
 
51
- Below is a real example of the console experience. In a terminal, the severity labels, summaries, and section headers are colorized for readability.
72
+ CVE Lite CLI produces a clean, summary-first console view by default, designed for fast triage before release.
52
73
 
53
- ![Image 1](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/image-1.png)
54
- ![Image 2](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/image-2.png)
74
+ For deeper investigation, running with `--verbose` provides full details, including dependency paths, a complete fix plan, and a detailed table view.
55
75
 
56
76
  That is the core idea: install it, point it at your project, and immediately get a practical fix plan instead of a wall of raw advisories.
57
77
 
58
78
  The final status line also gives the scan a clear ending, which makes terminal use and screenshots easier to read.
59
79
 
80
+ See the example below using OWASP Juice Shop for real output samples.
81
+
82
+ ## Example: Scanning OWASP Juice Shop (Real Output)
83
+
84
+ CVE Lite CLI can be used against real-world vulnerable applications such as the OWASP Juice Shop.
85
+
86
+ OWASP [Juice Shop](https://github.com/juice-shop/juice-shop) is a deliberately insecure JavaScript application widely used for security training and testing. Running CVE Lite CLI against it provides a realistic example of how the tool behaves on a dependency tree with known vulnerabilities.
87
+
88
+ To try this yourself:
89
+
90
+ Example:
91
+
92
+ ```bash
93
+ git clone https://github.com/juice-shop/juice-shop.git
94
+ cd juice-shop
95
+ cve-lite .
96
+ ```
97
+
98
+ <p align="center">
99
+ <img src="./assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
100
+ </p>
101
+
102
+ Verbose examples:
103
+
104
+ <p align="center">
105
+ <img src="./assets/verbose-output-1.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
106
+ <img src="./assets/verbose-output-2.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
107
+ <img src="./assets/verbose-output-3.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
108
+ <img src="./assets/verbose-output-4.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
109
+ </p>
110
+
60
111
  ## Why this tool exists
61
112
 
62
113
  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:
@@ -105,16 +156,19 @@ This section is here to make the scope clear. CVE Lite CLI aims to complement th
105
156
 
106
157
  ## How it works
107
158
 
108
- CVE Lite CLI follows a simple workflow:
159
+ ### Architectural Philosophy
160
+ 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.
109
161
 
110
- 1. Read a supported lockfile from your project.
111
- 2. Resolve package names and versions locally.
112
- 3. Match those packages against OSV advisory data.
113
- 4. Classify findings as direct or transitive where possible.
114
- 5. Highlight the most important fixes first.
115
- 6. Produce terminal, JSON, or SARIF output.
162
+ <p align="center">
163
+ <img src="./assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
164
+ </p>
116
165
 
117
- The goal is to keep vulnerability scanning practical, understandable, and easy to act on.
166
+ ### Workflow Specifications
167
+ * **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.
168
+ * **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.
169
+ * **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.
170
+ * **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.
171
+ * **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.
118
172
 
119
173
  ## What makes it stand out
120
174
 
@@ -139,7 +193,7 @@ The goal is to keep vulnerability scanning practical, understandable, and easy t
139
193
  - **release-focused**
140
194
  It is especially useful before a release, in CI, or during final dependency cleanup.
141
195
 
142
- ## Core features
196
+ ## Features
143
197
 
144
198
  ### 1. Lockfile-based scanning
145
199
 
@@ -162,6 +216,8 @@ Instead of only showing advisory IDs, the CLI reports:
162
216
  - advisory IDs
163
217
  - dependency path hints
164
218
 
219
+ By default, the CLI now presents a cleaner summary-first view, with `--verbose` available for the full detailed output.
220
+
165
221
  ### 3. Top priority fixes
166
222
 
167
223
  The CLI highlights the most important issues first, so developers can focus on the findings most likely to matter immediately.
@@ -245,16 +301,18 @@ Run it before a release, during dependency cleanup, or after a major package upg
245
301
 
246
302
  This repository also uses CVE Lite CLI in its own GitHub Actions workflow to scan itself as part of CI. See [`self-scan.yml`](./.github/workflows/self-scan.yml).
247
303
 
304
+ For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, and detailed table output when a scan fails.
305
+
248
306
  Use it as a release gate in CI:
249
307
 
250
308
  ```bash
251
- cve-lite . --fail-on high
309
+ cve-lite . --verbose --fail-on high
252
310
  ```
253
311
 
254
312
  Export SARIF in CI:
255
313
 
256
314
  ```bash
257
- cve-lite . --sarif --output reports/scan.sarif
315
+ cve-lite . --verbose --sarif --output reports/scan.sarif
258
316
  ```
259
317
 
260
318
  ### Scripted automation
@@ -346,20 +404,6 @@ CVE Lite CLI is best for:
346
404
 
347
405
  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.
348
406
 
349
- ## Philosophy
350
-
351
- CVE Lite CLI is not trying to be everything.
352
-
353
- It is trying to be **one of the easiest and most useful tools for developers who need a practical CVE scan right now**.
354
-
355
- That means:
356
-
357
- - fast setup
358
- - understandable output
359
- - useful remediation guidance
360
- - low friction
361
- - realistic adoption for developers without enterprise budgets
362
-
363
407
  ## Current limitations
364
408
 
365
409
  To keep the project honest, here is what it does **not** do in the current version:
@@ -376,17 +420,23 @@ CVE Lite CLI is best described as:
376
420
 
377
421
  **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.**
378
422
 
379
- ## Roadmap ideas
423
+ ## Roadmap
424
+
425
+ CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remediation engine.
426
+
427
+ ### Phase 1: Advanced Remediation Intelligence (Short-Term)
428
+ * **Executable Fix-Plan:** Move from suggesting a plan to generating executable commands (e.g., `npm install package@version`) to resolve direct vulnerabilities.
429
+ * **Transitive Parent Mapping:** Enhance output to explicitly map the dependency path from the root to the vulnerable nested package, making manual triage effortless.
430
+ * **Deduplication Analysis:** Identify instances where multiple versions of the same vulnerable package exist and suggest a single version for consolidation.
380
431
 
381
- Planned or possible future improvements include:
432
+ ### Phase 2: Ecosystem & Integration (Mid-Term)
433
+ * **Official GitHub Action:** Create a dedicated Action for one-line setup in CI/CD pipelines.
434
+ * **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
435
+ * **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
382
436
 
383
- - richer remediation guidance
384
- - stronger CI examples
385
- - broader export improvements
386
- - improved caching options
387
- - better package grouping and deduplication insights
388
- - publishable npm release polish
389
- - GitHub Action or container workflow support
437
+ ### Phase 3: Maturity & Compliance (Long-Term)
438
+ * **Standardized SBOM Support:** Add the ability to export findings as an **SBOM (Software Bill of Materials)** in CycloneDX or SPDX formats.
439
+ * **Community Plugin System:** Decouple the scanner logic to allow community-contributed data sources and custom security rules.
390
440
 
391
441
  ## Contributing
392
442
 
package/dist/banner.js ADDED
@@ -0,0 +1,10 @@
1
+ import { chalk } from "./chalk";
2
+ export const CLI_BANNER = [
3
+ `${chalk.green(">_")} ${chalk.bold.whiteBright("CVE Lite CLI")}`,
4
+ chalk.gray("────────────────────────────────"),
5
+ `${chalk.green("✔")} Scan dependencies`,
6
+ `${chalk.green("✔")} Highlight critical issues`,
7
+ `${chalk.green("✔")} Show a clear fix plan`,
8
+ "",
9
+ chalk.gray("Fast. Local. Developer-first.")
10
+ ].join("\n");
package/dist/chalk.js ADDED
@@ -0,0 +1,44 @@
1
+ import process from "node:process";
2
+ const ansi = {
3
+ reset: "\x1b[0m",
4
+ bold: "\x1b[1m",
5
+ red: "\x1b[31m",
6
+ redBright: "\x1b[91m",
7
+ green: "\x1b[32m",
8
+ greenBright: "\x1b[92m",
9
+ yellow: "\x1b[33m",
10
+ blue: "\x1b[34m",
11
+ blueBright: "\x1b[94m",
12
+ magenta: "\x1b[35m",
13
+ cyan: "\x1b[36m",
14
+ white: "\x1b[37m",
15
+ whiteBright: "\x1b[97m",
16
+ gray: "\x1b[90m"
17
+ };
18
+ const colorEnabled = Boolean(process.stdout.isTTY) && process.env.NO_COLOR !== "1";
19
+ function paint(code, text) {
20
+ if (!colorEnabled)
21
+ return text;
22
+ return `${code}${text}${ansi.reset}`;
23
+ }
24
+ export const chalk = {
25
+ bold: Object.assign((text) => paint(ansi.bold, text), {
26
+ cyan: (text) => paint(ansi.bold + ansi.cyan, text),
27
+ green: (text) => paint(ansi.bold + ansi.green, text),
28
+ magenta: (text) => paint(ansi.bold + ansi.magenta, text),
29
+ blue: (text) => paint(ansi.bold + ansi.blue, text),
30
+ yellow: (text) => paint(ansi.bold + ansi.yellow, text)
31
+ }),
32
+ cyan: (text) => paint(ansi.cyan, text),
33
+ green: (text) => paint(ansi.green, text),
34
+ greenBright: (text) => paint(ansi.greenBright, text),
35
+ red: (text) => paint(ansi.red, text),
36
+ redBright: (text) => paint(ansi.redBright, text),
37
+ yellow: (text) => paint(ansi.yellow, text),
38
+ blue: (text) => paint(ansi.blue, text),
39
+ blueBright: (text) => paint(ansi.blueBright, text),
40
+ magenta: (text) => paint(ansi.magenta, text),
41
+ gray: (text) => paint(ansi.gray, text),
42
+ white: (text) => paint(ansi.white, text),
43
+ whiteBright: (text) => paint(ansi.whiteBright, text)
44
+ };
@@ -0,0 +1,84 @@
1
+ export function parseArgs(argv) {
2
+ const options = {
3
+ failOn: "critical",
4
+ batchSize: "100",
5
+ searchDepth: "4",
6
+ minSeverity: "medium"
7
+ };
8
+ let projectArg;
9
+ for (let i = 0; i < argv.length; i++) {
10
+ const arg = argv[i];
11
+ if (arg === "-h" || arg === "--help") {
12
+ options.help = true;
13
+ continue;
14
+ }
15
+ if (arg === "--json") {
16
+ options.json = true;
17
+ continue;
18
+ }
19
+ if (arg === "--verbose") {
20
+ options.verbose = true;
21
+ continue;
22
+ }
23
+ if (arg === "--prod-only") {
24
+ options.prodOnly = true;
25
+ continue;
26
+ }
27
+ if (arg === "--offline") {
28
+ options.offline = true;
29
+ continue;
30
+ }
31
+ if (arg === "--all") {
32
+ options.all = true;
33
+ continue;
34
+ }
35
+ if (arg === "--fail-on") {
36
+ options.failOn = argv[++i] ?? options.failOn;
37
+ continue;
38
+ }
39
+ if (arg.startsWith("--fail-on=")) {
40
+ options.failOn = arg.slice("--fail-on=".length);
41
+ continue;
42
+ }
43
+ if (arg === "--batch-size") {
44
+ options.batchSize = argv[++i] ?? options.batchSize;
45
+ continue;
46
+ }
47
+ if (arg.startsWith("--batch-size=")) {
48
+ options.batchSize = arg.slice("--batch-size=".length);
49
+ continue;
50
+ }
51
+ if (arg === "--cache-dir") {
52
+ options.cacheDir = argv[++i];
53
+ continue;
54
+ }
55
+ if (arg.startsWith("--cache-dir=")) {
56
+ options.cacheDir = arg.slice("--cache-dir=".length);
57
+ continue;
58
+ }
59
+ if (arg === "--search-depth") {
60
+ options.searchDepth = argv[++i] ?? options.searchDepth;
61
+ continue;
62
+ }
63
+ if (arg.startsWith("--search-depth=")) {
64
+ options.searchDepth = arg.slice("--search-depth=".length);
65
+ continue;
66
+ }
67
+ if (arg === "--min-severity") {
68
+ options.minSeverity = argv[++i] ?? options.minSeverity;
69
+ continue;
70
+ }
71
+ if (arg.startsWith("--min-severity=")) {
72
+ options.minSeverity = arg.slice("--min-severity=".length);
73
+ continue;
74
+ }
75
+ if (arg.startsWith("-"))
76
+ throw new Error(`Unknown option: ${arg}`);
77
+ if (!projectArg) {
78
+ projectArg = arg;
79
+ continue;
80
+ }
81
+ throw new Error(`Unexpected argument: ${arg}`);
82
+ }
83
+ return { options, projectArg };
84
+ }
@@ -0,0 +1,41 @@
1
+ import { chalk } from "../utils/chalk.js";
2
+ const CLI_BANNER = [
3
+ `${chalk.green(">_")} ${chalk.bold.whiteBright("CVE Lite CLI")}`,
4
+ chalk.gray("────────────────────────────────"),
5
+ `${chalk.green("✔")} Scan dependencies`,
6
+ `${chalk.green("✔")} Highlight critical issues`,
7
+ `${chalk.green("✔")} Show a clear fix plan`,
8
+ "",
9
+ chalk.gray("Fast. Local. Developer-first.")
10
+ ].join("\n");
11
+ export function printBanner(options) {
12
+ if (options?.json)
13
+ return;
14
+ console.log(CLI_BANNER);
15
+ console.log("");
16
+ }
17
+ export function printHelp() {
18
+ printBanner();
19
+ const lines = [
20
+ "cve-lite",
21
+ "",
22
+ "Fast local-first CVE scanner for JS/TS projects using lockfiles + OSV",
23
+ "",
24
+ "Usage:",
25
+ " cve-lite [projectPath] [options]",
26
+ "",
27
+ "Options:",
28
+ " --json Print JSON output",
29
+ " --verbose Show detailed output with fix plan, paths, and full table",
30
+ " --prod-only Exclude dev dependencies where available",
31
+ " --fail-on <severity> Exit non-zero at or above severity (default: critical)",
32
+ " --batch-size <number> OSV batch size (default: 100)",
33
+ " --offline Use cached vulnerability details only",
34
+ " --cache-dir <path> Override cache directory",
35
+ " --search-depth <number> Recursive search depth (default: 4)",
36
+ " --all Show all findings in the main table",
37
+ " --min-severity <level> Minimum severity shown in table (default: medium)",
38
+ " -h, --help Show this help message"
39
+ ];
40
+ console.log(lines.join("\n"));
41
+ }
@@ -0,0 +1,19 @@
1
+ export const severityOrder = {
2
+ none: 0,
3
+ low: 1,
4
+ medium: 2,
5
+ high: 3,
6
+ critical: 4,
7
+ unknown: 1
8
+ };
9
+ export const EXCLUDED_DIRS = new Set([
10
+ ".git",
11
+ "node_modules",
12
+ "dist",
13
+ "build",
14
+ "coverage",
15
+ ".next",
16
+ ".turbo",
17
+ ".angular",
18
+ ".nx"
19
+ ]);