# Contrast Security Node.js Agent

This package will enable instrumentation of your Node.js application for
security anaylsis and runtime protection by [Contrast Security](https://www.contrastsecurity.com).

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.

## Getting Started

Existing Contrast Node.js agent users should install and update the Contrast
Node.js agent from [npm](https://www.npmjs.com/). Auto-update for the Node.js
agent is no longer supported. 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](http://nodejs.org/)

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

```sh
$ npm install @contrast/agent
```

## Usage

### Using [CommonJS (CJS)](https://nodejs.org/docs/latest-v12.x/api/modules.html) Modules

CommonJS 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/agent app-main.js [agent arguments] -- [app arguments]

    Options:

        -h, --help               output usage information
        -V, --version            output the version number
        -c, --configFile <path>  path to agent config file
```

### Using [ECMAScript Modules (ESM)](https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_ecmascript_modules)

> NOTE: ECMAScript instrumentation is experimental and Contrast requires at least Node version 14.15.0 for support.

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/agent/esm.mjs app-main.mjs [agent arguments] -- [app arguments]

    Options:

        -h, --help               output usage information
        -V, --version            output the version number
        -c, --configFile <path>  path to agent config file
```

### Configuration

The agent expects that the `contrast_security.yaml` configuration file exists 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
use either the `-c` or `--configFile` command-line arguments or provide the
`CONTRAST_CONFIG_PATH` environment variable:

```
node -r @contrast/agent app-main.js -c /path/to/config.yml
node -r @contrast/agent app-main.js --configFile /path/to/config.yml
CONTRAST_CONFIG_PATH=/path/to/config.yml node -r @contrast/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](https://docs.contrastsecurity.com/en/install-node-js.html).
