Node.js - Agent update guide – Contrast Security Support Portal

Overview

This guide offers examples to easily update the Contrast Node.js agent and keep it updated. Contrast frequently releases new versions of agents, so this is important to do. We encourage you to take this guide, make it your own, and distribute it to teams who need to update agents.

Main Steps

Choose a source for the Contrast Node.js agent.
- npm repository
- Contrast API
Install the agent and use scripts for automatic updates.
- Use package.json
- Install and update manually

Supported technologies

Before you begin, please be sure Contrast supports your preferred tools and environments for Node.js:
Supported technologies for Node.js

This guide assumes you have:

Some familiarity with DevOps practices and Node’s npm package manager.
Access to the npm repository for the Contrast agent.
Confirmed that your Node.js application runs properly without the Contrast Node.js agent
Previously successfully installed the Contrast Node.js agent.
Defined a policy for how and when to update the agent, based on your change management policy and the environment where you deploy agents.

Instructions

The most reliable and effective way to automatically update the Contrast Node.js agent is to use the Node.js npm package manager to install and download the latest version available. Because npm manages all dependencies for your Node.js application, it should already be available and part of your build environment. How frequently you update the Contrast Node.js agent and where you get updates depends on your organization’s preferences and your Contrast implementation: SaaS or on-premises.

1) Choose a source for the Contrast Node.js agent

npm public (or private) repository
Contrast API

Depending on your Contrast installation, you can use one or both sources to get the latest Contrast Node.js agent:

For SaaS installations:
Contrast Node.js agents synchronize between Contrast and the public npm repository. You can get the latest version of the agent from either source, so use your preference. If your organization prefers to validate agents before using them, you can also use a private npm repository with approved versions only.
For on-premises (EOP) installations:
Many organizations that use EOP installations do not immediately update core software or agents when Contrast releases new software. Because of this, we don’t recommend public repositories (like npm) to update the agent. These typically host new versions of the agent that are not designed or tested to work with older versions of Contrast.
In this situation, Contrast recommends that you source agent updates directly from the Contrast API or from a private npm repository where you only store versions of the agent that match your EOP Contrast installation.

2) Install the agent and use scripts for automatic updates

There are two ways to install the agent into your environment, if you want to easily update it. Choose the method that works for your situation:

Specify the Contrast Node.js agent as a dependency in your package.json
Manually retrieve and add the Contrast Node.js agent

Method 1: Use package.json

package.json is the file where you specify which dependencies you want to automatically resolve every time your Node.js application builds with artifacts from npm (public or private). Include the Contrast Node.js agent here to easily keep every new build of your application aligned with the latest version of the agent.

Here is an example that shows how to specify the agent in your package.json:

{
  "name": "sample_application",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "nodemon",
    "contrast": "node -r @contrast/agent index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.17.1",
    "@contrast/agent": "latest",
  },
  "devDependencies": {
    "nodemon": "^1.19.2"
  }
}

After you update package.json, use the following command when you build your application. This will automatically download and add or update the Contrast Node.js agent from npm to the Node.js application:

$ npm update

Method 2: Install and update manually

For some organizations, the package.json file must be consistent across environments, or they do not plan to install the Contrast Node.js agent into all environments. In these cases, install the agent manually. You can manually update agents as part of a Node.js build process.

Use the following command to manually retrieve and add or update the Contrast Node.js agent from npm (public or private) to the Node.js application:

$ npm install @contrast/agent

You can also manually add or update the Contrast Node.js agent directly from the Contrast API. Use the following authentication details and commands:

CONTRAST_URL=https://app.contrastsecurity.com OR EOP TeamServer URL
ORG_ID=<YOUR TEAMSERVER ORGANIZATION ID>
AUTH_TOKEN=<YOUR TEAMSERVER AUTHENTICATION TOKEN>
API_KEY=<YOUR TEAMSERVER API KEY>
curl -X GET $CONTRAST_URL/Contrast/api/ng/$ORG_ID/agents/default/NodeJS \
  -o /PATH/TO/NodeJS/APP/DIR/contrast-agent.tar.gz -H 'Authorization: $AUTH_TOKEN' \
  -H 'API-Key: $API_KEY' -H 'Accept: application/json'-OJ
npm install /PATH/TO/NodeJS/APP/DIR/node-contrast-#.#.#.tgz

Expected output
After initial execution for either method, you will see output that looks like the following:

$ npm install @contrast/agent

> grpc@1.24.4 install /Users/<aUserName>/Documents/test-apps/juice-shop/node_modules/grpc
> node-pre-gyp install --fallback-to-build --library=static_library

node-pre-gyp WARN Using request for node-pre-gyp https download
[grpc] Success: "/Users/<aUserName>/Documents/test-apps/juice-shop/node_modules/grpc/src/node/extension_binary/node-v72-darwin-x64-unknown/grpc_node.node" is installed via remote
npm WARN jest-config@26.6.1 requires a peer of ts-node@>=9.0.0 but none is installed. You must install peer dependencies yourself.
npm WARN jsdom@16.4.0 requires a peer of canvas@^2.5.0 but none is installed. You must install peer dependencies yourself.
npm WARN ws@7.3.1 requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN ws@7.3.1 requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.

+ @contrast/agent@3.4.0
added 19 packages from 43 contributors, updated 5 packages and audited 1995 packages in 14.904s
found 19 vulnerabilities (5 low, 7 moderate, 4 high, 3 critical)
  run `npm audit fix` to fix them, or `npm audit` for details

To check whether the installation/update succeeded, run the following command. You should see something like the following:

$ npm list | grep contrast
├─┬ @contrast/agent@3.4.0
│ ├─┬ @contrast/distringuish-prebuilt@2.0.0
│ ├─┬ @contrast/escodegen@1.16.0
│ ├── @contrast/esprima@4.1.1
│ ├── @contrast/estraverse@5.1.0
│ ├── @contrast/flat@4.2.0
│ ├── @contrast/fn-inspect@2.3.0
│ ├─┬ @contrast/heapdump@1.0.0
│ ├─┬ @contrast/protobuf-api@2.2.3
│ ├─┬ @contrast/require-hook@1.1.2
│ ├─┬ @contrast/synchronous-source-maps@1.1.0

Known issues

Unless Contrast Technical Support advises you to do this, we do not recommend using a version of the Contrast Node.js agent that is ahead of the version available from your Contrast instance.
Check for the latest Node.js agent installation issues here: I'm unable to install the Node agent

Agent Update Guides articles: