Merge pull request #147 from sonukapoor/feature/issue-146-fix-mode-docs

docs: add --fix guide and Juice Shop auto-fix evidence

Author: sonukapoor

README.md

@@ -37,6 +37,7 @@
       <a href="#why-offline-mode-matters">Why offline mode matters</a><br/>
       <a href="docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop case study</a><br/>
       <a href="docs/case-studies/nestjs.md">NestJS case study</a><br/>
+      <a href="docs/fix-mode.md">Fix mode guide (--fix)</a><br/>
       <a href="docs/how-to-read-verbose-output.md">How to read verbose output</a><br/>
       <a href="#what-it-looks-like">What it looks like</a><br/>
       <a href="#why-this-tool-exists">Why this tool exists</a><br/>
@@ -83,6 +84,7 @@ It is designed to be:
 
 For real-world remediation examples, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md) and the [NestJS case study](docs/case-studies/nestjs.md).
 If you are new to verbose mode, use the [How to read verbose output guide](docs/how-to-read-verbose-output.md).
+If you want automatic direct remediation, use the [Fix mode guide](docs/fix-mode.md).
 
 ## New here? Start here
 
@@ -179,6 +181,9 @@ cve-lite /path/to/project --min-severity high
 # Recommended for CI logs when you want full context
 cve-lite /path/to/project --verbose
 
+# Apply validated direct dependency fixes and rescan
+cve-lite /path/to/project --fix
+
 # Limit the scan to production dependencies where supported by the lockfile
 cve-lite /path/to/project --prod-only
 
