Skip to content

Commit 892dbba

Browse files
sonukapoorsonukapoor
authored
Merge pull request #241 from OWASP/docs/issue-240-readme-reposition
docs: reposition README as developer-first security platform
2 parents cc8e27f + f1d4c57 commit 892dbba

1 file changed

Lines changed: 132 additions & 84 deletions

File tree

‎README.md‎

Lines changed: 132 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
**🏆 Officially recognized as an [OWASP Incubator Project](https://owasp.org/cve-lite-cli)**
1818

19-
<p>Fast, developer-friendly vulnerability scanning for JavaScript and TypeScript projects.<br/>Practical fix guidance. Offline support. Usage-aware reachability. Clear direct vs transitive visibility.</p>
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>
2020

2121
<strong>Scan. Understand. Fix.</strong>
2222

@@ -45,6 +45,24 @@
4545

4646
---
4747

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+
4866
## Quick start
4967

5068
```bash
@@ -58,39 +76,18 @@ Or one-off with `npx`:
5876
npx cve-lite-cli /path/to/project
5977
```
6078

61-
## What is CVE Lite CLI
62-
63-
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.
79+
No account. No configuration. No source code leaves your machine.
6480

65-
It is built for the moment right before release: fast, local-first, and honest about what it does and does not do.
81+
## What it does
6682

67-
**Key differentiators:**
68-
69-
- **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
70-
- **Usage-aware reachability scanning** — uses static analysis to detect if vulnerable packages are actually imported in your code, cutting alert fatigue with `--usage` and `--only-used`
71-
- **Direct vs transitive visibility** — shows whether the risk comes from something you installed directly or a nested dependency
72-
- **Offline advisory DB** — sync advisory data ahead of time and scan with zero runtime API calls, useful for enterprise and restricted-network environments
73-
- **No account required** — no sign-up, no cloud dashboard, no source code upload
74-
- **Small dependency footprint** — only four runtime dependencies, intentionally kept minimal for a security tool
75-
76-
## How it compares
77-
78-
| Capability | CVE Lite CLI | npm audit | OSV-Scanner | Snyk CLI | Socket CLI |
79-
|---|:---:|:---:|:---:|:---:|:---:|
80-
| JS/TS lockfile scanning | ✅ | ✅ | ✅ | ✅ | ✅ |
81-
| npm + pnpm + Yarn + Bun support | ✅ | ❌ | ✅ | ✅ | ✅ |
82-
| No account required | ✅ | ✅ | ✅ | ❌ | ❌ |
83-
| Free to use | ✅ | ✅ | ✅ | ❌ | ❌ |
84-
| Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
85-
| Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
86-
| Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
87-
| Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
88-
| JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
89-
| Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
90-
91-
<sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
92-
93-
For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
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
9491

9592
## What it looks like
9693

@@ -126,16 +123,97 @@ For detailed per-tool analysis, see [Comparison with other tools](docs/compariso
126123
</p>
127124
</details>
128125

129-
## HTML vulnerability report (`--report`)
126+
## Workflow integration
130127

131-
Generate a self-contained HTML dashboard from any scan — severity cards, an interactive findings table, and copy-ready fix commands, all written to a local directory and opened automatically in your browser.
128+
CVE Lite CLI fits at every stage of the development workflow, not just CI.
132129

133-
```bash
134-
cve-lite /path/to/project --report
135-
cve-lite /path/to/project --report ./my-report --no-open
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.
131+
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.
133+
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.
135+
136+
**GitHub Actions** — a first-party action is available on the Marketplace:
137+
138+
```yaml
139+
- uses: OWASP/cve-lite-cli@v1
140+
with:
141+
verbose: "true"
142+
fail-on: high
136143
```
137144
138-
See the [HTML Report guide](docs/html-report.md) for the full option reference and output details.
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).
148+
149+
## How it compares
150+
151+
| Capability | CVE Lite CLI | npm audit | OSV-Scanner | Snyk CLI | Socket CLI |
152+
|---|:---:|:---:|:---:|:---:|:---:|
153+
| JS/TS lockfile scanning | ✅ | ✅ | ✅ | ✅ | ✅ |
154+
| npm + pnpm + Yarn + Bun support | ✅ | ❌ | ✅ | ✅ | ✅ |
155+
| No account required | ✅ | ✅ | ✅ | ❌ | ❌ |
156+
| Free to use | ✅ | ✅ | ✅ | ❌ | ❌ |
157+
| Usage-aware reachability scanning | ✅ | ❌ | ❌ | ✅ | ⚠️ |
158+
| Direct vs transitive visibility | ✅ | ⚠️ | ✅ | ✅ | ✅ |
159+
| Copy-and-run fix commands | ✅ | ❌ | ❌ | ✅ | ⚠️ |
160+
| Suggested remediation plan | ✅ | ❌ | ⚠️ | ✅ | ⚠️ |
161+
| JSON output | ✅ | ✅ | ✅ | ✅ | ✅ |
162+
| Offline/local advisory DB | ✅ | ❌ | ⚠️ | ❌ | ❌ |
163+
164+
<sub>✅ = built-in strength · ⚠️ = partial or workflow-dependent · ❌ = not a core strength</sub>
165+
166+
For detailed per-tool analysis, see [Comparison with other tools](docs/comparison.md).
167+
168+
## Real-world validation
169+
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.
171+
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
175+
176+
These are not demos. They are documented scans against real codebases with real findings, recorded before and after applying fix commands.
177+
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.
179+
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:**
190+
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.
139217

140218
## Usage
141219

@@ -192,7 +270,7 @@ cve-lite --version
192270

193271
### Why is `--usage` an opt-in flag?
194272

195-
CVE Lite CLI is designed to be blazing fast. Scanning a lockfile is nearly instantaneous, whereas running static reachability analysis across thousands of source files takes significantly more time. Furthermore, static analysis can occasionally produce false negatives (e.g., if a package is used in a build script 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.
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.
196274

197275
## Auto-fix mode (`--fix`)
198276

@@ -210,6 +288,17 @@ npx cve-lite-cli /path/to/project --fix
210288

211289
See the [Fix mode guide](docs/fix-mode.md) for output details and interpretation.
212290

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+
213302
## Offline support
214303

215304
For teams in enterprise, restricted-network, or air-gapped environments:
@@ -226,51 +315,6 @@ Syncing ~217,065 advisory records runs in under 9 seconds after bulk SQLite inge
226315

227316
See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full workflow including CI, scheduled refresh, and controlled-network patterns.
228317

229-
## CI integration
230-
231-
The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
232-
233-
```yaml
234-
- uses: OWASP/cve-lite-cli@v1
235-
with:
236-
verbose: "true"
237-
fail-on: high
238-
```
239-
240-
CVE Lite CLI also uses itself in CI to scan its own dependencies. See [`self-scan.yml`](https://github.com/OWASP/cve-lite-cli/blob/main/.github/workflows/self-scan.yml).
241-
242-
For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
243-
244-
## Recognized by OWASP
245-
246-
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:
247-
248-
- **Peer-reviewed** by security professionals
249-
- **Community-driven** development and governance
250-
- **Vendor-neutral** with no commercial platform required
251-
- **Open source** with transparent security practices and a minimal dependency footprint
252-
253-
**Where it fits in the OWASP ecosystem:**
254-
255-
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:
256-
257-
| Tool | Focus |
258-
|---|---|
259-
| CVE Lite CLI | Lockfile-first, local developer CLI, remediation-focused, JS/TS |
260-
| OWASP Dependency-Check | Multi-language, SAST-style, broader ecosystem |
261-
| OWASP dep-scan | Multi-language and environment, SBOM and cloud-native |
262-
| OWASP Dependency-Track | Platform and SBOM management, not a local CLI |
263-
264-
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.
265-
266-
## Real-world case studies
267-
268-
- [OWASP Juice Shop](docs/case-studies/owasp-juice-shop.md) — scanning a deliberately vulnerable application with known dependency issues
269-
- [NestJS](docs/case-studies/nestjs.md) — working through a real transitive dependency remediation sequence
270-
- [Analog](docs/case-studies/analog.md) — scanning a modern pnpm v9 Angular monorepo (3,367 packages) with unexpected toolchain vulnerabilities
271-
272-
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.
273-
274318
## Who uses it
275319

276320
CVE Lite CLI is a good fit for:
@@ -339,6 +383,10 @@ For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-
339383

340384
If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/OWASP/cve-lite-cli) helps more developers find it.
341385

386+
---
387+
388+
*Most tools tell you what's wrong. CVE Lite CLI tells you what to run.*
389+
342390
## License
343391

344392
MIT

0 commit comments

Comments
 (0)