Overview

The plugin allows maven based projects to automatically create new inventories, keep existing inventories up to date and more. The plugin can be found on the Maven Central Repository.

The plugin source code, issues and wiki is hosted on GitHub together with the technical documentation.

Maven Version

Maven versions 3.0.x, 3.1.x and 3.2.x are supported since version 3.0 of the plugin. Previous versions of the plugin supports only Maven 3.0.x.

Proxy Support

The maven plugin depends on the WhiteSource agents API which uses the proxy-vole 20121203 library for auto proxy detection.

The proxy-vole library is not hosted in any known maven repository, it must be downloaded manually from here. Upload to your repo manager or download directly to your local m2 repository.

This is required when using version 1.1.7 and above of the maven plugin.

Updated: Starting version 3.1.3 the proxy-vole library has been embedded into the maven plugin, no need to manually download and install into your local m2 repository.

In version 3.2.1 and higher, automatic proxy detection will be done only if requested using the autoDetectProxySettings parameter (see below). By default, it will use any proxy configuration found in Maven's settings.xml file (see here).

Using the Plugin

The plugin can be used like any other maven plugin.

Adding the Plugin Configuration to the Project's pom.xml File

Copy & paste the following snippet into the plugins section in your parent pom.xml file.

Update on deploy

<plugin>
	<groupId>org.whitesource</groupId>
	<artifactId>whitesource-maven-plugin</artifactId>
	<version>18.4.2</version>
	<configuration>
		<orgToken>Your organization token</orgToken>
	</configuration>
</plugin>

The plugin's associated prefix is 'whitesource'. In order to use the prefix, you'll need to add the whitesource groupId to the pluginGroups section in your settings.xml.

Configuring pluginGroup to use the whitesource prefix

<pluginGroups>
	<!-- ... other plugin group IDs -->
	<pluginGroup>org.whitesource</pluginGroup>
	<!-- ... other plugin group IDs -->
</pluginGroups>

Organization Token (API Key)

A unique identifier of the organization. You can get yours in the Admin Integration API page.

Project Token

You can define each module with a project token using the moduleTokens tag:

<plugin>
	...
	<configuration>
		...
		<moduleTokens>
			<module_name_1>project_token_1</module_name_1>
			<module_name_2>project_token_2</module_name_2>
		</moduleTokens>
	</configuration>
</plugin>

Executing the Plugin

The whitesource maven plugin achieves 2 goals:

Update

The update goal sends an update request to WhiteSource with the following cases:

  1. You have no projects in WhiteSource that are mapped to your maven project. The plugin will create a project for each module in WhiteSource with all dependencies approved and populated in the project's inventory.

  2. You already have a project in WhiteSource that is mapped to your maven project. The plugin will create requests for new dependencies that don't exist in the WhiteSource project's inventory.

Both cases can send a "check policies" request to WhiteSource before sending the update request by setting the checkPolicies parameter to true, if any new dependency doesn't comply with your organization's policies, the update request will not be sent.

A report will be generated to show you the rejected dependencies.

To execute the plugin directly, simply run in your shell.

mvn whitesource:update

You can also bind the plugin execution to any phase of the build. See more no maven's build life cycle

If the plugin is not in your pom file under profile configuration tag, and you still want to use our plugin, first you need to check that you have "<pluginGroup>org.whitesource</pluginGroup>" in your settings.xml.
Then run "mvn whitesource:update -Dorg.whitesource.orgToken="your-api-key".
Please note that with this configuration the plugin will run the latest release.

Check Policies

The checkPolicies goal simply sends a check policies request to WhiteSource without sending the update request afterwards if all dependencies comply with your organization's policies.

A report will be generated to show you the rejected dependencies.

To execute the plugin directly, simply run in your shell.

mvn whitesource:checkPolicies

On-Premises

When running the plugin in an On-Premise installation make sure to pass the IP or url of your machine:

 mvn whitesource:update -Dwss.url=http://your.server.ip/agent

Setup Maven

Where should you put the plugin configuration? Well, it depends.

Multi-module projects (Aggregation) should put it in the parent pom file.

Projects with a single module or several independent modules (Inheritance) should put it in each module's pom file. 

More information on maven projects structure can be found here.

You can gain more control on the execution of the plugin if you declare it in a dedicated build profile. For more information on maven build profiles see here.

Plugin Configuration

The plugin configuration is flexible and can be customized for the cases when a simple configuration like the one suggested above is not sufficient to your needs.

Required Parameters

Name

Type

Description

-D Parameter

 orgToken

String

Unique identifier of the organization to update, also known as 'API Token'.

org.whitesource.orgToken

Since version 3.1.6

Optional Parameters

Name

Type

Description

-D Parameter

