OWASP Dependency-Check: Setup, CI Integration & Report Guide

OWASP Dependency-Check is a free, open-source SCA (Software Composition Analysis) tool that identifies known vulnerabilities in project dependencies by cross-referencing NVD CVE data. This guide covers installation, Maven/Gradle setup, CI integration, and false positive management.

What is OWASP Dependency-Check?

OWASP Dependency-Check (DC) scans your project's libraries and compares them against the National Vulnerability Database (NVD) CVE feed. It supports Java JARs, .NET assemblies, npm packages, Python requirements files, and more. Because it stores the NVD data locally, it works in offline and air-gapped environments — a major advantage over cloud-based SaaS tools.

Installation

Three installation paths: standalone CLI, Maven plugin, or Gradle plugin.

# Option 1: Standalone CLI (download zip from GitHub releases)
unzip dependency-check-*.zip
./dependency-check/bin/dependency-check.sh --version

# Option 2: Maven plugin (add to pom.xml)
# <plugin>
#   <groupId>org.owasp</groupId>
#   <artifactId>dependency-check-maven</artifactId>
#   <version>9.0.9</version>
# </plugin>

# Option 3: Homebrew (macOS/Linux)
brew install dependency-check

Running a Scan

# CLI scan with NVD API key
./dependency-check.sh \
  --project "MyApp" \
  --scan ./target/ \
  --format HTML \
  --nvdApiKey YOUR_NVD_API_KEY \
  --out ./reports/

# Maven: run as part of build
mvn dependency-check:check -DnvdApiKey=YOUR_KEY

# Maven: fail build on CVSS >= 7
mvn verify -DfailBuildOnCVSS=7 -DnvdApiKey=YOUR_KEY

HTML Report Walkthrough

The HTML report (dependency-check-report.html) contains three sections: a summary table of all scanned dependencies with their CVE counts, a detailed findings section with CPE identifiers and CVSS scores, and a suppressed findings section. Focus on the Critical and High rows first. Each row links to the NVD entry for full CVE details and available patches.

CI/CD Integration — GitHub Actions

name: OWASP Dependency-Check

on: [push, pull_request]

jobs:
  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run OWASP Dependency-Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: 'MyApp'
          path: '.'
          format: 'HTML'
          args: >
            --failOnCVSS 7
            --nvdApiKey {{ secrets.NVD_API_KEY }}

      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: dependency-check-report
          path: reports/

NVD API Key Setup

Register for a free API key at nvd.nist.gov/developers/request-an-api-key. After registration you receive an email with the key. Without it, NVD updates are throttled at 5 requests/30 sec — the first update can take over an hour. With the key: 50 requests/30 sec, typically under 5 minutes.

Store the key as a CI secret (NVD_API_KEY) and pass it via --nvdApiKey flag or Maven property. Never hardcode it in pom.xml.

Suppression File for False Positives

<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.3.xsd">
  <suppress>
    <notes>CVE affects a code path not reachable in our app</notes>
    <cve>CVE-2023-12345</cve>
    <gav regex="true">^com\.example:mylib:.*$</gav>
  </suppress>
</suppressions>

Pass via --suppression suppression.xml (CLI) or <suppressionFile> (Maven). Always include a <notes> element explaining why the suppression is valid — it serves as your compliance audit trail.

OWASP DC vs Snyk Comparison