CPE¶

Search CPE¶

Searching for CPEs is similar to searching for CVEs albeit less parameters. CPE match strings are allowed, meaning if partial strings are known, you can search for all possible CPE names. Like searching CVEs, the parameters are not positional.

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 0.6 (seconds).

Get a NIST NVD API key here (free): https://nvd.nist.gov/developers/request-an-api-key

Here is an example of a CPE search with a keyword and a limit of 2 results then iterate through said CPE names.

import nvdlib

r = nvdlib.searchCPE(keywordSearch = 'Microsoft Exchange', limit = 2)
for eachCPE in r:
    print(eachCPE.cpeName)


'cpe:2.3:a:ca:unicenter_management_microsoft_exchange:-:*:*:*:*:*:*:*'
'cpe:2.3:a:microsoft:exchange_instant_messenger:-:*:*:*:*:*:*:*'

Build and send GET request then return list of objects containing a collection of CPEs.

Parameters:

cpeNameId (str) – Returns a specific CPE record using its UUID. If a correctly formatted UUID is passed but it does not exist, it will return empty results. The UUID is the cpeNameId value when searching CPE.
cpeMatchString (str) – Use a partial CPE name to search for other CPE names.
keywordExactMatch (bool) – Searches metadata within CPE title and reference links for an exact match of the phrase or word passed to it. Must be included with keywordSearch.
keywordSearch (str) – Returns CPE records where a word or phrase is found in the metadata title or reference links. Space characters act as an AND statement.
lastModStartDate (str/datetime obj) –
CPE last modification start date. Maximum 120 day range. A start and end date is required. All times are in UTC 00:00.

A datetime object or string can be passed as a date. NVDLib will automatically parse the datetime object into the correct format.

String Example: ‘2020-06-28 00:00’
lastModEndDate (str/datetime obj) – CPE last modification end date. Maximum 120 day range. Must be included with lastModStartDate. Example: ‘2020-06-28 00:00’
matchCriteriaId (str) – Returns CPE records associated with a match string by its UUID. Requires a properly formatted UUID.
limit (int) – Limits the number of results of the search. Allowed any number between 1 and 10000.
key (str) – NVD API Key. Allows for a request every 0.6 seconds instead of 6 seconds.
delay (float) – Can only be used if an API key is provided. The amount of time to sleep in between requests. Must be a value above 0.6 seconds if an API key is present. delay is set to 6 seconds if no API key is passed.
asDict (bool) – Return each record as the plain dictionary from the NVD response instead of an object.

class nvdlib.classes.CPE(response)[source]¶

JSON dump class for CPEs

Variables:

deprecated (bool) – Indicates whether CPE has been deprecated
cpeName – CPE URI name
cpeNameId (str) – CPE UUID
lastModified (str) – CPE modification date
created (str) – CPE creation date
titles – List of available titles for the CPE
refs (list) – Optional, reference links for the CPE
deprecatedBy – If deprecated=true, one or more CPE that replace this one
deprecates (list) – Optional, one or more CPE that this CPE replaces

In addition to searchCPE there is also searchCPE_V2. This function uses the same parameters as searchCPE 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 CPE 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.searchCPE_V2(keywordSearch='Microsoft Exchange 2010', limit=100)
>>> oneCVE = next(r)
>>> print(oneCVE.cpeName)

CPE Search Examples¶

Filter for a partial cpeMatchString for Microsoft Exchange 2013, return all the vulnerabilities for said matching CPEs, and print their CVE IDs.

Note

The new NVD API version 2 (starting with NVDLib 0.7.0) cannot include CVE names in CPE searches anymore.

r = nvdlib.searchCPE(cpeMatchString='cpe:2.3:a:microsoft:exchange_server:2013:', key='xxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxx', delay=6)
for eachCPE in r:
    print(eachCPE.cpeName)

Filter for CPE names modfied between 2019-01-01 and 2021-01-01 with the keyword of PHP.

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.

len(r) will return how many CPE (or CVE) entries were found in the result.

r = nvdlib.searchCPE(lastModStartDate='2020-01-01 00:00', lastModEndDate='2020-02-01 00:00', keywordSearch='PHP')
print(len(r))

1599

Filter for all CPE names modified in the last 30 days using datetime objects.

>>> import datetime
>>> end = datetime.datetime.now()
>>> start = end - datetime.timedelta(days=30)
>>> r = nvdlib.searchCPE(lastModStartDate=start, lastModEndDate=end)

CPE Match Criteria API¶

This will allow you to search for CPE Match Strings that you can then use in CPE searches. When you search using this API, it will return a list of MatchStrings. I hightly recommend playing around with this API to get an understanding of how the responses work.