timeFormat

String

Set logging datetime format.

Default value is [HH:mm:ss] 

org.whitesource.timeFormat

Since version 17.11.3

checkPolicies

Boolean

Set to true to check policies before update.
Default value is: false.e

org.whitesource.checkPolicies

Since version 3.1.6

forceCheckAllDependencies

Boolean

Optional. Set to true to force check all policies for all dependencies, used only if checkPolicies is set to true.
Default value is: false - policies will be checked only for new dependencies introduced to the WhiteSource projects.

org.whitesource.forceCheckAllDependencies

Since version 3.1.7

forceUpdate

Boolean

Optional. Updates organization inventory regardless of policy violations. 
Default value is: false - in case of policy violations, the plugin won't update the inventory.

org.whitesource.forceUpdate

Since version 3.2.8

product

String

Product name or token.
Default value is: top most project name or artifactId.

org.whitesource.product

Since version 3.2.8

productVersion

String

Product version. Use this to override the version in each module.

org.whitesource.productVersion

Since version 3.2.8

projectToken

String

Unique identifier of the White Source project to update. If omitted, default naming convention will apply.


moduleTokens

Map

Map of module artifactId to White Source project token. See example


includes

String[]

Only modules with an artifactId matching one of these patterns will be processed by the plugin.

Should be used like this:

<includes>
   <include>module-a</include>
   <include>module-b</include>
</includes>


excludes

String[]

Modules with an artifactId matching any of these patterns will not be processed by the plugin.

Should be used like this:

<excludes>
   <exclude>module-a</exclude>
   <exclude>module-b</exclude>
</excludes>


ignore

Boolean

Set to true to ignore this maven project. Overrides any include patterns.
Default value is: false.


ignorePomModules

Boolean

Set to true to ignore this maven modules of type pom.
Default value is: true.

org.whitesource.ignorePomModules

Since version 3.2.8

ignoredScopes

String[]

By default the maven plugin ignores direct dependencies with scope 'test' and 'provided'.
Override to enable certain scopes (see example below). 

org.whitesource.ignoredScopes

Since version 3.3.1

failOnError

Boolean

Indicates whether the build will continue even if there are errors.
Default value is: false.

org.whitesource.failOnError

Since version 3.2.8

skip

Boolean

Set to true to skip the maven execution.
Default value is: false.


reportAsJson

Boolean

Set to true to create the check policies report as a text file in JSON format instead of the regular HTML format report.
Default value is: false.


aggregateModules

Boolean

Set to true to combine all pom modules into a single WhiteSource project with an aggregated dependency flat list (no hierarchy).
Default value is: false.

org.whitesource.aggregateModules

Since version 3.2.8

preserveModuleInfo

Boolean

Optional. Works only if the 'aggregateModules' parameter is set to 'true'. It creates a hierarchy tree for modules that appear in the root POM.
Default value is: false.

org.whitesource.preserveModuleInfo

Since version 18.5.2

aggregateProjectName

String

Optional. The project name that will appear in WhiteSource. If omitted and no project token defined, defaults to pom artifactId.
Will only apply if aggregateModules is set to true. 

org.whitesource.aggregateProjectName

Since version 3.2.8

aggregateProjectToken

String

Optional. Unique identifier of the White Source project to update, overrides aggregateProjectName. If omitted, default naming convention will apply.
Will only apply if aggregateModules is set to true. 

org.whitesource.aggregateProjectToken

Since version 3.2.8

requesterEmail

String

Optional. The provided email will be matched with an existing WhiteSource account. Requests for new libraries will be created with the matched account as the requester.

org.whitesource.requesterEmail

Since version 3.2.8

autoDetectProxySettings

Boolean

Indicates whether to try to detect proxy configuration in the underlying machine (e.g. in OS proxy settings, in JVM system properties etc.)
Default value is: false.

org.whitesource.autoDetectProxySettings

Since version 3.2.8

connectionTimeoutMinutes

int

Connection timeout in minutes.
Default value is: 60

wss.connectionTimeoutMinutes

Since version 3.2.7

ignoreDependencyResolutionErrors

Boolean

Indicates whether to ignore an error while resolving dependencies for a module, this module will not be included in the scan and will not appear as a project within WhiteSource.
Default value is: false.

org.whitesource.ignoreDependencyResolutionErrors

Since version 3.3.0

failOnConnectionError

Boolean

Fails the build when unable to connect to WhiteSource service
Default value is: true.

org.whitesource.failOnConnectionError

Since version 3.3.1

connectionRetries

int

Connection retries when unable to connect to WhiteSource service.
Default value is: 1.

org.whitesource.connectionRetries

Since version 3.3.1

orgTokenFile

String