@@ -204,6 +209,29 @@ cve-lite /path/to/project --offline
 cve-lite /path/to/project --offline-db /path/to/advisories.db
 ```
 
+## Auto-fix mode (`--fix`)
+
+`--fix` is designed to speed up remediation without overpromising safety.
+
+In v1, `--fix`:
+- applies only direct dependency fixes with a validated lowest known non-vulnerable target
+- uses your project’s package manager (`npm install`, `pnpm add`, or `yarn add`)
+- rescans automatically after applying fixes
+- prints a concise summary of applied fixes, skipped findings, and remaining findings
+
+In v1, `--fix` does not:
+- auto-apply transitive overrides/resolutions
+- guarantee compatibility with your application code
+- perform exploitability or runtime reachability analysis
+
+Example:
+
+```bash
+npx cve-lite-cli /path/to/project --fix
+```
+
+For output details and interpretation, see [Fix mode guide](docs/fix-mode.md).
+
 ## Workflow modes
 
 CVE Lite CLI now supports three clear advisory workflows:

assets/owasp-juice-shop-auto-fix.png

@@ -49,6 +49,44 @@ Terminal snapshots from this run:
 
 ![Juice Shop dependency path hints and remaining risk](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-5.png)
 
+## Auto-fix pass (`--fix`) evidence
+
+After the planning scan, we ran a focused auto-fix pass:
+
+```bash
+npx cve-lite-cli . --fix
+```
+
+Run outcome:
+
+- applied direct package fixes: `7`
+- skipped findings: `5`
+  - transitive (v1 skip): `3`
+  - no validated direct target: `2`
+- findings before fix: `39`
+- findings after fix pass: `39`
+- remaining severity mix: critical `3`, high `1`, medium `11`, low `23`, unknown `1`
+
+Applied direct dependency upgrades:
+
+- `jsonwebtoken: 0.1.0 -> 9.0.0`
+- `sanitize-html: 1.4.2 -> 2.12.1`
+- `multer: 1.4.5-lts.2 -> 2.1.1`
+- `express-jwt: 0.1.3 -> 6.0.0`
+- `file-type: 16.5.4 -> 21.3.1`
+- `js-yaml: 4.0.0 -> 4.1.1`
+- `socket.io: 3.1.2 -> 4.6.2`
+
+Why the total finding count can remain unchanged after auto-fix:
+
+- a large share of Juice Shop findings are transitive and still require parent-chain upgrades
+- some direct findings have no validated auto-apply target
+- duplicate vulnerable packages can still exist in other dependency paths until parent upgrades are applied
+
+Auto-fix terminal snapshot:
+
+![Juice Shop auto-fix summary output](https://raw.githubusercontent.com/sonukapoor/cve-lite-cli/main/assets/owasp-juice-shop-auto-fix.png)
+
 ## Copy-and-run remediation output
 
 In this run, CVE Lite CLI generated `6` command groups across `10` packages:

docs/case-studies/owasp-juice-shop.md

@@ -0,0 +1,58 @@
+# Fix Mode Guide (`--fix`)
+
+`--fix` is a conservative auto-remediation mode for CVE Lite CLI.
+
+It is intended to reduce manual install-scan-repeat loops while keeping behavior explicit and predictable.
+
+## What `--fix` does in v1
+
+- applies fixes for **direct dependencies only**
+- requires a validated **lowest known non-vulnerable version** target
+- uses package-manager-native commands:
+  - `npm install`
+  - `pnpm add`
+  - `yarn add`
+- rescans automatically after fixes are applied
+- prints a concise summary:
+  - applied fixes
+  - skipped findings
+  - findings before/after fix
+  - remaining severity mix
+
+## What `--fix` does not do in v1
+
+- does not auto-apply transitive override/resolution rules
+- does not guarantee compatibility with your codebase
+- does not perform exploitability or runtime reachability analysis
+
+## Basic usage
+
+```bash
+npx cve-lite-cli /path/to/project --fix
+```
+
+## Typical output flow
+
+1. scan starts and loads advisory matches
+2. `Applying fixes (--fix)` section begins
+3. direct package fixes are applied with progress (for example `Applying direct fix 3/7: npm install pkg@version`)
+4. scan reruns automatically
+5. concise fix summary is printed
+
+## How to interpret skipped findings
+
+- `Transitive (v1 skip)` means a parent upgrade path may exist, but `--fix` intentionally does not auto-apply it in v1.
+- `No validated direct target` means a direct dependency did not have a safe validated target for automatic remediation.
+
+For full diagnostic context, run a separate verbose scan:
+
+```bash
+npx cve-lite-cli /path/to/project --verbose
+```
+
+## Recommended workflow
+
+1. run `--fix` for fast direct remediation
+2. review remaining findings in summary
+3. run `--verbose` when you need full parent-path and table-level detail
+4. test your project after dependency updates

docs/fix-mode.md

@@ -28,6 +28,7 @@
       <nav>
         <a href="#quick-start">Quick Start</a>
         <a href="#features">Features</a>
+        <a href="#fix-mode">Fix Mode</a>
         <a href="#workflow">Workflow</a>
         <a href="#speed">Speed</a>
         <a href="#links">Links</a>
@@ -61,6 +62,7 @@ <h1>Scan. Prioritize. Fix.</h1>
             <li>npm, pnpm, Yarn lockfile support</li>
             <li>Offline scans with local advisory DB</li>
             <li>Copy-and-run direct fix commands</li>
+            <li>Conservative auto-remediation with `--fix`</li>
           </ul>
         </div>
         <div class="hero-art" aria-hidden="true">
@@ -121,6 +123,10 @@ <h3>Run one-off with npx</h3>
       <section class="container" id="features">
         <h2>What Makes It Useful</h2>
         <div class="grid three">
+          <article class="card" id="fix-mode">
+            <h3>Conservative `--fix` mode</h3>
+            <p>Apply validated direct dependency fixes automatically, then rescan immediately with a concise before/after summary.</p>
+          </article>
           <article class="card">
             <h3>Actionable output</h3>
             <p>Get summary-first scan results plus copy-and-run fix commands for manifest-declared direct dependencies, with lowest known non-vulnerable targets when data allows.</p>
@@ -196,6 +202,7 @@ <h3>Real-world case studies</h3>
             <p class="link-list">
               <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/case-studies/owasp-juice-shop.md">OWASP Juice Shop</a>
               <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/case-studies/nestjs.md">NestJS</a>
+              <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/fix-mode.md">Fix mode guide (--fix)</a>
               <a href="https://github.com/sonukapoor/cve-lite-cli/blob/main/docs/how-to-read-verbose-output.md">How to read verbose output</a>
             </p>
           </article>