How to configure a Ruby agent with Contrast in 5 minutes

An agent is a Contrast tool for application monitoring. Agents monitor, recording security data and the status of the application. They analyze the data collected, report it and then send it to Contrast. 

This data contains information about the security vulnerabilities in an application. When able to mitigate a security threat, agents can prevent or stop the threat with the use of sensors. A sensor is a security instrumentation technique used to collect security data by agents.

Contrast provides agents for various languages, including Ruby. The Ruby agent is compatible with web frameworks like Ruby on Rails, Grape and Sinatra. With this agent configured in your web application, you’re guaranteed security scanning for your web application without the trouble of having to configure testing in your development lifecycle. 

In this article, we will look at how you can configure a Ruby agent for your application.

Prerequisites

Before we get into the instructions, we encourage you to have the following ready to follow along:

• Ruby version 2.5 or above installed on your machine. Even if you’ve never used Ruby, if you’re using Linux, chances are high that it’s already installed. Check if it’s installed with the following terminal command: ruby -v
• A basic understanding of Ruby is helpful to understand concepts like gems, gem files and bundlers, which we briefly touch on but are not totally necessary.
• autoconf installed in your system. This is a package under the m4 macro language processor. It’s used by the Ruby agent when running. Follow the instructions to install it on macOS and Windows. autoconf comes pre-installed in most Linux distros. In Linux, you can check if it is installed using this command: autoconf --version

• Contrast enterprise account credentials, including username and service key. Credentials are not required if you’re only looking at how to configure a Ruby agent for possible future use or reference.

Ruby agent setup

In your working folder, open your Gemfile and paste the following:

source "https://rubygems.org"

# the contrast agent gem

gem 'contrast-agent'

Run this command in your terminal to install the Contrast agent:

bundle install

Configuring the Contrast Ruby agent

The Contrast Ruby agent requires several configuration parameters, which you can pass by setting environment variables or with a configuration YAML file. The YAML files are essential, as they can be used to store vital credentials, like your Contrast Security username and application programming interface (API) key. 

Note the order of precedence and where you can place your YAML file before you consider using them. 

The YAML file is critical, as we use it to derive what we can use in the environment variables and command-line arguments. Take, for instance, setting the agent logger. We can use these lines in the YAML file:

agent:

agent.logger

For the environment variables, capitalize every letter and replace the period with a double underscore:

AGENT__AGENT__LOGGER

At the bare minimum, this is what your YAML file should look like:

api:  

    url: https://app.contrastsecurity.com  

    user_name: <your-contrast-name> 

    api_key: <your-api-key> 

    service_key: <your-service-key>

As noted in the documentation, the YAML file should be named contrast_security.yaml. Place the file in the working directory for plain Ruby apps or in your framework’s configuration location. For example, when using the Ruby on Rails framework, you put it in the  ./config folder. You can choose where you place it as long as you set its location in the environment file using the CONTRAST_CONFIG_PATH variable.

You can use the Contrast agent configuration editor to validate your YAML configuration. This editor checks for correct YAML syntax. Note that it’s currently in beta.

First, import the agent using the require statement for all frameworks:

require 'contrast-agent'

Since the agent works like a Railtie, you don't have to configure anything for Ruby on Rails. For other Rack-based frameworks like Grape and Sinatra, this line inside your class configures the agent:

use Contrast::Agent::Middleware, true

Conclusion

We’ve just walked through the basic but vital steps of configuring a Contrast Ruby agent. 

It’s easy to start with Contrast’s securing monitoring features with these agents. Check out Contrast to learn more about its security capabilities and what it can do for your product. Also, check out Contrast Security’s support for Ruby agent here.