cve-lite-cli 1.1.1 → 1.2.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.
Files changed (2) hide show
  1. package/README.md +171 -8
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  [![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
6
6
 
7
7
  <div align="center">
8
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
8
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
9
9
 
10
10
  <h1>CVE Lite CLI</h1>
11
11
  <p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects, with offline support for restricted environments.</p>
@@ -23,6 +23,47 @@
23
23
 
24
24
  ---
25
25
 
26
+ ## Contents
27
+
28
+ <table>
29
+ <tr>
30
+ <td valign="top">
31
+ <strong>Overview</strong><br/>
32
+ <a href="#what-is-cve-lite-cli">What is CVE Lite CLI</a><br/>
33
+ <a href="#new-offline-advisory-db-support">Offline advisory DB support</a><br/>
34
+ <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
35
+ <a href="#what-it-looks-like">What it looks like</a><br/>
36
+ <a href="#why-this-tool-exists">Why this tool exists</a><br/>
37
+ <a href="#project-scope-and-differentiation">Project scope and differentiation</a>
38
+ </td>
39
+ <td valign="top">
40
+ <strong>Usage</strong><br/>
41
+ <a href="#quick-start">Quick start</a><br/>
42
+ <a href="#usage">Usage</a><br/>
43
+ <a href="#workflow-modes">Workflow modes</a><br/>
44
+ <a href="#network-behavior-and-privacy">Network behavior and privacy</a><br/>
45
+ <a href="#features">Features</a><br/>
46
+ <a href="#supported-workflows">Supported workflows</a>
47
+ </td>
48
+ <td valign="top">
49
+ <strong>CI and Offline</strong><br/>
50
+ <a href="#dependency-footprint">Dependency footprint</a><br/>
51
+ <a href="#example-use-cases">Example use cases</a><br/>
52
+ <a href="#recommended-workflow-patterns">Recommended workflow patterns</a><br/>
53
+ <a href="#comparison-with-other-tools">Comparison with other tools</a><br/>
54
+ <a href="#current-limitations">Current limitations</a><br/>
55
+ <a href="#positioning">Positioning</a>
56
+ </td>
57
+ <td valign="top">
58
+ <strong>Project</strong><br/>
59
+ <a href="#roadmap">Roadmap</a><br/>
60
+ <a href="#contributing">Contributing</a><br/>
61
+ <a href="#community-and-support">Community and support</a><br/>
62
+ <a href="#license">License</a>
63
+ </td>
64
+ </tr>
65
+ </table>
66
+
26
67
  ## What is CVE Lite CLI
27
68
 
28
69
  **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.
@@ -185,16 +226,16 @@ cve-lite .
185
226
  ```
186
227
 
187
228
  <p align="center">
188
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
229
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output screenshot" width="900"/>
189
230
  </p>
190
231
 
191
232
  Verbose examples:
192
233
 
193
234
  <p align="center">
194
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-1.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
195
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-2.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
196
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-3.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
197
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/verbose-output-4.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
235
+ <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"/>
236
+ <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"/>
237
+ <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"/>
238
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/verbose-output-4.png" alt="CVE Lite CLI verbose output screenshot" width="900"/>
198
239
  </p>
199
240
 
200
241
  ## Why this tool exists
@@ -338,7 +379,7 @@ So the practical model is: **local lockfile scan + advisory matching**. When mal
338
379
  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.
339
380
 
340
381
  <p align="center">
341
- <img src="https://github.com/sonukapoor/cve-lite-cli/blob/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
382
+ <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/diagram.png" alt="CVE Lite CLI Workflow" width="800"/>
342
383
  </p>
343
384
 
344
385
  ### Workflow Specifications
@@ -501,6 +542,49 @@ cve-lite . --offline
501
542
 
502
543
  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).
503
544
 
545
+ Use the reusable first-party GitHub Action in another repository:
546
+
547
+ ```yaml
548
+ name: Dependency Scan
549
+
550
+ on:
551
+ pull_request:
552
+ push:
553
+ branches: [main]
554
+
555
+ jobs:
556
+ cve-lite:
557
+ runs-on: ubuntu-latest
558
+ steps:
559
+ - uses: actions/checkout@v4
560
+ - uses: sonukapoor/cve-lite-cli@v1.1.1
561
+ with:
562
+ verbose: "true"
563
+ fail-on: high
564
+ ```
565
+
566
+ For an offline GitHub Actions workflow that refreshes the advisory DB first:
567
+
568
+ ```yaml
569
+ name: Offline Dependency Scan
570
+
571
+ on:
572
+ pull_request:
573
+
574
+ jobs:
575
+ cve-lite:
576
+ runs-on: ubuntu-latest
577
+ steps:
578
+ - uses: actions/checkout@v4
579
+ - uses: sonukapoor/cve-lite-cli@v1.1.1
580
+ with:
581
+ sync-advisories: "true"
582
+ offline: "true"
583
+ offline-db: ./.cache/cve-lite/advisories.db
584
+ verbose: "true"
585
+ fail-on: high
586
+ ```
587
+
504
588
  For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, and detailed table output when a scan fails.
505
589
 
506
590
  Use it as a release gate in CI:
@@ -530,6 +614,86 @@ cve-lite advisories sync --output ./.cache/advisories.db
530
614
  cve-lite . --offline-db ./.cache/advisories.db --json > cve-lite-report.json
531
615
  ```
532
616
 
617
+ ## Recommended workflow patterns
618
+
619
+ 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.
620
+
621
+ The recommended pattern is:
622
+
623
+ 1. choose a scan command that matches your environment
624
+ 2. wire it into scripts, hooks, CI, or scheduled refresh jobs
625
+ 3. keep the behavior explicit so developers and security reviewers can see exactly when scans run and whether network access is involved
626
+
627
+ ### Package scripts
628
+
629
+ Add a simple script to the consuming project so developers have a memorable command:
630
+
631
+ ```json
632
+ {
633
+ "scripts": {
634
+ "security:scan": "cve-lite .",
635
+ "security:scan:offline": "cve-lite . --offline"
636
+ }
637
+ }
638
+ ```
639
+
640
+ This is the best default for most teams because it is visible, easy to document, and easy to reuse in local development and CI.
641
+
642
+ ### Opt-in postinstall usage
643
+
644
+ Some teams want dependency scanning to run immediately after packages are installed. CVE Lite CLI supports that workflow, but it is recommended as an explicit opt-in in the consuming project rather than hidden default behavior in the tool itself.
645
+
646
+ For example:
647
+
648
+ ```json
649
+ {
650
+ "scripts": {
651
+ "postinstall": "cve-lite . --offline || true"
652
+ }
653
+ }
654
+ ```
655
+
656
+ Why this is opt-in:
657
+
658
+ - install hooks should be visible to the team using them
659
+ - controlled environments often prefer offline scanning for install-time checks
660
+ - explicit project scripts are easier to review, tune, and disable than implicit package behavior
661
+
662
+ ### Git hooks
663
+
664
+ For teams that want a lightweight local gate before code leaves a workstation, a git hook can be a good fit:
665
+
666
+ ```bash
667
+ cve-lite . --fail-on high
668
+ ```
669
+
670
+ This works well in `pre-push` or another team-approved hook if you want to catch high-severity dependency issues before changes are shared.
671
+
672
+ ### CI pipelines
673
+
674
+ For CI, a strong baseline is:
675
+
676
+ ```bash
677
+ cve-lite . --verbose --fail-on high
678
+ ```
679
+
680
+ For controlled or restricted environments, sync the advisory DB separately and then scan offline:
681
+
682
+ ```bash
683
+ cve-lite advisories sync --output ./.cache/advisories.db
684
+ cve-lite . --offline-db ./.cache/advisories.db --verbose --fail-on high
685
+ ```
686
+
687
+ ### Scheduled advisory DB refresh
688
+
689
+ If you use offline mode, keep the advisory DB fresh with a scheduler such as cron, CI, or an internal automation system:
690
+
691
+ ```bash
692
+ cve-lite advisories sync --output /path/to/advisories.db
693
+ ```
694
+
695
+ This keeps offline scans current without forcing every developer machine or build runner to make live advisory API calls during the scan itself.
696
+
533
697
  ## Comparison with other tools
534
698
 
535
699
  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.
@@ -653,7 +817,6 @@ CVE Lite CLI is evolving from a vulnerability scanner into a comprehensive remed
653
817
  * **Deduplication Analysis:** Identify instances where multiple versions of the same vulnerable package exist and suggest a single version for consolidation.
654
818
 
655
819
  ### Phase 2: Ecosystem & Integration (Mid-Term)
656
- * **Official GitHub Action:** Create a dedicated Action for one-line setup in CI/CD pipelines.
657
820
  * **Expanded Lockfile Support:** Introduce parsers for emerging JS/TS ecosystems, including `bun.lockb`.
658
821
  * **IDE Integration:** Develop a lightweight extension to highlight vulnerable packages directly within the code editor.
659
822
  * **Workflow Integration Guidance:** Expand official workflow patterns for local scripts, hooks, CI, and offline developer adoption.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cve-lite-cli",
3
- "version": "1.1.1",
3
+ "version": "1.2.0",
4
4
  "description": "Developer-friendly CLI for scanning JS/TS projects for dependency vulnerabilities using local lockfiles and OSV",
5
5
  "type": "module",
6
6
  "bin": {