...
Info |
---|
With the release of the WhiteSource Unified Mend Unified Agent (previously called the File System Agent (FSA)), WhiteSource Mend will no longer provide standard support, including updates and fixes for the NPM plugin after May 4th, 2019. Extended Support (limited to configuration & support/troubleshooting) will be provided until November 1st, 2019. Please migrate to the Unified Agent before this date. This plugin will no longer be supported by WhiteSource Mend on November 2nd, 2019. The WhiteSource Mend Support team is ready to assist with the necessary changes required to use the Unified Agent and can be contacted via the Customer Community. |
...
The plugin allows Node.js based projects to integrate with WhiteSource Mend open source management. Once configured and executed the plugin will create or update WhiteSource Mend projects and enforce inventory policies. Note the following:
...
Installing the Plugin
Install WhiteSource Mend Globally:
Code Block |
---|
$ npm install -g whitesourceMend |
Ubuntu Issues
If you experience trouble running WhiteSource Mend globally on Ubuntu after installing locate the WhiteSource Mend package by running:
Code Block |
---|
$ which whitesourceMend |
and then create an alias to run WhiteSource run Mend globally:
Code Block |
---|
$ alias whitesourceMend="node path/to/whitesourceMend" |
Troubleshooting: Having trouble finding "node" in Ubuntu?
...
Configuring the Plugin
Create a "whitesourceMend.config.json" file in your project root directory and input your WhiteSource Mend API Token found in the Admin Integration API page:
Code Block |
---|
{ "apiKey":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "checkPolicies":true, "productName":"My Product", "productVer":"1.0.0", "projectName":"My Project", "projectVer":"1.0.0", "devDep": true } |
General Parameters
Attribute | Type | Description | Required |
---|---|---|---|
apiKey | String | Unique identifier of the organization to update, can be retrieved from the admin page in your |
Mend account. | Yes | |
checkPolicies | Boolean | Whether or not to send the check policies request before updating |
Mend. | No | ||
productName | String | Name of the product to update. | No, if not defined matching to existing |
Mend products is done by productToken | |||
productVer | String | Version of the product and project to update. This overrides the project version. | No, only read if productName is defined |
productToken | String | API token to match an existing |
Mend product, can be retrieved from the Integration API page in your |
Mend account. | No, if not defined matching to existing |
Mend products is done by name. No projectToken is allowed | |||
projectName | String | Name of the project to update. | No, if not defined matching to existing |
Mend projects is done by projectToken | |||
projectVer | String | Version of the project. | No, only read if projectName is defined |
projectToken | String | API token to match an existing |
Mend project, can be retrieved from the Integration API page in your |
Mend account. | No, if not defined matching to existing |
Mend projects is done by name. No productToken is allowed | ||
devDep | String | Adds devDependencies to the |
Mend report. Accepts either "true" or "false" | No | |
baseURL | String | The IP / Name of the destination |
Mend service | No. Will use the default configuration | ||
port | Int | The port number of the destination baseURL | No. Will use the default configuration |
https | Boolean | Whether or not to use HTTPS secured connection | No. Will use the default configuration |
proxy | String | The proxy server from which you want to redirect the messages. (e.g - "proxy":"http://10.0.0.1:8080" ) | No |
forceUpdate | Boolean | If true - updates the project even if the "checkPolicies" step failed. (default is false) | No. Will use the default configuration |
failOnError | Boolean | If true, fails the process if "checkPolicies" failed (default is false) | No. Will use the default configuration |
timeoutMinutes | Int | Number of minutes to timeout. (default is one hour) | No. Will use the default configuration |
debugMode | Boolean | If true, adds to the root folder a new folder with log files. (default is false) | No. Will use the default configuration |
registryAccessToken | String | Access token to private registries | No |
connectionRetries | int | Connection retries when unable to connect to |
Mend service. (default is 1) | No. Will use the default configuration | |
failOnConnectionError | Boolean | Fails the build when unable to connect to |
Mend service | No, default value is true | |
userKey | String | Unique identifier of the user who updates, can be retrieved from the admin page in your |
Mend account. | Required if |
Mend administrator has enabled "Enforce user level access" option | |||
ignoreNpmLsErrors | Boolean | Whether or not to ignore errors of the 'npm ls' command. | No, the default value is false |
Resolving NPM Dependencies
...
If you scan a private registry that requires an access token, add the property "registryAccessToken" to the WhiteSource Mend config file.
Info |
---|
Supported from version 17.12.4 |
Executing the Plugin
Make sure you have package.json and whitesourceMend.config.json files located at project root.
Run the plugin with this command:
Code Block |
---|
$ whitesourceMend run |
WhiteSource Mend dependency report is saved in the project's "whitesourceMend.report.json" auto-generated file and posted to your WhiteSource Mend dashboard.
Custom config file location
If you want to use whitesourceMend.config.json file that is not located under the project root please run:
Code Block |
---|
$ whitesourceMend run -c c:\path\to\file\whitesourceMend.config.json |
In order to use multiple build environments (e.g npm and bower) it is recommended to use different whitesourceMend.config.json file for each build environment (i.e each of them in a different location)
...
To do so, run the plugin inside your yarn project folder with the following command:
Code Block |
---|
$ whitesourceMend yarn |
Debugging Instructions
...
If the "ls" process fails, please investigate your project and fix it.
WhiteSource Mend cannot run when the native npm ls command fails.
...
When encountering issues running the NPM plugin, follow these instructions:
Uninstall WhiteSourceMend: "npm uninstall whitesourceMend"
Install the updated version: "npm install -g whitesourceMend"
All config files are left as is (so you can use the same whitesourceMend.config.json file)
If the issue persists after running the plugin, send the npm-shrinkwrap.json, package.json, npm-debug.log
and the WhiteSource Mend log files (located in the project's root and prefixed with ws-log) to support@whitesourcesoftwaresupport@Mendsoftware.com.
Exit Code
Starting version 1.1.1 and later, the following exit codes are displayed upon scan completion:
...
Exit Codes in Bash
The exit codes WhiteSource Mend returns in the 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 256 = 255)
Exit code -2 is equivalent to code 254 (-2 mod 256 = 254)
Exit code -3 is equivalent to code 253 (-3 mod 256 = 253)
Exit code -4 is equivalent to code 252 (-4 mod 256 = 252)
Exit code -5 is equivalent to code 251 (-5 mod 256 = 251)
...
Code Block |
---|
$ [sudo] npm update -g whitesourceMend |
Running NPM Using Jenkins
...
You are using "Freestyle Project" as a Jenkins job.
NPM is installed - download here
WhiteSource Mend NPM plugin is installed:
Code Block $ [sudo] npm install -g whitesourceMend
In order to add the plugin to your job - Go to your job → configure → Add build step and use the following command:
Add "whitesourceMend.config.json" file as described above.