tools.cisa_kev_tools module

Search CISA’s Known Exploited Vulnerabilities (KEV) catalog.

Uses the official JSON feed from https://www.cisa.gov/known-exploited-vulnerabilities

async tools.cisa_kev_tools.run(cve_id='', vendor_project='', product='', vulnerability_name='', short_description='', required_action='', notes='', known_ransomware_campaign_use='', cwe='', date_added_on_or_after='', date_added_on_or_before='', due_on_or_after='', due_on_or_before='', field_filters=None, limit=50, force_refresh=False, ctx=None)[source]

Search the CISA Known Exploited Vulnerabilities catalog and return JSON.

The single entry point for the search_cisa_kev_catalog tool. It validates the request, loads the (cached) KEV feed, applies every supplied filter as a logical AND across the catalog, and returns the matching vulnerability records as a JSON document. Filtering covers exact CVE match, case-insensitive substring matches on the text fields, CWE overlap, inclusive ISO date bounds on dateAdded and dueDate, and an open-ended field_filters map; the result count is capped at limit (itself clamped to MAX_LIMIT) with a truncated flag when more matched than were returned.

It first checks field_filters via _validate_field_filters(), parses the four date bounds with _parse_iso_date(), then obtains the catalog through _get_catalog() (which serves a process-wide cached copy or, on a miss or force_refresh, fetches the live feed over HTTPS via _fetch_json()). Per-record matching delegates to _cve_exact() (with _normalize_cve()), _substr_match(), _cwe_match(), _vuln_date_iso(), and _field_filter_value(). The only external side effect is the possible network fetch; the ctx argument is unused. Dispatched by the tool loader as the module’s run handler; not called directly elsewhere.

Parameters:

  • cve_id (str) – Exact CVE id (normalized before matching).

  • vendor_project (str) – Substring filter on vendorProject.

  • product (str) – Substring filter on product.

  • vulnerability_name (str) – Substring filter on vulnerabilityName.

  • short_description (str) – Substring filter on shortDescription.

  • required_action (str) – Substring filter on requiredAction.

  • notes (str) – Substring filter on notes.

  • known_ransomware_campaign_use (str) – Substring filter on knownRansomwareCampaignUse.

  • cwe (str) – CWE token matched against the record’s cwes list.

  • date_added_on_or_after (str) – Inclusive lower dateAdded bound (YYYY-MM-DD).

  • date_added_on_or_before (str) – Inclusive upper dateAdded bound.

  • due_on_or_after (str) – Inclusive lower dueDate bound.

  • due_on_or_before (str) – Inclusive upper dueDate bound.

  • field_filters (dict[str, Any] | None) – Extra feed-field filters (keys restricted to _VULN_FIELD_KEYS).

  • limit (int) – Maximum records to return (clamped to [1, MAX_LIMIT]).

  • force_refresh (bool) – If True, bypass the cache and refetch the feed.

  • ctx (ToolContext | None) – Tool context; accepted but unused.

Returns:

A JSON string with catalog metadata, the total match_count, a truncated flag, and the (capped) vulnerabilities list; or a JSON error payload when validation fails or the feed cannot be fetched.

Return type:

str