CSC/ECE 517 Fall 2014/ch1b 33 jy

Software security in Ruby on Rails web applications using Brakeman scanner

Introduction

Brakeman is an open source vulnerability scanner specifically designed for Ruby on Rails applications. It statically analyzes Rails application code to find security issues at any stage of development.<ref name=brakeman>Brakeman Scanner Introduction</ref> Lift borrows fro Brakeman scans your application by looking at your source code, which means it is not necessary to set up your application stack to use it. Once the scan is complete, Brakeman displays a list of all security issues that were found.

Background

• 2011 - v1.0 released - Brakeman can now be used as a library
• v1.2 - Added rake options to create rake task to run Brakeman
• v1.3 - Added skip files option
• v1.5 - Added JSON Report Format
• v1.7 - Improved processing of Rails 3 routes
• v1.9 - Updated to RubyParser 3
• v2.0 - Combine deserialization checks into single check
• v2.1 - Support for ignoring warnings
• v2.2 - Reduce command injection false positives
• v2.4 - Detect SQL Injection in ‘delete_all’/’destroy_all’
• v2.6 - Parse most files upfront instead of on demand

Installation<ref>http://brakemanscanner.org/docs/install/</ref>

One can install Brakeman in 3 ways.

Using RubyGems

Brakeman can be installed by executing below gem install command at ruby prompt.

gem install brakeman

If you are among those people who are skeptical about installing unsigned gems, we have good news for you, Brakeman gems are now signed. To verify the Brakeman gem, one must add the public Brakeman certificate to their trusted list by using below command.

