# vuln-intel-json

> One merged record for a CVE or a package version

- Status: MCP package (hosted access coming soon)

## What question it answers

- "How urgent is it to patch CVE-XXXX-NNNN?" You get NVD's summary and CVSS, whether CISA lists it as exploited (with due date), the FIRST EPSS exploit probability, affected packages and fixed versions from OSV, and a plain `patchUrgency` rating with reasons.
- "Is this package version vulnerable?" Give an ecosystem, package and version; you get one merged record per matching CVE and the worst rating.
- CISA KEV questions: what was added in the last N days, is this CVE in KEV, which KEV entries match a vendor or product, and a batch check of up to 50 CVEs.

## When to use it

- A coding or security agent wants one merged answer instead of querying four sources and handling NVD's rate limit.
- Triage: sort a list of CVEs by KEV status and EPSS.

## When not to

- `patchUrgency` is a heuristic merge of KEV, EPSS and CVSS. It is not a substitute for your own risk process.
- Package queries: only OSV matches that map to a CVE id are enriched, and at most 8 per query. An empty `vulns` list does not prove a version is safe; check `osvTotalReported`.
- NVD allows 5 requests per 30 seconds without a key and this tool has no key support. A busy run can come back with NVD fields empty. Always read `sources.nvd.ok`, `sources.kev.ok`, `sources.epss.ok` and `sources.osv.ok`; a rating built without KEV data can read too low.
- Not a scanner. It does not look at your code or dependency files.

## Example (MCP tool `vuln_intel`, or CLI)

```bash
npx tsx src/cli.ts --cve CVE-2021-44228
```
Trimmed output (shape and values from `samples/cve-2021-44228.json`, a run on 2026-10-31):
```json
{
  "tool": "vuln-intel-json",
  "version": "0.1.0",
  "cve": "CVE-2021-44228",
  "summary": "Apache Log4j2 2.0-beta9 through 2.15.0 ...",
  "vulnStatus": "Analyzed",
  "cvss": { "version": "3.1", "baseScore": 10, "baseSeverity": "CRITICAL", "source": "nvd@nist.gov" },
  "kev": { "listed": true,
           "entry": { "vendorProject": "Apache", "product": "Log4j2", "dateAdded": "2021-12-10",
                      "dueDate": "2021-12-24", "overdue": true, "ransomwareKnown": true } },
  "epss": { "score": 0.99999, "percentile": 1, "date": "2026-10-31",
            "attribution": "See EPSS at https://www.first.org/epss" },
  "affectedPackages": [ { "ecosystem": "Maven", "name": "org.apache.logging.log4j:log4j-core",
                          "introduced": ["2.13.0"], "fixed": ["2.15.0"] } ],
  "patchUrgency": { "rating": "critical",
                    "reasons": ["Listed on CISA Known Exploited Vulnerabilities (KEV) ...", "EPSS exploit probability 100.0% (at least 70%)"],
                    "note": "Heuristic merge of KEV + EPSS + CVSS - not a substitute for your own risk process" },
  "sources": { "nvd": { "ok": true }, "kev": { "ok": true, "catalogVersion": "2026.10.30" }, "epss": { "ok": true }, "osv": { "ok": true } },
  "provenance": { "fetchedAt": "2026-10-31T...Z", "toolVersion": "0.1.0" },
  "notices": ["This product uses data from the NVD API but is not endorsed or certified by the NVD.", "See EPSS at https://www.first.org/epss"]
}
```
`rating` is one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Other calls: `--ecosystem Maven --package <name> --version <v>` (package), `--kev-recent --days 30`, `--kev-lookup --cve ...`, `--kev-search --vendor ...`, `--kev-check --cves A,B`.

## Data sources and licence

NVD (NIST), CISA KEV (CC0 1.0 per the package; no CISA logo or DHS seal), FIRST EPSS (free to the public, attribution requested), and OSV.dev (each advisory keeps its own licence, often CC BY 4.0, CC0, MIT or Apache-2.0, and some are ShareAlike). The tool is not endorsed by NIST, CISA, FIRST or the OSV maintainers. The NVD notice and EPSS attribution are returned in every record. Check each source's terms for your own use.

## Freshness and limits

- Cached in local files: NVD and OSV 1 hour, EPSS 6 hours, the KEV catalog 6 hours. `sources.*.cached` and `provenance.fetchedAt` show what was used.
- Package queries enrich at most 8 matches; `truncated` says when OSV reported more.
- `kev_recent` window 1 to 365 days; `kev_search` returns up to 100 (default 25); `kev_check` takes up to 50 CVEs.
- Depends on four public services being up; a missing source shows in `sources`.