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.

In an attempt to keep this README.md brief, the detailed documentation on how to use this plugin can be located in our wiki.

Add the plugin to your project configuration:

addSbtPlugin("net.nmoncho" % "sbt-dependency-check" % "1.9.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:

import net.nmoncho.sbt.dependencycheck.settings._

dependencyCheckNvdApi := NvdApiSettings(apiKey = "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 for SBT 1.x, and target/out/jvm/{scala-version}/{project}/dependency-check-report.html for SBT 2.x. The plugin will log where the reports are being written to.

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.

By default dependencyCheck will run under the selected project, or root if none is selected. And it will also run on projects aggregated by that project, like any other task on SBT, generating one report per project.

The task dependencyCheck supports arguments that can be used to change its behavior:

• list-settings: The settings used for the analysis will be printed before running the analysis. This works the same way as the task dependencyCheckListSettings.
• list-unused-suppressions: Any unused suppression rule will be printed after the analysis. This works the same way as the task dependencyCheckListUnusedSuppressions.
• single-report: A single report will be generated for this project, and all aggregates if any. This works the same way as the task dependencyCheckAggregate.
• all-projects: A single report will be generated for all projects. This works the same way as the task dependencyCheckAllProjects. Important: This arguments needs to be used together with single-report.

This task also supports modifying how the reporting summary is shown at the end:

• original-summary: This is the original summary provided by previous version of the plugin. Follows the structure as org.owasp.dependencycheck.agent.DependencyCheckScanAgent.showSummary
• all-vulnerabilities-summary: Shows a more compact report than original-summary, but includes the score for each vulnerability.
• offending-vulnerabilities-summary: Same as all-vulnerabilities-summary but only shows the offending vulnerabilities (i.e. the ones that made the build fail).

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.

In a CI environment one must use a caching strategy, like caching the CVE Database.

Feel read more about this on our wiki

Due to how dependency-check identifies libraries false positives may occur (i.e. a CPE was identified that is incorrect). sbt-dependency-check offer several ways to define these suppressions.

Feel read more about this on our wiki.

Analyzers, as the name imply, are a way to analyze dependencies or artifacts. DependencyCheck offers an extensive list of analyzers out of the box.

Feel read more about this on our wiki.

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.