cve-check

Enrich CVE IDs with severity, exploitability, and remediation data by querying public feeds (CISA KEV/Vulnrichment, FIRST EPSS, NVD, Metasploit, Nuclei, Exploit-DB, GitHub PoC aggregators, OSV, vendor trackers, endoflife.date).

Run

python3 cve-check.py CVE-2021-44228 CVE-2020-1472
python3 cve-check.py --refresh CVE-2021-44228        # force-refresh cached feeds
python3 cve-check.py --json CVE-2021-44228           # machine-parseable output
python3 cve-check.py --file cves.txt                 # read CVE IDs from a file
scanner-dump | python3 cve-check.py --file -         # ...or from stdin
python3 cve-check.py --debug CVE-2021-44228          # log why a source came back empty
python3 cve-check.py --fail-on critical --file cves.txt   # gate CI on CRITICAL only
python3 cve-check.py --explain CVE-2021-44228             # show why it got that tier
python3 cve-check.py --csv --file cves.txt                # spreadsheet-ready summary
python3 cve-check.py --markdown CVE-2021-44228            # paste-ready report/ticket body
python3 cve-check.py --sarif --file scan.txt > out.sarif  # CI / code-scanning ingestion

Pass any number of CVE IDs. Non-CVE args are ignored. --file PATH (or - for stdin) scrapes every CVE-… ID out of an arbitrary text/scanner dump. Output goes to stdout; progress/warnings to stderr. When more than one CVE is given, a priority-sorted summary table prints before the per-CVE detail.

Exit code (for CI gating), controlled by --fail-on (default high): high -> 2 if any CRITICAL, 1 if any HIGH, else 0; critical -> 2 only if any CRITICAL, else 0; never -> always 0. E.g. cve-check.py --file cves.txt || fail-the-build. Note: an uncaught error also exits nonzero, so --fail-on critical gives the cleanest CI signal.

Output formats — exactly one of --json, --csv, --markdown, --sarif may be given (mixing them exits 2); omit all for the human-readable text report.

• --json — prefer this when you (Claude) are consuming the result. Flat array (one object per CVE) with stable keys: tier, cvss, cwe, cpe, description, ssvc, kev/kev_details, epss, fixed_versions, mitigations, vendors, eol, exploits. Parse those fields instead of scraping the formatted report.
• --csv — one row per CVE, priority-sorted, for spreadsheet triage.
• --markdown — one paste-ready document (summary table + per-CVE sections) for a ticket, PR comment, or status report.
• --sarif — SARIF 2.1.0 for CI/code-scanning ingestion. With --file, each result is located at the actual line/column the CVE ID was found on in that file; without --file, results are fileless (keyed by CVE ID).

--explain stacks with any format (including the default text report). It adds the cascade of tier checks that were evaluated — which ones were ruled out and why, and which one actually fired — instead of just the tier label. Reach for it when the user asks "why is this CRITICAL/HIGH/etc." or when justifying a priority call in a writeup.

Notes

• NVD_API_KEY (optional but recommended): set the env var to avoid NVD rate limiting (403s), especially when querying several CVEs. Without it, CVSS may come back "NVD API Rate Limited".
• VULNCHECK_API_KEY (optional): enables VulnCheck Community KEV, broader in-the-wild coverage than CISA KEV. Skipped silently if unset.
• GITHUB_TOKEN (optional): raises the GitHub repo-search rate limit (10 req/min unauthenticated). GitHub search runs alongside the nomi-sec/trickest aggregators so fresh CVEs whose PoCs aren't indexed yet are still found.
• Feeds are cached 24h under ~/.cache/cve-check (KEV/MSF/Nuclei/EDB indexes plus all vendor-advisory scrape pages, Arch JSON, and endoflife.date — so they download once, not once per CVE); each CVE's full assessment is cached 6h under ~/.cache/cve-check/cve/. Rate-limited/partial assessments are not cached. First run is slow; later runs are fast. --refresh bypasses both.
• --debug: log to stderr why any source returned empty (network error vs. genuinely no data) — use when a section is blank and you can't tell which.
• TLS behind a corporate proxy: if fetches fail with CERTIFICATE_VERIFY_FAILED (a MITM proxy like Zscaler resigning certs), point SSL_CERT_FILE at your corporate CA bundle (safe, keeps verification). Last resort: --insecure disables cert verification entirely (traffic can be intercepted — avoid on untrusted networks).
• Pure stdlib, network required. No install step. Offline logic is covered by test_cve_check.py (python3 test_cve_check.py).

Output sections

1. Threat Intelligence & Enrichment — exploit tier, CVSS (with vector), CWE, CPE, description, CISA SSVC, mitigations / fixed versions / NVD patch links.
2. Ecosystem & Vendor Impact — OSV ecosystems, Red Hat / Debian / Arch, scraped vendor advisories, end-of-life status.
3. Public Exploitability — CISA KEV (+ransomware flag), VulnCheck KEV, EPSS %, Metasploit modules, Exploit-DB entries, Nuclei template, GitHub PoC repos.

Priority tier

Remediation urgency = likelihood x impact, combining KEV / EPSS / SSVC / exploit maturity / CVSS (thresholds tunable in assess()):

• CRITICAL Exploited in the wild — listed in CISA KEV or VulnCheck KEV (— ransomware if flagged).
• HIGH — EPSS >= 50%, a weaponized exploit (MSF exploit module or >=Great rank), or SSVC Exploitation: active.
• MEDIUM — public working exploit (Exploit-DB, any MSF module, popular PoC

  =50 stars), EPSS >= 10%, or CVSS base >= 9.0.

• LOW — a PoC/template exists but nothing weaponized.
• INFO — no public exploit found.

Tier → action

• CRITICAL / HIGH — patch now; if unpatchable, apply the mitigation/workaround shown.
• MEDIUM — schedule promptly; prioritize if internet-facing or matches your stack (see CPE).
• LOW / INFO — track; reassess if it later lands in KEV or EPSS climbs.

Guidance for Claude

• Batch: pass every requested CVE in a single invocation — feeds are cached and per-CVE lookups run in parallel, so one call with N CVEs is far faster than N calls.
• Summarize, don't dump: lead with tier + KEV + CVSS + fixed version. PoC lists can be hundreds of repos — cite the top few by stars, not all of them.
• Never fabricate: Unknown, NVD API Rate Limited, or an empty section means the data source was unavailable or silent — not that there is no risk. Say "not available", don't infer safety. If CVSS is rate-limited, suggest setting NVD_API_KEY and/or --refresh.
• Coverage is partial: KEV/MSF/EDB/vendor scrapes cover specific products; absence of a vendor hit does not mean unaffected. A single low tier across sparse data is weaker evidence than a high tier.
• Justify a tier with --explain rather than re-deriving the reasoning yourself from raw KEV/EPSS/CVSS fields — it returns the exact thresholds the script evaluated, so it can't drift from the actual classification logic.
• Match the format to the deliverable: --json to reason over the data yourself, --csv when the user wants a spreadsheet, --markdown when they want a ticket/report body they can paste as-is, --sarif when the target is a CI pipeline or code-scanning tool rather than a person.