WhiteSource provides several integrations that can be configured in the build process in order to:

• Notify if there are any WhiteSource policy violations found and provide details
• Fail the build if any policy violation is found
• Upload metrics to the WhiteSource project dashboard

Below are listed the integrations that have been currently tested.

NPM integration

The NPM integration allows to perform the tasks mentioned above for Javascript projects.

Below are listed the configuration items

Install WhiteSource npm

• Make sure you have npm installed on commandline
• Edit your package.json
  • add whitesource: 1.0.9, below devDependencies
  • add whitesource: node node_modules/whitesource/bin/whitesource.js run, below scripts

• Run npm install from the root project folder

Below is how your package.json file should look like.

{
  ...
  "scripts": {
    ...
    "whitesource": "node node_modules/whitesource/bin/whitesource.js run"
  },
  "devDependencies": {
    ...
    "whitesource": "1.0.9"
  },
  ...
}

Make sure you add the following entries in your .gitignore file.

ws-log*
ws-ls*

Configure WhiteSource metrics upload

Simply add whitesource.config.json file in the project root folder, using the following configuration.

{
  "checkPolicies":true,
  "productName":"<WhiteSource product name>",
  "projectName":"<WhiteSource project name>",
  "devDep": false
}

checkPolicies will check the code against the WhiteSource policies, looking for violations; if any violation is found, no metrics are uploaded to the WhiteSource project dashboard. Set it to false, if you want to test the upload of a policy violation (ie. to test the WhiteSource alert workflow).

productName and projectName are self-explanatory; if no productName/projectName exists in the Foundation WhiteSource dashboard, a new one will be created; as such, these values should never be changed, unless the names are changed from the WhiteSource dashboard first.

devDep enables the scanning to non-runtime packages; although the majority of license obligations affect distributed artifacts, running devDev to true (and checkPolicies to true) could be useful to spot possibly harmful licenses.

Testing

Try to add scrollreveal: 4.0.0-beta.14 (a package released under GPL-3.0 license) under dependency, in your package.json, then follow the instructions below.

Scan code for WhiteSource policy violations

Simply run

export WHITESOURCE_API_KEY=<WhiteSource API Key>
npm install
npm run whitesource

where <WhiteSource API Key> must be requested to (or configured on Travis CI by) the Foundation Staff.

If checkPolicies is set to true and policy violations are found, a file called ws-log-policy-violations.json will be created in the root project folder; an example of the file content is reported below.

[
	{
    "policy": {
		"displayName": "Reject Problematic (Category X license) libraries",
		"filterType": "LICENSE",
		"actionType": "Reject",
		"projectLevel": false,
		"inclusive": false
		},
	"resource": {
		"displayName": "scrollreveal-4.0.0-beta.14.tgz",
		"link": "https://saas.whitesourcesoftware.com/Wss/WSS.html#!libraryDetails;project=284955;uuid=bd023712-dae5-4cc5-ba07-1e51955a1dc1",
		"licenses": [
		"GPL 3.0"
],
	"sha1": "d7b8f0e8b3bea7f04a4e877cac4a02a8a3540d81",
	"vulnerabilities": []
		}
	}
]

If no policy violations are found, or checkPolicies is set to false, the repository metrics will be submitted to the Foundation WhiteSource dashboard.

OK: Config file is located in: ./whitesource.config.json
OK: Running whitesource...
OK: Done calculation dependencies!
OK: Building dependencies report
INFO: Total shasum found: 97
INFO: Missing shasum: 0
INFO: Total project dependencies: 97
OK: Saving dependencies report
OK: Getting ready to post report to WhiteSource...
OK: Check Policies: Posting to :https://saas.whitesourcesoftware.com:443/agent
OK: Code: 200 Message: OK
INFO: Checking Policies
OK: No policy violations. Posting update request
OK: Update: Posting to :https://saas.whitesourcesoftware.com:443/agent
OK: Code: 200 Message: OK
OK: Build success! ( took: 7.394s )

Travis CI integration

The following configuration allows to embed the WhiteSource integration execution in Travis CI, allowing to monitor any commit across the branches in the current repository. The bash code (embedded in YAML format) reported below must be added to a .travis.yml file, but can also be adapted to run on other CIs.

...
	scripts:
...
	- "if [[ $TRAVIS_PULL_REQUEST -eq 'false' ]]; then npm install ; npm run whitesource; fi;"
	- "if [[ -e 'ws-log-policy-violations.json' ]]; then echo 'Found Whitesource Policy violation, build failed.' ; cat ws-log-policy-violations.json ; exit -1; fi;"

The WHITESOURCE_API_KEY mentioned above will be configured by the Foundation Staff directly in the Travis Settings page.

Please note that Travis restricts access to the (encrypted) WhiteSource API Key for security reasons; as such, any Pull Request (PR) coming from other forks cannot run the WhiteSource integration. In order to enforce WhiteSource policies within the PR review mechanism, it is necessary to introduce an intermediate branch, hosted in the repository (ie. whitesource-validation), where PRs are merged - assuming they pass all other validations - before being merged to the final (ie master) branch.

Foundation Parent POM (Maven)

Java projects that are using Apache Maven as the build tool can specify ssf-parent-pom as parent POM and inherit a whitesource build profile that takes care of submitting metrics at build time; other than that, the project pom.xml doesn't need any further change.

By default, the WhiteSource Maven plugin excludes all dependencies with <scope> equal to test or provided.

mvn package -Pwhitesource

If any policy violation is found locally, the build will fail and a report will be generated on target/site/whitesource/index.html.

Override to enable certain scopes (see example below).
The following parameters can be passed to the mvn commandline:

• -Dwhitesource.org.token - specifies the WhiteSource API Key to use, which represents the WhiteSource Foundation account; Foundation Staff can configure this field on Travis CI or any other CI environment, but cannot redistribute the key in clear test. If no parameter is specified, the value will be taken from WHITESOURCE_TOKEN environment variable
• -Dwhitesource.product - specifies the WhiteSource product that contains the currently built project (or repository, in Github terms); default value is ${project.artifactId}
• -Dwhitesource.checkPolicies - whether to check the current build against WhiteSource policies; default value is true
• -Dwhitesource.failOnError - whether to trigger a BUILD ERROR if any policy violation is found; default value is true

Testing

Try to add com.github.lalyos:jfiglet:0.0.8 (GPL-3.0 license) to your pom.xml and run the mvn command again.

Travis CI configuration

...
	scripts:
...
	- "if [[ $TRAVIS_PULL_REQUEST -eq 'false' ]]; then mvn package -Pwhitesource ; fi"

For multi-module SNAPSHOT projects, the WhiteSource plugin fails due to unresolved dependencies; to work around this issue, use this configuration, instead of the one above.

...
	after_success:
...
	- "if [[ $TRAVIS_PULL_REQUEST -eq 'false' ]]; then mvn whitesource:update -Pwhitesource ; fi"

Multiple repositories

If you're managing a (Foundation) project that uses multiple GitHub repositories, you may want to use the same WhiteSource productName across the different project build configurations, by setting a product token.

Each WhiteSource product defines a token that can be found by accessing the Integrate menu item; the token is configured in the project build depending on the integration used.