NPM Plugin

With the release of the Mend Unified Agent (previously called the File System Agent (FSA)), 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 Mend on November 2nd, 2019.

The 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  

 

Overview

The plugin allows Node.js based projects to integrate with Mend open source management. Once configured and executed the plugin will create or update Mend 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 Mend Globally:

1 $ npm install -g Mend

Ubuntu Issues

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

1 $ which Mend

and then create an alias to run Mend globally:

1 $ alias Mend="node path/to/Mend"

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:

1 $ which node

if displayed /usr/sbin/node remove it:

1 $ sudo rm /usr/sbin/node

then make a link:

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

Configuring the Plugin

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

1 2 3 4 5 6 7 8 9 10 11 { "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

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

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 Mend config file.

Supported from version 17.12.4

Executing the Plugin

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

Run the plugin with this command:

1 $ Mend run

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

Custom config file location

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

1 $ Mend run -c c:\path\to\file\Mend.config.json

In order to use multiple build environments (e.g npm and bower) it is recommended to use different Mend.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.

To do so, run the plugin inside your yarn project folder with the following command:

1 $ Mend 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.

If the "ls" process fails, please investigate your project and fix it.

Mend cannot run when the native npm ls command fails.

This can be a sign of a misconfigured or invalid node project (check your package.json and npm-log file to investigate further).


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

  1. Uninstall Mend: "npm uninstall Mend"

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

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

 

If the issue persists after running the plugin, send the npm-shrinkwrap.json, package.json, npm-debug.log
and the Mend log files (located in the project's root and prefixed with ws-log) to support@Mendsoftware.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 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)

Updating the Plugin

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

1 $ [sudo] npm update -g Mend

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. Mend NPM plugin is installed:

    1 $ [sudo] npm install -g Mend



  4. In order to add the plugin to your job - Go to your job → configure → Add build step and use the following command:

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