cve-scanner 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# CVE Scanner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![NPM](https://img.shields.io/npm/v/cve-scanner.svg?style=flat-square)](https://www.npmjs.com/package/cve-scanner)
+
+An offline CLI that finds known-vulnerable dependencies in dependencies. Supports **Maven**, **Gradle** and **NPM**.
+
+It includes a subset of the complete [CVE List](https://www.cve.org/Downloads) to make it work completely offline. It can also use the complete List, if available, to produce richer feedback.
+
+It will not unpack bundled dependencies like uber/fat-jars. It does not use hashing to identify artifacts, like other vulnerability detection tools does. It relies on what the tools in each ecosystem provides.
+
+- **Maven**: runs `mvn dependency:list` (or the project's own `./mvnw` if checked in) to get the effective,
+  fully-resolved dependency list — correctly accounting for BOMs, dependency management, and exclusions.
+- **Gradle**: runs `gradle` (or `./gradlew`) with a small bundled init script that reports every resolved
+  module across every project/configuration.
+- **npm**: reads `package-lock.json` (or `npm-shrinkwrap.json`) — the versions actually resolved, not just
+  the ranges declared in `package.json`.
+
+A `--scan-dir` can contain more than one independent project (a monorepo with no shared root manifest, e.g.
+a `backend/` with its own `pom.xml` and a `frontend/` with its own `package-lock.json`) — all of them are
+discovered and scanned in one run.
+
+See [`specs/`](specs/) for the full design.
+
+Execute it with:
+
+```sh
+npx cve-scanner --scan-dir some/path
+```
+
+## Flags
+
+```sh
+Usage: cve-scanner [options]
+
+Options:
+  -s, --scan-dir <dir>          Directory to scan. (default: current working directory)
+  -f, --format <table|json>     Report output format. (default: "table")
+  -c, --cve-data-dir <dir>      Path to an extracted full CVE.org bulk download
+                                (https://www.cve.org/Downloads), used to enrich
+                                findings.
+  -d, --cve-data-download       Download the full CVE List
+                                (github.com/CVEProject/cvelistV5) and use it to
+                                enrich findings, instead of --cve-data-dir.
+                                Cached locally for 12 hours. (default: false)
+  -p, --print-prompt            Print a ready-to-paste AI investigation prompt
+                                per finding, for manual use in a web AI chat UI.
+                                (default: false)
+  -e, --ai-endpoint <url>       OpenAI-compatible base URL. When set, sends each
+                                finding's details to this endpoint and prints
+                                its response. Opt-in only.
+  -k, --ai-api-key <key>        API key for --ai-endpoint. Prefer the
+                                CVE_SCANNER_AI_API_KEY env var instead of this
+                                flag.
+  -m, --ai-model <name>         Model name, required when --ai-endpoint is set.
+  -x, --fail-on-score <number>  Only exit with a failure code if a finding's
+                                score is >= this value.
+  -v, --version                 Display version (default: false)
+  -h, --help                    display help for command
+```
+
+## Richer detail: `--cve-data-dir` / `--cve-data-download`
+
+The bundled dataset only carries a CVE id, score and title per finding — enough to triage, not enough to
+fully investigate. Two ways to get the full description, CVSS vector, CWE, and references, mutually
+exclusive:
+
+- **`--cve-data-dir <dir>`**: point at a copy of the complete CVE List you've separately downloaded and
+  extracted yourself from https://www.cve.org/Downloads.
+- **`--cve-data-download`**: let the tool download and extract it for you, from
+  `github.com/CVEProject/cvelistV5`, into a local cache reused across runs for 12 hours (so you're not
+  re-downloading hundreds of MB on every scan).
+
+## AI assistance: `--print-prompt` / `--ai-endpoint`
+
+Two independent ways to get help investigating a finding:
+
+- **`--print-prompt`** prints a ready-to-paste investigation prompt per finding — for anyone whose only
+  access to an AI is a web chat UI (ChatGPT, Claude, etc.) they'll copy/paste into by hand. No network call.
+- **`--ai-endpoint <url>`** (with `--ai-model` and an API key, via `--ai-api-key` or the
+  `CVE_SCANNER_AI_API_KEY` env var) sends that same prompt to any OpenAI-chat-completions-compatible
+  endpoint — OpenAI itself, an Azure OpenAI proxy, a local Ollama server, etc. — and prints the response
+  inline. **This sends the finding's coordinate/version/CVE details, the contents of your project's
+  manifest file (`pom.xml`/`build.gradle`/`package.json`, if present), and (if available) the
+  `--cve-data-dir` enrichment text to whatever endpoint you configure — opt-in only, nothing is sent
+  anywhere by default.**
+
+## CI usage: `--fail-on-score`
+
+By default the process exits `1` if there's any finding at all, `0` otherwise. Pass `--fail-on-score <n>`
+to only fail the build on findings whose CVSS score is `>= n` — lower-severity findings are still printed,
+they just won't break CI.
+
+## Design docs
+
+See [`specs/`](specs/) for the authoritative design of this tool, including the pieces not implemented yet.
+`AGENTS.md`/`CLAUDE.md` explain how that folder is meant to be used.

package/assets/gradle-init/list-dependencies.init.gradle

@@ -0,0 +1,20 @@
+// Bundled with cve-scanner, applied via --init-script.
+// Prints one "CVE_SCANNER_DEP:<group>:<name>:<version>" line per resolved
+// module across every resolvable configuration in every project.
+// See specs/30-java-detector.md.
+
+allprojects {
+  tasks.register("cveScannerListDependencies") {
+    doLast {
+      configurations.findAll { it.canBeResolved }.each { config ->
+        try {
+          config.resolvedConfiguration.lenientConfiguration.allModuleDependencies.each { dep ->
+            println "CVE_SCANNER_DEP:${dep.moduleGroup}:${dep.moduleName}:${dep.moduleVersion}"
+          }
+        } catch (ignored) {
+          // Not resolvable in this context (e.g. detached/test-only configs); skip it.
+        }
+      }
+    }
+  }
+}

package/data/dataset.hash

@@ -0,0 +1 @@
+959ac48aa57c9361d5938a463348ba7c36d6c51d28d1061e49968c0773722ffd