@contrast/agent

Contrast Security Node.js Agent

This package will enable instrumentation of your Node.js application for security analysis and runtime protection by Contrast Security.

Unlike legacy application security testing solutions, Contrast produces accurate results without dependence on application security experts. Accuracy comes from Contrast's patented Deep Security Instrumentation technology, which integrates the most effective elements of Interactive (IAST), Static (SAST), and Dynamic (DAST) application security testing technology, software composition analysis (SCA), and configuration analysis, and delivers them directly to applications.

Contrast produces a continuous stream of accurate vulnerability and compliance risk information whenever and wherever software is run. Development, QA and Security teams get results as they develop and test software, enabling them to find and fix security flaws early in the software lifecycle, when they are easiest and cheapest to remediate.

New in version 5

• The agent no longer ships or operates with the contrast-service "sidecar" executables. This allows for a drastically smaller download and simplified deployments.

• Framework support includes express, koa, and fastify, with others soon to come.

• The agent does not respond to any command-line configuration flags. Configuration options can be set using environment variables and/or contrast_security.yaml file. If you were previously using the agent's -c CLI option to set the location of your configuration file, you can use CONTRAST_CONFIG_PATH environment variable instead. See more about configuration below.

• Structured logging.

• Ablility to run Assess and Protect modes concurrently.

Getting Started

Existing Contrast Node.js agent users should install and update the Contrast Node.js agent from npm. The Contrast Node.js agent follows semantic versioning (major.minor.patch).

An API key, provided by Contrast Security, is required for the agent to function.

Ensure you have installed the latest LTS (Long Term Support) version of Node.js

To install from npm using the command line (run from the app root directory):

$ npm install @contrast/agent

Usage

CommonJS (CJS) Applications

CommonJS is the original Node.js module system. CJS modules are loaded with the const module = require('module') syntax.

When instrumenting an application written this way, without EJS modules or ESM dependencies, use the following method to start the application.

  node -r @contrast/agent app-main.js [app arguments]

ECMAScript (ESM) Applications

ECMAScript modules are the new official standard format to package JavaScript code for reuse. ES Modules are loaded with the import module from 'module' syntax.

When instrumenting an application that utilizes ECMAScript Modules, use the following methods to start the application. This is the appropriate method for instrumenting an application that uses CJS, ESM, or a combination of both.

• Node versions >=16.17.0 and <18.19.0:

  node --loader @contrast/agent app-main.mjs [app arguments]
  

• Node versions >=18.19.0 and <20.0.0, or versions >=20.6.0:

  node --import @contrast/agent app-main.mjs [app arguments]
  

Configuration

File Locations

The agent will look for the contrast_security.yaml configuration file in the following locations and order:

1. Within the processes current working directory, that is ${process.cwd()}/contrast_security.yaml.

2. OS-specific configuration directories.

   • Unix and MacOS systems:

     • /etc/contrast/node/contrast_security.yaml, then

     • /etc/contrast/contrast_security.yaml

   • Win32 systems:

     • ${process.env.ProgramData}\contrast\node\contrast_security.yaml, then

     • ${process.env.ProgramData}\contrast\contrast_security.yaml

3. Unix home directory.

   • ~/.config/contrast/node/contrast_security.yaml, then

   • ~/.config/contrast/contrast_security.yaml

Note: The optional /node/ path segment is useful in cases where you want to organize configuration files by agent language:

/etc
  /contrast
    /node/contrast_security.yaml
    /java/contrast_security.yaml
    /python/contrast_security.yaml

You can also specify the location of the configuration file with the CONTRAST_CONFIG_PATH environment variable:

CONTRAST_CONFIG_PATH=/path/to/config.yaml node -r @contrast/agent app-main.js

Note: If process.env.CONTRAST_CONFIG_PATH set, the agent will look at that location only. If there is an issue reading the configuration file from this location the agent will not look in the standard locations described above, but instead do the following:

1. Halt instrumentation
2. Communicate an error
3. Run the application as if without Contrast

Minimum Configuration Option Requirements

The agent requires a minimum set of configuration options be set. They are described below as YAML.

api:
  # Organization's API key
  api_key: dCBvm46uEJAUV2musNFb357SnvqYrlq1
  # Contrast user account service key
  service_key: PZU499KK3YD4X2DT
  # Contrast user account ID (In most cases, this is your login ID)
  user_name: agent_d228a527-130c-18cc-93b8-20096136ba0b@UserOrg
  # Address to the Contrast backend. This will vary.
  url: https://app.contrastsecurity.com

Visit https://agent.config.contrastsecurity.com/ to use our online tool for building your YAML file interactively.

For detailed installation and configuration instructions, see the Node.js Agent documentation.