Deprecated Vulnerabilities API

NOTICE

The 1.0 APIs have been retired and are no longer accessible. Click here for more information on the retirement timeline.

Vulnerabilities

This quickstart 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.

Requests

All requests to the API use the HTTP GET method. The URL stem for making requests is different depending on whether the request is for one specific CVE, or a collection of CVEs. REST parameters allow you to control and customize which vulnerabilities are returned. The parameters are akin to those found on the NVD public vulnerability search page, https://nvd.nist.gov/vuln/search.

Retrieve a specific CVE

The URL stem for retrieving a single CVE is shown below. Please note how the required {cveId} appears in the URL path.

https://services.nvd.nist.gov/rest/json/cve/1.0/CVE-2021-41172?addOns=dictionaryCpes

Parameters

Retrieve a collection of CVE

The parameters used to retrieve a collection are intended to limit or filter results. The parameters selected for the request are known as the search criteria, and all parameters should be included in the URL query. Please note how the only difference between the URL for requesting a single CVE and requesting a collection is a single "s".

https://services.nvd.nist.gov/rest/json/cves/1.0/

Parameters

addOns optional

dictionaryCpes By default, the response includes all CPE applicability statements associated with the vulnerability. Applicability statements are CPE match strings that may be used in searching the Official CPE Dictionary. Including addOns=dictionaryCpes adds the official CPE names to the request.

Please note that each CVE may have a dozen or more CPE associated with them. Including this parameter can return a large amount of data, which in some cases may become truncated. Reducing the resultsPerPage may prevent the data from being truncated.

apiKey optional

The API Key provided to the user. Including apiKey={key value}, (without brackets or spaces) allows users to make a greater number of requests in a given time than they could otherwise.

Beginning in September 2022, API keys may also be passed to the 1.0 APIs in the request header. This approach is required with the 2.0 APIs. The exact method of passing header information with a GET request varies based on the user agent.

cpeMatchString optional

This parameter is used to filter vulnerabilities more broadly than cpeName. The value of cpeMatchString is compared against the CPE Match Criteria present on CVE applicability statements. cpeName is a recommended alternative for many use cases. Please note, when both cpeName and cpeMatchString are provided, only the cpeName is used.

cpeName optional

This parameter is used to find CVEs that affect specific products. The exact value of cpeName is compared to the CPE Match Criteria so that only CVE affecting the named CPE are returned. Please note, when both cpeName and cpeMatchString are provided, only the cpeName is used. cpeName will accept CPE not yet present in the CPE Dictionary, but the value must be a well-formed CPE name (WFN).

https://services.nvd.nist.gov/rest/json/cves/1.0?cpeName=cpe:2.3:o:microsoft:windows_10:1607:*:*:*:*:*:x86:*

cvssV2Metrics optional

These parameters are used to filter vulnerabilities based on CVSS vector strings. Either full or partial vector strings may be used.

https://services.nvd.nist.gov/rest/json/cves/1.0?cvssV2Metrics=AV:L/AC:H/Au:M/C:N/I:N/A:N

https://services.nvd.nist.gov/rest/json/cves/1.0?cvssV2Metrics=A:N/C:H

cvssV2Severity optional

CVSS refers to the scoring system used by NIST to assess the severity of vulnerabilities, https://www.first.org/cvss/. Either the cvssV2Severity or cvssV3Severity parameter may be used to find vulnerabilities having a severity of LOW, MEDIUM, or HIGH. For CVSS V3.x, cvssV3Severity=CRITICAL is also supported.

cvssV3Metrics optional

These parameters are used to filter vulnerabilities based on CVSS vector strings. Either full or partial vector strings may be used.

https://services.nvd.nist.gov/rest/json/cves/1.0?cvssV3Metrics=AV:N/AC:L/PR:H/UI:N/S:U/C:L/I:L/A:N

https://services.nvd.nist.gov/rest/json/cves/1.0?cvssV3Metrics=S:U/AV:N/AC:L/PR:H/UI:N/S:U/C:L/I:L/A:N

cvssV3Severity optional

cweId optional

CWE refers to the classification of vulnerabilities used by NIST and managed by MITRE at https://cwe.mitre.org/. NVD analysts associate one or more CWE to each vulnerability during the analysis process.

