cisa-kev 1.0.1

A dependency-free API client for the CISA Known Exploited Vulnerabilities (KEV) catalogue

CISA Known Exploited Vulnerabilities (KEV) Catalog client

A dependency-free Python 3 client for the CISA Known Exploited Vulnerabilities (KEV) Catalog.

Features

• Download the latest copy of the catalog in JSON format or work with a local copy
• Query the catalog via the command line

Installation

To install using pip:

python3 -m pip install cisa_kev

To add to a Poetry project:

poetry add cisa_kev

To install from source:

poetry install

Usage

Command line interface

The command line interface only has a single command and allows you to query a local or remote copy of the catalog (i.e. using a local file or a URL).

python3 -m cisa_kev --help

usage: kev.py [-h] [--vendor VENDOR] [--product PRODUCT] [--ransomware] [--overdue] [--not-overdue]
              [--input-file INPUT_FILE] [--fallback-url FALLBACK_URL] [--output-file OUTPUT_FILE]
              [--output-type {full,cve_ids,dates,date_added,due_date}] [--output-format {json,jsonl}] [--indent INDENT]

CISA Known Exploited Vulnerabilities (KEV) Catalog

options:
  -h, --help            show this help message and exit
  --vendor VENDOR       Show vulnerabilities by vendor name
  --product PRODUCT     Show vulnerabilities by product name
  --ransomware          Show vulnerabilities related to ransomware campaigns
  --overdue             Show vulnerabilities that are overdue for patching
  --not-overdue         Hide vulnerabilities that are overdue for patching
  --input-file INPUT_FILE, -i INPUT_FILE
                        Input file (JSON)
  --fallback-url FALLBACK_URL, -u FALLBACK_URL
                        Fallback URL
  --output-file OUTPUT_FILE, -o OUTPUT_FILE
                        Output file
  --output-type {full,cve_ids,dates,date_added,due_date}, -t {full,cve_ids,dates,date_added,due_date}
                        Output type (i.e. what to output)
  --output-format {json,jsonl}, -f {json,jsonl}
                        Output format (i.e. how to output)
  --indent INDENT       Indentation level

Throughout this guide, the following commands are equivalent:

python3 cisa_kev/kev.py

python3 -m cisa_kev

poetry run kev

curl https://raw.githubusercontent.com/whitfieldsdad/cisa_kev/main/cisa_kev/kev.py -s | python3 -

wget -qO- https://raw.githubusercontent.com/whitfieldsdad/cisa_kev/main/cisa_kev/kev.py | python3 -

powershell -command "& { Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/whitfieldsdad/cisa_kev/main/cisa_kev/kev.py' -UseBasicParsing | Invoke-Expression }"

ℹ️ Glob patterns are supported and all pattern matching is performed case insensitively (i.e. you could use --vendor microsoft or --vendor Microsoft interchangeably).

Downloading the catalog

The catalog is available in CSV or JSON format, but at this time, only the JSON format is supported by this client.

The following command will download the catalog in JSON format, transform it, and save it to a local file:

python3 cisa_kev/kev.py -o data/known_exploited_vulnerabilities.json

The structure of the file will be as follows:

{
  "version": "2024.01.08",
  "time_released": "2024-01-08T15:01:52.959100+00:00",
  "vulnerabilities": [
    {
      "cve_id": "CVE-2021-34527",
      "vendor": "Microsoft",
      "product": "Windows",
      "name": "Microsoft Windows Print Spooler Remote Code Execution Vulnerability",
      "description": "Microsoft Windows Print Spooler contains an unspecified vulnerability due to the Windows Print Spooler service improperly performing privileged file operations. Successful exploitation allows an attacker to perform remote code execution with SYSTEM privileges. The vulnerability is also known under the moniker of PrintNightmare.",
      "date_added": "2021-11-03",
      "due_date": "2021-07-20",
      "required_action": "Apply updates per vendor instructions.",
      "known_ransomware_campaign_use": true,
      "notes": "Reference CISA's ED 21-04 (https://www.cisa.gov/emergency-directive-21-04) for further guidance and requirements."
    },
    ...
  ]
}

