NVDLib allows you to grab data on a single CVE if the CVE ID is known. This is useful if you know the CVE but you need to know something about it such as the score, publish date, etc.
You can also use this to iterate through a list of CVE IDs if you have a list of known CVE IDs.
Begin by importing NVDLib:
>>> import nvdlib
Lets grab CVE-2017-0144.
>>> r = nvdlib.searchCVE(cveId='CVE-2017-0144')
Example with an API key (insert your own API key).
>>> r = nvdlib.searchCVE(cveId='CVE-2017-0144', key='xxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxx', delay=6)
Due to rate limiting restrictions by NVD, a request will take 6 seconds with no API key. Requests with an API key have the ability to define a delay argument. The delay argument must be a integer/float greater than or equal to 0.6 (seconds).
Get a NIST NVD API key here (free): https://nvd.nist.gov/developers/request-an-api-key
nvdlib.searchCVE() will always return a list. Since we are obtaining a single CVE, there will always only be 1 element in the list
when using the cveId argument. From this point you are able to retrieve information on the CVE. Here is a method to print the version 3 CVSS severity on a single CVE after a search has been ran.
>>> print(r.v3severity) HIGH
If you just need a score and severity from a CVE, you can use the score attribute that contains a list. This exists on all CVE objects and will prefer version 3.1 scoring. If version 3.1 scoring does not exist, it will use version 3.0 and so on. If no scoring exists for the CVE, it will set all values to None. The first element is the CVSS version, then score, and severity.
>>> print(r.score) ['V30', 8.1, 'HIGH']
Below are all of the accessible variables within a CVE. Since these are assigned as is from the response of the API, I recommend printing some of the values to get an idea of what they will return. You can see what the JSON API response looks like and more details here https://nvd.nist.gov/developers/vulnerabilities
- class nvdlib.classes.CVE(response)¶
- JSON dump class for CVEs
For more information the values returned from a CVE, please visit https://nvd.nist.gov/developers/vulnerabilities
id (str) – CVE ID
sourceIdentifier (str) – Contact who reported the vulnerability.
published (str) – CVE publication date. ISO 8601 date/time format.
lastModified (str) – CVE modified date. ISO 8601 date/time format.
vulnStatus (str) – CVE modified status.
exploitAdd (str) – Optional, only exists if the CVE is listed in the Known Exploited Vulnerabilities (KEV) catalog.
actionDue (str) – Optional, only exists if the CVE is listed in the Known Exploited Vulnerabilities (KEV) catalog.
requiredAction (str) – Optional, only exists if the CVE is listed in the Known Exploited Vulnerabilities (KEV) catalog.
descriptions (list) – CVE descriptions. Includes other languages.
metrics (dict) – Class attribute containing scoring lists (cvssMetricV31 / V30 / V2).
weaknesses (list) – Contains relevant CWE information.
configurations – List containing usually a single element of CPE information.
references (list) – CVE reference links
cwe (list) – Common Weakness Enumeration Specification (CWE)
url (str) – Link to additional details on nvd.nist.gov for that CVE.
cpe (list) – Common Platform Enumeration (CPE) assigned to the CVE.
metrics – CVSS metrics. Some CVEs may not have v2/v3 scores or none at all.
v30score – List that contains V3.0 CVSS score (float 1 - 10) as index 0 and the version that score was taken from as index 1.
v2vector (str) – Version two of the CVSS score represented as a vector string, a compressed textual representation of the values used to derive the score. Example: ‘AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H’
v3vector (str) – Version three of the CVSS score represented as a vector string.
v2severity (str) – LOW, MEDIUM, HIGH (Critical is only available for v3).
v3severity (str) – LOW, MEDIUM, HIGH, CRITICAL.
v2exploitability (float) – Version 2 CVSS exploitability. Reflects the ease and technical means by which the vulnerability can be exploited.
v3exploitability (float) – Version 3 CVSS exploitability. Reflects the ease and technical means by which the vulnerability can be exploited.
v2impactScore (float) – Reflects the direct consequence of a successful exploit.
v3impactScore (float) – Reflects the direct consequence of a successful exploit.
score (list) – Contains the v3 CVSS score (v2 if v3 isn’t available) [score, severity, version]. Where score is an int, severity is a string(‘LOW’,’MEDIUM’,’HIGH’,’CRITICAL’), and version is a string (V3 or V2).
Searching for CVEs will return a list containing the objects of all of the CVEs the search had found.
- Example search for all vulnerabilities for Microsoft Exchange 2013, cumulative_update_11 and a limit of two:
>>> r = nvdlib.searchCVE(cpeName = 'cpe:2.3:a:microsoft:exchange_server:2013:cumulative_update_11:*:*:*:*:*:*', limit = 2)
Now we have the results of the search in a list containing each CVE.
>>> type(r) <class 'list'> >>> for eachCVE in r: ... print(eachCVE.id) CVE-1999-1322 CVE-2016-0032
Below are all of the available parameters when searching for a collection of CVEs, along with what is expected to be passed to that parameter.
- nvdlib.cve.searchCVE(cpeName=False, cveId=False, cvssV2Metrics=False, cvssV2Severity=False, cvssV3Metrics=False, cvssV3Severity=False, cweId=False, hasCertAlerts=False, hasCertNotes=False, hasKev=False, hasOval=False, isVulnerable=False, keywordExactMatch=False, keywordSearch=False, lastModStartDate=False, lastModEndDate=False, pubStartDate=False, pubEndDate=False, sourceIdentifier=False, virtualMatchString=False, limit=False, delay=False, key=False, verbose=False)¶
Build and send GET request then return list of objects containing a collection of CVEs. For more information on the parameters available, please visit https://nvd.nist.gov/developers/vulnerabilities
cpeName (str) – This value will be compared agains the CPE Match Criteria within a CVE applicability statement. (i.e. find the vulnerabilities attached to that CPE). Partial match strings are allowed.
cveId (str) – Returns a single CVE that already exists in the NVD.
cvssV2Metrics (str) – This parameter returns only the CVEs that match the provided CVSSv2 vector string. Either full or partial vector strings may be used. This parameter cannot be used in requests that include cvssV3Metrics.
cvssV2Severity (str) – Find vulnerabilities having a ‘LOW’, ‘MEDIUM’, or ‘HIGH’ version 2 severity.
cvssV3Metrics (str) – This parameter returns only the CVEs that match the provided CVSSv3 vector string. Either full or partial vector strings may be used. This parameter cannot be used in requests that include cvssV2Metrics.
cvssV3Severity (str) – Find vulnerabilities having a ‘LOW’, ‘MEDIUM’, ‘HIGH’, or ‘CRITICAL’ version 3 severity.
cweId (str) – Filter collection by CWE (Common Weakness Enumeration) ID. You can find a list at https://cwe.mitre.org/. A CVE can have multiple CWE IDs assigned to it.
hasCertAlerts (bool) – Returns CVE that contain a Technical Alert from US-CERT.
hasCertNotes (bool) – Returns CVE that contain a Vulnerability Note from CERT/CC.
hasOval (bool) – Returns CVE that contain information from MITRE’s Open Vulnerability and Assessment Language (OVAL) before this transitioned to the Center for Internet Security (CIS).
isVulnerable (bool) – Returns CVE associated with a specific CPE, where the CPE is also considered vulnerable. REQUIRES cpeName parameter. isVulnerable is not compatible with virtualMatchString parameter.
keywordExactMatch (bool) – When keywordSearch is used along with keywordExactmatch, it will search the NVD for CVEs containing exactly what was passed to keywordSearch. REQUIRES keywordSearch.
keywordSearch (str) – Searches CVEs where a word or phrase is found in the current description. If passing multiple keywords with a space character in between then each word must exist somewhere in the description, not necessarily together unless keywordExactMatch=True is passed to searchCVE.
lastModStartDate (str,datetime obj) – These parameters return only the CVEs that were last modified during the specified period. If a CVE has been modified more recently than the specified period, it will not be included in the response. If filtering by the last modified date, both lastModStartDate and lastModEndDate are REQUIRED. The maximum allowable range when using any date range parameters is 120 consecutive days.
lastModEndDate (str, datetime obj) – Required if using lastModStartDate.
pubStartDate (str,datetime obj) – These parameters return only the CVEs that were added to the NVD (i.e., published) during the specified period. If filtering by the published date, both pubStartDate and pubEndDate are REQUIRED. The maximum allowable range when using any date range parameters is 120 consecutive days.
pubEndDate (str, datetime obj) – Required if using pubStartDate.
sourceIdentifier (str) – Returns CVE where the data source of the CVE is the value that is passed to sourceIdentifier.
virtualMatchString (str) – A more broad filter compared to cpeName. The cpe match string that is passed to virtualMatchString is compared against the CPE Match Criteria present on CVE applicability statements.
limit (int) – Custom argument to limit the number of results of the search. Allowed any number between 1 and 2000.
delay (int) – Can only be used if an API key is provided. This allows the user to define a delay. The delay must be greater than 0.6 seconds. The NVD API recommends scripts sleep for atleast 6 seconds in between requests.
key (str) – NVD API Key. Allows for the user to define a delay. NVD recommends scripts sleep 6 seconds in between requests. If no valid API key is provided, requests are sent with a 6 second delay.
verbose (bool) – Prints the URL request for debugging purposes.
The arguments are not positional. SearchCVE will build the request based on what is passed to it. All of the parameters can be mixed together in any order. If a value is not passed to the function, it is assumed to be false and will not be added to the filter.
There is a maximum 120 day range when using date ranges. If searching publication or modified dates, start and end dates are required. A datetime object can also be used instead of a string.
Filter by publication start and end date, keyword, version 3 severity of critical, and an API key.
>>> r = nvdlib.searchCVE(pubStartDate = '2021-09-08 00:00', pubEndDate = '2021-12-01 00:00', keywordSearch = 'Microsoft Exchange', cvssV3Severity = 'Critical', key='xxxxx-xxxxxx-xxxxxxx', delay=6)
Get all CVEs in the last 7 days using a datetime object and use an API key.
>>> import datetime >>> end = datetime.datetime.now() >>> start = end - datetime.timedelta(days=7) >>> r = nvdlib.searchCVE(pubStartDate=start, pubEndDate=end, key='xxxxx-xxxxxx-xxxxxxx')
Filter for publications between 2019-06-02 and 2019-06-08:
>>> r = nvdlib.searchCVE(pubStartDate = '2019-06-08 00:00', pubEndDate = '2019-06-08 00:00')
Filter by CPE name and keyword with keyword exact match enabled:
>>> r = nvdlib.searchCVE(cpeName = 'cpe:2.3:a:microsoft:exchange_server:2013:cumulative_update_11:*:*:*:*:*:*', keywordSearch = '1ArcServe', keywordExactMatch = True)
Filter by CPE name, keyword, exact match enabled, and isVulnerable enabled:
>>> r = nvdlib.searchCVE(cpeName = 'cpe:2.3:a:microsoft:exchange_server:2013:cumulative_update_11:*:*:*:*:*:*', keywordSearch = '1ArcServe', keywordExactMatch = True, isVulnerable = True)
Get the CVE IDs, score, and URL of all CVEs with a specific CPE name:
r = nvdlib.searchCVE(cpeName = 'cpe:2.3:a:microsoft:exchange_server:5.0:-:*:*:*:*:*:*') for eachCVE in r: print(eachCVE.id, str(eachCVE.score), eachCVE.url)
Grab the CPE names that match a CVE.
r = nvdlib.searchCVE(cpeName = 'cpe:2.3:a:microsoft:exchange_server:2013:cumulative_update_11:*:*:*:*:*:*') for eachCVE in r: print(eachCVE.cpe)
Search for 100 CVEs that have a source identifier of firstname.lastname@example.org
>>> r = nvdlib.searchCVE(sourceIdentifier = 'email@example.com', limit = 100)