includeMatchStringChange optional

true By default, the modStartDate and modEndDate parameters include only a collection of CVE where the CVE information was modified. The modification of product names by NIST in the Official CPE Dictionary does not modify related CVE. includeMatchStringChange=true returns a collection of CVE where either the vulnerabilities or the associated product names were modified.

isExactMatch optional

true If the keyword is a phrase, i.e., contains more than one term, including isExactMatch=true retrieves records matching the exact phrase. Otherwise, the results contain any record having any of the terms.

keyword optional

This parameter is used to retrieve records where a word or phrase is found in the vulnerability description or reference links.

modStartDate optional

modEndDate optional

These parameters specify a collection of CVE that were last modified during the 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 modStartDate and modEndDate are REQUIRED. Filtering with only one parameter will return a successful response without data. The maximum allowable range when using the date range parameters is 120 consecutive days. Date range parameters are in the form:

yyyy-MM-ddTHH:mm:ss:SSS Z

The T is a literal to separate the date from the time. The Z indicates an offset-from-UTC. 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". This may be handled automatically by the user agent. An example is provided below showing a +01:00 offset-from-UTC.

https://services.nvd.nist.gov/rest/json/cves/1.0/?modStartDate=2021-08-04T13:00:00:000 UTC%2B01:00&modEndDate=2021-10-22T13:36:00:000 UTC%2B01:00

pubStartDate optional

pubEndDate optional

These parameters specify a collection of CVE that were added to the NVD (i.e., published) during the period. If filtering by the publication date, both pubStartDate and pubEndDate are REQUIRED. Filtering with only one parameter will return a successful response without data. The maximum allowable range when using the date range parameters is 120 consecutive days. Date range parameters are in the form:

yyyy-MM-ddTHH:mm:ss:SSS Z

https://services.nvd.nist.gov/rest/json/cves/1.0/?pubStartDate=2021-08-04T13:00:00:000 UTC-05:00&pubEndDate=2021-10-22T13:36:00:000 UTC-05:00

resultsPerPage optional

This parameter specifies the maximum number of results that are returned based on the request parameters. The default value is 20. For network considerations, maximum allowable limit is 2,000.

The response content totalResults indicates the number of CVE results that match request parameters. If the value of totalResults is greater than the value of resultsPerPage, the parameter startIndex may be used in subsequent requests to identify the starting point for the request.

sortBy optional

modifiedDate By default, the API responds with the most recently modified CVE first.

 
		                            publishDate

Including sortBy=publishDate changes the sort order so that the API responds with the most recently published CVE first.

When making iterative requests for a large number of CVE, such as the initial population of all CVE in a local database, sorting by the modified date may occasionally result in missing CVE. This may happen if new CVE are added during the iterative requests. Sorting by the published date avoids these errors.

startIndex optional

This parameter determines the first CVE in the collection returned by the response. The index is zero-based, meaning the first CVE is at index zero. The response header totalResults indicates the number of CVE results that match request parameters. If the value of totalResults is greater than the value of resultsPerPage, the parameter startIndex may be used in subsequent requests to identify the first CVE for the request.

The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters in order to request only those CVE that have been published or modified since the last request.

Presently NVD contains more than 160,000 vulnerabilities relating to thousands of vendor products. Multiple consecutive requests are required to return all available records. Requesting an API key significantly raises the number of requests that can be made in a given time frame. However, NIST firewall rules put in place to prevent denial of service attacks on NVD can thwart your application. To avoid this, it is recommended that your application sleeps for several seconds between requests so that legitimate requests are not denied.

Response

This section describes the response returned by the vulnerability API. Each CVE has a text description and reference links. Vulnerabilities that have undergone NVD analysis include CVSS scores, product applicability statements, and more. The response is based on four JSON schema that were developed independently as part of three separate initiatives. Hence the stylistic differences in data element names. The following diagram shows where the main feed schema is dependent on the other three.

Click to view the full JSON response schema

Response Body

The vulnerabilities API returns four primary elements in the body of the response: resultsPerPage, startIndex, totalResults, and result.

