@contrast/agent v5.4.1
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
, andfastify
, 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 useCONTRAST_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
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
and<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
and <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.
With @contrast/agent v4
The Contrast Node.js agent v4 is still available for use, but does not support ESM
modules. To use the v4 agent, use the --require
(-r
) flag.
node -r @contrast/agent app-main [app arguments]
Configuration
File Locations
The agent will look for the contrast_security.yaml
configuration file in the following locations and order:
Within the processes current working directory, that is
${process.cwd()}/contrast_security.yaml
.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
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.
3 days ago
4 days ago
9 days ago
23 days ago
1 month ago
1 month ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
4 months ago
9 months ago
8 months ago
8 months ago
9 months ago
8 months ago
9 months ago
9 months ago
5 months ago
4 months ago
5 months ago
5 months ago
6 months ago
5 months ago
7 months ago
6 months ago
7 months ago
7 months ago
4 months ago
8 months ago
8 months ago
4 months ago
5 months ago
5 months ago
7 months ago
7 months ago
4 months ago
4 months ago
4 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
12 months ago
11 months ago
11 months ago
11 months ago
11 months ago
10 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago