Agent installation guide

Overview

This guide offers examples for using Contrast Security’s Node.js agent with Docker. We encourage you to take this guide, make it your own, and distribute it to teams who both need to instrument Node applications and manage them through Docker. 

The main portion of the guide details the most popular methods customers use to instrument Node applications contained in Docker and see security data in Contrast.

There is also a lab section that describes how to instrument a sample Node application with known vulnerabilities called OWASP Juice Shop. It’s a good way to learn before proceeding with your own applications. You can instrument OWASP Juice Shop through Docker and see security data for this application in Contrast using the source code samples section at the end of this guide.

Main steps

Update the application’s Dockerfile

1. Add the Contrast agent to the application
2. Create an agent configuration file
3. Update the start command to use the agent

Instrument your application

4. Start up with Contrast enabled 

Supported technologies

Before you begin, please be sure Contrast supports your preferred tools and environments for Node.js:
Supported technologies for Node.js 

This guide assumes you have:

• Some familiarity with DevOps practices and how Docker works
• The information needed to connect the Contrast Node.js agent to the Contrast dashboard: Install Node.js agent with npm
• Downloaded and started the agent before running your applications

Instructions

Begin by updating the Dockerfile for your application.

1. Add the Contrast Node.js agent

Here are two options to add the Contrast agent and basic configuration to a Docker image. Choose the one that works best for you.

Option 1: Add to the application

The preferred approach is to add the Contrast agent to your application during development. This way, the agent will be included with your app’s package.json 

• You can use a typical “npm install” command to populate the agent into your pipelines and container images.

npm install @contrast/agent

Option 2: Add to a Dockerfile

If option 1 doesn’t work or you prefer to maintain separate images for the application--with and without the Contrast agent--you can add the Contrast agent at container build time. To do this:

• Use the same npm install command to add the agent into your existing Dockerfile
• Or add it into a new Dockerfile that uses your application’s image as a base image

2. Configure the agent

There are different values you can use to configure Contrast agents. This is the order of precedence. Each level overrides the next, and 1 is highest.

1. Corporate rule (e.g., expired license overrides assess.enable)
2. Environment variable value
3. YAML configuration file value
4. Contrast UI value
5. Default value

The order of precedence is explained more here:
Order of precedence

We recommend a mixed approach:

• Keep the common configuration in the YAML file so it can be placed in the base image
• Use environment variables for application-specific configuration values

Common configuration

This approach keeps a core set of configurations in the YAML file. Here are a few examples of common configurations. You can modify these, as desired. 

• Redirect logging to console output
• Proxy configuration, if any
• Performance tuning options to limit agent activity

To do this:

1. Add base configuration options that will remain static.

api: 
  url: https://app.contrastsecurity.com
agent: 
  service: 
    grpc: true
  logger: 
    path: /proc/1/fd/1
    level: INFO

2. Next, create and copy the YAML file into the base image. Let's assume the YAML file is saved in /app/contrast_security.yaml, which is the base directory for your app in the image.
3. Copy the edited YAML file into the Dockerfile

COPY WORKSPACE/contrast_security.yaml /app/contrast_security.yaml

Application-specific configuration

This allows additional options, per application. To set an application-specific configuration, use environment variables. Note: these may be specified using ENV statements in the Dockerfile or passed to the Docker run command with the -e option as appropriate.

• Application metadata: Specify application-specific metadata
  CONTRAST__APPLICATION__METADATA
• Application name: Specify the application name reported to Contrast CONTRAST__APPLICATION__NAME
• Application session metadata: Send application details like build number, version, GIT hash, etc.
  CONTRAST__APPLICATION__SESSION_METADATA

For more, see Contrast documentation: View session metadata

• Application group: Specify the application access group for this application during onboarding. NOTE: Application access groups have to be created first in Contrast. CONTRAST__APPLICATION__GROUP
• Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production. CONTRAST__SERVER__ENVIRONMENT

3. Update the start command to use the agent

To enable Contrast, you will need to preload the Contrast agent when you launch your application. Normally, you do this in the Dockerfile’s CMD statement, but you can also use an npm script defined in the package.json.

For example, if your application normally starts with...

CMD [“node”, “app”]

...you can use the following command to enable Contrast:

CMD [“node”, “-r”, “@contrast/agent”, “app”]

4. Instrument your application

When the agent starts, it will try to connect to Contrast with the URL and agent credentials from step 2. To protect the agent credentials, utilize the Docker secret and pass them as environment variables during deployment time. Here is an example of the Docker run command:

docker run -e CONTRAST__API__URL=<value> -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value> -e CONTRAST__API__USER_NAME=<value> -e CONTRAST__SERVER__ENVIRONMENT=<value> -p 3000:3000 image_with_contrast

You can verify that Contrast is running by seeing messages in the container log, such as:

{"level":30,"time":1717709981057,"tid":0,"pid":4743,"hostname":"LTAN-C02DL1KHMD6R","name":"contrast","msg":"Starting @contrast/agent v5.8.0"}
{"_errors":[],"enable":"true","api":{"enable":"true","url":...,"msg":"Agent configuration"}
info: All dependencies in ./package.json are satisfied (OK)
info: Detected Node.js version v18.16.0 (OK)
info: Detected OS darwin (OK)
info: Detected CPU x64 (OK)
info: Configuration default validated (OK)
info: Entity models 19 of 19 are initialized (OK)
{"level":50,"time":1717709986369,"tid":0,"pid":4743,"hostname":"LTAN-C02DL1KHMD6R","name":"contrast","funcKey":"assess-dataflow-sink:Express.Response.push","obj":{},"msg":"attempted to hook property push that is not a method or does not exist"}
info: Required file server.js is present (OK)
info: Required file index.html is present (OK)
info: Required file runtime.js is present (OK)
info: Required file styles.css is present (OK)
info: Required file polyfills.js is present (OK)
info: Required file main.js is present (OK)
info: Required file vendor.js is present (OK)
info: Port 3000 is available (OK)
info: Domain https://www.alchemy.com/ is reachable (OK)
info: Chatbot training data botDefaultTrainingData.json validated (OK)
info: Server listening on port 3000

Source code example: OWASP Juice Shop

Use this GitHub repository to learn how to first. It contains a lab that walks you through different ways Node.js applications delivered via Docker can be instrumented for security monitoring with Contrast.
https://github.com/Contrast-Security-OSS/contrastsecurity-node-docker-onboarding-guide-sample-project

FAQ

1. How much will the Node.js agent affect performance for my applications? You will need to increase available CPU and memory for your applications
   System requirements for the Node.js agent
2. Is there any impact on application startup when running with Node.js?
   Does the Node.js agent affect my application's performance?
3. How do I handle connection errors in the Contrast log?
   Connectivity Issues with the Node Agent
4. Will the new version of a Contrast agent work with older versions of Contrast? Or vice-versa? It may work, but it is not recommended. Always update both.
   Install an agent

Known Issues

• SSL communication issues when using slim images