diff --git a/README-updated.md b/README-updated.md deleted file mode 100644 index e8ba1fb1..00000000 --- a/README-updated.md +++ /dev/null @@ -1,460 +0,0 @@ -
- CVE Lite CLI - -

CVE Lite CLI

-

Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.

- - Scan. Prioritize. Fix. - -

- Quick Start • - Features • - Usage • - Contributing -

- -
- ---- - -

- CVE Lite CLI workflow -

- ---- - -## What is CVE Lite CLI - -**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. - -## Quick start - -Install globally: - -```bash -npm install -g cve-lite-cli -``` - -Then run: - -```bash -cve-lite /path/to/project -``` - -Or run it one-off with `npx`: - -```bash -npx cve-lite-cli /path/to/project -``` - -## Usage - -```bash -# Basic scan -cve-lite /path/to/project - -# Show all findings -cve-lite /path/to/project --all - -# Focus only on urgent findings -cve-lite /path/to/project --min-severity high - -# Show full detailed output, fix plan, paths, and full table -# Recommended for CI logs when you want full context -cve-lite /path/to/project --verbose - -# Fail a build on high severity and above -cve-lite /path/to/project --fail-on high - -# JSON output -cve-lite /path/to/project --json - -# SARIF output -cve-lite /path/to/project --sarif --output reports/scan.sarif -``` - -## What it looks like - -By default, CVE Lite CLI shows a cleaner, calmer, summary-first console view designed for fast local triage. For CI and deeper investigation, run with `--verbose` to include the full detailed output, dependency paths, fix plan, and table view. - - -

- CVE Lite CLI default output screenshot placeholder -

- -Verbose examples: - -

- CVE Lite CLI verbose output screenshot placeholder - CVE Lite CLI verbose output screenshot placeholder - CVE Lite CLI verbose output screenshot placeholder - CVE Lite CLI verbose output screenshot placeholder -