Optional. Path to file that contains the org token. Use this to override the orgToken parameter in the pom.xml file.

org.whitesource.orgTokenFile

Since version 18.2.2

userKey

String

Unique identifier of user, can be generate from the profile page in your whitesource account.

Required if WhiteSource administrator has enabled "Enforce user level access" option.

org.whitesource.userKey

Since version 18.4.2

userKeyFile

String

Optional. Path to file that contains the userKey . Use this to override the userKey parameter in the pom.xml file.

org.whitesource.userKeyFile

Since version 18.4.2

updateEmptyProject

Boolean

Optional. Whether or not to upload/update an empty project
Default value is: true

org.whitesource.updateEmptyProject

Since version 19.5.1

If you didn't find what you need, you can try the plugin documentation or drop a line to our support team.

Check Policies Report

The generated check policies report is located in project_location\target\site\whitesource, there are two types of report formats:

HTML

The plugin generates an HTML report (index.html and wss.css).

JSON

The plugin generates a test file in JSON format that represents the WhiteSource agents API CheckPoliciesResult object.

This can be enabled by setting the reportAsJson parameter to true.

Other Operations

Override Ignored Scopes

By default the maven plugin doesn't send information regarding direct dependencies with scope 'test' and 'provided' to WhiteSource. 

To override ignoring direct dependencies with scope 'provided' enter the following configuration:

<!-- ignore scope test to enable scope provided -->
<ignoredScopes>
	<ignoredScope>test</ignoredScope>
</ignoredScopes>

Then change the Maven Dependency Resolution Settings in the Admin section in WhiteSource, uncheck "Ignore Provided Scope Direct Dependencies".

Aggregate POM Modules

This feature is available since version 3.1.2.

By default the maven plugin creates a WhiteSource project for each module in you POM structure.

In order to create a single WhiteSource project that aggregates dependencies from all modules (without hierarchy) use the aggregateModules property:

<aggregateModules>true</aggregateModules>
<aggregateProjectName>your.project.name</aggregateProjectName>

Can also be passed via the command line:

mvn whitesource:update -Dorg.whitesource.aggregateModules=true -Dorg.whitesource.aggregateProjectName="your.project.name"

Project token can be used as well:

<aggregateModules>true</aggregateModules>
<aggregateProjectToken>your.project.name</aggregateProjectToken>


A Maven project with both the aggregateModules and preserveModuleInfo properties set to true is displayed as follows on the 'Libraries' panel of the 'Project' page:

Make sure you select the "Show as Hierarchy" mode (by default, the "Show as Flat List" mode is enabled).

Note that the POM modules are represented in a darker color and contain a '(module)' extension. Opening such a module displays all of the module's dependencies.

Hovering over the "(module)" text opens up a tool-tip displaying the GAV information on the actual module.

Clicking on a specific library of a module navigates you to the 'Library Details' page. You can then click on the 'View Impact Analysis' link next to the Library title to navigate to the relevant library's 'Impact Analysis' page.
The "(aggregate project)" extension on the 'Direct Dependency' panel indicates that the project has the 'aggregateModules' setting enabled.

Requester Email

Using the requesterEmail parameter, the provided email will be matched with an existing WhiteSource account. Requests for new libraries will be created with the matched account as the requester.

This will only work with the email you use to sign in to your WhiteSource account, in case you're using social login use your social email address.

How to Configure checkPolicies and forceCheckAllDependencies in pom file

 'forceCheckAllDependencies' tag used only if 'checkPolicies' tag set to true.

Setting 'forceCheckAllDependencies' tag to true will force check all policies for all dependencies introduced to the WhiteSource projects.

Setting 'forceCheckAllDependencies' tag to false or not using it at all will check only the new dependencies introduced to the WhiteSource projects.

Copy & paste the following snippet into the plugins section in your parent pom.xml file.

<plugin>
	<groupId>org.whitesource</groupId>
	<artifactId>whitesource-maven-plugin</artifactId>
	<version>18.4.2</version>
	<configuration>
		<orgToken>Your organization token</orgToken>
		<checkPolicies>true</checkPolicies>
		<forceUpdate>true</forceUpdate>
		<forceCheckAllDependencies>true</forceCheckAllDependencies>
	</configuration>
</plugin>

Release Notes

Version

Content

Version 20.7.1

  • Bug Fix - send the right version of the maven plugin to WhiteSource service

Version 19.5.1

  • Added configuration parameter 'updateEmptyProject' with default 'true'. When set to 'false', empty projects will not be uploaded/updated.

Version 18.11.1

  • Minor bug fixes.

Version 18.6.2

  • Minor fixes.

Version 18.5.1

  • Upgrade api version.

Version 18.4.2

  • Added support for user-level access control in integrations.

