Use WhiteSource Unified Agent
All the language-specific WhiteSource plugins have been deprecated in favour of the WhiteSource Unified Agent.
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.
Below are listed the configuration items
Install WhiteSource npm
Below is how your
package.json file should look like.
"whitesource": "node node_modules/whitesource/bin/whitesource.js run"
Make sure you add the following entries in your
Configure WhiteSource metrics upload
whitesource.config.json file in the project root folder, using the following configuration.
"productName":"<WhiteSource product name>",
"projectName":"<WhiteSource project name>",
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
true) could be useful to spot possibly harmful licenses.
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
export WHITESOURCE_API_KEY=<WhiteSource API Key>
npm run whitesource
where <WhiteSource API Key> must be requested to (or configured on Travis CI by) the Foundation Staff.
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.
"displayName": "Reject Problematic (Category X license) libraries",
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.
- "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;"
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
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
mvn package -Pwhitesource
If any policy violation is found locally, the build will fail and a report will be generated on
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
-Dwhitesource.checkPolicies - whether to check the current build against WhiteSource policies; default value is
-Dwhitesource.failOnError - whether to trigger a
BUILD ERROR if any policy violation is found; default value is
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
- "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.
- "if [[ $TRAVIS_PULL_REQUEST -eq 'false' ]]; then mvn whitesource:update -Pwhitesource ; fi"
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.