Agent installation guide
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.
Update the application’s Dockerfile
- Add the Contrast agent to the application
- Create an agent configuration file
- Update the start command to use the agent
Instrument your application
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
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 --no-optional
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.
- Corporate rule (e.g., expired license overrides assess.enable)
- Environment variable value
- YAML configuration file value
- Contrast UI value
- 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
This approach keeps a core set of configurations in the YAML file. Here are a few examples of common configuration. 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:
- Add base configuration options that will remain static.
- 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.
- Copy the edited YAML file into the Dockerfile
COPY WORKSPACE/contrast_security.yaml /app/contrast_security.yaml
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
- Application name: Specify the application name reported to Contrast
- Application session metadata: Send application details like build number, version, GIT hash, etc.
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.
- Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production.
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_ -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value> -e CONTRAST__API__USER_NAME=<value> -e CONTRAST__SERVER__ENVIRONMENT=<value> image_with_contrast
You can verify that Contrast is running by seeing messages in the container log, such as:
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.
- 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
- Is there any impact on application startup when running with Node.js?
Does the Node.js agent affect my application's performance?
- How do I handle connection errors in the Contrast log?
Connectivity Issues with the Node Agent
- 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