Ruby agent with Docker

Agent installation guide

Overview

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

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

There is also a lab section that describes how to instrument a sample Ruby application called RailsGoat. It’s a good way to learn before proceeding with your own applications. You can instrument RailsGoat 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 Ruby agent
2. Configure the agent
3. Add authentication credentials for your environment
4. Instrument your application

Supported technologies

Before you begin, please be sure Contrast supports your preferred tools and environments for Ruby:
Supported technologies for the Ruby agent

This guide assumes you have:

• Some familiarity with DevOps practices and how Docker works
• Access to the RubyGems repository

The information needed to connect the Contrast Ruby agent to the Contrast dashboard:
Install the Ruby agent

Instructions

Begin by updating the Dockerfile for your application.

1. Add the Contrast Ruby 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 Dockerfile

In this approach the Contrast agent is added to the application’s Dockerfile. To do this: 

• Add the Contrast agent to the end of the application’s Docker image.
• Add Contrast configuration values

You can add the agent to the most recent Ruby gem:

RUN bundle add contrast-agent

OR target a specific version: 

RUN bundle add contrast-agent -v 3.12.1

Example: Dockerfile configuration:

FROM ruby:2.6.5
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
RUN mkdir /myapp
WORKDIR /myapp
ADD Gemfile /myapp/Gemfile
ADD Gemfile.lock /myapp/Gemfile.lock
RUN bundle install
ADD . /myapp
RUN bundle add contrast-agent -v 3.12.1

Option 2: Add to the Gemfile

In this approach, the agent is added to the source Gemfile. To do this:

• Add the Contrast agent to the application’s Gemfile. Specify the agent version, if desired. Or add directly to the gem list or as an optional group.
• Add Contrast configuration values

Example: Gemfile command to run the Contrast Ruby agent in all environments

gem "contrast-agent", "3.12.1"

Example: Gemfile command to run the Contrast Ruby agent in specific environments

gem 'contrast-agent', require: !!ENV['CONTRAST__ENABLE'] != "production"

2. Configure the agent

There are different values you can use to configure Contrast agents. This is the order of precedence, and each level overrides the next: 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

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 environmental variables for authentication and application-specific settings.

Common configuration

This approach keeps a core set of configurations in the YAML file. These can be added to a base image and overridden by environmental variables when needed. 

To do this:

1. Add a base service and logging configuration:

agent:
  logger:
    path: /proc/1/fd/1
    level: ERROR
    # Set to `true` for the agent to tag logs
    # with \"!AM!\" for the metrics tool.
    # metrics: true
  security_logger:
    path: /proc/1/fd/1
    level: ERROR
  service:
    host: localhost
    port: 30555
    logger:
      path: /proc/1/fd/1
      level: ERROR

2. Copy the edited YAML into the base image Dockerfile:

This can be copied into any of the following locations in the container:

• <approot>/contrast_security.yaml
• <approot>/config/contrast_security.yaml
• /etc/contrast_security.yaml
  

COPY WORKSPACE/contrast_security.yaml approot/contrast_security.yaml

Application-specific configuration

To set an application-specific configuration, use the environmental variables in the application’s container. These are some common configuration options. NOTE: use double-underscores here.

For more, see Contrast documentation: Ruby-specific configuration

• Application name: Specify the application name reported to Contrast
  CONTRAST__APPLICATION__NAME
• 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
• Application tags: Add labels to an application
  CONTRAST__APPLICATION__TAGS
• Server name: Specify the server name reported to Contrast
  CONTRAST__SERVER__NAME
• Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production. CONTRAST__SERVER__ENVIRONMENT
• Server tag: Add labels to the server.  CONTRAST__SERVER__TAG

3. Add authentication credentials for your environment

For the Ruby agent to send data to Contrast, it needs an API URL and agent credentials for authentication to the server. This is sensitive data and should be treated carefully.

CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast
CONTRAST__API__API_KEY={Your API KEY}
CONTRAST__API__SERVICE_KEY={Your Service key}
CONTRAST__API__USER_NAME={Your agent user}

You can get API values (agent keys) from Contrast or by downloading a YAML file for the Ruby agent. For more, see Contrast documentation: Find the agent keys

4. Instrument your application

You can now run the application image with Contrast enabled. Contrast will instrument your application during startup and begin reporting security vulnerabilities to Contrast.

You can verify that Contrast is running by checking the container log. You should see messages such as:

web_1  | !!! Contrast - working directory: /myapp
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:58.085+0000","v":0,"msg":"Framework detected. Enabling support.","framework":"Rails"}
web_1  | Puma starting in single mode...
web_1  | * Version 4.2.1 (ruby 2.6.5-p114), codename: Distant Airhorns
web_1  | * Min threads: 0, max threads: 16
web_1  | * Environment: development
web_1  | * Listening on tcp://0.0.0.0:3000
web_1  | Use Ctrl-C to stop
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Current rule settings:"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Assess Rule mode set","rule":"redos","mode":true}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":50,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Field 'user': Value must not be blank"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"CONTRAST-SERVICE -- Version: 2.9.2 PID: 20 WorkingDir: /myapp"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.280+0000","v":0,"msg":"Current rule settings:"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.280+0000","v":0,"msg":"Assess Rule mode set","rule":"redos","mode":false}

Known issues

If you choose a configuration which does not use the contrast_security.yaml file, you will see error messages logged like the following:

web_1  | !!! Contrast - valid configuration file could not be found at any of the search paths

These can be safely ignored. 

Source code example: RailsGoat

Use this GitHub repository to learn how first. It contains a lab that walks you through the different ways Ruby applications delivered via Docker can be instrumented for security monitoring with Contrast.
https://github.com/Contrast-Security-OSS/railsgoat 

FAQ

1. How do I run the Contrast Ruby agent in testing suites?
2. How do I get logs from the Ruby agent?
3. What other Ruby-specific configurations can I use?

Will a new version of an agent work with an older version of Contrast? Or vice-versa?
It may work, but it is not recommended. Always update both.
Install an agent