- -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. - -The final status line also gives the scan a clear ending, which makes terminal use and screenshots easier to read. - -## Why this tool exists - -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: - -**Do we have known vulnerable packages in this project, and what should we fix first?** - -CVE Lite CLI is built for that workflow. - -It focuses on being: - -- fast -- local-first -- easy to understand -- useful in CI -- honest about what it does and does not do - -## Project scope and differentiation - -CVE Lite CLI is intentionally focused. - -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. - -The project emphasizes: - -- npm, pnpm, and Yarn lockfile support -- direct vs transitive visibility -- top-priority fixes and a suggested remediation plan -- JSON and SARIF output for automation -- a small, reviewable runtime footprint - -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. - -## Relationship to similar OWASP projects - -CVE Lite CLI is not trying to replace broader OWASP security tooling. - -Its role is narrower and workflow-focused: - -- focused on JavaScript and TypeScript dependency scanning -- designed for fast local checks and simple CI release gates -- centered on direct vs transitive visibility -- built to highlight top-priority fixes and a suggested remediation plan -- intentionally lightweight in runtime footprint and setup - -This section is here to make the scope clear. CVE Lite CLI aims to complement the broader security ecosystem by being a practical, low-friction option for JS/TS dependency checks close to release time. - -## How it works - -CVE Lite CLI follows a simple workflow: - -1. Read a supported lockfile from your project. -2. Resolve package names and versions locally. -3. Match those packages against OSV advisory data. -4. Classify findings as direct or transitive where possible. -5. Highlight the most important fixes first. -6. Produce terminal, JSON, or SARIF output. - -The goal is to keep vulnerability scanning practical, understandable, and easy to act on. - -## What makes it stand out - -- **fast, low-friction workflow** - Run it locally against a project without adopting a large security platform. - -- **practical remediation guidance** - It does not stop at raw advisory output. It highlights top-priority fixes and suggests a fix plan. - -- **direct vs transitive visibility** - The output makes it easier to see whether the risk comes from something you installed directly or from a nested package. - -- **developer-first** - It is optimized for developers working with npm, pnpm, and Yarn lockfiles. - -- **budget-friendly** - It is intended for developers and teams who want useful security checks without paying for a large commercial product. - -- **local-first** - It reads your project locally and uses package/version matching against OSV advisories. - -- **release-focused** - It is especially useful before a release, in CI, or during final dependency cleanup. - -## Features - -### 1. Lockfile-based scanning - -CVE Lite CLI scans resolved dependency versions from: - -- `package-lock.json` -- `pnpm-lock.yaml` -- `yarn.lock` - -It also supports a limited `package.json` fallback for exact pinned direct dependencies. - -### 2. Clear vulnerability output - -Instead of only showing advisory IDs, the CLI reports: - -- package name and version -- severity -- direct vs transitive relationship -- fixed-version hint when available -- advisory IDs -- dependency path hints - -By default, the CLI now presents a cleaner summary-first view, with `--verbose` available for the full detailed output. - -### 3. Top priority fixes - -The CLI highlights the most important issues first, so developers can focus on the findings most likely to matter immediately. - -### 4. Suggested fix plan - -CVE Lite CLI organizes likely remediation work into a practical sequence, such as: - -- direct critical and high issues first -- urgent transitive issues next -- medium direct cleanup after that -- duplicated vulnerable packages to consolidate - -### 5. Parent package hints for transitive issues - -For transitive vulnerabilities, the tool can point to the likely parent dependency to review. That makes the output more actionable than simply saying a nested package is vulnerable. - -### 6. JSON output - -Structured JSON output makes it easier to integrate with scripts, logs, or pipeline artifacts. - -### 7. SARIF output - -CVE Lite CLI supports SARIF (Static Analysis Results Interchange Format) output for security tooling and code-scanning workflows. SARIF is a standardized JSON-based format for security and code analysis results, which means CI systems, scanners, and code analysis platforms can all understand the same output without custom adapters. This is important because it makes CVE Lite CLI more than just a terminal tool: you can export findings into a format that fits modern DevSecOps workflows, archive results as build artifacts, and integrate vulnerability scans into automated release pipelines. For developers and teams, SARIF support helps security results travel cleanly from a local scan into CI/CD and other tooling, instead of being trapped in plain console output. - -Example: - -```bash -cve-lite /path/to/project --sarif --output reports/scan.sarif -``` - -### 8. CI-friendly behavior - -The CLI can be used in CI/CD pipelines and can fail builds based on severity thresholds. - -### 9. Local cache - -It caches advisory detail results locally so repeated scans are faster and make fewer repeated requests. - -### 10. Clear final scan status - -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. - -### 11. Small runtime footprint - -This project intentionally keeps runtime dependencies minimal to reduce attack surface and keep the tool easier to review. - -## Dependency footprint - -CVE Lite CLI is intentionally designed with a very small dependency surface. - -**Runtime dependencies** -- `yaml` -- `yarn-lockfile` - -**Development dependencies** -- `@types/node` -- `tsx` -- `typescript` - -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. - -## Example use cases - -CVE Lite CLI is a good fit for: - -- independent developers shipping side projects -- startups watching every tool budget -- consultants doing release checks for client projects -- teams that want a lightweight dependency scan in CI -- developers who want a second opinion alongside other tools -- OSS maintainers who need a practical scan before publishing - -## Supported workflows - -### Local development - -Run it before a release, during dependency cleanup, or after a major package upgrade. - -### CI/CD - -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). - -For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, and detailed table output when a scan fails. - -Use it as a release gate in CI: - -```bash -cve-lite . --verbose --fail-on high -``` - -Export SARIF in CI: - -```bash -cve-lite . --verbose --sarif --output reports/scan.sarif -``` - -### Scripted automation - -Use JSON output for custom reporting: - -```bash -cve-lite . --json > cve-lite-report.json -``` - -## Comparison with other tools - -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. - -### Where CVE Lite CLI stands out - -Compared with other tools in this space, CVE Lite CLI focuses on: - -- **free to use** -- **fast to run** -- **easy to understand** -- **practical remediation guidance** instead of just raw advisory dumps -- **clear direct vs transitive visibility** -- **top priority fixes** and a suggested fix plan -- support for **npm**, **pnpm**, and **Yarn** lockfiles -- **SARIF** and **JSON** output for CI and automation -- a **lightweight**, **security-conscious** dependency footprint -- a **developer-friendly** option for teams that want useful **CVE scanning without paying for a larger commercial product** - -### At a glance - -| Tool | Best at | Ecosystem scope | Lockfile support | Guided remediation | JSON/SARIF | Best fit | -|---|---|---|---|---|---|---| -| **CVE Lite CLI** | Fast, developer-friendly pre-release CVE scanning | Focused on JS/TS | npm, pnpm, Yarn | **Yes** | **Yes** | Developers and small teams who want a free, practical release-time check | -| `npm audit` | Built-in npm auditing | npm-centric | npm | Basic remediation info | Limited compared to dedicated scanner workflows | Teams already living fully inside npm | -| OSV-Scanner | Broad multi-ecosystem scanning | Broad | Many ecosystems and lockfiles | More general-purpose | Strong machine-readable workflows | Teams needing wider ecosystem coverage | -| Snyk CLI | Broader enterprise security workflows | Broad | Strong ecosystem coverage | Strong commercial guidance | Strong | Teams adopting a larger security platform | -| Socket CLI | Broader package and supply-chain risk visibility | Broad | Multi-ecosystem/package-risk focus | Strong for package risk workflows | Strong | Teams that want more than CVE scanning alone | - -### CVE Lite CLI vs npm audit - -`npm audit` is the built-in default for npm users, which makes it convenient when your workflow is entirely npm-based. - -CVE Lite CLI stands out when you want: - -- support across npm, pnpm, and Yarn lockfiles -- cleaner, more guided console output -- priority fixes and a suggested remediation plan -- a more focused pre-release scanning experience for JS/TS teams - -### CVE Lite CLI vs OSV-Scanner - -OSV-Scanner supports many ecosystems and lockfile types, which makes it broader overall. - -CVE Lite CLI stands out when you want: - -- a narrower, easier-to-understand tool built specifically around JS/TS dependency workflows -- remediation-first output instead of a more general multi-ecosystem scanner experience -- a more approachable local workflow for everyday developers - -### CVE Lite CLI vs Snyk CLI - -Snyk CLI is part of a much broader commercial platform with wider enterprise coverage. - -CVE Lite CLI stands out when you want: - -- a simpler and lighter dependency CVE workflow -- an affordable option for small teams, startups, consultants, and independent developers -- a focused tool for lockfile-based release checks without adopting a larger platform - -### CVE Lite CLI vs Socket CLI - -Socket CLI goes beyond CVEs into broader package and supply-chain risk signals. - -CVE Lite CLI stands out when you want: - -- a focused dependency vulnerability scanner -- a straightforward answer to “what should I fix before release?” -- readable output centered on known vulnerability findings and practical next steps - -### Best fit - -CVE Lite CLI is best for: - -- developers shipping JavaScript or TypeScript applications -- teams that want a lightweight release gate -- maintainers who want actionable vulnerability output without heavy platform overhead -- users who care about simplicity, readability, and fast adoption - -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. - -## Philosophy - -CVE Lite CLI is not trying to be everything. - -It is trying to be **one of the easiest and most useful tools for developers who need a practical CVE scan right now**. - -That means: - -- fast setup -- understandable output -- useful remediation guidance -- low friction -- realistic adoption for developers without enterprise budgets - -## Current limitations - -To keep the project honest, here is what it does **not** do in the current version: - -- it does not prove exploitability -- it does not verify runtime reachability -- it does not scan container images, binaries, secrets, or IaC -- it does not replace a full application security program -- it is currently focused on JS/TS dependency scanning - -## Positioning - -CVE Lite CLI is best described as: - -**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.** - -## Roadmap ideas - -Planned or possible future improvements include: - -- richer remediation guidance -- stronger CI examples -- broader export improvements -- improved caching options -- better package grouping and deduplication insights -- publishable npm release polish -- GitHub Action or container workflow support - -## Contributing - -This project is being shaped around real-world developer usability. Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable. - -To get started, see [CONTRIBUTING.md](./CONTRIBUTING.md). - -## Community and support - -CVE Lite CLI is being shaped in public and feedback is welcome. - -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. - -Helpful feedback includes: - -- reproducible bug reports -- real-world lockfile edge cases -- ideas for clearer output and remediation guidance -- CI usage examples -- JSON and SARIF workflow feedback -- comparison feedback based on real usage - -As the project grows, contribution and security guidance will be expanded further in dedicated project docs. - -For bug reports and feature requests, please use [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues). For contribution guidance, see [CONTRIBUTING.md](./CONTRIBUTING.md). For security-related reporting, see [SECURITY.md](./SECURITY.md). - -## License - -MIT diff --git a/README.md b/README.md index 1d767a5c..e8ba1fb1 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ -
CVE Lite CLI - +