Version 18.4.1

  • Fixed minor bug (empty projects will not upload).

Version 18.2.2

  • Add 'orgTokenFile' parameter.

Version 18.1.3

  • Add 'connectionRetryInterval' parameter.

  • Add 'enableDebug' parameter.

  • Remove debug messages.

Version 17.11.3

  • Add 'timeFormat' parameter.

Version 3.3.1

  • Read the 'ignoredScopes' parameter from command line using -D.

  • Add 'failOnConnectionError' parameter.

  • Add 'connectionRetries' parameter, when unable to connect to WhiteSource.

Version 3.3.0

Add property ignoreDependencyResolutionErrors for ignoring modules where dependency resolution failed, false by default.

To enable add the following line to the whitesource maven plugin configuration:

<ignoreDependencyResolutionErrors>true</ignoreDependencyResolutionErrors>

or via command line:

$ mvn whitesource:update -Dorg.whitesource.ignoreDependencyResolutionErrors=true

Version 3.2.9

Fix incorrect message when skipping an excluded module.

Version 3.2.8

Read the following properties from command line using -D:

  • ignorePomModules

  • forceUpdate

  • product

  • productVersion

  • requesterEmail

  • aggregateModules

  • aggregateProjectName

  • aggregateProjectToken

  • failOnError

  • autoDetectProxySettings

  • connectionTimeoutMinutes

Version 3.2.7

Add parameter 'connectionTimeoutMinutes'.

Version 3.2.6

Bug fix for 'includes' parameter.

Version 3.2.5

Fail the build upon policy violation if 'failOnError' is enabled and 'forceUpdate' is enabled.

Version 3.2.4

Add force update functionality - inventory update regardless of policy violations.

Version 3.2.3

Improve exceptions handling.

Version 3.2.2

Generate a policy rejection summary in JSON format (named 'policyRejectionSummary.json') after policies are checked.

This is the JSON format:

{
  "rejectingPolicies": [
    {
      "policyName": "No BSDs",
      "filterType": "LICENSE",
      "productLevel": true,
      "rejectedLibraries": [
        {
          "name": "antlr-2.7.7.jar",
          "sha1": "83cd2cd674a217ade95a4bb83a8a14f351f48bd0",
          "link": "http://localhost/Wss/WSS.html#!libraryDetails;id=13671557",
          "projects": [
            "Jars"
          ]
        }
      ]
    },
    {
      "policyName": "No High Vulnerabilities",
      "filterType": "VULNERABILITY_SEVERITY",
      "productLevel": false,
      "rejectedLibraries": [
        {
          "name": "xalan-2.7.1.jar",
          "sha1": "75f1d83ce27bab5f29fff034fc74aa9f7266f22a",
          "link": "http://localhost/Wss/WSS.html#!libraryDetails;id=13670946",
          "projects": [
            "Jars",
	    	"Other Jars"
          ]
        }
      ]
    }
  ],
  "summary": {
    "totalRejectedLibraries": 2
  }
}

Version 3.2.1

Auto-detect proxy settings only when requested (via autoDetectProxySettings parameter)

Version 3.1.7

Add the ability to choose which dependencies (all / new) using will be checked when setting checkPolicies to true, using the forceCheckAllDependencies property.

Version 3.1.6

Define orgToken and checkPolicies as -D parameters (with "org.whitesource." as prefix).

Version 3.1.5

Add and change logs.

Version 3.1.4

Add requester email as parameter.

Version 3.1.3

Embedded proxy-vole library, no need to manually download and install into your local m2 repository.

Version 3.1.2

Simplified aggreateModules property to allow passing values via command line.

Version 3.1.1

Added option to aggregate pom modules into a single WhiteSource project.

Implementation changed according to documentation, use 3.1.2.

Version 3.1

Minor bug fixes.

Version 3.0

Support for maven versions 3.0.x, 3.1.x and 3.2.x

Version 2.1.0

Implement client-side dependency resolution.

Should be used with "resolve dependencies" set to false (when creating a new organization).

Version 2.0.1

Added option to resolve in-house dependencies.

Should only be used if any internal (in-house) dependencies appear in your project and in-house rules exist in your WhiteSource account.

This version is deprecated, please use another version.

Version 1.1.9

Added checkPolicies goal.

Support for report as text file in JSON format.

This version is deprecated, please use another version.

Version 1.1.8

Support for dependency exclusions.

Ignore test scope direct dependencies (don't send them to WhiteSource).

This version is deprecated, please use another version.

Version 1.1.7

Auto proxy detection in agent client.

This version is deprecated, please use another version.

Version 1.1.6

  • Product identification is now available

  • Policy check is now disabled by default

This version is deprecated, please use another version.