WhiteSource provides several integrations that can be configured in the build process in order to:
Below are listed the integrations that have been currently tested.
The NPM integration allows to perform the tasks mentioned above for Javascript projects.
Below are listed the configuration items
package.json
whitesource: 1.0.9
, below devDependencies
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* |
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.
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.
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 ) |
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.
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
Try to add com.github.lalyos:jfiglet:0.0.8
(GPL-3.0 license) to your pom.xml
and run the mvn
command again.
... 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" |
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.