A dependency-free API client for the CISA Known Exploited Vulnerabilities (KEV) catalogue
Project description
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
- Determine which vulnerabilities have been added to the catalog, when those vulnerabilities must be patched, and which vulnerabilities are overdue for patching
Installation
To install the client locally:
python3 -m pip install cisa_kev
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"}
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.