docs: add OWASP Juice Shop case study

Author: sonukapoor

README.md

@@ -212,6 +212,8 @@ The final status line also gives the scan a clear ending, which makes terminal u
 
 See the example below using OWASP Juice Shop for real output samples.
 
+For a real-world case study, see the [OWASP Juice Shop case study](docs/case-studies/owasp-juice-shop.md).
+
 ## Example: Scanning OWASP Juice Shop (Real Output)
 
 CVE Lite CLI can be used against real-world vulnerable applications such as the OWASP Juice Shop.

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

@@ -0,0 +1,148 @@
+# OWASP Juice Shop Case Study
+
+This case study shows how CVE Lite CLI was used against OWASP [Juice Shop](https://github.com/juice-shop/juice-shop) to identify, prioritize, and reduce dependency risk in a realistic JavaScript application.
+
+It is intentionally practical. The goal is not to claim that every finding was removed, but to show how the tool helped move from an initial scan to a narrower, better-prioritized remediation state.
+
+## Project context
+
+- Project: OWASP Juice Shop
+- Revision used for the scan: `7ae7184dbf84baae9ee1d85be39f793b777ae996`
+- Scan input: `package-lock.json`
+- Scan mode: standard OSV-backed mode with `--verbose --all`
+
+The remediation walkthrough was performed locally against that same Juice Shop revision. Dependency and code changes were applied during the exercise, but they were not committed in the Juice Shop repository. The documented "after" state in this case study refers to the first successful remediation pass that removed the urgent critical and high findings tied to `jsonwebtoken`, `express-jwt`, and `sanitize-html`.
+
+## Commands used
+
+Baseline scan:
+
+```bash
+node /Users/sonukapoor/Projects/cve-lite-cli-v1.0.1/dist/index.js . --verbose --all
+```
+
+The initial remediation work focused on the highest-priority direct and transitive issues surfaced by CVE Lite CLI:
+
+- `jsonwebtoken`
+- `express-jwt`
+- `sanitize-html`
+- `marsdb`
+
+## Baseline findings
+
+Initial scan summary:
+
+- vulnerable packages: `40`
+- critical: `3`
+- high: `1`
+- medium: `11`
+- low: `24`
+- unknown: `1`
+- unique advisories matched: `79`
+
+Top priority fixes identified by CVE Lite CLI:
+
+- `jsonwebtoken@0.4.0` as a direct critical dependency
+- `marsdb@0.6.11` as a direct critical dependency
+- `express-jwt -> jsonwebtoken@0.1.0` as a transitive critical dependency
+- `sanitize-html -> lodash@2.4.2` as a transitive high dependency
+
+This was a strong example of the tool's intended workflow: surface the most urgent direct issues first, then highlight the transitive parent chains that are worth upgrading next.
+
+## Remediation steps
+
+The following dependency changes were applied locally:
+
+- upgraded `jsonwebtoken` from `0.4.0` to `4.2.2`
+- upgraded `express-jwt` from `0.1.3` to `8.5.1`
+- upgraded `sanitize-html` from `1.4.2` to `2.17.2`
+
+These changes updated the resolved dependency tree and removed several of the highest-priority findings:
+
+- upgrading `express-jwt` also removed transitive `jsonwebtoken@0.1.0`
+- upgrading `sanitize-html` removed the `lodash@2.4.2` high finding
+
+One issue required more than a package version bump. After upgrading `express-jwt`, Juice Shop's code needed an API adjustment in [lib/insecurity.ts](/Users/sonukapoor/Projects/juice-shop/lib/insecurity.ts) because the newer `express-jwt` export shape no longer matched the older callable default import pattern.
+
+## What slowed remediation down
+
+One of the most useful lessons from this walkthrough was that the first remediation attempt appeared to work in `npm ls`, but the CVE Lite CLI scan did not change.
+
+The reason was simple and important:
+
+- the project had `.npmrc` configured with `package-lock=false`
+- `package.json` changed, but `package-lock.json` did not regenerate
+- CVE Lite CLI was correctly reporting the vulnerable versions still pinned in the lockfile
+
+Once the lockfile was regenerated with `package-lock` enabled, the scan reflected the intended dependency changes.
+
+This is exactly the kind of situation where a lockfile-first scanner is useful. It shows the dependency graph the project actually records and ships, not just what a local install tree happens to resolve temporarily.
+
+## After state
+
+After the dependency updates, code adjustment, and lockfile regeneration, the scan summary changed to:
+
+- vulnerable packages: `35`
+- critical: `1`
+- high: `0`
+- medium: `11`
+- low: `21`
+- unknown: `2`
+- unique advisories matched: `55`
+
+Notable improvements:
+
+- critical findings dropped from `3` to `1`
+- high findings dropped from `1` to `0`
+- unique matched advisories dropped from `79` to `55`
+- the urgent `jsonwebtoken` and `sanitize-html` driven findings were removed
+
+Key resolved package state:
+
+- `express-jwt@8.5.1`
+- `jsonwebtoken@4.2.2`
+- `sanitize-html@2.17.2`
+- `marsdb@0.6.11`
+
+## Remaining risk
+
+The most important remaining finding after this pass was:
+
+- `marsdb@0.6.11` as a direct critical dependency
+
+At the time of this walkthrough, `0.6.11` was still the latest published `marsdb` version. The upstream [MarsDB repository](https://github.com/c58/marsdb) is also archived and read-only, which makes this a stronger example of a real remediation limit: some findings can be fixed with normal dependency upgrades, while others may require package replacement, deeper review, or migration away from an unmaintained dependency.
+
+Several medium findings also remained, including:
+
+- `diff@5.0.0`
+- `messageformat@2.3.0`
+- `minimatch` in direct and transitive paths
+- `multer@1.4.5-lts.2`
+- `parseuri@0.0.6`
+
+Those were left intentionally as follow-up work. The purpose of this case study was to show a realistic first remediation pass, not to claim a fully clean result.
+
+## Why this case study stops here
+
+An additional medium-only cleanup pass was attempted after this state, but it introduced more dependency churn than useful signal. Some packages shifted into different vulnerable versions or moved between direct and transitive paths without materially improving the overall story.
+
+That is exactly why this case study uses the earlier post-remediation checkpoint as its final state: it shows a meaningful reduction in urgent risk, keeps the remediation path understandable, and avoids overstating what a single dependency cleanup pass should realistically accomplish.
+
+## What CVE Lite CLI contributed
+
+This walkthrough highlighted a few parts of the tool that were especially useful:
+
+- clear separation of direct and transitive findings
+- parent-chain visibility for transitive remediation work
+- a practical top-priority fix list instead of a flat wall of advisories
+- lockfile-first behavior that exposed stale dependency state when `package-lock` generation was disabled
+- a narrow, developer-oriented workflow that fit well near release-time triage
+
+## Takeaways
+
+- A focused first pass can remove the most urgent dependency risk quickly.
+- Transitive issues often become fixable once the right parent dependency is identified.
+- Lockfile state matters. Updating `package.json` alone is not enough.
+- Some critical findings still have no easy upgrade path and need separate handling.
+
+CVE Lite CLI was useful here not because it claimed complete dependency security, but because it helped turn a large set of findings into an ordered, understandable remediation workflow on a real application.