Contrast Security Node.js Protect-only Agent
This package will enable instrumentation of your Node.js application for runtime protection by Contrast Security. The Protect-only agent represents a completely new design for Contrast Security's runtime application security protection (RASP) agent. The main benefits of this new design are improved performance and reduced dependencies.
Contrast Protect can be used to either replace or augment an existing Web Application Firewall (WAF). Contrast Protect provides a production application with API protection that blocks attacks and reduces false positives, helping developer teams prioritize vulnerability backlogs. Unlike perimeter defenses, instrumentation and sensors accurately detect and block runtime application attacks. Contrast Protect provides a firm yes or no on whether the exploit reached its target. The agent also protects against many zero-day attacks without tuning or reconfiguration.
The agent is intended to run in production and becomes part of your application. We strive to impart minimal overhead to your application's latency and throughput. The latency and throughput impact of the agent will vary depending on the complexity of your application and the baseline latency and throughput.
Getting Started
Existing Contrast Node.js agent users should install and update the Contrast Node.js Protect-only 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. This agent requires Node.js 14.15.0 or later.
To install from npm using the command line, run the following from the application root directory:
$ npm install @contrast/protect-agent
Usage
CommonJS (CJS) Modules
UsingCommonJS is the original Node.js module system. CJS modules are loaded with the const module = require('module')
syntax. When instrumenting an application written with CJS modules, use the following method to start the application.
Usage: node -r @contrast/protect-agent app-main.js -- [app arguments]
ECMAScript Modules (ESM)
UsingNOTE: ECMAScript instrumentation is experimental. 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 method to start the application. This is the appropriate method for instrumenting an application that uses CJS, ESM, or a combination of both.
Usage: node --experimental-loader @contrast/protect/lib/esm-loader.mjs app-main.mjs -- [app arguments]
Configuration
Configuring the agent requires either a YAML file, contrast_security.yaml
, or environment variables. The configuration file should be placed in the application's root directory (where the package.json
file usually resides).
If you need to specify a different location for the configuration file you can provide path using the CONTRAST_CONFIG_PATH
environment variable:
CONTRAST_CONFIG_PATH=/path/to/config.yml node -r @contrast/protect-agent app-main.js
The minimum required contrast_security.yaml
setup should look something like this:
api:
url: https://app.contrastsecurity.com
user_name: contrast_user
api_key: demo
service_key: demo
Property | Description |
---|---|
api.api_key | Organization's API key |
api.user_name | Contrast user account ID (In most cases, this is your login ID) |
api.service_key | Contrast user account service key |
api.url | Address of the Contrast installation you would like your agent to report to |
For detailed installation and configuration instructions, see the Node.js Agent documentation.