1. Introduction

The National Vulnerability Database (NVD) is a vulnerability database maintained by the National Institute of Standards and Technology (NIST).

NVD provides security information about publicly known vulnerabilities, including:

• CVE identifiers
• Vulnerability descriptions
• CVSS severity scores
• Affected products
• CWE information
• References
• CPE information
• Vulnerability configurations
• Known vulnerability metadata

NVD is widely used by security tools such as OWASP Dependency-Check to identify vulnerable third-party software dependencies.

2. What is NVD?

NVD = National Vulnerability Database

Official website:

The NVD provides information about publicly disclosed software and hardware vulnerabilities.

For example, a vulnerability may have an identifier such as:

CVE-2021-44228

This is the well-known Log4Shell vulnerability.

You can search for a CVE directly on the NVD website.

Example:

https://nvd.nist.gov/vuln/detail/CVE-2021-44228Code language: JavaScript (javascript)

3. What is CVE?

Before understanding the NVD API, it is important to understand CVE.

CVE = Common Vulnerabilities and Exposures

A CVE identifier uniquely identifies a publicly known vulnerability.

Example:

CVE-2021-44228

The CVE record can contain information such as:

CVE ID
Description
Affected products
CVSS score
CWE
References
Published date
Modified date

NVD enriches CVE information with additional security information.

4. What is CVSS?

CVSS = Common Vulnerability Scoring System

CVSS is used to describe the severity of a vulnerability.

Typical severity categories are:

For example:

CVSS = 9.8

generally indicates a critical-severity vulnerability.

Important: CVSS is a severity measurement, not necessarily an indication of the actual risk in your specific environment.

5. Exploring the NVD Website

Open:

The NVD website provides several useful areas.

Commonly used sections include:

Vulnerabilities
CVE
CPE
Data Feeds
Developers / API

For vulnerability research, the most commonly used functionality is the CVE search.

6. Searching for a CVE

Go to:

Search for:

CVE-2021-44228

You can inspect information such as:

CVE ID
Description
CVSS
Weakness
Configurations
References

This is useful when manually investigating a vulnerability discovered by an SCA tool.

7. What is the NVD API?

The NVD also provides programmatic access to vulnerability information.

Instead of manually opening the website, a security tool can communicate with NVD using an API.

Conceptually:

Security Tool
     |
     | HTTP API Request
     v
NVD API
     |
     v
CVE Vulnerability Data

This allows security tools to automatically retrieve vulnerability information.

8. Why Do Security Tools Use the NVD API?

Consider a Java application with hundreds of dependencies.

For example:

Application
 |
 +-- Spring
 |
 +-- Jackson
 |
 +-- Log4j
 |
 +-- Apache Commons
 |
 +-- Tomcat
 |
 +-- Other libraries

Manually checking every dependency against NVD would be impractical.

An SCA tool can automate this process:

Source Code
     |
     v
Dependency Analysis
     |
     v
Identify Dependencies
     |
     v
Query Vulnerability Database
     |
     v
NVD
     |
     v
Match CVEs
     |
     v
Generate Security Report

This is one of the reasons OWASP Dependency-Check uses NVD vulnerability information.

9. What is an NVD API Key?

The NVD API key is a credential provided by NVD that allows applications to access the NVD API.

It is used by tools such as:

OWASP Dependency-Check
Security scanners
Vulnerability management systems
Custom security applications
CI/CD security pipelines

The API key helps NVD identify and manage API requests.

10. Do You Always Need an NVD API Key?

Not every interaction with the NVD website requires an API key.

For example, you can manually browse:

https://nvd.nist.gov/Code language: JavaScript (javascript)

without an API key.

However, automated tools that query the NVD API can benefit from an API key and may require one depending on the tool, API usage, rate limits, and configuration.

For OWASP Dependency-Check, using an NVD API key is recommended for reliable and efficient NVD updates.

11. Requesting an NVD API Key

Open the official NVD API key request page:

Follow the instructions provided by NVD.

Typically, you provide information such as:

Organization
Email address
Organization type

Then submit the request.

NVD will provide instructions for activating/obtaining the API key.

12. Important: Protect Your API Key

Treat the NVD API key like a credential.

Do NOT put it directly into:

GitHub repositories
Public scripts
Docker images
Public documentation
ScreenshotsCode language: PHP (php)

For example, avoid:

dependency-check.sh --nvdApiKey 75C90-XXXXXXXX-CB64Code language: CSS (css)

when sharing terminal screenshots publicly.

Instead, use an environment variable.

13. Setting the NVD API Key as an Environment Variable

Linux/macOS:

export NVD_API_KEY="YOUR_API_KEY"Code language: JavaScript (javascript)

Verify that it exists:

echo "$NVD_API_KEY"Code language: PHP (php)

For security, avoid displaying the actual key when recording a tutorial.

