An NVD API 2.0 response wraps a list of vulnerabilities in paging fields. Each CVE object has descriptions, metrics, weaknesses, references and configurations. Configurations are nested nodes with an operator and cpeMatch entries, where vulnerable true means affected and vulnerable false marks a platform that is merely required.
The envelope
I queried the public endpoint for a single CVE by ID. The top level of the response held resultsPerPage, startIndex, totalResults, format with the value NVD_CVE, version 2.0 and a timestamp. Those paging fields are what you use to walk a larger query: read totalResults, then step startIndex until you have them all.
Each item in the vulnerabilities array wraps a cve object. In my sample that object held these fields.
| Field | What it holds |
|---|---|
| id | The CVE identifier |
| sourceIdentifier | Who supplied the record |
| published, lastModified | Timestamps |
| vulnStatus | Analysis status, which read Analyzed in the sample |
| descriptions | Text, per language |
| metrics | Scores, grouped by scoring system |
| weaknesses | CWE entries |
| configurations | Which products are affected |
| references | Links |
| cisaExploitAdd and related fields | Known exploited details when applicable |
The sample also had an affected field. Field sets change over time, so parse by name and ignore what you do not use.
Metrics are grouped by version
In the sample, the metrics object had separate keys for CVSS 3.1, CVSS 2 and an SSVC entry. A CVE may carry some of these and not others, and newer records may carry a different set. Pick the version you support, and handle a missing group as unknown.
Configurations and cpeMatch
Configurations are where tool builders get confused. Each configuration has nodes, each node has an operator such as AND or OR, and each node has a list of cpeMatch objects. A cpeMatch holds a vulnerable flag, a criteria string in CPE 2.3 form, and optional version bounds such as versionEndExcluding.
The sample showed a case with an AND at the top level. One OR node held a firmware entry with vulnerable true and an end version, and another OR node held the hardware product with vulnerable false. The meaning: the firmware below that version is vulnerable, and it is vulnerable when running on that hardware. The hardware entry is a condition, not a vulnerable thing.
So the rule is simple. Report as affected only entries where vulnerable is true, and use the sibling nodes with vulnerable false as context for the AND logic.
How to evaluate a match
- Convert your component to a CPE if you can, or search by CPE name.
- For each configuration, evaluate nodes with their operators.
- For a cpeMatch with vulnerable true, compare your version to the bounds: start including, start excluding, end including, end excluding.
- If an AND configuration includes a platform node, check the platform too.
- Record which node matched, so you can explain the result.
Mapping package names to CPEs is the weak link. Many open source packages have no clean CPE, so matching by package URL against ecosystem advisories often works better. See purl or CPE.
Be a good API client
Cache responses. Use paging fields rather than huge result sets. Check NVD's own developer pages for current rate limits and API key rules, because those details can change and I did not confirm them for this post.
Try it yourself
Click through it at your own pace, or open it full screen. See how affected and fixed versions are shown together for each finding.
Where this fits
NVD data is one input among several. See why two scanners report different vulnerabilities for one SBOM. Safeguard offers SBOM and dependency scanning, and the free scan shows results on a real project.
Quick check
What does vulnerable false mean in cpeMatch?
In the sample, it marked a required platform in an AND configuration, not a vulnerable product. Treat it as a condition.
Is every CVE scored with CVSS 3.1?
No. The metrics object is grouped by scoring system and a record may lack some groups. Handle missing ones as unknown.
Sources
Last reviewed: 19 October 2026.
