OWASP Dependency-Check

OWASP Dependency-Check is the software composition analysis engine that stayed deliberately old-school while most of the SCA market moved toward proprietary, curated vulnerability databases. It doesn't buy or maintain its own intelligence feed. It builds a local mirror of the U.S. National Vulnerability Database (NVD), reads an identity off every dependency it can find using Common Platform Enumeration (CPE) strings, and matches one against the other. That design is exactly why the Certified DevSecOps Professional curriculum names it directly as the SCA tool to know cold: it's free, it's self-hostable, it runs entirely offline once its data is cached, and the way it can be wrong is worth understanding precisely, because the matching underneath it is a heuristic guess wearing a lookup's clothing.

What Dependency-Check is, and the problem it solves

☺ Like you're 10: Two jobs live inside every SCA tool: figuring out exactly what you're running, and checking whether that thing is on a danger list. Dependency-Check does both itself, for free, using a public government database as its danger list.

Dependency-Check is an OWASP flagship project, created and long maintained by Jeremy Long, first released in the early 2010s and still under active development. It's Apache-2.0 licensed and ships in several forms that all share the same core engine: a standalone CLI (dependency-check.sh / dependency-check.bat), a Maven plugin, a Gradle plugin, an Ant task, and a Jenkins plugin — pick whichever one matches how the rest of your build already runs, not a separate tool with separate rules.

The problem it solves is a genuine mismatch most SCA discussions skip past. Ecosystem-native tools like npm audit or the GitHub Advisory Database work because their advisories are keyed to exact package-registry coordinates — this npm package name, this version range, this CVE — a clean lookup with almost no ambiguity. The NVD was never built that way. It was built decades ago to track vulnerabilities in operating systems and commercial software inventories, and it identifies affected products with CPE strings — cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:* — assigned by NVD analysts, not by package maintainers, and with no concept of "Maven coordinate" or "npm package" baked in anywhere. Dependency-Check's whole reason for existing is bridging that gap: turning a JAR, a wheel, or an assembly sitting on disk into a CPE-shaped identity guess, so it can be checked against a database that predates every modern package ecosystem it now gets asked to cover. See SAST, DAST & SCA for where SCA sits as one-third of a pipeline scan trio, and Software Composition Analysis in Depth for how dependency graphs resolve and how CVSS/EPSS turn a finding into a triage decision — this page goes one tool deeper into the mechanism both of those pages take as given.

How CPE matching actually works — and where it produces false positives

☺ Like you're 10: It can't always read an exact barcode, so it reads the label instead and makes its best guess at who made the product — and every guess is a chance to guess wrong.

Every scan runs a pipeline of analyzers, one per artifact type — a Jar Analyzer and Archive Analyzer for Java, an Assembly Analyzer for .NET, analyzers for Python's requirements.txt/Pipfile, Node's package-lock.json, Ruby's Gemfile, Go modules, and more, each enabled or disabled depending on what a scan finds in the target directory. Each analyzer's job is to extract evidence — candidate vendor, product, and version strings — from whatever it can read: a JAR's MANIFEST.MF attributes (Implementation-Vendor, Implementation-Title), an embedded pom.properties file, the artifact's own filename, or package-registry metadata where one exists. Every piece of evidence carries a confidence level — HIGH, MEDIUM, or LOW — reflecting how much the analyzer trusts where that string came from; a filename guess is weighted far less than an exact embedded Maven coordinate.

One analyzer gets a genuine shortcut around all that guessing: the Central Analyzer hashes a JAR with SHA-1 and queries Maven Central's search API directly. If the hash matches an unmodified artifact that's actually published on Central, Dependency-Check gets back the exact GroupId:ArtifactId:Version coordinate — no fuzzy matching required, and false-positive risk drops sharply for that dependency. That lookup needs outbound network access at scan time, and it only works for artifacts published to Central unmodified — a vendored, patched, or internally rebuilt JAR gets none of that benefit and falls back to ordinary evidence collection.

Everything else feeds into CPE identification: the collected evidence, weighted by confidence, drives a fuzzy search — built on a Lucene index — against a local copy of the NVD's own CPE dictionary. The best-scoring candidate CPE is accepted as this dependency's identity, and that CPE is then used to query the local mirror of the NVD's CVE data for anything that lists it as affected. Two independent guesses, evidence-to-CPE and CPE-to-CVE, stacked on top of each other — and the first of those two guesses is where nearly every false positive in this tool's history has come from.