To download the catalog without modifying it you could use curl:

curl https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json -o data/known_exploited_vulnerabilities.json

Or, wget:

wget -qO- https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json -O data/known_exploited_vulnerabilities.json

The structure of the catalog will be as follows and is described in a JSON schema maintained by CISA.

{
    "title": "CISA Catalog of Known Exploited Vulnerabilities",
    "catalogVersion": "2024.01.08",
    "dateReleased": "2024-01-08T15:01:52.9591Z",
    "count": 1061,
    "vulnerabilities": [
        {
            "cveID": "CVE-2021-34527",
            "vendorProject": "Microsoft",
            "product": "Windows",
            "vulnerabilityName": "Microsoft Windows Print Spooler Remote Code Execution Vulnerability",
            "dateAdded": "2021-11-03",
            "shortDescription": "Microsoft Windows Print Spooler contains an unspecified vulnerability due to the Windows Print Spooler service improperly performing privileged file operations. Successful exploitation allows an attacker to perform remote code execution with SYSTEM privileges. The vulnerability is also known under the moniker of PrintNightmare.",
            "requiredAction": "Apply updates per vendor instructions.",
            "dueDate": "2021-07-20",
            "knownRansomwareCampaignUse": "Known",
            "notes": "Reference CISA's ED 21-04 (https:\/\/www.cisa.gov\/emergency-directive-21-04) for further guidance and requirements."
        },
        ...
    ]
}

Query the catalog via the command line

To search for vulnerabilities by vendor name, use the --vendor option:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --vendor microsoft --output-format=jsonl | jq -r '.cve_id'

...
CVE-2023-36884
CVE-2023-38180
CVE-2023-41763

To search for vulnerabilities by product name, use the --product option:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --vendor apache --product 'log4j*' --output-format=jsonl | jq -r '.cve_id'

...
CVE-2021-44228
CVE-2021-45046

To search for vulnerabilities related to ransomware campaigns, use the --ransomware option:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --ransomware --output-format=jsonl | jq -r '.cve_id'

...
CVE-2023-42793
CVE-2023-46604
CVE-2023-4966

To search for vulnerabilities that are overdue for patching, use the --overdue option:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --overdue --output-format=jsonl | jq -r '.cve_id'

CVE-2023-5631
CVE-2023-6345
CVE-2023-6448
...

To see when the vulnerabilities are due, you can either list the entire entries:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --overdue --output-format=jsonl | jq

...
{
  "cve_id": "CVE-2023-32049",
  "vendor": "Microsoft",
  "product": "Windows",
  "name": "Microsoft Windows Defender SmartScreen Security Feature Bypass Vulnerability",
  "description": "Microsoft Windows Defender SmartScreen contains a security feature bypass vulnerability that allows an attacker to bypass the Open File - Security Warning prompt.",
  "date_added": "2023-07-11",
  "due_date": "2023-08-01",
  "required_action": "Apply updates per vendor instructions or discontinue use of the product if updates are unavailable.",
  "known_ransomware_campaign_use": false,
  "notes": "https://msrc.microsoft.com/update-guide/en-US/vulnerability/CVE-2023-32049"
}
...

Or, just the dates:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --overdue --output-format=jsonl --output-type dates | jq -c

...
{"cve_id":"CVE-2023-41266","date_added":"2023-12-07","due_date":"2023-12-28"}
{"cve_id":"CVE-2023-41265","date_added":"2023-12-07","due_date":"2023-12-28"}
{"cve_id":"CVE-2023-6448","date_added":"2023-12-11","due_date":"2023-12-18"}

To lookup a specific vulnerability, use the --cve-id option:

python3 cisa_kev/kev.py -i data/known_exploited_vulnerabilities.json --cve-id CVE-2020-0796 --output-format=jsonl --output-ty
pe dates | jq -c

{"cve_id":"CVE-2020-0796","date_added":"2022-02-10","due_date":"2022-08-10"}