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

Contrast agents

Contrast agents are supported for one year after release. Older agents may continue to function and remain compatible, but they are no longer fully supported.

Contrast applies bug fixes and develops new features on the latest version of the agent. Code changes are not backported to previous versions. While a workaround may be provided for a bug, to resolve issues, you should update to the release in which the issue was addressed.

Operating systems

Agent testing is done on 64-bit OSX and 64-bit Linux.

Starting with version 3.0.0 of the agent, the gem installation step requires the compilation of C extensions. This process is automatic, but it requires that certain software is installed in the target environment:

  • At a minimum, gcc, make, automake and autoconf are required. The package names may be different on different platforms. It may be useful to install your platform's version of build-essential.
  • On some platforms, it may be necessary to install system headers.

Ruby versions

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.


  • 2.7.X: First supported agent was 3.8.0
  • 2.6.X: First supported agent was 2.3.0
  • 2.5.X: First supported agent was 2.0.0


  • 2.4.X: Last supported agent was 3.9.1

Web servers

Web frameworks

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.


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

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.



To install the Ruby 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 RubyGems as a Gem Source or by installing the gem manually.

RubyGems as a Gem Source

To download Contrast from RubyGems, add the following to your application's Gemfile:

gem 'contrast-agent'

and run an install:

bundle install

or an update:

bundle update

Note: If you only want to run with Contrast in certain environments, you can do so using the Bundler's Group function.

Manual installation

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

gem 'contrast-agent'

and install the gem in the gemset for the current application:

gem install ./path/to/contrast-agent-*.gem --platform ruby

and run an install:

bundle install

or an update:

bundle update

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.

Note: In cases where the Gem is not installed and the system can connect to RubyGems, Bundler will fall back to using RubyGems.


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.

Connecting to your Application


The Ruby Agent functions as a Railtie, so no additional configuration is required.


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

require 'sinatra'
require 'contrast-agent'

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

Run the Service

On application startup, the Ruby agent 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 and Linux 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 Ruby 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 Ruby 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.