...

...

Overview

The plugin allows Node.js based projects to integrate with WhiteSource open source management. Once configured and executed the plugin will create or update WhiteSource projects and enforce inventory policies. Note the following:

• The plugin is licensed under the Apache 2.0 license.

• Source code and issues are hosted on GitHub and on NPM.

Prerequisites

• NodeJS, version 5.x.x or later

...

Installing the Plugin

Install WhiteSource Globally:

$ npm install -g whitesource

Ubuntu Issues

If you experience trouble running WhiteSource globally on Ubuntu after installing locate the WhiteSource package by running:

...

$ alias whitesource="node path/to/whitesource"

Troubleshooting: Having trouble finding "node" in Ubuntu?

The node package can be found in several packages in Ubuntu: node and nodejs. Locate the node package by running:

...

$ sudo ln -s /usr/bin/nodejs /usr/bin/node

...

Configuring the Plugin

Create a "whitesource.config.json" file in your project root directory and input your WhiteSource API Token found in the Admin Integration API page:

{
	"apiKey":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"checkPolicies":true,
	"productName":"My Product",
	"productVer":"1.0.0",
 
	"projectName":"My Project",
	"projectVer":"1.0.0",
	"devDep": true
 
}

General Parameters

Resolving NPM Dependencies

To resolve NPM dependencies, you should first run "npm install" command on the relevant folders before executing the plugin.

Private Registries

If you scan a private registry that requires an access token, add the property "registryAccessToken" to the WhiteSource config file.

Executing the Plugin

Make sure you have package.json and whitesource.config.json files located at project root.

...

WhiteSource dependency report is saved in the project's "whitesource.report.json" auto-generated file and posted to your WhiteSource dashboard.

Custom config file location

If you want to use whitesource.config.json file that is not located under the project root please run:

...

In order to use multiple build environments (e.g npm and bower) it is recommended to use different whitesource.config.json file for each build environment (i.e each of them in a different location)

Yarn Project

Starting with version 18.2.1, the NPM plugin can scan and upload yarn projects as well.

...

$ whitesource yarn

Debugging Instructions

First, please try to run "npm ls --json > ./test.json",

Important- The NPM Plugin is dependent on the "ls" command. In order for the NPM to work the command "npm ls" must be completed successfully.

...

When encountering issues running the NPM plugin, follow these instructions:

1. Uninstall WhiteSource: "npm uninstall whitesource"

2. Install the updated version: "npm install -g whitesource"

3. All config files are left as is (so you can use the same whitesource.config.json file)

If the issue persists after after running the plugin, send  send the npm-shrinkwrap.json, package package.json, npm-debug.log
and the WhiteSource log files (located in the project's root and prefixed with ws-log) to support@whitesourcesoftware.com.

Exit Code

Starting version 1.1.1 and later, the following exit codes are displayed upon scan completion:

SUCCESS: 0,
ERROR: -1,
POLICY_VIOLATION: -2,
CLIENT_FAILURE: -3,
CONNECTION_FAILURE: -4,
SERVER_FAILURE: -5

Exit Codes in Bash

The exit codes WhiteSource returns in the Bash Bash command language should be treated as 'x' modulo 256: 

• Exit code 0 is equivalent to code 0 (0 mod 256 = 0)

• Exit code -1 is equivalent to code 255 (-

  1 mod

  1 mod 256 = 255)

• Exit code -2 is equivalent to code 254 (-

  2 mod

  2 mod 256 = 254)

• Exit code -3 is equivalent to code 253 (-

  3 mod

  3 mod 256 = 253)

• Exit code -4 is equivalent to code 252 (-

  4 mod

  4 mod 256 = 252)

• Exit code -5 is equivalent to code 251 (-

  5 mod

  5 mod 256 = 251)

Updating the

...

Plugin

 In  In order to update the plugin please run it with it with the following command:

$ [sudo] npm update -g whitesource

Running NPM Using Jenkins

Make sure that you've installed/using the following tools:

1. You are using "Freestyle Project"  as a Jenkins job.

2. NPM is installed - download here

3. WhiteSource NPM plugin is installed:

   Code Block
   $ [sudo] npm install -g whitesource

   
   

4. In order to add the plugin to your job - Go to your

   job →

   job → configure → Add build step and use the following command:
   Image Modified

5. Add "whitesource.config.json" file as described above.