Merge pull request #223 from OWASP/docs/issue-221-html-report-and-owasp

docs: add HTML report guide, OWASP affiliation, and update GitHub links

Author: sonukapoor

README.md

@@ -1,15 +1,19 @@
 
+[![OWASP Incubator Project](https://img.shields.io/badge/OWASP-Incubator%20Project-F68B1F?logo=owasp)](https://owasp.org/cve-lite-cli)
 [![npm version](https://img.shields.io/npm/v/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
 [![npm downloads](https://img.shields.io/npm/dm/cve-lite-cli)](https://www.npmjs.com/package/cve-lite-cli)
-[![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)
+[![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)
 [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-CVE%20Lite%20CLI-blue)](https://github.com/marketplace/actions/cve-lite-cli)
-[![License](https://img.shields.io/github/license/sonukapoor/cve-lite-cli)](https://github.com/sonukapoor/cve-lite-cli/blob/main/LICENSE)
-[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
+[![License](https://img.shields.io/github/license/OWASP/cve-lite-cli)](https://github.com/OWASP/cve-lite-cli/blob/main/LICENSE)
+[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
+  <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/logo-with-title.png" alt="CVE Lite CLI" width="320"/>
 
   <h1>CVE Lite CLI</h1>
+
+  **🏆 Officially recognized as an [OWASP Incubator Project](https://owasp.org/cve-lite-cli)**
+
   <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>
 
   <strong>Scan. Understand. Fix.</strong>
@@ -30,9 +34,10 @@
     <a href="#quick-start">Quick Start</a> •
     <a href="#usage">Usage</a> •
     <a href="#what-it-looks-like">Screenshots</a> •
+    <a href="docs/html-report.md">HTML Report</a> •
     <a href="docs/comparison.md">Compare</a> •
     <a href="docs/roadmap.md">Roadmap</a> •
-    <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
+    <a href="https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md">Contributing</a>
   </p>
 </div>
 
@@ -96,22 +101,39 @@ cve-lite .
 ```
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png">
-    <img src="https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output" width="600"/>
+  <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png">
+    <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/default-output.png" alt="CVE Lite CLI default output" width="600"/>
   </a>
 </p>
 
 Verbose output — includes the `Copy And Run These Fix Commands` section:
 
 <p align="center">
-  <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>
-  <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>
-  <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>
+  <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>
+  <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>
+  <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>
 </p>
 <p align="center"><sub>Click any screenshot to enlarge</sub></p>
 
 For a section-by-section walkthrough, see [How to read verbose output](docs/how-to-read-verbose-output.md).
 
+## HTML vulnerability report (`--report`)
+
+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.
+
+```bash
+cve-lite /path/to/project --report
+cve-lite /path/to/project --report ./my-report --no-open
+```
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png">
+    <img src="https://raw.githubusercontent.com/OWASP/cve-lite-cli/main/assets/html-report-dashboard.png" alt="CVE Lite CLI HTML Report Dashboard" width="700"/>
+  </a>
+</p>
+
+See the [HTML Report guide](docs/html-report.md) for the full option reference and output details.
+
 ## Usage
 
 ```bash
@@ -139,6 +161,10 @@ cve-lite /path/to/project --fail-on high
 # JSON output
 cve-lite /path/to/project --json
 
+# Generate an HTML vulnerability dashboard (opens in browser automatically)
+cve-lite /path/to/project --report
+cve-lite /path/to/project --report ./my-report --no-open
+
 # Scan project source files to check if vulnerable dependencies are actually imported
 cve-lite /path/to/project --usage
 
@@ -202,27 +228,37 @@ See the [Offline Advisory DB guide](docs/offline-advisory-db.md) for the full wo
 The project ships a first-party [GitHub Action on the Marketplace](https://github.com/marketplace/actions/cve-lite-cli):
 
 ```yaml
-- uses: sonukapoor/cve-lite-cli@v1
+- uses: OWASP/cve-lite-cli@v1
   with:
     verbose: "true"
     fail-on: high
 ```
 
-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).
+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).
 
 For full CI patterns including offline workflows, git hooks, and scripted automation, see the [CI and Workflow Integration guide](docs/ci-integration.md).
 
-## Relationship to similar OWASP projects
+## OWASP project
+
+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:
+
+- **Peer-reviewed** by security professionals
+- **Community-driven** development and governance
+- **Vendor-neutral** with no commercial platform required
+- **Open source** with transparent security practices and a minimal dependency footprint
 
-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.
+**Where it fits in the OWASP ecosystem:**
 
-The closest OWASP comparisons are:
+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:
 
-- **OWASP Dependency-Check** — broader ecosystem coverage, different operational model
-- **OWASP dep-scan** — wider language and environment coverage
-- **OWASP Dependency-Track** — SBOM- and platform-oriented, not a local developer CLI
+| Tool | Focus |
+|---|---|
+| CVE Lite CLI | Lockfile-first, local developer CLI, remediation-focused, JS/TS |
+| OWASP Dependency-Check | Multi-language, SAST-style, broader ecosystem |
+| OWASP dep-scan | Multi-language and environment, SBOM and cloud-native |
+| OWASP Dependency-Track | Platform and SBOM management, not a local CLI |
 
-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.
+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.
 
 ## Real-world case studies
 
@@ -278,27 +314,27 @@ See [parser-coverage.md](docs/parser-coverage.md) for supported lockfile formats
 
 Feedback on output clarity, remediation guidance, ecosystem coverage, and CI usage is especially valuable.
 
-See [CONTRIBUTING.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
+See [CONTRIBUTING.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/CONTRIBUTING.md) to get started.
 
 ## Add a badge to your project
 
 If you use CVE Lite CLI in your project, add this badge to your README:
 
 ```markdown
-[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
+[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
 ```
 
-[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/sonukapoor/cve-lite-cli)
+[![Protected by CVE Lite CLI](https://img.shields.io/badge/Protected_by-CVE_Lite_CLI-brightgreen)](https://github.com/OWASP/cve-lite-cli)
 
 ## Community and support
 
-For bug reports and feature requests: [GitHub Issues](https://github.com/sonukapoor/cve-lite-cli/issues)
+For bug reports and feature requests: [GitHub Issues](https://github.com/OWASP/cve-lite-cli/issues)
 
 Helpful feedback includes reproducible bug reports, real-world lockfile edge cases, ideas for clearer output and remediation guidance, and CI or JSON workflow examples.
 
-For security-related reporting: [SECURITY.md](https://github.com/sonukapoor/cve-lite-cli/blob/main/src/docs/SECURITY.md)
+For security-related reporting: [SECURITY.md](https://github.com/OWASP/cve-lite-cli/blob/main/src/docs/SECURITY.md)
 
-If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/sonukapoor/cve-lite-cli) helps more developers find it.
+If CVE Lite CLI helps your release workflow, a [GitHub star](https://github.com/OWASP/cve-lite-cli) helps more developers find it.
 
 ## License
 

assets/html-report-dashboard.png

@@ -0,0 +1,60 @@
+# HTML Vulnerability Report (`--report`)
+
+The `--report` flag generates a self-contained HTML dashboard from a scan. Results are written to a local directory and the report opens automatically in your browser when generation completes.
+
+## Screenshot
+
+<p align="center">
+  <img src="../assets/html-report-dashboard.png" alt="CVE Lite CLI HTML Report Dashboard" width="900"/>
+</p>
+
+## Generating a report
+
+```bash
+# Generate to the default directory (./cve-report/)
+cve-lite /path/to/project --report
+
+# Generate to a specific directory
+cve-lite /path/to/project --report ./my-report
+
+# Generate without auto-opening in the browser
+cve-lite /path/to/project --report --no-open
+```
+
+## Output files
+
+The report writes two files to the output directory:
+
+| File | Description |
+|---|---|
+| `index.html` | Self-contained dashboard. Open in any browser — no server required. |
+| `report.json` | Machine-readable scan data in JSON format. |
+
+Running `--report` to the same directory a second time overwrites both files.
+
+## What the report shows
+
+**Severity summary cards** at the top give an immediate count for Critical, High, Medium, and Low findings alongside a total.
+
+**Suggested Fix Plan** mirrors the terminal output: copy-ready package manager commands for your direct dependencies, grouped by severity. Skipped entries (transitive or no fix available) are listed in a collapsible section.
+
+**Findings table** with interactive controls:
+- Filter by severity or direct-only
+- Expandable rows showing vulnerability description, dependency path, and recommended action
+- CVE / GHSA advisory IDs linked to osv.dev and GitHub Security Advisories
+- Fix version shown inline when one is available
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--report [dir]` | `./cve-report` | Generate an HTML report in `[dir]`. Omit the path to use the default. |
+| `--no-open` | — | Skip auto-opening the report in the browser after generation. |
+
+`--report` cannot be combined with `--json`.
+
+## Notes
+
+- The report is fully self-contained: no CDN calls, no internet connection required to view it.
+- The CVE Lite CLI logo is embedded as a Base64 data URI inside `index.html`.
+- The report path is printed to the terminal at the end of the scan so it can be picked up by CI scripts or shared with teammates.