CVE¶

Single CVE¶

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)

Note

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[0].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[0].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)[source]¶

JSON dump class for CVEs: For more information the values returned from a CVE, please visit https://nvd.nist.gov/developers/vulnerabilities

Variables

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.
v31score (int) – Integer that contains V3.1 CVSS score (float 1 - 10). Optional, some CVEs may not contain version 3.1 CVSS scoring.
v30score (int) – Integer that contains V3.0 CVSS score (float 1 - 10) Optional, some CVEs may not contain version 3.0 CVSS scoring.
v2score (int) – Integer that contains V2 CVSS score (float 1 - 10) Optional, some CVEs may not contain version 2 CVSS scoring.
v31vector (str) – Version 3.1 of the CVSS score represented as a vector string. Optional, some CVEs may not contain version 3.1 CVSS scoring.
v30vector (str) – Version 3.0 of the CVSS score represented as a vector string. Optional, some CVEs may not contain version 3.0 CVSS scoring.
v2vector (str) – Version 2 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’. Optional, some CVEs may not contain version 2 CVSS scoring.
v31severity (str) – LOW, MEDIUM, HIGH, CRITICAL. Optional, some CVEs may not contain version 3.1 CVSS scoring.
v30severity (str) – LOW, MEDIUM, HIGH, CRITICAL. Optional, some CVEs may not contain version 3.0 CVSS scoring.
v2severity (str) – LOW, MEDIUM, HIGH (Critical is only available for v3). Optional, some CVEs may not contain version 2 CVSS scoring.
v31exploitability (float) – Version 3.1 CVSS exploitability. Reflects the ease and technical means by which the vulnerability can be exploited. Optional, some CVEs may not contain version 3.1 CVSS scoring.
v30exploitability (float) – Version 3.0 CVSS exploitability. Reflects the ease and technical means by which the vulnerability can be exploited. Optional, some CVEs may not contain version 3.0 CVSS scoring.
v2exploitability (float) – Version 2 CVSS exploitability. Reflects the ease and technical means by which the vulnerability can be exploited. Optional, some CVEs may not contain version 2 CVSS scoring.
v31impactScore (float) – Version 3.1 of impact score. Reflects the direct consequence of a successful exploit. Optional, some CVEs may not contain version 3.1 CVSS scoring.
v30impactScore (float) – Version 3.0 of impact score. Reflects the direct consequence of a successful exploit. Optional, some CVEs may not contain version 3.0 CVSS scoring.
v2impactScore (float) – Version 2 of impact score. Reflects the direct consequence of a successful exploit. Optional, some CVEs may not contain version 2 CVSS scoring.
score (list) – Contains the CVSS score of the latest CVSS version (3.1 > 3.0 > 2). Where score is an int, severity is a string(‘LOW’,’MEDIUM’,’HIGH’,’CRITICAL’), and version is a string (V3.1, V3.0, or V2).
v31attackVector (str) – NETWORK, ADJACENT_NETWORK, LOCAL, PHYSICAL. Present if CVE is scored.
v2accessVector – NETWORK, ADJACENT_NETWORK, LOCAL. Present if CVE is scored.
v31attackComplexity (str) – HIGH, LOW. Present if CVE is scored.
v2accessComplexity (str) – HIGH, MEDIUM, LOW. Present if CVE is scored.
v31privilegesRequired (str) – HIGH, LOW, NONE. Present if CVE is scored.
v31userInteraction (str) – NONE, REQUIRED. Present if CVE is scored.
v31scope (str) – UNCHANGED, CHANGED. Present if CVE is scored.
v31confidentialityImpact (str) – LOW, MEDIUM, HIGH, CRITICAL. Present if CVE is scored.
v2authentication (str) – MULTIPLE, SINGLE, NONE. Present if CVE is scored.
v2confidentialityImpact (str) – NONE, PARTIAL, COMPLETE. Present if CVE is scored.
v31integrityImpact (str) – LOW, MEDIUM, HIGH, CRITICAL. Present if CVE is scored.
v2integrityImpact (str) – NONE, PARTIAL, COMPLETE. Present if CVE is scored.
v31availabilityImpact (str) – LOW, MEDIUM, HIGH, CRITICAL. Present if CVE is scored.
v2availabilityImpact (str) – NONE, PARTIAL, COMPLETE. Present if CVE is scored.

Searching CVEs¶

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: Optional[str] = None, cveId: Optional[str] = None, cvssV2Metrics: Optional[str] = None, cvssV2Severity: Optional[str] = None, cvssV3Metrics: Optional[str] = None, cvssV3Severity: Optional[str] = None, cweId: Optional[str] = None, hasCertAlerts: Optional[bool] = None, hasCertNotes: Optional[bool] = None, hasKev: Optional[bool] = None, hasOval: Optional[bool] = None, isVulnerable: Optional[bool] = None, keywordExactMatch: Optional[bool] = None, keywordSearch: Optional[str] = None, lastModStartDate: Optional[Tuple[str, datetime.datetime]] = None, lastModEndDate: Optional[Tuple[str, datetime.datetime]] = None, noRejected: Optional[bool] = None, pubStartDate: Optional[Tuple[str, datetime.datetime]] = None, pubEndDate: Optional[Tuple[str, datetime.datetime]] = None, sourceIdentifier: Optional[str] = None, versionEnd: Optional[str] = None, versionEndType: Optional[str] = None, versionStart: Optional[str] = None, versionStartType: Optional[str] = None, virtualMatchString: Optional[str] = None, limit: Optional[int] = None, delay: Optional[int] = None, key: Optional[str] = None, verbose: Optional[bool] = None) → list[source]¶

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

Parameters

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.
hasKev (bool) – Returns CVE that appear in CISAs Known Exploited Vulnerabilities (KEV) catalog.
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.
noRejected (bool) – Filters out all CVEs that are in a reject or rejected status. Searches without this parameter include rejected CVEs.
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.
versionEnd (str) – Must be combined with versionEndType and virtualMatchString. Returns only the CVEs associated with CPEs in specific version ranges.
versionEndType (str) – Must be combined with versionEnd and virtualMatchString. Valid values are including or excluding. Denotes to include the specified version in versionEnd, or exclude it.
versionStart (str) – Must be combined with versionStartType and virtualMatchString. Returns only CVEs with specific versions. Requests that include versionStart cannot include a version component in the virtualMatchString.
versionStartType (str) – Must be combined with versionStart and virtualMatchString. Valid values are including or excluding. Denotes to include the specified version in versionStart, or exclude it.
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.

In addition to searchCVE there is also searchCVE_V2. This function uses the same parameters as searchCVE except creates a generator. This is useful if the search performed consumes a lot of data and there are memory constraints on the system. It will convert the CVE response one object at a time, instead of attempting to convert the entire data set into memory at once. Here is an example using next().

>>> r = nvdlib.searchCVE_V2(keywordSearch='Microsoft Exchange 2010', limit=100)
>>> oneCVE = next(r)
>>> print(oneCVE.id)

SearchCVE Examples¶

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.

Note

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[0]), 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 cve@mitre.org

>>> r = nvdlib.searchCVE(sourceIdentifier = 'cve@mitre.org', limit = 100)