Three shapes of false positive account for nearly everything this pipeline produces:

• Name and vendor/product collisions in the CPE dictionary itself. The NVD's CPE space was populated over more than a decade by many different vendors and analysts, and short, common names collide — a Java library evidence-matched to "spring" or "commons" or a similarly generic term can land on a CPE entry for a completely unrelated product that happens to share the same vendor/product string, because CPE identification is a text match against a dictionary, not a check of what the software actually is.
• Shaded, uber, and fat JARs. When a build tool repackages several libraries' classes into one artifact, the analyzers reading that artifact's manifest and embedded metadata pick up evidence from whichever library's descriptors happened to survive the repackaging — sometimes producing a CPE candidate that doesn't correspond cleanly to any one real dependency, and sometimes losing the vulnerable component's own evidence entirely inside the merge, which flips the failure into a false negative instead.
• Version-string granularity mismatches. A dependency's actual version string and the version granularity the matched CPE entry expects don't always line up — a JAR versioned 4.5.13 matching cleanly against a dictionary entry that only distinguishes at the 4.5.x level, for instance — which can pull in a CVE that was fixed two patch releases before the version actually running, or one still true because the vulnerable range extends past it. The project's own issue tracker has a long, ongoing history of exactly this category, spanning most major Java libraries at one point or another.

The suppression-file workflow

☺ Like you're 10: When the guess is wrong, you don't turn the whole guesser off — you write down, in one specific sentence, exactly which guess was wrong, why, and when to look again, and only that one guess goes quiet.

Because false positives are a known, expected cost of CPE-based matching rather than a rare bug, Dependency-Check ships a first-class suppression file mechanism instead of leaving teams to fork the tool or silence it entirely. A suppression file is XML, validated against the project's own suppression schema, and it can live locally in the repo or be fetched from an https:// URL at scan time — which is what lets a security team maintain one organization-wide suppression list that every repository's pipeline pulls centrally, rather than each team hand-copying entries.

<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.3.xsd">

  <!-- FALSE POSITIVE: CPE-name collision. This is Spring Framework,
       matched against an unrelated product sharing the same vendor
       string in the NVD's own CPE dictionary. Matches by CPE, so it
       will keep applying across future versions too — reviewed on
       every dependency bump as a matter of habit, not just once. -->
  <suppress>
    <notes><![CDATA[
      False positive — CPE vendor/product collision, not our Spring
      Framework artifact. See go/odc-fp-log entry #14. Reviewed 2026-06-02.
    ]]></notes>
    <packageUrl regex="true">^pkg:maven/org\.springframework/spring\-core@.*$</packageUrl>
    <cpe>cpe:/a:pivotal_software:spring_framework</cpe>
  </suppress>

  <!-- RISK ACCEPTANCE, not a false positive: real CVE, unreachable code
       path. Pinned to the EXACT file by SHA-1, so upgrading the jar at
       all invalidates the suppression automatically. Also time-boxed —
       it expires and the finding reappears if nobody revisits it. -->
  <suppress until="2026-12-31Z">
    <notes><![CDATA[
      CVE-2023-XXXXX: annotation processor is compile-time only, never
      packaged into the runtime artifact. Ticket SEC-4821. Revisit at
      next major upgrade or expiry, whichever comes first.
    ]]></notes>
    <sha1>3D2E5C7A1B4F9E0C6A8D2B1F4E7C9A0D3B5F8E12</sha1>
    <cve>CVE-2023-XXXXX</cve>
  </suppress>

</suppressions>

