This guide offers examples to easily update the Contrast Ruby agent and keep it updated. Contrast frequently releases new versions of agents, so this is important to do. We encourage you to take this guide, make it your own, and distribute it to teams who need to update agents.
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 Ruby’s Bundler package manager.
- Access to the RubyGems repository for the Contrast Ruby agent
- Confirmed that your Ruby application runs properly without the Contrast Ruby agent.
- Previously successfully installed the Contrast Ruby agent
- Defined a policy for how and when to update the agent, based on your change management policy and the environment where you deploy agents.
The most reliable and effective way to automatically update the Contrast Ruby agent is to use the Ruby Bundler package manager to install and download the latest version available. Because Bundler typically manages all dependencies for your Ruby application, it should already be available and part of your build environment. How frequently you update the Contrast Ruby agent and where you get updates depends on your organization's preferences and your Contrast implementation: SaaS or on-premises.
1) Choose a source for the Contrast Ruby agent
- RubyGems public (or private) repository
- Contrast API
Depending on your Contrast installation, you can use one or both sources to get the latest Contrast Ruby.
- For SaaS installations:
Contrast Ruby agents are synchronized between Contrast and the public RubyGems repository. You can get the latest version of the agent from either source, so use your preference. If your organization prefers to validate agents before using them, you can also use a private RubyGems repository with approved versions only.
- For on-premises (EOP) installations:
Many organizations that use EOP installations do not immediately update core software or agents when Contrast releases new software. Because of this, we don’t recommend public repositories (like RubyGems) to update the agent. These typically host new versions of the agent that are not designed or tested to work with older versions of Contrast.
In this situation, Contrast recommends that you source agent updates directly from the Contrast API or from a private RubyGems repository where you only store versions of the agent that match your EOP Contrast installation.
2) Install the agent and use scripts for automatic updates
There are two ways to install the agent into your environment, if you want to easily update it. Choose the method that works for your situation:
- Use RubyGems as a source
- Manually install the gem
Method one: Use RubyGems as a source
The Gemfile is where you specify which dependencies you want to automatically resolve every time your Ruby application builds with artifacts from RubyGems (public or private). Include the Contrast Ruby agent here to easily keep every new build of your application aligned with the latest version of the agent. Do not specify a version for
contrast-agent, and it will retrieve the latest version.
Here is an example of how to include the Ruby agent in the Gemfile:
gem "bcrypt" gem "coffee-rails" gem "contrast-agent"
After you update the Gemfile, use one of the following commands when you build your application. This will automatically download and add or update the Contrast Ruby agent from RubyGems to the Ruby application.
$ bundle install or
$ bundle update
Method two: Manually install the gem
You can manually update agents as part of a Ruby build process in two ways. Choose the one that works best for your organization and workflow:
- Rubygems. Use the following command to manually retrieve and install the Contrast Ruby agent from RubyGems (public or private) to the application:
$ gem install contrast-agent
Add the following line to your Gemfile to manage updates with Bundler, because the previous command only installs the agent locally:
Then to either install or update the agent using bundler run one of the following:
$ bundle installor
$ bundle update
- Contrast API. Use the following commands to manually add or update the Contrast Ruby agent directly from the Contrast API:
CONTRAST_URL=https://app.contrastsecurity.com OR EOP TeamServer URL ORG_ID=<YOUR TEAMSERVER ORGANIZATION ID> AUTH_TOKEN=<YOUR TEAMSERVER AUTHENTICATION TOKEN> API_KEY=<YOUR TEAMSERVER API KEY> curl -X GET $CONTRAST_URL/Contrast/api/ng/$ORG_ID/agents/default/RUBY \ -o /PATH/TO/RUBY/APP/DIR/contrast-agent.tar.gz -H 'Authorization: $AUTH_TOKEN' \ -H 'API-Key: $API_KEY' -H 'Accept: application/json' -OJ gem install /PATH/TO/RUBY/APP/DIR/contrast-agent.gem
Again, add the following line to your Gemfile to manage the updates with Bundler, because the previous command only installs the agent locally:
3) Use scripts for automatic updates
After you add
contrast-agent to your Gemfile, you can use Bundler to update your agent, like this:
After initial execution, you will see output that looks like the following:
Fetching contrast-agent-3.14.0.gem Fetching protobuf-3.10.3.gem Fetching middleware-0.1.0.gem Successfully installed middleware-0.1.0 Successfully installed protobuf-3.10.3 Building native extensions. This could take a while... To generate the required contrast_security.yaml file you can run: bundle exec rake contrast:config:create Successfully installed contrast-agent-3.14.0 Parsing documentation for middleware-0.1.0 Installing ri documentation for middleware-0.1.0 Parsing documentation for protobuf-3.10.3 Installing ri documentation for protobuf-3.10.3 Parsing documentation for contrast-agent-3.14.0 Installing ri documentation for contrast-agent-3.14.0 Done installing documentation for middleware, protobuf, contrast-agent after 3 seconds
You will know the update succeeded when you see a verification like this:
$ gem list | grep contrast contrast-agent (3.14.0)
If there is not a new Contrast Ruby agent since the last update, Ruby application builds that use either the RubyGems or manual update methods will return output like this:
Using contrast-agent 3.14.0
When there is a new Contrast Ruby agent to download and apply, Ruby application builds will return output like this:
Fetching contrast-agent 3.14.0 Installing contrast-agent 3.14.0 with native extensions
- Unless Contrast Technical Support advises you to do this, we do not recommend using a version of the Contrast Ruby agent that is ahead of the version available from your Contrast instance.
- Check for the latest Ruby agent issues here: Troubleshooting > Ruby Agent