Products
This documentation assumes that you already understand at least one common programming language and are generally familiar with JSON RESTful services. JSON specifies the format of the data returned by the REST service. REST refers to a style of services that allow computers to communicate via HTTP over the Internet. Click here for a list of best practices and additional information on where to start. The NVD is also documenting popular workflows to assist developers working with the APIs.
CPE API
The CPE API is used to easily retrieve information on a single CPE record or a collection
of CPE records from the Official CPE Dictionary .
The dictionary contains 1,292,345
CPE Names and more than 420,000
match strings. Because of this, the NVD enforces
offset-based pagination to answer requests for large collections. Through a series of
smaller “chunked” responses controlled by an offset startIndex
and a page
limit resultsPerPage
users may page through all the records in the dictionary.
For more information on the full CPE specification please refer to the
Computer Security Resource Center.
The URL stem for retrieving CPE information is shown below.
https://services.nvd.nist.gov/rest/json/cpes/2.0
Parameters
cpeNameId optional
This parameter returns a specific CPE record identified by a
Universal Unique Identifier (UUID). Please note,
The CPE Match Criteria API response
provides valid cpeNameId
|
cpeMatchString optional
This parameter returns CPE Names that exist in the Official CPE Dictionary, based
on the value of A CPE Name is a string of characters comprised of 13 colon separated values that describe a product. In CPEv2.3 the first two values are always “cpe” and “2.3”. The 11 values that follow are referred to as the CPE components. A CPE Match string is a single CPE string that correlates to one or many CPE Names in the Official CPE Dictionary. Because the NVD publishes CPE applicability statements for thousands of CVE each year, match strings are made to withstand changes to the Official CPE Dictionary, without requiring consistent maintenance. Request CPE names for Microsoft Windows 10
Request CPE names for Microsoft Windows 10, version 1511
Request all CPE names with the vendor "Microsoft"
|
keywordExactMatch optional
By default,
If the value of Request all exact matches of "Microsoft Windows"
Please note, the example above would not return a CPE unless the exact phrase "Microsoft Windows" appears in the metadata title or reference links. |
keywordSearch optional
This parameter returns only the CPE records where a word or phrase is found in the metadata title or reference links. Request all mentions of "Red" and "Hat"
Request any CPE mentioning both "Java" and "Oracle"
Please note, multiple |
lastModStartDate & lastModEndDate optional
These parameters return only the CPE records that were last
modified during the specified period. If a CPE record 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
A CPE record is considered "modified" when any of the follow actions occur:
Values must be entered in the extended ISO-8601 date/time format: [YYYY][“-”][MM][“-”][DD][“T”][HH][“:”][MM][“:”][SS][Z]
The "T" is a literal to separate the date from the time. The Z indicates an optional offset-from-UTC. Please note, if a positive Z value is used (such as +01:00 for Central European Time) then the "+" should be encoded in the request as "%2B". The user agent may handle this automatically. Request all CPE records modified between the start and end datetimes
|
matchCriteriaId optional
This parameter returns all CPE records associated with a match string identified by its
CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges.
Both are abstract concepts that are then correlated to CPE URIs in the Official CPE
Dictionary. Unlike a CPE Name, match strings and match string ranges do not require
a value in the part, vendor, product, or version components. The CVE API returns
valid Request all CPE names that match a uuid
|
resultsPerPage optional
This parameter specifies the maximum number of CPE records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 10,000. |
startIndex optional
This parameter specifies the index of the first CPE to be returned in the response data. The index is zero-based, meaning the first CPE is at index zero.
The CPE API returns four primary objects in the response body that are
used for pagination:
resultsPerPage, startIndex, totalResults,
and products. totalResults indicates the
total number of CPE records that match the request parameters.
If the value of totalResults is greater than the value of resultsPerPage
there are more records than could be returned by a single API
response and additional requests must update the The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters to request only the CPE that have been modified since your last request. Request 20 CPE records, beginning at index 0 and ending at index 19
Request the CPE records, beginning at index 20 and ending at index 39
|
Response
CPE API JSON Schema
This API response includes only one JSON schema for defining the structure of the response data. The following document includes information on data types, regex patterns, maximum character length, and other information that can support developers and database administrators looking to create their own local repository.
Response Details
The CPE API returns seven primary objects in the body of the response: resultsPerPage, startIndex, totalResults, format, version, timestamp, and products.
The totalResults object indicates the number of CPE records that match the request criteria, including all parameters. If the value of totalResults is greater than the value of resultsPerPage, then additional requests are necessary to return the remaining records. The parameter startIndex may be used in subsequent requests to identify the starting point for the next request. More information and the best practices for using resultsPerPage and startIndex are described above.
The format and version objects identify the format and version of the API response. timestamp identifies when the response was generated.
The products object contains an array of objects equal to the number of records returned in the response and is sorted in ascending order by the created property of the cpe object. The cpe object is explained in more detail below.
cpe required
This object contains a boolean flag indicating whether the CPE is deprecated, the cpeName (including the reverse solidus escape character \), the cpeNameId, the date and time that the CPE was added to the Official CPE Dictionary, the date and time that the CPE was last modified, as well as additional metadata under the titles object. If the CPE is deprecated an optional deprecatedBy field will provide the CPE Name that that replaces it.
{
"resultsPerPage": 2,
"startIndex": 0,
"totalResults": 2,
"format": "NVD_CPE",
"version": "2.0",
"timestamp": "2023-01-10T19:46:53.290",
"products": [
{
"cpe": {
"deprecated": false,
"cpeName": "cpe:2.3:a:3com:3cdaemon:-:*:*:*:*:*:*:*",
"cpeNameId": "BAE41D20-D4AF-4AF0-AA7D-3BD04DA402A7",
"lastModified": "2011-01-12T14:35:43.723",
"created": "2007-08-23T21:05:57.937",
"titles": [
{
"title": "3Com 3CDaemon",
"lang": "en"
},
{
"title": "スリーコム 3CDaemon",
"lang": "ja"
}
]
}
},
{
"cpe": {
"deprecated": true,
"cpeName": "cpe:2.3:o:linux:linux_kernel:2.6.2:*:*:*:*:*:*:*",
"cpeNameId": "DF3171C4-00E8-4B0F-97EB-2F3EC3394A87",
"lastModified": "2021-06-01T14:14:47.707",
"created": "2007-08-23T21:16:59.567",
"titles": [
{
"title": "Linux Kernel 2.6.2",
"lang": "en"
}
],
"refs": [
{
"ref": "https://github.com/torvalds/linux",
"type": "Version"
}
],
"deprecatedBy": [
{
"cpeName": "cpe:2.3:o:linux:linux_kernel:2.6.2:-:*:*:*:*:*:*",
"cpeNameId": "1B4C49FC-8606-45D7-94D1-19C5626D69C7"
}
],
"deprecates": [
{
"cpeName": "cpe:2.3:o:linux:kernel:2.6.2:*:*:*:*:*:*:*",
"cpeNameId": "B548E49E-BC95-4804-A2C2-D7ACC7F72095"
}
]
}
}
]
}
Match Criteria API
The CPE Match Criteria API is used to easily retrieve the complete list of valid CPE Match Strings. Unlike a CPE Name, match strings and match string ranges do not require a value in the part, vendor, product, or version components.
The URL stem for retrieving match criteria information is shown below.
https://services.nvd.nist.gov/rest/json/cpematch/2.0
Parameters
cveId optional
This parameter returns all non-deprecated CPE match strings in the availability statement of a specific vulnerability identified by its Common Vulnerabilities and Exposures identifier (the CVE ID). cveId
|
lastModStartDate & lastModEndDate optional
These parameters return only the CPE records that were last
modified during the specified period. If a CPE record 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
When a user populates the Values must be entered in the extended ISO-8601 date/time format: [YYYY][“-”][MM][“-”][DD][“T”][HH][“:”][MM][“:”][SS][Z]
The "T" is a literal to separate the date from the time. The Z indicates an optional offset-from-UTC. Please note, if a positive Z value is used (such as +01:00 for Central European Time) then the "+" should be encoded in the request as "%2B". The user agent may handle this automatically. Request all CPE match strings modified between the start and end datetimes
|
matchCriteriaId optional
This parameter returns all CPE records associated with a match string identified by its
CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges.
Both are abstract concepts that are then correlated to CPE URIs in the Official CPE
Dictionary. Unlike a CPE Name, match strings and match string ranges do not require
a value in the part, vendor, product, or version components. The CVE API returns
valid Request all CPE names that match a uuid
|
matchStringSearch optional
This parameter returns all CPE Match Strings that conform to the pattern of the
CPE Match Criteria comes in two forms: CPE Match Strings and CPE Match String Ranges. Both are abstract concepts that are then correlated to CPE URIs in the Official CPE Dictionary. Unlike a CPE Name, CPE Match Strings and CPE Match String Ranges do not require a value in the part, vendor, product, or version components. This parameter does not support CPE Match String Ranges.
Request all CPE Match Strings where the vendor and product components conform to the following pattern.
|
resultsPerPage optional
This parameter specifies the maximum number of match records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 500.
Note: Per the /cpematch/ resultsPerPage update this value will be
reduced to |
startIndex optional
This parameter specifies the index of the first match string to be returned in the response data. The index is zero-based, meaning the first record is at index zero.
The CPE Match API returns four primary objects in the response body that are
used for pagination:
resultsPerPage, startIndex, totalResults,
and matchStrings. totalResults indicates the
total number of CPE records that match the request parameters.
If the value of totalResults is greater than the value of resultsPerPage
there are more records than could be returned by a single API
response and additional requests must update the The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters to request only the CPE Match Strings that have been modified since your last request. |
Response
CPE Match API JSON Schema
This API response includes only one JSON schema for defining the structure of the response data. The following document includes information on data types, regex patterns, maximum character length, and other information that can support developers and database administrators looking to create their own local repository.
Response Details
The Match Criteria API returns seven primary objects in the body of the response: resultsPerPage, startIndex, totalResults, format, version, timestamp, and matchStrings.
The totalResults object indicates the number of CPE records that match the request criteria, including all parameters. If the value of totalResults is greater than the value of resultsPerPage, then additional requests are necessary to return the remaining records. The parameter startIndex may be used in subsequent requests to identify the starting point for the next request. More information and the best practices for using resultsPerPage and startIndex are described above.
The format and version objects identify the format and version of the API response. timestamp identifies when the response was generated.
The matchStrings object contains an array of objects equal to the number of records returned in the response and is sorted in ascending order by the created property of the matchString object.
matchString required
This object contains a matchCriteriaId UUID identifier, the CPE formatted match criteria value, the date and time that the CPE was created or lastModified within the Official CPE Dictionary, as well as version range information for CPE Match String Ranges versionStartIncluding,versionStartExcluding, versionEndIncluding,versionEndExcluding. There is also metadata relating to the status of the CPE Match Criteria, an array of paired CPE Names and IDs within the CPE Dictionary that matches the CPE Match Criteria and cpeLastModified, a date and time for when the values within the matches array were last updated.
{
"resultsPerPage": 2,
"startIndex": 0,
"totalResults": 413574,
"format": "NVD_CPEMatchString",
"version": "2.0",
"timestamp": "2022-09-12T19:47:48.350",
"matchStrings": [
{
"matchString": {
"matchCriteriaId": "36FBCF0F-8CEE-474C-8A04-5075AF53FAF4",
"criteria": "cpe:2.3:a:nmap:nmap:3.27:*:*:*:*:*:*:*",
"lastModified": "2019-06-17T09:16:33.960",
"cpeLastModified": "2019-07-22T16:37:38.133",
"created": "2019-06-17T09:16:33.960",
"status": "Active",
"matches": [
{
"cpeName": "cpe:2.3:a:nmap:nmap:3.27:*:*:*:*:*:*:*",
"cpeNameId": "4DAAA102-AB17-4491-B383-A1AAC764704C"
}
]
}
},
{
"matchString": {
"matchCriteriaId": "D21D57EA-DF58-429B-9FBE-F0080085B62E",
"criteria": "cpe:2.3:a:gnu:cfengine:2.0.7:p1:*:*:*:*:*:*",
"lastModified": "2019-06-17T09:16:33.960",
"cpeLastModified": "2019-07-22T16:37:38.133",
"created": "2019-06-17T09:16:33.960",
"status": "Active"
}
}
]
}
Questions, comments, or concerns may be shared with the NVD by emailing nvd@nist.gov