CVE API is being used by tons of vulnerability management programs and application security programs to investigate whether a piece of software or library is vulnerable to a in preparation for CVSS v4/ CVSS4m and adding CISA KEV. The new API is changing or at least their JSON representations, as provided by two key data providers: the CVE Project and NIST’s NVD.

What is changing? Everything… but not quite.

The new formats are not backwards compatible with the previous vulnerability format. If you leverage this API for CVSS calculation, vulnerability management and application security program you might want to consider the changes. In other words, any parser that processes data provided by the earlier formats for CVE and Vulnerabilities would not work with the new format without modification. However, they capture the same information records as before, so their structure and contents would be very easily recognizable by anyone familiar with the old formats.

From a practical point of view, any script or software currently dealing with these data formats would have to be updated to parse and handle the new ones.

We are looking at two independent but connected changes…

CVE JSON version 5

As described here, the old (version 4) format and related downloads will be deprecated on or before Dec 31st 2023.

If you are currently working with V4 files for your vulnerability and vulnerability management program, you need to start looking to migrate your scripts and code to the new format. The CVE Project provides access to CVE data with the new format in its repository. If you are leveraging this API for CVSS calculation, vulnerability management and application security program, you might want to consider the changes

What is the new CVE API format?

Vulnerability grouping:

The bulk of the CVE data is now placed within the top-level containers array, with the cna container capturing the “canonical” information from the CVE Numbering Authority (CNA) that originally assigned the CVE ID. This container is the only one required and always present.

The other containers live inside the adp array (itself inside containers), with each object in the array holding CVE details from a different Authorized Data Publisher (ADP) participating in the CVE program. Each object inside the “adp” array mirrors the structure of the “cna” container.

The image below shows the top-level “containers” element, with its “cna” (object, required) and “adp” (array, optional) elements.

Affected vs Affects (CPEs all the way)

When describing the products affected by each CVE, the new format has replaced the affects object with the affected array.

This seems like a small change on the face of it, but it hides an important shift: inside “affected” all vendors and products are now described through their CPE name.

CPE can be software you extract from vulnerability scanners, in your vulnerability management program or libraries for your application security program.

Below we can see the same product entry for CVE-2023-36874 in the current/old version 4 format and the new version 5.

Apart from changes to the overall structure of the affects/affected elements (e.g. products are no longer grouped by vendor), we can see that the product information is more specific and complete, including CPE names and a structured version constraint.

CVSS Impacts move to Metrics

The other noticeable change in the structure of the JSON from NVD is the move of CVSS information from the impact object to the metrics array. This critical parameter is used to calculate the base score in CVSS for your vulnerabilities in the vulnerability management or application security program.

However, please note that V5 features a new “impacts” element (array) that can be confused with the V4 “impact” object. They contain different information. Remember that the CVSS details are in the new “metrics” array.

Other changes

The new structure is generally more extensible, adapting to application security and vulnerability management, as we can see from the transitions from singular objects to arrays containing many elements. This is clearly noticeable at the top level by introducing the “cna” and “adp” containers.

On a different front, apart from the CPE details now available in the “affected” array, the configurations element contains the “configuration required for exploiting this vulnerability”.

Furthermore, the new schema features elements for “workarounds”, “solutions”, “exploits”, “timeline”, “tags” and others. The official V5 schema documentation is quite well structured and a must-read for anybody working with these formats.

How to query NVD API to get CVSS

there are open alternatives to CVSS and NVD databases for your vulnerability management program. Those toolsets would need to be updated, so beware if after September, there is some interruption

Official query tool from first: https://github.com/toolswatch/pycvss3

NIST Wrapper: https://nvdlib.com/en/latest/

CVE API from open Vulnerability DB: https://docs.opencve.io/api/cve/

NVD API V2

NIST’s NVD provides its own version of the CVE database, with additional information and query capabilities. Naturally, this has meant this database and its access APIs are changing as well.

Most of the CVE API V2 data format changes align with the CVE JSON schema V5 updates, but others are specific to NVD.

This transition has been in progress for a while now, following a schedule defined by NIST as follows (text in bold is for future milestones).

As before, the NVD data includes the “configurations” elements to capture the combinations of affected products. 

However, the new version provides more details and includes the “matchCriteriaId”, which can be used to query the list of CPEs matching that CPE name (through the CPE APIs V2).

How does CISA KEV Integrate in new CVE API

But one of the key additions to V2 (in part because it’s completely new to this version) is the inclusion of CISA KEV information for each CVE. This is a very nice touch from the NVD guys that can save us additional requests to the CISA data sources.

The new CVE APIs

While the new APIs have been improved in terms of structure and performance, we should keep in mind that they are a free service, not geared towards extremely high volumes.

Even though they provide powerful search capabilities, they don’t provide multi-CVE (or multi-CPE) requests, which means that many requests must be performed per-CVE/CPE basis.

The above, coupled with a rate limit of 50 requests per 30-second window (for requests with API Key; without Key it’s only 5 requests), could mean that some users might find this quite limiting. Clearly, the preferred strategy for consuming this data should be based around local storage of the complete DB and regular updates only of modified data.

Another significant change with this upgrade is removing the one-file-per-year downloads. These were a good way to kick-start a local copy of the database, but now we’ll have to rely on the paginated API V2 for this purpose, as described in the recommended workflow.

Taking into account that the maximum number of CVEs per request is 2000, and that there are around 220,000 CVEs in the database, it would take 110 requests to fetch the whole dataset. If each request takes around 4 seconds, as our tests show, and we sleep for 6 seconds between requests, as recommended in the documentation, it should take less than 20 minutes to fetch the whole CVE database into your local copy.

After that, it’s just a question of fetching only new and updated items…