Brakeman - A Static Analysis Security Vulnerability Scanner For Ruby on Rails Applications

Brakeman - A Static Analysis Security Vulnerability Scanner For Ruby on Rails Applications

Brakeman is an open source security scanner for Ruby on Rails applications. Unlike many security scanners, Brakeman analyses the source code of the application and produces a report of all the security issues.

It requires zero setup or configuration once it is installed.

Note: It works with any version of Rails from 2.3.x to 5.x. Brakeman can analyse code written with Ruby 1.8 syntax and newer, but requires at least Ruby 1.9.3 to run.

As you know that all Brakeman needs is source code, so it can be run at any stage of development: you can generate a new application with "rails new" and immediately check it with Brakeman.

Since it does not rely on spidering sites to determine all their pages, it can provide more complete coverage of an application. This includes pages which may not be 'live' yet. In theory, Brakeman can find security vulnerabilities before they become exploitable.

Brakeman may not be exceptionally speedy, but it is definitely much faster than "black box" website scanners. Even large applications should not take more than a few minutes to scan.

Here are some of the limitations of Brakeman:
  • False Positives: Only the developers of an application can understand if certain values are dangerous or not. By default, Brakeman is extremely suspicious. This can lead to many "false positives".
  • Unusual Configurations: Brakeman assumes a "typical" Rails setup. There may be parts of an application which are missed because they do not fall within the normal Rails application layout.
  • Only Knows Code: Dynamic vulnerability scanners which run against a live website are able to test the entire application stack, including the webserver and database. Naturally, Brakeman will not be able to report if a webserver or other software has security issues.
  • Isn't Omniscient: Brakeman cannot understand everything which is happening in the code. Sometimes it just makes reasonable assumptions. It may miss things. It may misinterpret things. But it tries its best. 

INSTALLATION

Using RubyGems:
gem install brakeman

Using Bundler:
group :development do
  gem 'brakeman', :require => false
end

USAGE

From a Rails application's root directory:
brakeman

Outside of Rails root:
brakeman /path/to/rails/application


BASIC OPTIONS

To specify an output file for the results:
brakeman -o output_file

The output format is determined by the file extension or by using the -f option. Current options are: text, html, tabs, json, markdown, csv, and codeclimate.

Multiple output files can be specified:
brakeman -o output.html -o output.json

To suppress informational warnings and just output the report:
brakeman -q

Note: All Brakeman output except reports are sent to stderr, making it simple to redirect stdout to a file and just get the report.

To see all kinds of debugging information:
brakeman -d

Specific checks can be skipped, if desired. The name needs to be the correct case. For example, to skip looking for default routes (DefaultRoutes):
brakeman -x DefaultRoutes

Multiple checks should be separated by a comma:
brakeman -x DefaultRoutes,Redirect

To do the opposite and only run a certain set of tests:
brakeman -t SQL,ValidationRegex

If Brakeman is running a bit slow, try
brakeman --faster

This will disable some features, but will probably be much faster (currently it is the same as --skip-libs --no-branching). WARNING: This may cause Brakeman to miss some vulnerabilities.

By default, Brakeman will return 0 as an exit code unless something went very wrong. To return an error code when warnings were found:
brakeman -z

To skip certain files or directories that Brakeman may have trouble parsing, use:
brakeman --skip-files file1,/path1/,path2/

To compare results of a scan with a previous scan, use the JSON output option and then:
brakeman --compare old_report.json

This will output JSON with two lists: one of fixed warnings and one of new warnings.

Brakeman will ignore warnings if configured to do so. By default, it looks for a configuration file in config/brakeman.ignore. To create and manage this file, use:
brakeman -I

Brakeman assigns a confidence level to each warning. This provides a rough estimate of how certain the tool is that a given warning is actually a problem. Naturally, these ratings should not be taken as absolute truth.

There are three levels of confidence:
  • High - Either this is a simple warning (boolean value) or user input is very likely being used in unsafe ways.
  • Medium - This generally indicates an unsafe use of a variable, but the variable may or may not be user input.
  • Weak - Typically means user input was indirectly used in a potentially unsafe manner.

To only get warnings above a given confidence level:
brakeman -w3

The -w switch takes a number from 1 to 3, with 1 being low (all warnings) and 3 being high (only highest confidence warnings).

Brakeman options can stored and read from YAML files. To simplify the process of writing a configuration file, the -C option will output the currently set options.

Options passed in on the command-line have priority over configuration files.

The default config locations are ./config/brakeman.yml, ~/.brakeman/config.yml, and /etc/brakeman/config.yml

The -c option can be used to specify a configuration file to use.

Comments

Post a Comment