More information on how to utilize this API can be found on NVD’s API page: https://nvd.nist.gov/developers/products

Build and send GET request then return list of objects containing a collection of CPEs.

Parameters:

cveId (str) – Returns all matching CPE match strings for a CVE.
lastModStartDate (str/datetime obj) –
Match string last modification start date or CPE last modified start date. Maximum 120 day range. A start and end date is required. All times are in UTC 00:00.

A datetime object or string can be passed as a date. NVDLib will automatically parse the datetime object into the correct format.

String Example: ‘2020-06-28 00:00’
lastModEndDate (str/datetime obj) – CPE last modification end date. Maximum 120 day range. Must be included with lastModStartDate. Example: ‘2020-06-28 00:00’
matchCriteriaId (str) – Returns CPE records associated with a match string by its UUID. Requires a properly formatted UUID.
matchStringSearch (str) – Returns CPE records that match the provided CPE match string. See the NVD API documentation website for more details on how to use CPE match strings. https://nvd.nist.gov/developers/products
limit (int) – Limits the number of results of the search. Allowed any number between 1 and 500.
key (str) – NVD API Key. Allows for a request every 0.6 seconds instead of 6 seconds.
delay (float) – Can only be used if an API key is provided. The amount of time to sleep in between requests. Must be a value above 0.6 seconds if an API key is present. delay is set to 6 seconds if no API key is passed.
asDict (bool) – Return each record as the plain dictionary from the NVD response instead of an object.

class nvdlib.classes.MatchString(response)[source]¶

JSON dump class for CPE match strings

Variables:

matchCriteriaId (str) – UUID match criteria
criteria (str) – CPE name
lastModified (str) – Match string modification date
cpeLastModified (str) – CPE modification date
created (str) – CPE creation date
status (str) – CPE active status
versionStartIncluding (str) – Optional, only exists if the match string is a version range.
versionStartExcluding (str) – Optional, only exists if the match string is a version range.
versionEndIncluding (str) – Optional, only exists if the match string is a version range.
versionEndExcluding (str) – Optional, only exists if the match string is a version range.
matches (list) – CPE Names and IDs within the CPE Dictionary that matches the CPE Match Criteria

searchCPEmatch_V2 uses the same parameters as searchCPEmatch except creates a generator. The Match Criteria API returns at most 500 match strings per page, so limit must be between 1 and 500.

>>> r = nvdlib.searchCPEmatch_V2(cveId='CVE-2017-0144')
>>> oneMatch = next(r)
>>> print(oneMatch.criteria)

CPE Match String Search Examples¶

To obtain the CPE match strings for a single CVE and print the matchCriteriaId for each match.

r = nvdlib.searchCPEmatch(cveId='CVE-2017-0144')
for eachMatchString in r:
    print(eachMatchString.matchCriteriaId)

Within each MatchString element in the response there are the CPE names that match. Here is how we can print them.

r = nvdlib.searchCPEmatch(cveId='CVE-2017-0144')
for eachMatchString in r:
    for eachCPE in eachMatchString.matches:
        print(eachCPE.cpeName)

We can also filter down this result even further using the other arguments for the Match String API. Here is searching for all match strings for the CVE ID CVE-2017-0144, along with only matchStrings that contain cpe:2.3:o:microsoft:windows_server_2012:*.

r = nvdlib.searchCPEmatch(cveId='CVE-2017-0144', matchStringSearch='cpe:2.3:o:microsoft:windows_server_2012:*')
for eachMatchString in r:
    for eachCPE in eachMatchString.matches:
        print(eachCPE.cpeName)

Not that this search would be very useful in reality, but we can also search for a specific matchCriteriaId on top of the other two filters. This will search for all CPE match strings for the CVE ID CVE-2017-0144, match strings that contain cpe:2.3:o:microsoft:windows_server_2012:*, and that have a matchCriteriaId UUID of ‘AB506484-7F0C-46BF-8EA6-4FB5AF454CED’. Match criteria is a unique UUID to a match string, so searching for them will only yield a single result. Keep in mind nvdlib.searchCPEmatch is still returning a list, so even though there is only one element in the list, you must select element index 0 to access that data of that element.

r = nvdlib.searchCPEmatch(cveId='CVE-2017-0144', matchStringSearch='cpe:2.3:o:microsoft:windows_server_2012:*', matchCriteriaId='AB506484-7F0C-46BF-8EA6-4FB5AF454CED')
print(r[0].matchCriteriaId)
'AB506484-7F0C-46BF-8EA6-4FB5AF454CED'