@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 size and simplified deployments.

• Framework support includes express, koa, fastify, hapi, and restify.

• 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.

• Full support for ESM modules

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 or token, 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

With LTS (Long Term Support) Node.js Versions

Node.js policy is that production applications should use only Active LTS or Maintenance LTS releases. All current LTS versions of Node.js support ECMAScript modules (ESM) and CommonJS modules (CJS) with the --import flag. To ensure that the agent can instrument your application, use:

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

Notes:

• --import should be used for Node.js LTS (Active and Maintenance) versions >=18.19.0
• Node.js versions >=20.0.0 <20.6.0 are not supported

With end-of-life Node.js Versions

When using the agent with end-of-life Node.js versions, use either the --loader or --require flag, depending on the version of Node.js and the module system used.

Use the --loader flag for Node.js versions >=16.17.0 <18.19.0.

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

Use the --require (-r) flag for Node.js versions <16.17.0.

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

Note:

• -r will still work for Node.js versions that have no ESM modules or dependencies.

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 --import @contrast/agent app-main

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

OR

api:
  # base64 encoded JSON object containing the url, api_key, service_key, and user_name
  token: eyJ1cmwiOiJodHRwczovL2FwcC5jb250cmFzdHNlY3VyaXR5LmNvbSIsImFwaV9rZXkiOiJkQ0J2bTQ2dUVKQVVWMm11c05GYjM1N1NudnFZcmxxMSIsInNlcnZpY2Vfa2V5IjoiUFpVNDk5S0szWUQ0WDJEVCIsInVzZXJfbmFtZSI6ImFnZW50X2QyMjhhNTI3LTEzMGMtMThjYy05M2I4LTIwMDk2MTM2YmEwYkBVc2VyT3JnIn0=

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.