You can check whether it is set:

if [ -n "$NVD_API_KEY" ]; then
    echo "NVD API key is configured"
else
    echo "NVD API key is not configured"
fiCode language: PHP (php)

14. Testing the NVD API

The NVD API provides a CVE API endpoint.

Example:

https://services.nvd.nist.gov/rest/json/cves/2.0Code language: JavaScript (javascript)

You can test access using curl.

Example:

curl \
  -H "apiKey: $NVD_API_KEY" \
  "https://services.nvd.nist.gov/rest/json/cves/2.0?resultsPerPage=1"Code language: JavaScript (javascript)

The API should return JSON data.

15. Understanding the API Response

The response is JSON.

Conceptually, it contains information similar to:

{
  "resultsPerPage": 1,
  "startIndex": 0,
  "totalResults": 1,
  "vulnerabilities": [
    {
      "cve": {
        "id": "CVE-XXXX-XXXXX",
        "descriptions": [],
        "metrics": {},
        "references": []
      }
    }
  ]
}Code language: JSON / JSON with Comments (json)

The exact response structure can vary depending on the API request and available vulnerability information.

16. NVD API and OWASP Dependency-Check

OWASP Dependency-Check can use NVD vulnerability information to identify vulnerabilities in application dependencies.

The workflow is approximately:

Java Application
       |
       v
pom.xml
       |
       v
Dependency-Check
       |
       v
Dependency Identification
       |
       v
NVD API
       |
       v
CVE Information
       |
       v
Vulnerability Matching
       |
       v
Dependency-Check Report

17. Configure NVD API Key for Dependency-Check

If you are using the Dependency-Check CLI:

dependency-check.sh \
  --project "My Application" \
  --scan . \
  --nvdApiKey "$NVD_API_KEY"Code language: JavaScript (javascript)

On Windows:

dependency-check.bat ^
  --project "My Application" ^
  --scan . ^
  --nvdApiKey "%NVD_API_KEY%"Code language: JavaScript (javascript)

18. Maven Configuration

If you use the OWASP Dependency-Check Maven plugin, you can pass the API key using an environment variable.

Example:

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>YOUR_VERSION</version>

    <configuration>
        <nvdApiKey>${env.NVD_API_KEY}</nvdApiKey>
    </configuration>
</plugin>Code language: HTML, XML (xml)

Then:

export NVD_API_KEY="YOUR_API_KEY"Code language: JavaScript (javascript)

Run:

mvn dependency-check:checkCode language: CSS (css)

This approach prevents the actual API key from being hard-coded in pom.xml.

19. GitHub Actions

For CI/CD, do not hard-code the API key.

Store it as a GitHub Actions secret.

Go to:

GitHub Repository
    ↓
Settings
    ↓
Secrets and variables
    ↓
Actions
    ↓
New repository secretCode language: PHP (php)

Use:

Name:
NVD_API_KEY

Value:
Your NVD API key

Then use it in GitHub Actions.

Example:

name: Dependency Check

on:
  push:
  pull_request:

jobs:
  dependency-check:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run OWASP Dependency-Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: "My Application"
          path: "."
          format: "HTML"
          args: >
            --nvdApiKey ${{ secrets.NVD_API_KEY }}

      - name: Upload Dependency-Check Report
        uses: actions/upload-artifact@v4
        with:
          name: dependency-check-report
          path: reports/Code language: JavaScript (javascript)

Always verify the current Dependency-Check GitHub Action documentation before using a specific action version in production.

20. Common NVD API Key Error

A common error is:

NvdApiException: Invalid API KeyCode language: HTTP (http)

Example:

[ERROR] Error updating the NVD Data

Caused by:
NvdApiException: Invalid API KeyCode language: JavaScript (javascript)

This generally means that the API key being supplied to Dependency-Check is not being accepted by the NVD API.

21. Troubleshooting Invalid API Key

Step 1 — Check the key

Make sure you are using the correct current key.

echo "$NVD_API_KEY"Code language: PHP (php)

Do not publish the output.

Step 2 — Test the API directly

curl \
  -H "apiKey: $NVD_API_KEY" \
  "https://services.nvd.nist.gov/rest/json/cves/2.0?resultsPerPage=1"Code language: JavaScript (javascript)

If the API returns an invalid-key response, investigate the NVD key itself.

If the direct API call works but Dependency-Check fails, investigate the Dependency-Check configuration and version.

Step 3 — Check the environment variable

Run:

if [ -z "$NVD_API_KEY" ]; then
    echo "NVD_API_KEY is not set"
else
    echo "NVD_API_KEY is set"
fiCode language: PHP (php)

Step 4 — Check for accidental spaces

An API key copied with leading/trailing spaces can cause problems.

Instead of:

export NVD_API_KEY=" YOUR_API_KEY "Code language: JavaScript (javascript)

use:

