) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.
Vulnerabilities
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.
CVE API
The CVE API is used to easily retrieve information on a single CVE or a collection
of CVE from the NVD. The NVD contains 268,929
CVE records. Because of this, its APIs enforce
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 CVE in the NVD.
The URL stem for retrieving CVE information is shown below.
https://services.nvd.nist.gov/rest/json/cves/2.0Parameters
cpeName optional
This parameter returns all CVE associated with a specific CPE.
The exact value provided with
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.
When filtering by 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 CPE Match Criteria within the configurations object. Request the CVE associated a specific CPE
Request the CVE associated a specific CPE using an incomplete name
|
cveId optional
This parameter returns a specific vulnerability identified by its unique
Common Vulnerabilities and Exposures identifier (the CVE ID).
Request a specific CVE using its CVE-ID
|
cveTag optional
This parameter returns only the CVE records that include the provided Request all CVE records that have the disputed CVE Tag
|
cvssV2Metrics optional
This parameter returns only the CVEs that match the provided Please note, as of July 2022, the NVD no longer generates new information for CVSS v2. Existing CVSS v2 information will remain in the database but the NVD will no longer actively populate CVSS v2 for new CVEs. NVD analysts will continue to use the reference information provided with the CVE and any publicly available information at the time of analysis to associate Reference Tags, information related to CVSS v3.1, CWE, and CPE Applicability statements. Request all CVE matching the CVSSv2 vector string
An example of a valid request for which there exists no vulnerabilities
|
cvssV2Severity optional
This parameter returns only the CVEs that match the provided CVSSv2 qualitative severity rating.
This parameter cannot be used in requests that include Please note, as of July 2022, the NVD no longer generates new information for CVSS v2. Existing CVSS v2 information will remain in the database but the NVD will no longer actively populate CVSS v2 for new CVEs. NVD analysts will continue to use the reference information provided with the CVE and any publicly available information at the time of analysis to associate Reference Tags, information related to CVSS v3.1, CWE, and CPE Applicability statements. Request all CVE matching the CVSSv2 qualitative severity rating of LOW
|
cvssV3Metrics optional
This parameter returns only the CVEs that match the provided Request all CVE matching the CVSSv3 vector string
An example of a valid request for which there exists no vulnerabilities
|
cvssV3Severity optional
This parameter returns only the CVEs that match the provided CVSSv3 qualitative severity rating.
This parameter cannot be used in requests that include Request all CVE matching the CVSSv3 qualitative severity rating of LOW
|
cvssV4Metrics optional
This parameter returns only the CVEs that match the provided An example of a valid request for which there exists no vulnerabilities
|
cvssV4Severity optional
This parameter returns only the CVEs that match the provided CVSSv4 qualitative severity rating.
This parameter cannot be used in requests that include Request all CVE matching the CVSSv4 qualitative severity rating of HIGH
|
cweId optional
This parameter returns only the CVE that include a weakness identified by
Common Weakness Enumeration
using the provided Request all CVE that include Improper Authentication
|
|
hasCertAlerts optional
This parameter returns the CVE that contain a Technical Alert from US-CERT. Please note, this parameter is provided without a parameter value. Request all CVE containing a Technical Alert
|
|
hasCertNotes optional
This parameter returns the CVE that contain a Vulnerability Note from CERT/CC. Please note, this parameter is provided without a parameter value. Request all CVE containing a Vulnerability Note from CERT/CC
|
|
hasKev optional
This parameter returns the CVE that appear in CISA's Known Exploited Vulnerabilities (KEV) Catalog. Please note, this parameter is provided without a parameter value. Request all CVE that appear in the KEV catalog
|
|
hasOval optional
This parameter returns the CVE that contain information from MITRE's Open Vulnerability and Assessment Language (OVAL) before this transitioned to the Center for Internet Security (CIS). Please note, this parameter is provided without a parameter value. Request all CVE containing an OVAL record
|
|
isVulnerable optional
This parameter returns only CVE associated with a specific CPE,
where the CPE is also considered vulnerable. The exact value provided
with
If filtering by Request all CVE associated a specific CPE and are marked as vulnerable
|
|
keywordExactMatch optional
By default,
If the value of Request all CVE mentioning the exact phrase "Microsoft Outlook"
Please note, the example above would not return a CVE unless the exact phrase "Microsoft Outlook" appears in the current description. |
keywordSearch optional
This parameter returns only the CVEs where a word or phrase is found in the current description. Descriptions associated with CVE are maintained by the CVE Assignment Team through coordination with CVE Numbering Authorities (CNAs). The NVD has no control over CVE descriptions.
Please note, empty spaces in the URL should be encoded in the request as "%20".
The user agent may handle this encoding automatically. Multiple Request any CVE mentioning "Microsoft"
Request any CVE mentioning "Windows", "MacOs", and "Debian"
|
lastModStartDate & lastModEndDate optional
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
A CVE's lastModified changes when any of the follow actions occur:
A CVE's lastModified does not change 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 encoding automatically. Request all CVE records modified between the start and end datetimes
|
|
noRejected optional
By default, the CVE API includes CVE records with the REJECT or Rejected status. This parameter excludes CVE records with the REJECT or Rejected status from API response. Please note, this parameter is provided without a parameter value. Request all CVE without the REJECT or Rejected status
|
pubStartDate & pubEndDate optional
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
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 encoding automatically. Request all CVE published between the start and end dates, defaulting to GMT
Request all CVE published between the start and end datetimes
|
resultsPerPage optional
This parameter specifies the maximum number of CVE records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 2,000.
It is recommended that users of the CVE API use the default |
startIndex optional
This parameter specifies the index of the first CVE to be returned in the response data. The index is zero-based, meaning the first CVE is at index zero.
The CVE API returns four primary objects in the response body that are
used for pagination:
resultsPerPage, startIndex, totalResults,
and vulnerabilities. totalResults indicates the
total number of CVE 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 CVEs that have been modified since your last request. Request 20 CVE records, beginning at index 0 and ending at index 19
Request the CVE records, beginning at index 20 and ending at index 39
|
sourceIdentifier optional
This parameter returns CVE where the exact value of Request all CVE with the data source "[email protected]"
|
versionEnd & versionEndType optional
The
If filtering by the ending version, Request all CVE affiliated with version 2.6 of a specific CPE
|
versionStart & versionStartType optional
The
If filtering by the starting version, Request all CVE affiliated with versions 2.2 through 2.5.x of a specific CPE
|
virtualMatchString optional
This parameter filters CVE more broadly than 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 CPE Match Criteria within the configurations object.
CPE Match String Ranges are only supported for the version component and only when
Request all CVE where the associated CPE's language component denotes the German language version of a product.
|
Response
CVE API JSON Schema
The API response may contain up to four JSON schema that define the structure of the response data. Each of the documents below describe a different aspect of the response but all include 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 CVE API returns seven primary objects in the body of the response: resultsPerPage, startIndex, totalResults, format, version, timestamp, and vulnerabilities.
The totalResults object indicates the number of CVE 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 CVE. 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 vulnerabilities object contains an array of objects equal to the number of CVE returned in the response and is sorted in ascending order by the published property of the cve object. The cve object is explained in more detail below.
JSON response objects are either optional or required. Required response objects are always returned by the API and may contain fields without data. Optional response objects are only returned when they contain data. For example, the cvssMetricV3 object is optional. CVSSv3.0 was released in 2016, thus most CVE published before 2016 do not include the cvssMetricV3 object. The exception are CVE published before 2016 that were later reanalyzed or modified. These CVE may have been updated to include CVSSv3 information. If the CVE was updated in this way, the API response would include this optional information.
cve required
This object always contains the CVE-ID, sourceIdentifier an identifier for the source of the CVE, published the date and time that the CVE was published to the NVD, lastModified the date and time that the CVE was last modified, and vulnStatus the CVE's status in the NVD.
This object also contains seven optional fields. The evaluatorComment, evaluatorImpact, and evaluatorSolution provide additional context to help understand the vulnerability or its analysis. If the CVE is listed in CISA's Known Exploited Vulnerabilities (KEV) Catalog cisaExploitAdd, cisaActionDue, cisaRequiredAction, and cisaVulnerabilityName will be returned. The cisaActionDue object indicates the date by which all federal civilian executive branch (FCEB) agencies are required to complete the cisaRequiredAction under Binding Operational Directive (BOD) 22-01, Reducing the Significant Risk of Known Exploited Vulnerabilities. Although not bound by BOD 22-01, every organization, including those in state, local, tribal, and territorial (SLTT) governments and private industry can significantly strengthen their security and resilience posture by prioritizing the remediation of the vulnerabilities listed in the KEV catalog as well.
This object may also contain up to seven objects with additional nested information. The cveTags, description, metrics, weaknesses, configurations, references, and vendorComments objects are explained in more detail below.
|
cveTags optional
This object contains one or more tags that provide contextual information about the CVE. source identifies the organization that provided the CVE Tag information and tags identifies each relevant CVE Tag. |
|
descriptions required
This object contains a description of the CVE in one or more languages. ISO 639-1:2002's two-letter language identifiers indicate the language of the description. Spanish language translations are provided by the Spanish National Cybersecurity Institute (INCIBE). |
|
metrics optional
This object contains information on the CVE's impact. If the CVE has been analyzed, this object will contain any CVSSv2 or CVSSv3 information associated with the vulnerability. source identifies the organization that provided the metrics information and type identifies whether the organization is a primary or secondary source. Primary sources include the NVD and CNA who have reached the provider level in CVMAP. 10% of provider level submissions are audited by the NVD. If a submission has been audited the NVD will appear as the primary source and the provider level CNA will appear as the secondary source. |
|
weaknesses optional
This object contains information on specific weaknesses, considered the cause of the vulnerability. Please note, a CVE that is Awaiting Analysis, Undergoing Analysis, or Rejected may not include the weaknesses object. source identifies the organization that provided the weakness information and type identifies whether the organization is a primary or secondary source. Primary sources include the NVD and CNA who have reached the provider level in CVMAP. 10% of provider level submissions are audited by the NVD. If a submission has been audited the NVD will appear as the primary source and the provider level CNA will appear as the secondary source. |
|
configurations optional
This object contains the CVE applicability statements that convey which product, or products, are associated with the vulnerability according to the NVD analysis. Please note, a CVE that is Awaiting Analysis, Undergoing Analysis, or Rejected will not include the configurations object. Like the JSON response, configurations are a hierarchical data structure that always contain one or more CPE match strings. Each object within configurations includes either an OR- or an AND-operator (and in rare cases a NEGATE flag) to covey the logical relationship of the CPE or child objects 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”.
The cpeMatch object contains the CPE Match Criteria,
the criteria's unique identifier, and a statement of whether the criteria is vulnerable.
The matchCriteriaId's corresponding
|
|
references required
This object contains supplemental information relevant to the vulnerability, and may include details that are not present in the CVE Description. Each reference within this object provides one or more resource tags (e.g., third-party advisory, vendor advisory, technical paper, press/media, VDB entries). Resource tags are designed to categorize the type of information each reference contains. source identifies the organization that provided the reference information and type identifies whether the organization is a primary or secondary source. Primary sources include the NVD and CNA who have reached the provider level in CVMAP. 10% of provider level submissions are audited by the NVD. If a submission has been audited, the NVD will appear as the primary source and the provider level CNA will appear as the secondary source. |
|
vendorComments optional
This object contains any Official Vendor Comment for the CVE. NVD provides a service whereby organizations can submit Official Vendor Comments for CVE associated with their products. Organizations can use the service in a variety of ways. For example, they can provide configuration and remediation guidance, clarify vulnerability applicability, provide deeper vulnerability analysis, dispute third party vulnerability information, and explain vulnerability impact. Official Vendor Comments can be submitted to the NVD by email at [email protected]. More information is provided on the vendor comments page. |
CVE Change History API
The CVE Change History API is used to easily retrieve information on changes made to a single CVE or a collection of CVE from the NVD. This API provides additional transparency to the work of the NVD, allowing users to easily monitor when and why vulnerabilities change.
The NVD has existed in some form since 1999 and the fidelity of this information has changed several times over the decades. Earlier records may not contain the level of detail available with more recent CVE records. This is most apparent on CVE records prior to 2015.
The URL stem for retrieving CVE information is shown below.
https://services.nvd.nist.gov/rest/json/cvehistory/2.0Parameters
changeStartDate & changeEndDate optional
These parameters return any CVE that changed during the
specified period. Please note, this is different from
the last modified date parameters used with other APIs.
If filtering by the change date, both
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 encoding automatically. Request all CVE change histories between the start and end datetimes
|
||||||||||||||||||||||||||||
cveId optional
This parameter returns the complete change history for a specific vulnerability
identified by its unique Common Vulnerabilities and Exposures identifier
(the CVE ID). Request the change history for a specific CVE using its CVE-ID
|
||||||||||||||||||||||||||||
eventName optional
This parameter returns all CVE associated with a specific
type of change event.
Please note, each request can contain only one value for the
Request all CVE that were rejected in the specified time frame
|
||||||||||||||||||||||||||||
resultsPerPage optional
This parameter specifies the maximum number of change events to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 5,000. |
||||||||||||||||||||||||||||
startIndex optional
This parameter specifies the index of the first change events to be returned in the response data. The index is zero-based, meaning the first change events is at index zero.
The CVE Change History API returns four primary objects in the response body that are
used for pagination:
resultsPerPage, startIndex, totalResults,
and cveChanges. totalResults indicates the
total number of change events that match the request parameters.
If the value of totalResults is greater than the value of resultsPerPage,
there are more events than could be returned by a single API
response and additional requests must update the Request 20 change events, beginning at index 0 and ending at index 19
|
Response
CVE Change History 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 similar information that can support developers and database administrators looking to create their own local repository.
Response Details
The CVE Change History API returns seven primary objects in the body of the response: resultsPerPage, startIndex, totalResults, format, version, timestamp, and cveChanges.
The totalResults object indicates the number of change events that match the request, 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 cveChanges object contains an array of objects equal to the number of change events returned in the response and is sorted in ascending order by the created property of the change object. The change object is explained in more detail below.
JSON response objects are either optional or required. Required response objects are always returned by the API and may contain fields without data. Optional response objects are only returned when they contain data.
change required
This object contains the following required data: the CVE-ID, the type of change event, a Universally Unique Identifier (UUID) for the change event, the source of the change event, the date and time that the CVE was modified, and an array of data containing any additional details.
The details array is a required object. It will appear whether or not the array contains additional data.
{
"resultsPerPage": 1,
"startIndex": 0,
"totalResults": 558843,
"format": "NVD_CVEHistory",
"version": "2.0",
"timestamp": "2022-10-24T12:30:00.000",
"cveChanges": [
{
"change": {
"cveId": "CVE-2020-12448",
"eventName": "Initial Analysis",
"cveChangeId": "5DEF54B9-7FF3-4436-9763-2958C5B78731",
"sourceIdentifier": "[email protected]",
"created": "2020-05-11T15:05:30.490",
"details": [
{
"action": "Added",
"type": "CVSS V2",
"newValue": "NIST (AV:N/AC:L/Au:N/C:P/I:N/A:N)"
},
{
"action": "Added",
"type": "CVSS V3.1",
"newValue": "NIST AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N"
},
{
"action": "Changed",
"type": "Reference Type",
"oldValue": "https://about.gitlab.com/blog/categories/releases/ No Types Assigned",
"newValue": "https://about.gitlab.com/blog/categories/releases/ Product, Release Notes"
},
{
"action": "Changed",
"type": "Reference Type",
"oldValue": "https://about.gitlab.com/releases/2020/04/30/security-release-12-10-2-released/ No Types Assigned",
"newValue": "https://about.gitlab.com/releases/2020/04/30/security-release-12-10-2-released/ Release Notes, Vendor Advisory"
},
{
"action": "Added",
"type": "CWE",
"newValue": "NIST CWE-22"
},
{
"action": "Added",
"type": "CPE Configuration",
"newValue": "OR\n *cpe:2.3:a:gitlab:gitlab:*:*:*:*:enterprise:*:*:* versions from (including) 12.8.0 up to (excluding) 12.8.10"
}
]
}
}
]
}
Questions, comments, or concerns may be shared with the NVD by emailing [email protected]