Agent installation guide
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.
Update the application’s Dockerfile
- Add the Contrast Ruby agent
- Configure the agent
- Add authentication credentials for your environment
- Instrument your application
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
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:
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.
- Corporate rule (e.g., expired license overrides assess.enable)
- Environment variable value
- YAML configuration file value
- Contrast UI value
- 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.
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:
- Add a base service and logging configuration:
- Copy the edited YAML into the base image Dockerfile:
This can be copied into any of the following locations in the container:
COPY WORKSPACE/contrast_security.yaml approot/contrast_security.yaml
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
- Application group: Specify the application access group for this application during onboarding. NOTE: Application access groups have to be created first in Contrast.
- Application tags: Add labels to an application
- Server name: Specify the server name reported to Contrast
- Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production.
- Server tag: Add labels to the server.
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.
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
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.
- How do I run the Contrast Ruby agent in testing suites?
- How do I get logs from the Ruby agent?
- 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