Merge pull request #41 from sonukapoor/docs/advisory-driven-malware-detection-note

docs: clarify advisory-driven malware detection limits

Author: sonukapoor

README.md

@@ -174,6 +174,21 @@ Support for stricter network-controlled environments is planned on the roadmap,
 - custom advisory endpoint support for internal mirrors or proxies
 - local advisory database input for controlled or air-gapped workflows
 
+## Detecting malicious package incidents
+
+CVE Lite CLI can help detect malicious package incidents and supply-chain compromises **once the affected versions are represented in OSV or equivalent advisory data available through the configured advisory endpoint**.
+
+In practice, that means the tool can catch incidents such as a compromised npm package **when the exact malicious version appears in your lockfile** and the advisory data has already been published and indexed. This makes the tool useful for real-world release checks after a malicious package disclosure becomes known.
+
+It is important to be precise about the current scope:
+
+- CVE Lite CLI is **advisory-driven**, not a behavioral malware detector
+- it does **not** perform static malware analysis on package contents
+- it does **not** detect a package compromise before advisory intelligence exists for it
+- it works best with lockfiles because they capture the exact resolved version that was actually installed
+
+So the practical model is: **local lockfile scan + advisory matching**. When malicious versions are published to OSV or mirrored through a compatible internal endpoint, CVE Lite CLI can flag those exact versions during a scan.
+
 ## How it works
 
 ### Architectural Philosophy
@@ -422,6 +437,8 @@ If your goal is a practical developer-first CVE scan right before release, CVE L
 
 To keep the project honest, here is what it does **not** do in the current version:
 
+- it does not detect malicious packages before they are represented in advisory data
+- it does not perform behavioral malware detection or package content analysis
 - it does not prove exploitability
 - it does not verify runtime reachability
 - it does not scan container images, binaries, secrets, or IaC