export NVD_API_KEY="YOUR_API_KEY"Code language: JavaScript (javascript)

22. NVD API Without Hard-Coding Credentials

Bad practice:

dependency-check.sh \
  --nvdApiKey "YOUR_REAL_API_KEY"Code language: JavaScript (javascript)

Better:

export NVD_API_KEY="YOUR_REAL_API_KEY"

dependency-check.sh \
  --nvdApiKey "$NVD_API_KEY"Code language: JavaScript (javascript)

Best practice in CI/CD:

GitHub Secret
      |
      v
GitHub Actions
      |
      v
Environment/CLI argument
      |
      v
Dependency-Check
      |
      v
NVD API

23. NVD API and Rate Limiting

The NVD API has request-rate considerations.

If many applications or CI/CD jobs continuously request NVD data, unnecessary API calls can create problems.

Therefore:

• Use an API key where appropriate.
• Avoid unnecessary repeated database updates.
• Cache vulnerability data where your tool supports it.
• Avoid running full vulnerability database updates unnecessarily.
• Configure CI/CD jobs carefully.

24. NVD API 2.0

Modern NVD integrations use the NVD API 2.0.

The CVE API endpoint is:

https://services.nvd.nist.gov/rest/json/cves/2.0Code language: JavaScript (javascript)

For example:

curl \
  -H "apiKey: $NVD_API_KEY" \
  "https://services.nvd.nist.gov/rest/json/cves/2.0?resultsPerPage=5"Code language: JavaScript (javascript)

The API can be queried using parameters to retrieve specific vulnerability information.

25. Practical Lab

Objective

In this lab you will:

1. Open the NVD website.
2. Search for a CVE.
3. Request an NVD API key.
4. Configure the API key.
5. Test the NVD API.
6. Configure OWASP Dependency-Check.
7. Run a vulnerability scan.

Step 1 — Open NVD

Open:

https://nvd.nist.gov/Code language: JavaScript (javascript)

Explore:

Vulnerabilities
CVE
CPE
Developers

Step 2 — Search for a CVE

Search:

CVE-2021-44228

Review:

CVE ID
Description
CVSS
Weakness
Configurations
References

Step 3 — Request an API Key

Open:

https://nvd.nist.gov/developers/request-an-api-keyCode language: JavaScript (javascript)

Complete the NVD API key request process.

Step 4 — Configure the Key

macOS/Linux:

export NVD_API_KEY="YOUR_API_KEY"Code language: JavaScript (javascript)

Verify:

if [ -n "$NVD_API_KEY" ]; then
    echo "API key configured"
fiCode language: PHP (php)

Step 5 — Test the API

Run:

curl \
  -H "apiKey: $NVD_API_KEY" \
  "https://services.nvd.nist.gov/rest/json/cves/2.0?resultsPerPage=1"Code language: JavaScript (javascript)

Confirm that the API returns JSON.

Step 6 — Run Dependency-Check

Example:

dependency-check.sh \
  --project "NVD Lab" \
  --scan . \
  --nvdApiKey "$NVD_API_KEY"Code language: JavaScript (javascript)

Step 7 — Review the Report

Open the generated Dependency-Check report.

Look for:

Dependencies
Vulnerabilities
CVE
CVSS
Severity
Evidence
References

26. Complete Security Data Flow

The complete SCA flow can be represented as:

                Developer
                    |
                    v
              Source Code
                    |
                    v
             pom.xml/package.json
                    |
                    v
          OWASP Dependency-Check
                    |
                    v
          Identify Dependencies
                    |
                    v
               NVD API
                    |
             NVD API Key
                    |
                    v
             NVD CVE Data
                    |
                    v
          Vulnerability Matching
                    |
                    v
             SCA Report
                    |
                    v
          Developer / Security Team

27. NVD Website vs NVD API

28. Important Security Practices

Follow these practices when using an NVD API key:

Do not commit the key to Git
Do not publish the key in tutorials
Do not put the key in screenshots
Do not put the key directly into public YAML files
Do not share the key with other people
Use GitHub Secrets for CI/CD
Use environment variables for local testing
Rotate/reissue credentials when necessaryCode language: PHP (php)

29. Key Takeaways

Remember these five concepts:

NVD
 ↓
National Vulnerability Database

CVE
 ↓
Unique vulnerability identifier

CVSS
 ↓
Vulnerability severity scoring system

NVD API
 ↓
Programmatic access to NVD vulnerability data

NVD API Key
 ↓
Credential used when accessing the NVD API

The overall SCA relationship is:

Application
    ↓
Dependencies
    ↓
OWASP Dependency-Check
    ↓
NVD API
    ↓
CVE Database
    ↓
Vulnerability Detection
    ↓
Security Report

This makes the NVD API an important component of an automated Software Composition Analysis workflow, particularly when using tools such as OWASP Dependency-Check.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.