Automating Rails Security with Brakeman Pro

Jul 10, 2017

“Security” is a vast, constantly-changing subject and protecting your company and customers is a daunting yet absolutely necessary task.

One way to approach security is to slowly layer on different defenses, automating as much as possible: dynamic web scanners, dependency tracking, log alerts, security libraries, and so on.

An important piece of security automation can be provided by code scanning tools like Brakeman Pro.

Brakeman Pro Automation

Brakeman Pro scans the source code of Ruby on Rails applications and reports potentional security vulnerabilities.

The benefit of operating at the source code level is speed (compared to spidering and testing a website with a dynamic scanner) and ease of automation. All you need to have is your source code - no running application, web server, database, external services, etc.

Source code scans can be run on each code change, making it especially appealing for integration into the software development workflow.

Adding security scans to the development workflow can prevent suspect code from ever being merged or deployed.

Below are some ways of automating Brakeman Pro to fit into your development and deployment process.

Test Integration

The easiest, fastest way to automate security with Brakeman Pro is adding Brakeman Pro Engine to your tests!

Tests are already a part of nearly everyone’s development process, especially in the Ruby community, so this should be a very quick and easy way to run Brakeman Pro.

Out of the box, Brakeman Pro supports Minitest and RSpec, as well as offering a generic interface.

All it takes is adding the Brakeman Pro gem to your Gemfile and a single test or spec to your test suite.

require "brakeman/test/minitest"

class TestBrakemanWarnings < Minitest::Test

  # Assert zero Brakeman warnings
  def test_no_brakeman_warnings


If unexpected warnings are found, the test will fail.

1) Failure:
TestBrakemanWarnings#test_no_brakeman_warnings [/home/you/yourapp/test/integration/brakeman_pro_test.rb:8]:
Brakeman found 3 warnings:
Weak Hash (High)
Weak hashing algorithm (MD5) used

Dangerous Send (High)
User controlled method execution

Session Setting (High)
Session cookies should be set to HTTP only

It is also possible to specify other requirements, such as only warning about “High” severity warnings.

Brakeman Pro Engine will automatically fork a new process to run the scan. This avoids polluting the test suite with Brakeman Pro’s dependencies.

In Minitest, Brakeman Pro can run in parallel with other tests as long as all the tests use parallelize_me!

Learn more about Brakeman Pro tests

Continuous Integration

For automating code scans, tracking issues over time, and ensuring all code goes through security testing, continuous integration servers are an excellent approach.

As a command line tool, Brakeman Pro Engine is designed to easily be added to any continuous integration tool. The key is to run Brakeman Pro with the --exit-on-warn option:

brakeman-pro --exit-on-warn

If Brakeman Pro finds any warnings, it will return a non-zero exit code to fail the build.

We have documented how to use Brakeman Pro with Jenkins, Circle CI, Travis CI, Codeship, and Bitbucket Pipelines.

Using a different service? Let us know and we can help figure out the best way to integrate Brakeman Pro with your tools.

Code Climate Platform

Brakeman Pro on Code Climate

Code Climate provides a cloud platform for many code scanning tools.

For another simple solution to automating Brakeman Pro, we offer the Brakeman Pro Engine on Code Climate.

Brakeman Pro on Code Climate

Try Brakeman Pro on Code Climate for free

Starting from Zero

The best way to use code scanning tools like Brakeman Pro is to have the tools fail tests/builds or block deployments if there are any warnings.

To do so, the application needs to start out with zero warnings. Most applications are unlikely to have zero warnings.

In order to reach zero warnings, we suggest first using Brakeman Pro Desktop to go through the results of the initial scan.

Brakeman Pro mark as false positive

Using Brakeman Pro Desktop, warnings can be marked as “valid” or “false positive”. Once triaged, fix the valid warnings!

The false positives can be exported to a brakeman.ignore file. This file can be added to the application’s config/ directory.

The next time the codebase is scanned, the warnings you have already marked as false positives will be ignored, putting the results at zero warnings.

Now you can start failing builds when new warnings are introduced!

Closing the Loop

When warnings do pop up in continuous integration, Brakeman Pro Desktop is still the easiest way to triage them.

If your continuous integration server supports build artifacts, Brakeman Pro Engine can export findings as an artifact:

brakeman-pro --exit-on-warn --export your_app

This artifact can then be imported into Brakeman Pro Desktop for investigation.

Import Menu

See our Circle CI documentation for an example of using artifacts.

Getting Started

If you have not purchased Brakeman Pro yet, you can review pricing and purchase licenses directly from our site.

Need to try before buying? Take Brakeman Pro Desktop for a spin.

Please feel free to contact us with any questions!