Add the OWASP Dependency-Check with an NVD API key to secure your Java project

gist-add-dependency-check-maven-with-nvd-api-key.md

Using an NVD API Key with dependency-check-maven

📷 Photo: Antique Door Lock Athens, Ohio by Wendy Bayer

---

For Java-based projects, you can use the Open Worldwide Application Security Project (OWASP) Dependency-Check to statically scan your project's dependencies for security vulnerabilities.

Recent versions of this Maven plugin require a National Vulnerability Database (NVD) API key to avoid severe pull rate limiting of the database. This is especially critical in Continuous Integration/Continuous Deployment (CI/CD) environments.

This post guides you through...

1. Requesting an NVD API key
2. Configuring dependency-check-maven with it

---

Request an NVD API Key

To run OWASP Dependency-Check in your project, you will most likely need to set your own National Vulnerability Database (NVD) API key to pull the vulnerability database used to scan your project's dependencies. Without this key set, the scan will either fail with a 403 or similar unauthorized return code, or the download will be throttled with a message like this...

[WARNING] An NVD API Key was not provided - it is highly recommended to use an NVD API key as the update can take a VERY long time without an API Key

The National Vulnerability Database is maintained by the National Institute of Standards and Technology (NIST)

To get an NVD API key...

1. Request one online at NVD Developers: Request an API Key

   📧 You will need at least your email address

2. You will receive an email at that address with an expiring link that redirects you to activate your API key

3. Be sure to click on that link before it expires and store your key in a secure place, like a password manager

4. Verify your key by substituting your activated NVD API key below...

   export NVD_API_KEY=<your-nvd-api-key> && \
     curl -s -o /dev/null -w "%{http_code}\n" \
     -H "Accept: application/json" \
     -H "apiKey: $NVD_API_KEY" \
     "https://services.nvd.nist.gov/rest/json/cves/2.0?cpeName=cpe:2.3:o:microsoft:windows_10:1607:*:*:*:*:*:*:*"

   🟢 You should get a returned 200 response code

   The cpeName=cpe:2.3:o:microsoft:windows_10:1607:*:*:*:*:*:*:* is just a known vulnerability to find using your key.

   export NVD_API_KEY=xxxxxx-yyyy-zz && \
   curl -s -o /dev/null -w "%{http_code}\n" \
   -H "Accept: application/json" \
   -H "apiKey: $NVD_API_KEY" \
   "https://services.nvd.nist.gov/rest/json/cves/2.0?cpeName=cpe:2.3:o:microsoft:windows_10:1607:*:*:*:*:*:*:*"
   
   200

---

Configure dependency-check-maven

One of the safest, most portable, and testable approaches is to use an environment variable to supply the NVD API key.

export NVD_API_KEY=<your-nvd-api-key>

You then have more than one option to configure your Maven pom.xml to use the environment variable.

Define a Maven Property and Use the nvdApiKey Parameter

Container-native (The Twelve-Factor App) and environment-agnostic practices prefer environment variables to have precedence over all other configurations. The highest precedence parameter of the dependency-check-maven plugin is nvdApiKey.

First, declare a standard Maven property for your NVD API key environment variable (NVD_API_KEY), and then reference this property in the plugin configuration for the nvdApiKey parameter.

This example shows the configuration for the dependency check to run as part of the Maven verify lifecycle phase, i.e., mvn verify -DskipTests...

<?xml version="1.0"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
...
    <name>My Project</name>
    <properties>
      ...
        <dependencyCheckMavenVersion>12.2.0</dependencyCheckMavenVersion>
        ...
                <!-- Used in Dependency Security Scanning -->
        <nvd.apiKey>${env.NVD_API_KEY}</nvd.apiKey>
    </properties>
    ...
    <build>
        ...
        <plugins>
        ...
            <!-- Dependency Security Scanning -->
            <plugin>
                <groupId>org.owasp</groupId>
                <artifactId>dependency-check-maven</artifactId>
                <version>${dependencyCheckMavenVersion}</version>
                <configuration>
                    <nvdApiKey>${nvd.apiKey}</nvdApiKey>
                    ...
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>check</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            ...
        </plugins>
    </build>
</project>

📖 For a full reference, see this Groovy (Selenium) example

Use the nvdApiKeyEnvironmentVariable Parameter

Per the documentation, you can use the nvdApiKeyEnvironmentVariable parameter to configure the plugin with an environment variable that contains your NVD API key.

👉 However, as the documentation states...

is potentially overwritten by nvdApiKey

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>${dependency-check.version}</version>
  <configuration>
    <nvdApiKeyEnvironmentVariable>NVD_API_KEY</nvdApiKeyEnvironmentVariable>
  </configuration>
</plugin>

---