The first three elements identify how how many CVE meet the search criteria and how many CVE have been returned in this response. The element totalResults indicates the number of CVE results that match search criteria. If the value of totalResults is greater than the value of resultsPerPage, then additional requests are necessary to return the remaining CVE. The parameter startIndex may be used in subsequent requests to identify the starting point for the request next. More information and the best practices for using resultsPerPage and startIndex are described above.

The result element contains an array of five additional elements. CVE_data_type, CVE_data_format, CVE_data_version, and CVE_data_timestamp describe the request while the fifth element CVE_Items contains the CVE.

CVE Items

At the high-level, each vulnerability in the CVE_Items array can have the following elements:

cve required

This element contains the CVE identifier, description, reference links, and problem type (CWE). In rare occasions description_data can contain multiple values. All vulnerabilities have at least one Internet link under references that provides additional information about the vulnerability. NIST categorizes link using the tags elements, e.g., Third Party Advisory. All CWE assigned to a vulnerability are found in problem_type. In some cases there are more than one CWE.

	"cve":{
		"data_type":"CVE",
		"data_format":"MITRE",
		"data_version":"4.0",
		"CVE_data_meta":{
			"ID":"CVE-2019-1010218",
			"ASSIGNER":"cve@mitre.org"
						},
							
		"description":{
			"description_data":[{
				"lang":"en",
				"value":"Cherokee Webserver Latest Cherokee Web server Upto Version 1.2.103 (Current stable) is affected by: Buffer Overflow - CWE-120. The impact is: Crash. The component is: Main cherokee command. The attack vector is: Overwrite argv[0] to an insane length with execl. The fixed version is: There's no fix yet."
								}]
						},

		"references":{
			"reference_data":[{
				"url":"https://i.imgur.com/PWCCyir.png",
				"name":"https://i.imgur.com/PWCCyir.png",
				"refsource":"MISC",
				"tags":["Exploit","Third Party Advisory"]
								}]
						},

		"problemtype":{
			"problemtype_data":[{
				"description":[{
					"lang":"en",
					"value":"CWE-119"
							}]
						}]
					},
		}

configurations not required

The configurations element has the CVE applicability statements that convey which product, or products, are associated with the vulnerability according to analysis by NIST. Recall that each CPE shown here is a match string that can be used to search the Official CPE Dictionary.

Configurations are a tree, or hierarchical data structure consisting of nodes where each node contains CPE match string or child nodes. (A node will never contain both CPEs and child nodes, and is never empty.)

Each node has either an OR- or an AND-operator (and in rare cases a NEGATE flag) to covey the logical relationship of the CPE or child nodes within. For example, if the vulnerability exists only when both CPE products are present, the operator is “AND”. If the vulnerability exists if either CPE is present, then the operator is “OR”.

	"configurations":{
		"CVE_data_version":"4.0",
		"nodes":[{
				"operator":"AND",
				"children":[{
						"operator":"OR",
						"cpe_match":[{
								"vulnerable":true,
								"cpe23Uri":"cpe:2.3:o:tesla:model_3_firmware:-:*:*:*:*:*:*:*"
									}]
							},{
						"operator":"OR",
						"cpe_match":[{
								"vulnerable":false,
								"cpe23Uri":"cpe:2.3:h:tesla:model_3:-:*:*:*:*:*:*:*"
							}]
						}
					]
				}]
			},

Notice that the first product is marked as vulnerable, but the second is not. (The vulnerability is said to exist only if the firmware in this example is running on the hardware.) Configurations vary in complexity, partly due to their recursive nature. Some vulnerabilities have one node with one CPE, while others have more than one configuration, i.e., more than one root node element. Nodes may contain a single CPE match string or dozens.

In some cases, the CPE match string indicates a range of product versions. Notice in the following example that the version is not specified in the cpe23Uri element; instead, the versionEndIncluding indicates the last vulnerable version. Other possible elements are versionEndExcluding, versionStartIncluding, and versionStartExcluding.

	"configurations" : {
		"CVE_data_version" : "4.0",
		"nodes" : [ {
			"operator" : "OR",
			"cpe_match" : [ {
				"vulnerable" : true,
				"cpe23Uri" :
				"cpe:2.3:a:imapfilter_project:imapfilter:*:*:*:*:*:*:*:*",
				"versionEndIncluding" : "2.6.12"
					} ]
				} ]
			},

