`cve_lookup`¶

Authoritative data for one CVE, fused from three canonical feeds into a single record with per-field provenance.

Use it before rating or reporting any CVE. A recalled CVSS score goes stale, and affected-version detail is the easiest thing in security work to misremember with confidence. Every source is keyless, so the tool is always registered.

Parameters¶

Parameter	Type	Default	Description
`cve_id`	string	required	The identifier, e.g. `CVE-2021-44228`. Case-insensitive; validated against the `CVE-YYYY-NNNN` shape before any request.
`action`	string	`get`	Only `get` — one CVE by id — is supported.
`refresh`	boolean	`false`	Re-fetch from every source, ignoring the cache. Only worth setting for a CVE published or revised inside the cache TTL.

Sources¶

Source	Contributes	Answers
NVD	CVSS score, severity, vector, CWE, description, references	How bad is it, in the abstract?
CISA-KEV	Whether the CVE is on the Known Exploited Vulnerabilities catalog	Is it being exploited in the wild right now?
EPSS	Exploitation probability score	How likely is exploitation in the next 30 days?

The three are merged into one record that records which source supplied each field, so a partial answer is still a usable one. If NVD is unreachable but KEV answers, you still learn the most urgent fact available.

KEV and EPSS outrank CVSS for prioritization

A CVSS 9.8 nobody is exploiting is a lower priority than a CVSS 7.5 on the KEV catalog. Rank by what is actually happening, and use CVSS for the technical severity of the flaw rather than the urgency of the finding.

A KEV listing is also proof the identifier is real. A bare "not on the KEV catalog" is not proof of anything — it comes back identically for a CVE that does not exist — so the tool does not treat KEV non-membership alone as data.

Caching¶

Records are cached on disk under INTEL_CACHE_DIR for CVE_CACHE_TTL_HOURS (24), so repeat lookups cost nothing.

Negative answers are cached too. That stops an unknown identifier re-hitting three APIs on every mention, and it means a refresh that now finds nothing correctly overwrites a stale positive. A cache write that fails — a read-only or full cache directory — is logged and ignored rather than discarding data already fetched.

Approval¶

Approval widens to the whole tool: every call is a keyless read of public vulnerability intelligence, and there is nothing below it worth distinguishing. The packaged rules do not auto-approve it, so it prompts in strict and normal — allow: "cve_lookup({})" in ~/.kerkov/approvals.yaml is a sensible addition if you look up CVEs often.

Returns¶

A compact human-readable summary as output: the id, CVSS score and severity, title, vector, CWE, KEV status, EPSS score, and references.

Metadata carries action, cve_id, cache_hit, and record — the complete merged record, including the per-source provenance the summary leaves out.

Two shapes of "nothing found" are distinguished, and the difference matters:

Every source that could answer failed → success: false. This is a network or availability problem; retry.
The sources answered, and none of them knows this CVE → success: true with a note to check the identifier. A very recently published CVE may simply not be indexed yet.

Examples¶

{ "cve_id": "CVE-2021-44228" }

Forcing a re-fetch of a CVE that was revised today:

{ "cve_id": "CVE-2026-1234", "refresh": true }

Configuration¶

Variable	Default	Effect
`NVD_API_KEY`	(unset)	Optional. Raises NVD's rate limit; nothing else.
`CVE_CACHE_TTL_HOURS`	`24`	Cache lifetime for merged records.
`INTEL_CACHE_DIR`	`~/.kerkov/cache/intel`	Cache location.
`CVE_LOOKUP_TIMEOUT_SECONDS`	`15`	Per-source request timeout.

vulnerability_scan — finds which CVEs apply to a target; cve_lookup says how much each one matters.
web_search and read_url — for what the feeds do not carry: exploit availability, vendor advisories, writeups.
ledger — record the CVE as a finding once it is confirmed, so it survives compaction.

cve_lookup¶