Notice the deliberate asymmetry the two examples above show. A <sha1>-pinned suppression forces a re-review on every version bump, because the hash simply stops matching — the safest default for a genuine risk-acceptance decision. A <packageUrl> or bare <cpe> match keeps silently applying to every future version of that dependency, which is exactly the convenience you want for a confirmed false positive (you shouldn't have to re-suppress the same wrong guess every release) and exactly the risk you don't want for a real, accepted vulnerability (a newly-introduced, unrelated CVE on that same component would vanish just as quietly). Pick the matcher for what you're actually suppressing, not out of habit. The HTML report itself helps here — most current releases print a ready-to-copy suppression snippet, pre-filled with the finding's own hash and identifiers, right next to each result, which is the fastest way to get the matcher fields right without hand-typing a SHA-1.

Running it as a build step: Maven, Gradle, and the CLI

☺ Like you're 10: Three different doors into the same house — pick whichever one matches how the rest of your build already runs.

Maven

The dependency-check-maven plugin is the natural fit for a Java build, because it can read the resolved dependency tree Maven itself already computed instead of re-resolving anything. Bind the check goal to the verify phase so it runs after packaging, alongside your integration tests; a multi-module reactor should use the aggregate goal instead, so every submodule's dependencies land in one consolidated report rather than one report per module.

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>10.0.4</version>  <!-- check Maven Central for the current release before pinning -->
  <configuration>
    <nvdApiKey>${env.NVD_API_KEY}</nvdApiKey>
    <suppressionFiles>
      <suppressionFile>config/suppression.xml</suppressionFile>
    </suppressionFiles>
    <formats>
      <format>HTML</format>
      <format>SARIF</format>
    </formats>
    <failBuildOnCVSS>7</failBuildOnCVSS>
  </configuration>
  <executions>
    <execution>
      <goals><goal>aggregate</goal></goals>  <!-- use "check" instead for a single-module build -->
    </execution>
  </executions>
</plugin>

# runs automatically in the verify phase:
$ mvn verify
# or invoke the goal directly, without running the rest of the build:
$ mvn org.owasp:dependency-check-maven:check

Gradle

The equivalent Gradle plugin applies with the same shape of configuration block, and it exposes its work as ordinary Gradle tasks rather than a single bound goal — which matters, because it lets you separate "refresh the local NVD cache" from "actually scan and gate," a distinction the operations section below leans on.

plugins {
    id 'org.owasp.dependencycheck' version '10.0.4'  // check the Gradle Plugin Portal for current
}

dependencyCheck {
    failBuildOnCVSS = 7
    suppressionFile = 'config/suppression.xml'
    formats = ['HTML', 'JSON', 'SARIF']
    nvd {
        apiKey = System.getenv('NVD_API_KEY')
    }
    data {
        directory = System.getenv('ODC_DATA_DIR') ?: "${System.getProperty('user.home')}/.dependency-check-data"
    }
}

# ./gradlew dependencyCheckAnalyze   — the main scan + gate task
# ./gradlew dependencyCheckUpdate    — refresh the local NVD cache only, no scan
# ./gradlew dependencyCheckAggregate — one report across a multi-project build
# ./gradlew dependencyCheckPurge     — delete the local cache and start clean

Standalone CLI

Outside a JVM build — a polyglot repo, a Node or Python service, or CI running the tool as an isolated step against a set of build artifacts — the CLI covers the same ground directly, and every flag above has a direct equivalent:

$ dependency-check.sh \
    --project "checkout-service" \
    --scan ./target/*.jar \
    --format ALL \
    --suppression config/suppression.xml \
    --failOnCVSS 7 \
    --nvdApiKey "$NVD_API_KEY" \
    --data /var/cache/odc-data \
    --out ./odc-report

--format ALL writes every supported format — HTML, XML, CSV, JSON, JUNIT, and SARIF — into --out in one pass, so downstream consumers (a human reading the HTML report, a JUnit-format test-result panel in CI, DefectDojo's Dependency Check Scan import parser reading the XML) each get the shape they want without a second run. On Windows, the same binary ships as dependency-check.bat with identical flags.

Day-to-day operations: the NVD API key, caching, and offline scans

☺ Like you're 10: The first run has to copy the whole danger list to your own shelf before it can check anything against it — do that copying once, on purpose, instead of by accident every single time.

Before a scan can match anything, Dependency-Check needs a local copy of the relevant slice of the NVD's CVE and CPE data, stored by default in an embedded H2 database. Since NIST introduced its NVD API 2.0 and tightened rate limits on unauthenticated access, running without a registered API key means a severely throttled trickle of requests — a first-time database population that can take hours, or simply time out inside a CI job's default timeout window. Registering a free key at nvd.nist.gov/developers/request-an-api-key and passing it via --nvdApiKey / nvdApiKey / nvd.apiKey raises that ceiling substantially and is close to a hard requirement for using this tool in CI at all.

The second half of the same problem is caching. An ephemeral CI runner that starts from a clean filesystem on every job re-downloads and rebuilds that entire local mirror from scratch every single run — slow, wasteful, and exactly the kind of thing a persistent cache action or mounted volume exists to prevent. The more production-grade pattern goes one step further: point every scanning job's --data (or data.directory) at a shared database server — Dependency-Check supports MySQL, PostgreSQL, Oracle, and SQL Server as alternatives to the embedded H2 file — refresh it on its own schedule with a dedicated update-only job, and have every actual scan run in read-only mode against that already-warm cache instead of managing its own.

# a scheduled job (nightly cron, or a dedicated CI pipeline) — refreshes
# the shared cache; does NOT scan anything, so it never fails a build
$ dependency-check.sh --updateonly --nvdApiKey "$NVD_API_KEY" --data /shared/odc-data

# every actual pipeline scan — reads the already-warm cache, never touches the network for data
$ dependency-check.sh --project checkout --scan ./target/*.jar \
    --data /shared/odc-data --noupdate --failOnCVSS 7 --out ./odc-report

# fully air-gapped: pre-populate --data on a machine with internet access, ship the
# directory into the isolated environment, and --noupdate makes sure it never tries to reach out

Gotchas and failure modes

☺ Like you're 10: Most of the surprises trace back to one of two things: the guess in the middle being wrong, or the local copy of the danger list not being ready yet.

• NVD API key and first-run duration, again. Worth repeating as a gotcha specifically because it's the single most common reason a team's first attempt at wiring this tool into CI just times out or appears to hang — before assuming the tool is broken, check whether it even has a key and a warm cache.
• CPE false positives. Covered at length above — name collisions, shaded jars, and version-string mismatches are the recurring three shapes, and a growing suppression file is the expected cost of running this tool, not a sign something's misconfigured.
• Silent false negatives from thin evidence. The flip side of the same mechanism: an artifact whose manifest and metadata carry too little signal to build any confident CPE candidate produces no finding at all, not a low-confidence one — there's no "we weren't sure" result in the report, only "found" or "not found."
• The embedded H2 database isn't built for concurrent writers. Several pipeline jobs pointed at the same local H2 data directory at once can hit file-locking errors, because the default embedded database expects one process at a time. The shared-cache pattern above — one scheduled writer, many read-only scanning jobs — sidesteps this entirely; pointing at a real database server (MySQL/PostgreSQL/etc.) removes the constraint outright.
• Flag and property names shift across major versions. Configuration surface (suppression-file property names, format flags, plugin goal names) has changed shape more than once across this project's history. Confirm current flags with dependency-check.sh --help or the installed plugin version's own goal documentation before assuming a config block copied from an older tutorial — including this page — still applies verbatim.
• The Central Analyzer's benefit costs outbound calls. On a very large monorepo scanning hundreds of JARs, every Central Analyzer lookup is its own call to Maven Central's search API, which can slow a scan noticeably or run into its own rate limiting — a real cost for the false-positive reduction it buys, worth knowing about before disabling it out of confusion over a slow scan.

Where it sits against Snyk, Syft & Grype, and npm-audit-style scanners

☺ Like you're 10: Every SCA tool trades the same two things against each other — how it knows what's vulnerable, and how sure it can be about what you're actually running — just in different proportions.

The real question is rarely "which SCA tool is best" in the abstract — it's which matching basis fits the ecosystem and the false-positive tolerance of the pipeline in front of you.

Dependency-Check's honest niche is the combination no other row in that table matches at once: zero licensing cost, genuinely offline-capable once the cache is warm, and broad multi-ecosystem coverage through one engine — paid for with a false-positive rate the ecosystem-native and commercially-curated alternatives don't carry, because they were built around exact identity instead of an inferred one. A mature pipeline commonly runs it precisely where that trade pays off (Java and .NET builds with no free ecosystem-native advisory feed as good as npm's or PyPI's) and lets an exact-match tool cover ecosystems that already have one. See Software Bills of Materials for how Syft's SBOM-first approach avoids the identity-guessing step structurally rather than managing it after the fact, and Vulnerability Management & Triage for how a Dependency-Check finding and a Trivy or Grype finding on the same underlying package get deduplicated into one entry instead of two tickets for one bug.

This page is the tool-level companion to Software Composition Analysis in Depth, which covers dependency-graph resolution, transitive vulnerabilities, and reading CVSS/EPSS to triage exactly the kind of finding this tool produces. For the SBOM half of "what's actually in this build," see Software Bills of Materials and Dependency & License Risk Management; for how a Dependency-Check finding gets deduplicated against everything else your pipeline runs, see Vulnerability Management & Triage and the DefectDojo tool page. And for the wider SCA landscape this tool sits inside, see The Tool Landscape.