The sbt-dependency-check plugin allows projects to monitor dependent libraries for known, published vulnerabilities (e.g. CVEs). The plugin achieves this by using the awesome OWASP DependencyCheck library which already offers several integrations with other build and continuous integration systems.

For more information on how OWASP DependencyCheck works and how to read the reports check the project's documentation.

This plugin is inspired by the great work of Alexander v. Buchholtz et al. sbt-dependency-check. This plugin seeks to build on top of the previous plugin, keeping some settings and tasks the same, while offering some functionalities on top. The work on this plugin started when we noticed NVD deprecating data-feed, which the previous plugin still relied on. If you're looking to migrate from Buchholtz's plugin, please read the Migration Guide

Add the plugin to your project configuration:

addSbtPlugin("net.nmoncho" % "sbt-dependency-check" % "1.4.0")

The minimum SBT version supported is 1.9.0.

Don't feel deterred by all the configuration settings defined in this plugin. All of them have sensible defaults.

The best way to get started is to install the plugin, set your NVD API Key:

dependencyCheckNvdApi := NvdApiSettings("YOUR_NVD_API_KEY")

And then just run:

sbt -Dlog4j2.level=info dependencyCheck

The first time you run these tasks it will take some time, even a couple of minutes. The analysis will write a report to target/{scala-version}/dependency-check-report.html.

After this, feel free to take a look at the available tasks and settings.

The following tasks are available:

The reports will be written to crossTarget.value by default. This can be overwritten by setting dependencyCheckOutputDirectory. See Configuration for details.

The plugin uses the default DependencyCheck configuration which can be overridden by either a SBT Setting Key, or a System Property. Properties are resolved by the library in this order: (1) dependencycheck.properties values , (2) SBT Setting Keys, (3) System Property. Last non-empty value wins.

The default properties file can be overridden with the Setting Key dependencyCheckSettingsFile. Most, if not all, settings are picked up from the default DependencyCheck is defining. You can run the task dependencyCheckListSettings to know what's the final value of each setting, and an example of this properties file's content.

SBT Setting Keys are usually wrapped with an Option. This is meant to allow keeping the default value, at the cost of some configuration convenience.

DependencyCheck may use sensitive information like usernames, passwords, and Bearer Tokens. Although these could be added as SBT Setting Keys this is discouraged in order to avoid committing sensitive information to your VCS. Here are some options to that:

• Install this plugin globally under ~/.sbt/<version>/plugins.sbt, then define these values on that file.
• Set the setting dependencyCheckSettingsFile using an external dependencycheck.properties.
• Use System Properties when running an SBT Task: sbt -Danalyzer.central.password=12348765 dependencyCheck

Dependency-check has moved from using the NVD data-feed to the NVD API. It is highly encouraged to obtain an NVD API Key; see Requesting an API Key. Without an NVD API Key, updating will be extremely slow.

The NVD API has enforced rate limits. If you are using a single API KEY and multiple builds occur you could hit the rate limit and receive 403 errors. In a CI environment one must use a caching strategy, like caching the Database (see Database Settings), or sharing the Data Directory between builds.

Data Feed Settings

Suppressions can be specified either as suppression files, as hosted suppressions, or as a SBT Setting Key. A suppression file can be either an actual file or a URL. Hosted suppression are specified with a URL. The different between the two is that suppression files are meant to be project specific, whereas hosted suppression are meant, or can be, more general. Hosted Suppressions are considered "base" suppressions, whereas suppression files are not.

Suppressions defined with the suppressions field on the dependencyCheckSuppressions key are created using the net.nmoncho.sbt.dependencycheck.settings.SuppressionRule class, providing an alternative to defining suppressions with XML files.

Whether this suppression is taken into account or not is governed by the Analyzer Setting vulnerabilitySuppressionEnabled. Another useful setting is failOnUnusedSuppressionRule which will fail the build if there is any non-base suppression not applied.

Suppression Files

Hosted Suppressions

In order to avoid duplicating suppression rules between related projects, we can export suppressions rules defined in a project, and then reuse those suppressions on downstream projects. For example, say you have a "commons" project that includes a library with a CVE. And then another project including that "commons" project. If we run CI on both projects with a dependency check, we'd have to define the same suppression rule in both projects, as "commons" would have this dependency in its classpath, and the other project would also have it as a transitive dependency. If we could define the suppression only in "commons", and then reuse it on downstream projects, we would save us a lot of copy/paste and headaches.

We can use and export package suppressions by enabling with the packagedEnabled field in the dependencyCheckSuppressions key. By default, packaged suppressions rules are disabled.

Using Packaged Suppressions To use exported packaged suppressions rules by other projects we need to whitelist what dependencies we'll accept suppressions rules from. By default, all dependencies are blacklisted.

For example, imagine we only want to accept packaged suppressions from libraries published by Typesafe or Lightbend, we would configure our builds like:

dependencyCheckSuppressions := SuppressionSettings(
  packagedEnabled = true,
  packagedFilter = PackageFilter.ofGav {
    case ("com.typesafe" | "com.lightbend", _, _) => true
    case _ => false
  }
)

There are other ways to define PackageFilters that can filter each dependency available in the classpath.

Exporting Packaged Suppressions We can export the suppression rules we define in a project by just enabling the packaged suppression rules. An XML suppression rules file will be created and treated as a managed resource (i.e. will be included in the packaged JAR).

Only the suppression rules defined in the files (non-URLs, just files) and the suppressions fields on the dependencyCheckSuppressions key will be included in the packaged suppressions rules. The rationale is that URLs defined in the files field, or the hosted suppressions can be easily shared already.

Every packaged suppression rule will be marked as "base", meaning it won't show in the dependency check report, nor on the unused suppressions rules list. This is to avoid duplicating information on multiple projects.

Analyzer settings are grouped together where they make sense. This is an attempt to make the Setting Keys offered by the plugin a bit more readable and comprehensible.

To learn more see the available File Type Analyzers. Some analyzers may be enabled but marked as experimental, which may not run if experimentalEnabled is disabled. If you don't care about a particular Analyzer, feel free to ignore it, leaving the default values as they are.

Settings are grouped by either analyzer, tool, or language:

Most of the settings here are picked up from either the default dependencycheck.properties, or from source, thus these tables try to gather them as best effort.

SBT and sbt-dependency-check both honor the standard http and https proxy settings for the JVM.

sbt -Dhttp.proxyHost=proxy.example.com \
    -Dhttp.proxyPort=3218 \
    -Dhttp.proxyUser=username \
    -Dhttp.proxyPassword=password \
    -Dproxy.nonproxyhosts="localhost|http://www.google.com" \
    dependencyCheck

Add -Dlog4j2.level=<level> when running a task, for example:

sbt -Dlog4j2.level=debug dependencyCheck

Replace dependencyCheck with the right task name that you use for your project.