The Contrast Ruby agent analyzes the behavior of Ruby web applications using established techniques, such as monkey patching, to add Contrast sensors to an application at runtime.

About the Agent

There are two primary components of the Ruby agent: the agent and a service used to communicate to the Contrast Server.

The Ruby agent is a Rack middleware designed to integrate with Rack-based frameworks. From its position within the Rack middleware stack, the Ruby agent inspects HTTP requests to identify potentially harmful input vectors. During the request, the agent inspects database queries, file writes, system calls, and other potentially damaging actions resulting from the request.

Note: For a list of frameworks supported by the Ruby agent, see the Supported Technologies article.

The service is a standalone executable that translates messages from the agent to a format consumable by the Contrast Server. On application start, the agent manages this service as a separate child process, which isolates the service's impact on the application.

Use the Agent

To start analyzing an application, download the Ruby agent and create a configuration file using the process outlined in the Ruby agent's Installation article. The Ruby agent is installed as a standard Ruby Gem and then activated as a standard middleware.

Supported Technologies

Agent Version Support

Agent support window

Contrast works to maintain compatibility with released agents as long as possible. To maintain compatibility as well as progress, agents are supported for one year after release. Older agents may continue to function and remain compatible with the Contrast UI or Service after one year; but, there are no guarantees that incompatibilities won't arise over time.

Bug fix and feature release policy

Contrast applies bug fixes and develops new features on the latest version of the agent. Code changes are not back ported to previous versions. While a work around may be provided for a bug, the supported resolution is to update to the release in which the issue was addressed.

Ruby Version Support

Contrast supports Ruby Long-Term Support (LTS) versions in normal maintenance and security maintenance status. Contrast shifts its support for Ruby versions as the working group shifts its LTS windows. See the Ruby Maintenance Branches schedule for specific release dates.

Note: The Ruby agent shifts minor version support as quickly as possible upon release; but, Contrast may require a quarter to complete compatibility testing.

Web Framework Support

Note: The agent itself supports Rails through version 6; however, a bug introduced in Rails 6, issue 37308, may prevent it from properly monkey patching in cases where eager_load is enabled. As such, it is recommended for Rails 6 that this configuration be disabled.

While the agent can still run on Rack-based web frameworks that aren't officially supported, Contrast may produce less-specific findings than it does for supported frameworks. Instead of reporting that a vulnerability occurs in your application code, Contrast may need to report it within the framework code where it interfaces directly with the Rack methods.

Third-Party Module Support

Contrast doesn't guarantee support for old or deprecated versions of third-party modules.

OS Support

The agent runs in the Ruby application layer with some C dependencies. Agent testing is done on 64-bit OSX and 64-bit Linux. As the agent has glibc C dependencies, it may not work in other operating system environments.

Testing Environments

When changes are made, Contrast runs a battery of automated tests to ensure that it detects findings in supported technologies across all supported versions of Ruby. In addition to its own testing, Contrast also runs the Ruby Spec Suite against an environment with the agent enabled.

Additional Technology

Contrast runs with a range of third-party technology, including options that aren't listed here. If you want to confirm that Contrast supports your preferred technology, or you'd like to make a case for Contrast to support it, let Contrast know.

More Information

Working with MuslC



To install the Contrast agent into your Ruby application, you must complete the following steps.

  1. Add the contrast-agent-*.gem to the application Gemfile. (This is outlined in the Setup section below.)
  2. Add the contrast_security.yaml file to the application's config directory. (This is outlined in the Configuration section below.)
  3. Verify that autoconf is installed on the system where you will run the agent.


The contrast-agent-*.gem is a standard Ruby library that you can add to the application Gemfile. You can complete setup using Contrast UI as a Gem Source or by installing the gem manually. (Note: You may want to take precautions so this doesn't cause issues in a CI environment.)

For manual installation, use the gem command:

gem install path/to/contrast-agent-2.x.x.gem

Contrast as a Gem Source

To use Contrast as a Gem Source, add the following line to your application's Gemfile:

group :contrast, :development, :test, :production do
    gem 'contrast-agent'

Add the following line to the top of your application's Gemfile:

source 'https://app.contrastsecurity.com/Contrast/api/repo/rvm'

After editing the Gemfile, you must bundle the contrast-agent gem by adding authorization to your Bundler:

Note: Make sure that your username is CGI escaped. For example, fname.lname@example.com becomes fname.lname%40example.com.

bundle config https://app.contrastsecurity.com/Contrast/api/repo/rvm ${username}:${service_key}

Finally, run an update:

bundle install
bundle update --group contrast

If you're using the Sinatra framework, you must configure your application to use the Contrast agent. A simple application configured to work with the Contrast agent looks like the following example:

require 'sinatra'
require 'contrast-agent'

class App < Sinatra::Base
  use Contrast::Agent::Middleware, true

Manual installation

To install the Contrast agent manually, download the contrast-agent-*.gem file to a local directory, and add the gem to the project Gemfile:

gem 'contrast-agent'

Install the gem in the gemset for the current application:

bundle install ./path/to/contrast-agent-*.gem

Note: In systems using the rvm or rbenv, the environment of a user on the system might be different than the environment that the runtime server environment is using. If you can't find the gem after server startup, make sure that the gem is in a gemset available to the running web server environment.


Download a standard configuration file from the Contrast application. You must place the file in the web application's config directory, and define the following fields, at a minimum:


For Sinatra applications, you may directly place the configuration file in the working directory. For sharing a configuration file across multiple applications, you may place the file in /etc/contrast/contrast_security.yaml.

Run the Service

On application startup, the Contrast agent gem starts a service in a separate process. This process is responsible for aggregating messages from the agent, sending attack information to Contrast UI and receiving updates to settings from the UI. The agent is packaged with 64-bit Mac, Linux and Windows services. Because the service is launched by the agent, it has access to the same configuration file that the agent used. If the service process is stopped, the agent will attempt to restart it. In the unlikely event that the restart process fails, the agent will cease trying to restart the service after five attempts, and won't send findings to the Contrast UI. However, the agent will continue to protect the application using the last settings it received.

You can access the service status using take tasks:

  • rake contrast:service:status: Returns online or offline.
  • rake contrast:service:start: Attempts to start the service using the configuration for the local contrast agent.
  • rake contrast:service:stop: Attempts to stop the service. If the agent receives additional requests, it will attempt to restart the service on its own.


Multiple Agents

Ensure that the service host and port values are consistent. If there are multiple applications protected by the Contrast agent, the first one to start will launch the service. This is not a problem since the service is designed to handle communication with multiple agents. But, if the agent.service.host and agent.service.port configuration values don't match, the additional agent won't be able to communicate with the previously started service.


Contrast requires compilation in the local environment to install C libraries. While you can compile the Contrast libraries using MuslC locally, one of the Ruby agent's dependencies, google-protobuf, can't. To work around this, you must locally reinstall the dependency.


Reinstall a single gem

The least invasive option is to reinstall a single gem. After installing the Contrast gem, uninstall its dependency and re-install using the ruby platform flag.

CS__PROTOBUF="$(gem list | grep google-protobuf | grep -o '[0-9]*\.[0-9]*\.[0-9]*')"
gem uninstall -I google-protobuf
gem install google-protobuf --version=$CS__PROTOBUF --platform=ruby

Reinstall full platform

If the single gem installation doesn't work, you may also try to reinstall all gems under the Ruby platform.


Note: This option will change the dependencies of your project.

More Information

You can find more details about this issue and the work around in GitHub.