Skip to main content

Update the Node.js agent

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: hosted (SaaS) or on-premises (EOP).

You can either update the agent automatically or manually.

Before you begin

Before you begin, you should 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.


Unless Contrast Support advises you to do so, do not use a version of the Contrast Node.js agent that is ahead of the version available from your Contrast instance.


  1. You will install the Node.js agent from the npm public (or private) repository. Depending on your Contrast installation, you can use one or both sources to get the latest Contrast Node.js agent:

    • Hosted (SaaS) installations: You can get the latest version of the agent from npm. If your organization prefers to validate agents before using them, you can also use a private npm repository with approved versions only.

    • On-premises (EOP) installations: Many organizations that use on-premises installations do not immediately update core software or agents when Contrast releases new software. Public repositories (like npm) typically host new versions of the agent that are not designed or tested to work with older versions of Contrast. On-premises users should source agent updates from a private npm repository where you only store versions of the agent that match your on-premises Contrast installation.

  2. Install the agent and use scripts for automatic updates using the best method for you:

    • Use package.json: This file specifies which dependencies will 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. For example:

        "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"

      Then use the $ npm update command whenever you build your application. This will automatically download, and add or update, the Contrast Node.js agent from npm to the Node.js application.

    • Install and update manually using command line: 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 this 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
  3. After installing with either method, you will see output like this:

    $ 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 remotenpm 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.0added 19 packages from 43 contributors, updated 5 packages and audited 1995 packages in 14.904sfound 19 vulnerabilities (5 low, 7 moderate, 4 high, 3 critical)
      run `npm audit fix` to fix them, or `npm audit` for details
  4. To check whether the installation/update succeeded, run the following command and look for this output:

    $ 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

See also