Install the Node.js agent using a container

Before you begin

This topic provides general guidance for installing the Contrast Node.js agent in a containerized application, with Docker as an example.

You should have a basic understanding of how containers and related software work. You may need to adjust the instructions to meet your specific circumstances.

Install the agent

Install the Node.js agent using one of these options:

  • Add the agent to the application during development. (recommended)

    This way, the agent will be included with your application’s package.json.

    Use this command to populate the agent into your pipelines and container images.

    npm install @contrast/agent --no-optional
  • Add the agent to the Dockerfile.

    Add the agent at container build time if you prefer to maintain separate images for the application (with and without the Contrast agent).

    Use this command to add the agent into your existing Dockerfile or into a new Dockerfile that uses your application's image as a base image.

    npm install @contrast/agent --no-optional

Configure the agent

Follow these instructions when configuring the Node.js agent for an application deployed into a container like Docker (otherwise, see more general information on configuring the Node.js agent). Configuration for the Node.js agent follows this order of precedence.

  1. Create a YAML file with your agent keys and any other configuration values that are common across your organization. Replace <YourURL>, <YourUserName>, <YourAPIKey> and <YourServiceKey> with your values. The path to write to stdout is /proc/1/fd/1. A typical YAML file for a container installation might look like this:

       url: <YourURL>
       user_name: <YourUserName>  
       api_key: <YourAPIKey>  
       service_key: <YourServiceKey>
         enable: true
            path: /proc/1/fd/1
            level: INFO
         port: 30555
        path: /proc/1/fd/1
        level: INFO
  2. Copy the YAML file into the base image using this command (in this example, /app/contrast_security.yaml is the base directory for your application in the image).

    COPY WORKSPACE/contrast_security.yaml /app/contrast_security.yaml
  3. Use environment variables to set application-specific configuration. These can be ENV statements in the Dockerfile or they can be passed to the Docker run command with the -e option. See a list of environment variables commonly used to set application-specific values.

Run and verify

  1. You must 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 you normally start your application with:

    CMD [“node”, “app”]

    Then you can use this command to run the application with Contrast:

    CMD [“node”, “-r”, “@contrast/agent”, “app”]
  2. When the agent starts, it will try to connect to Contrast with authentication keys in the YAML configuration file.


    To protect the agent credentials, use the Docker secret and pass them as environment variables during deployment time. For example:

    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
  3. Verify that Contrast is running by checking the activity in the container log.

    For example, log activity might look like this:

    @contrast/agent 2.16.8--------------------------------------2020-07-20T19:05:14.407Z INFO contrast-service: BUILD {"progname": "Contrast Service", "version": "2.8.1", "buildTime": ""}2020-07-20T19:05:14.407Z INFO Building timer for orphan request cleanup {"progname": "Contrast Service", "cleanupMs": 5000}2020-07-20T19:05:14.408Z INFO Building timer for orphan app cleanup {"progname": "Contrast Service", "time": 5000}2020-07-20T19:05:14.450Z INFO Creating New Application Server {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "clientId": "1", "pid": 1}2020-07-20T19:05:14.450Z WARN Failed to initialize secure client, falling back to insecure client {"progname": "Contrast Service"}2020-07-20T19:05:15.473Z INFO setting new server features for context{"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a"}2020-07-20T19:05:15.474Z ERROR Error setting up CEF syslog {"progname": "Contrast Service", "err": "open /juice-shop/security.log: permission denied"}2020-07-20T19:05:15.475Z INFO starting event scanner {"progname": "Contrast Service", "report": {}}2020-07-20T19:05:15.486Z INFO Creating new application {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "appName": "juiceshop-guide", "language": "Node", "clientId": "1", "pid": 1}2020-07-20T19:05:15.486Z INFO AppCreate: creating and initializing new application {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "server_name": "bc1bd6e5cd3a", "app_name": "juiceshop-guide", "app_lang": "Node", "client_id": "1", "pid": 1}2020-07-20T19:05:15.921Z INFO setting new application settings {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "appName": "juiceshop-guide", "language": "Node"}2020-07-20T19:05:15.922Z INFO Setting session id on app context: {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "clientid": "1", "appname": "juiceshop-guide", "applang": "Node", "apppath": "/juice-shop/package.json", "sessionid": "cd0b271e66974162bf5fcca8b32e37b1"}Entering main at /juice-shop/appinfo: All dependencies in ./package.json are satisfied (OK)...

See also

Contrast Support Portal Node.js agent with Kubernetes

Contrast Support Portal AWS Fargate and Contrast agents