Recall that the vulnerability service has an optional query parameter, addOns=dictionaryCpes, described above. When the request has this parameter, the response returns official CPE names for each CPE match string in the configuration, in so far as they are present in the Official CPE Dictionary. The following example shows matching CPE names for a match string.

	"configurations":{
		"CVE_data_version":"4.0",
		"nodes":[{
			"operator":"OR",
				"negate":false,
				"cpe_match":[{
					"vulnerable":true,
					"cpe23Uri":"cpe:2.3:a:elementor:elementor:*:*:*:*:*:*:*:*",
					"versionEndExcluding":"1.8.0",
					"cpe_name":[{
						"cpe23Uri":"cpe:2.3:a:elementor:elementor:-:*:*:*:*:*:*:*",
							"lastModifiedDate":"2019-09-10T15:38Z"},
							{"cpe23Uri":"cpe:2.3:a:elementor:elementor:0.1.0:*:*:*:*:*:*:*",
							"lastModifiedDate":"2019-09-10T15:38Z"},
							{"cpe23Uri":"cpe:2.3:a:elementor:elementor:0.1.1:*:*:*:*:*:*:*",
							"lastModifiedDate":"2019-09-10T15:38Z"},
							{"cpe23Uri":"cpe:2.3:a:elementor:elementor:0.1.2:*:*:*:*:*:*:*",
							"lastModifiedDate":"2019-09-10T15:38Z"},
							{"cpe23Uri":"cpe:2.3:a:elementor:elementor:0.1.3:*:*:*:*:*:*:*",
							"lastModifiedDate":"2019-09-10T15:38Z"},

Since configurations can be large, and the number of matches can be many, applications are cautioned from using this parameter for requests that return large numbers of vulnerabilities.

impact not required

The impact element provides the CVSS severity scores for the vulnerability if it has been analyzed by NIST. The cvssV3 and cvssV2 elements within the impact element conform to the cvss-v3.x.json and cvssv2.0.json schemas, respectively. Additional elements provided by NIST conform to the parent nvd_cve_feed_json_1.1.schema such as the exploitability and impact sub-scores.

	"impact":{
		"baseMetricV3":{
			"cvssV3":{
				"version":"3.0",
				"vectorString":"CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H",
				"attackVector":"NETWORK",
				"attackComplexity":"LOW",
				"privilegesRequired":"NONE",
				"userInteraction":"REQUIRED",
				"scope":"UNCHANGED",
				"confidentialityImpact":"HIGH",
				"integrityImpact":"HIGH",
				"availabilityImpact":"HIGH",
				"baseScore":8.8,
				"baseSeverity":"HIGH"
				},
			"exploitabilityScore":2.8,
			"impactScore":5.9
		},
		
		"impact":{
			"baseMetricV2":{
				"cvssV2":{
					"version":"2.0",
					"vectorString":"AV:N/AC:M/Au:N/C:P/I:P/A:P",
					"accessVector":"NETWORK",
					"accessComplexity":"MEDIUM",
					"authentication":"NONE",
					"confidentialityImpact":"PARTIAL",
					"integrityImpact":"PARTIAL",
					"availabilityImpact":"PARTIAL",
					"baseScore":6.8
				},
				"severity":"MEDIUM",
				"exploitabilityScore":8.6,
				"impactScore":6.4,
				"obtainAllPrivilege":false,
				"obtainUserPrivilege":false,
				"obtainOtherPrivilege":false,
				"userInteractionRequired":true
				}
			}

publishedDate not required

The date that the CVE was published.

lastModifiedDate not required

The date that the CVE was last modified.

Questions, comments, or concerns may be shared with the NVD by emailing nvd@nist.gov

Created September 20, 2022 , Updated December 17, 2023

You are viewing this page in an unauthorized frame window.

Information Technology Laboratory

National Vulnerability Database

National Vulnerability Database

NVD

Vulnerabilities

Requests

Retrieve a specific CVE

Parameters

Retrieve a collection of CVE

Parameters

Response

Response Body

CVE Items