gem cert --add <(curl -Ls https://raw.github.com/presidentbeef/brakeman/master/brakeman-public_cert.pem)

certificate can also be added to trusted list by manually downloading and adding it. Once certificate is added gems can be installed with trust policy. HighSecurity trust policy implies that all dependent gems must be signed and verified where as MediumSecurity implies that all signed dependent gems must be verified. Since all the dependent dependencies are not yet signed by their authors at this time, only MediumSecurity can be enforced.

gem install brakeman -P MediumSecurity

Bundle install

Brakeman can be added to a Gemfile using below line

gem "brakeman", :require => false

Brakeman gem will be installed as part of bundle install.

Source code

If you would like to have latest version of Brakeman you can always clone the Brakeman git project, build the gem yourself and install it. Following are the commands used to install Brakeman from source code.

git clone git://github.com/presidentbeef/brakeman.git
cd brakeman
gem build brakeman.gemspec
gem install brakeman-*.gem

Running Brakeman

You can run Brakeman in 2 ways. 1. Running brakeman from your rails app directory

cd your_rails_app/
brakeman

This will scan the application in the current directory and output a report to the command line. 2. Supplying path as an option to Brakeman

brakeman your_rails_app

where your_rails_app is the path to your rails application.

Options<ref>http://brakemanscanner.org/docs/options/</ref>

Output Options

Output File

To specify an output file for the results:

brakeman -o output_file

Output Format

The output format is determined by the file extension used with the -o option or by using the -f option. Current options are: text, html, tabs, and csv. For example, to output an HTML report:

brakeman -o report.html

Message Length

By default, brakeman truncates warning messages to 100 characters. The --message-limit option can be used to adjust this. Setting the limit to -1 will disable truncation completely.

Quiet Operation

To suppress informational warnings and just output the report:

brakeman -q

Debugging Information

To see all kinds of debugging information:

brakeman -d

Scanning Options

Specify Path to Application

Usually the path to the Rails app is the last argument. Optionally, the --path option can be used to specify a path.

brakeman --path your_rails_app -o report.html

Manually Turn on XSS Protection

If you are using the rails_xss gem or some other plugin, but Brakeman is not detecting it, the --escape-html option will use Erubis for rendering ERB files and turn on HTML escaping for ERB and HAML.

Manually Turn on Rails 3 Support

Brakeman should detect Rails 3 applications, but if not the -3 will switch Brakeman to Rails 3 mode.

Specifying Which Checks to Run

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

Report Routes

To see what actions brakeman has detected as being routes, use the --routes option.

Warning Options

Ignore Safe Methods

To indicate certain methods are “safe”:

brakeman -s benign_method,totally_safe

Assume Unknown Methods are Safe

By default, brakeman will assume that unknown methods involving untrusted data are dangerous. For example, this would raise a warning (in Rails 2.x):

<%= some_method(:option => params[:input]) %>

To only raise warnings only when untrusted data is being directly used:

brakeman -r

Ignore Model Output

By default, brakeman will report unescaped model attributes as dangerous. To disregard these warnings, use --ignore-model-output.

Set Minimum Confidence Level

To only report warnings at or above a certain confidence level, use the -w option.

1. Weak confidence
2. Medium confidence
3. High confidence

For example, to only show high confidence warnings:

brakeman -w3

Confidence Levels<ref>http://brakemanscanner.org/docs/confidence/</ref> Brakeman assigns each warning a confidence level. This rating is intended to indicate how certain Brakeman is that the given warning is a real problem. The following guidelines are used:

• High - Either this is a simple warning 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.

However, Brakeman can easily guess wrong, so it is best to read through all warnings and assess their importance manually.

Warning Types<ref>http://brakemanscanner.org/docs/warning_types/</ref>

Below are list of warning Brakeman can detect and report in an application. You can know more about a warning by clicking on that warning.

• Cross Site Scripting
• Cross Site Scripting (JSON)
• Cross Site Scripting (Content Tag)
• SQL Injection
• Command Injection
• Mass Assignment
• Attribute Restriction
• Cross-Site Request Forgery
• Unsafe Redirects
• Default Routes
• Format Validation
• Denial of Service
• Dynamic Render Paths
• Dangerous Evaluation
• Unsafe Deserialization
• File Access
• Basic Authentication
• Session Settings
• Information Disclosure
• Dangerous Send
• Mail Link
• Remote Code Execution
• Remote Execution in YAML.load
• SSL Verification Bypass

Reducing False Positives<ref>http://brakemanscanner.org/docs/reducing_false_positives/</ref>

Brakeman tries to report maximum number of warning. As of now there is no method for Brakeman to know certain items are actually safe or not. Hence false positives can become overwhelming. For this reason Brakeman provides options for customizing reports and reduce false positives.

Specify Checks to Run

One can specify Brakeman to run a specific set of checks/tests using --test. For example, to only check for SQL injection and cross-site scripting:

brakeman --test CheckSQL,CheckCrossSiteScripting

One can also specify Brakeman to exclude certain checks/test using --except. To exclude checks for dynamic render paths:

brakeman --except CheckRender

(‘Check’ can actually be omitted from the names.) Both --test and --except options take a comma-separated list of check names, which are case-sensitive. To get list of checks supported by Brakeman one can use below command.

brakeman --checks

Set Confidence Threshold

Brakeman allows to set the confidence levels of warnings one would like to see in the report by using -w For example if you want Brakeman to report high and medium confidence warnings only use below command.

brakeman –w2

Mark Methods as Safe

If you want Brakeman to ignore some methods, this can be achieved by using --safe-methods option. This option can take methods as a comma-separated list. For example:

brakeman --safe-methods this_one,that_one,totally_safe,my_sanitizer

Only Reporting Direct Vulnerabilities

With the default settings, Brakeman will report cross-site scripting vulnerabilities if the return value of a method where user input is a parameter is output. For example, this will raise a warning unless some_method is marked as safe like above:

<%= some_method(params[:blah]) %>

To ignore this kind of output, use the --report-direct option. This also applies to some other situations, such as checking calls to redirect_to.

Ignoring Model Attributes

Brakeman assumes database values are suspect (and so should you). But for some applications this does not make sense. Use the --ignore-model-output option to suppress reporting model attributes as cross-site scripting vulnerabilities.

Using Brakeman as a Library

Brakeman was initially designed to be used as a command-line application. Version 1.0 introduced changes that allowed Brakeman to be used as a library and future releases will make it even easier to use.

require 'brakeman'
tracker = Brakeman.run "my/app"
puts tracker.report

This code runs Brakeman against the Rails application in ‘my/app’ and prints out the report.<ref name=brakeman>Brakeman Scanner Introduction</ref> This is the same as running Brakeman with no options. Brakeman.run returns a Tracker object which contains all the information from the scan. Tracker#checks holds the results from running the checks. Brakeman can be run with a host of command-line options:

Brakeman.run :app_path => "my/app"

• app_path - path to root of Rails app (required)
• assume_all_routes - assume all methods are routes (default: false)
• check_arguments - check arguments of methods (default: true)
• collapse_mass_assignment - report unprotected models in single warning (default: true)
• combine_locations - combine warning locations (default: true)
• config_file - configuration file
• escape_html - escape HTML by default (automatic)
• exit_on_warn - return false if warnings found, true otherwise. Not recommended for library use (default: false)
• html_style - path to CSS file
• ignore_model_output - consider models safe (default: false)
• message_limit - limit length of messages
• min_confidence - minimum confidence (0-2, 0 is highest)
• output_file - file for output
• output_format - format for output (:to_s, :to_tabs, :to_csv, :to_html)
• parallel_checks - run checks in parallel (default: true)
• print_report - if no output file specified, print to stdout (default: false)
• quiet - suppress most messages (default: true)
• rails3 - force Rails 3 mode (automatic)
• report_routes - show found routes on controllers (default: false)
• run_checks - array of checks to run (run all if not specified)
• safe_methods - array of methods to consider safe
• skip_libs - do not process lib/ directory (default: false)
• skip_checks - checks not to run (run all if not specified)

Advantages

1. No Configuration Necessary -

Once Brakeman has been installed, no configuration is required. It can directly be run.

2. Run It Anytime -

Brakeman can run at any stage of development because all it needs is source code. A new application can be generated instantly and can be run against Brakeman.

3. Better Coverage -

Brakeman provides security before they can become exploitable because it can scan pages that are not ‘live’ yet.

4. Best Practices -

Brakeman is built specifically for Rails applications, so it can check configuration settings for best practices.

5. Flexible Testing -

Each Brakeman check is independent of the other and hence testing can be limited to a small subset of checks.

6. Speed -

Much faster than “black box” website scanner. Large applications can be scanned in a matter of minutes.

Disadvantages

1. False Positives -

Brakeman is extremely suspicious by default. Some values that are safe may be marked suspicious by Brakeman.

2. Unusual Configurations -

Brakeman assumes all applications follow the typical Rails setup. If not, it may miss scanning certain files.

3. Only Knows Code -

Brakeman cannot scan the entire application stack,, but only the software code.

4. Isn’t Omniscient -

Brakeman may miss certain things or misunderstand them.

References

<references></references>