CVE Lite CLI

Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.

Scan. Prioritize. Fix. - +

Quick Start • Features • @@ -60,6 +59,10 @@ cve-lite /path/to/project --all # Focus only on urgent findings cve-lite /path/to/project --min-severity high +# Show full detailed output, fix plan, paths, and full table +# Recommended for CI logs when you want full context +cve-lite /path/to/project --verbose + # Fail a build on high severity and above cve-lite /path/to/project --fail-on high @@ -72,10 +75,21 @@ cve-lite /path/to/project --sarif --output reports/scan.sarif ## What it looks like -Below is a real example of the console experience. In a terminal, the severity labels, summaries, and section headers are colorized for readability. +By default, CVE Lite CLI shows a cleaner, calmer, summary-first console view designed for fast local triage. For CI and deeper investigation, run with `--verbose` to include the full detailed output, dependency paths, fix plan, and table view. + + +

+ CVE Lite CLI default output screenshot placeholder +

+ +Verbose examples: -![Image 1](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/image-1.png) -![Image 2](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/image-2.png) +

+ CVE Lite CLI verbose output screenshot placeholder + CVE Lite CLI verbose output screenshot placeholder + CVE Lite CLI verbose output screenshot placeholder + CVE Lite CLI verbose output screenshot placeholder +

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. @@ -186,6 +200,8 @@ Instead of only showing advisory IDs, the CLI reports: - advisory IDs - dependency path hints +By default, the CLI now presents a cleaner summary-first view, with `--verbose` available for the full detailed output. + ### 3. Top priority fixes The CLI highlights the most important issues first, so developers can focus on the findings most likely to matter immediately. @@ -269,16 +285,18 @@ Run it before a release, during dependency cleanup, or after a major package upg 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). +For CI, we recommend using `--verbose` so build logs include the full fix plan, dependency paths, and detailed table output when a scan fails. + Use it as a release gate in CI: ```bash -cve-lite . --fail-on high +cve-lite . --verbose --fail-on high ``` Export SARIF in CI: ```bash -cve-lite . --sarif --output reports/scan.sarif +cve-lite . --verbose --sarif --output reports/scan.sarif ``` ### Scripted automation