Data Sources
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.
Source API
The Source API is used to easily retrieve detailed information on the organizations that provide the data contained in the NVD dataset.
The API is updated whenever a new source is added, or an existing source is modified. Data sources change so infrequently that users interested in this information may choose to limit their requests to once per day.
https://services.nvd.nist.gov/rest/json/source/2.0Parameters
{start date}{end date}
These parameters return only the source records that were last
modified during the specified period. If a source 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
lastModStartDate and lastModEndDate are
required.
The maximum allowable range when using any
date range parameters is 120 consecutive days.
A source record is considered "modified" when any of the follow actions occur:
- A new source record is created
- An existing source record is modified
- An existing source changes acceptance level in CVMAP
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.
https://services.nvd.nist.gov/rest/json/source/2.0/?lastModStartDate=2021年08月04日T13:00:00.000%2B01:00&lastModEndDate=2021年10月22日T13:36:00.000%2B01:00{page limit}
This parameter specifies the maximum number of source records to be returned in a single API response. For network considerations, the default value and maximum allowable limit is 1,000.
{sourceIdentifier}
This parameter returns all source records where the exact value of sourceIdentifiers
matches the {sourceIdentifier}.
A request made to the Source API without any additional parameters will return detailed information on
all organizations that provide the data contained in the NVD dataset, including every valid
{sourceIdentifier} value. The CVE API also
returns valid {sourceIdentifier} values within the descriptions object.
https://services.nvd.nist.gov/rest/json/source/[email protected] {offset}
This parameter specifies the index of the first source record to be returned in the response data. The index is zero-based, meaning the first source record is at index zero.
The Source API returns four primary objects in the response body that are
used for pagination:
resultsPerPage, startIndex, totalResults,
and sources. totalResults indicates the
total number of source 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 startIndex
to get the remaining records.
The best, most efficient, practice for keeping up to date with the NVD is to use the date range parameters to request only the source records that have been modified since your last request.
https://services.nvd.nist.gov/rest/json/source/2.0/?resultsPerPage=20&startIndex=0https://services.nvd.nist.gov/rest/json/source/2.0/?resultsPerPage=20&startIndex=20Response
Data Sources 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 Source API returns seven primary objects in the body of the response: resultsPerPage, startIndex, totalResults, format, version, timestamp, and sources.
The totalResults object indicates the number of source 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 sources 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. The sources 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 v3AcceptanceLevel object is optional so it will only appear when a data source is a participant in the Collaborative Vulnerability Metadata Acceptance Process (CVMAP) and it has an CVSSv3 acceptance level.
sources required
This object contains the following required data: source name, the email address used by the CVE Program to identify the source, an object containing all email addresses linked to the source, the date and time that the source first appeared in the NVD, and the date and time that the record was last modified.
If the source participates in CVMAP the following optional objects may be returned: v2AcceptanceLevel, v3AcceptanceLevel, and cweAcceptanceLevel. Each object contains the source's current level in the process and the date that the level last changed. Complete audit histories are available on the CVMAP webpage.
{
"resultsPerPage": 2,
"startIndex": 0,
"totalResults": 215,
"format": "NVD_SOURCE",
"version": "2.0",
"timestamp": "2022-08-25T17:48:15.150",
"sources": [
{
"name": "MITRE",
"contactEmail": "[email protected]",
"sourceIdentifiers": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"lastModified": "2019-09-09T16:18:45.930",
"created": "2019-09-09T16:18:45.930",
"v3AcceptanceLevel": {
"description": "Contributor",
"lastModified": "2022-08-18T00:00:05.690"
},
"cweAcceptanceLevel": {
"description": "Reference",
"lastModified": "2022-08-19T00:00:00.060"
}
},
{
"name": "DWF",
"contactEmail": "[email protected]",
"sourceIdentifiers": [
"[email protected]",
"[email protected]"
],
"lastModified": "2019-09-09T16:18:45.930",
"created": "2019-09-09T16:18:45.930",
"cweAcceptanceLevel": {
"description": "Reference",
"lastModified": "2020-10-01T00:00:00.070"
}
}
]
}
Questions, comments, or concerns may be shared with the NVD by emailing [email protected]