Overview

The Black Duck Black Duck SonarQube plugin works through the Black Duck sensor in the sonar-scanner.

To populate a SonarQube instance with data regardless of having the Black Duck SonarQube plugin installed, the sonar-scanner must be run in the base directory of the project to be scanned. This directory requires a sonar-project.properties file where the following fields are specified:

Project name
Project version
Source directory

These fields configure project mappings and plugin settings. Configuring the Black Duck SonarQube plugin can also be done through the SonarQube user interface (UI), where you can overwrite the sonar-project.properties file. This can only be done after the initial scan.

Basic Workflow

Follow the instructions for installing SonarQube at https://docs.sonarqube.org/display/SONAR/Installing+a+Plugin
Get the plugin from https://github.com/blackducksoftware/hub-sonarqube/releases
Copy the plugin JAR file to the extensions/plugins/ directory of your SonarQube installation and then restart the server.
Configure the sonar-project.properties file with the project name, project version, and source directory.
Configure the Black Duck SonarQube plugin properties file with the global and project-level properties for the Black Duck SonarQube plugin.
Run sonar-scanner in the base directory of the project to be scanned with Black Duck SonarQube installed and configured.
Black Duck SonarQube does not perform a Black Duck scan, but instead examines a previously-scanned Black Duck project, gathers its Black Duck Bill of Materials (BOM) components, and compares the matched files from the Black Duck to the local files.

Requirements

SonarQube versions 6.7.1 or higher.
Black Duck Black Duck versions 4.2.0 or higher.
Java versions 8 or higher.
Black Duck Signature Scanner.

For additional version compatibility information, refer to https://docs.sonarqube.org/display/DEV/API+Changes.

Installing the plugin

To install the Black Duck SonarQube plugin, refer to the SonarQube installation procedures for the manual installation steps at https://docs.sonarqube.org/display/SONAR/Installing+a+Plugin
Get the latest releases for the plugin at https://github.com/blackducksoftware/hub-sonarqube/releases

Using the Black Duck SonarQube plugin

When the sonar-scanner is run with Black Duck SonarQube installed and configured, it uses inclusion patterns to collect a list of local binaries and compares them with a Black Duck project version. By default, the plugin attempts to locate a Black Duck project version using the name and version from the SonarQube project being scanned. This can be overridden in sonar-project.properties file. Note that Black Duck SonarQube does not perform a Black Duck scan, but instead examines an already-scanned Black Duck project, gathers its Black Duck Bill of Materials (BOM) components, and compares the matched files from the Black Duck to the local files. Metrics are attached to shared components and displayed in the SonarQube UI under Your_project_name > More > Black Duck Black Duck Security Analysis. The displayed metrics are:

Component ratings
High, medium, and low-security vulnerabilities
Number of vulnerable components

Clicking any of these metrics displays the data on a per-file basis.

Black Duck SonarQube plugin properties

The following are listings of global and project-level properties for the Black Duck SonarQube plugin.

Global

sonar.hub.url
sonar.hub.username
sonar.hub.password
sonar.hub.timeout
sonar.hub.trust.ssl.cert
sonar.hub.proxy.proxy
sonar.hub.proxy.host
sonar.hub.proxy.port
sonar.hub.proxy.non.hosts
sonar.hub.proxy.username
sonar.hub.proxy.password

Project level

sonar.hub.project.override
sonar.hub.project.version.override
sonar.hub.binary.inclusion.pattern.override
sonar.hub.binary.exclusion.pattern.override

Release Notes

Version 1.2.0

Resolved issues

Resolved an authentication issue with Black Duck.

Changed features

Updated plugin to support Black Duck version 2019.12.0 and later.

Version 1.1.1

Added compatibility for Black Duck Hub version 4.5.0.

Version 1.1.0

Resolved issues

Resolved an issue wherein the page extension may fail if no comparison is performed.
Incorporated additional logging during metric creation.
Expanded the functionality of the HubServerConfigBuilder's createValidator() property to validate the global configuration before scanning.
Previously, invalid inclusion patterns provided by the user may have caused unexpected behavior and/or incorrect file matching. In version 1.1.0, logging is added around its logic. In these cases, invalid patterns are ignored, and a warning is logged.

Known issues

When the sonar-scanner is run using the Maven goal sonar:sonar, an issue arises where the Hub SonarQube plugin cannot find local binary files. According to the SonarQube documentation found here, "If [the sonar.sources property is] not set, the source code is retrieved from the default Maven source code location."

To fix the issue, sonar.sources should be set to the base directory of the project; ideally using the absolute path to that directory.

Setting this property could produce the error, "File <FILE_NAME> can't be indexed twice. Please check that inclusion/exclusion patterns produce disjoint sets for main and test files." This means you should explicitly set the properties sonar.inclusions and sonar.exclusions. More information on these properties can be found in the SonarQube Analysis Parameters documentation.

Version 1.0.0

The first release of the product.