CSC/ECE 517 Fall 2014/ch1b 33 jy: Difference between revisions

From Expertiza_Wiki
Jump to navigation Jump to search
(Adding content to wiki)
Line 20: Line 20:
* v2.4 - Detect SQL Injection in ‘delete_all’/’destroy_all’
* v2.4 - Detect SQL Injection in ‘delete_all’/’destroy_all’
* v2.6 - Parse most files upfront instead of on demand
* 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.
<pre>gem install brakeman</pre>
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.
<pre>gem cert --add <(curl -Ls https://raw.github.com/presidentbeef/brakeman/master/brakeman-public_cert.pem)</pre>
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.
<pre>gem install brakeman -P MediumSecurity</pre>
===Bundle install===
Brakeman can be added to a Gemfile using below line
<pre>gem "brakeman", :require => false</pre>
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.
<pre>git clone git://github.com/presidentbeef/brakeman.git
cd brakeman
gem build brakeman.gemspec
gem install brakeman-*.gem</pre>
==Running Brakeman==
You can run Brakeman in 2 ways.
1. Running brakeman from your rails app directory
<pre>cd your_rails_app/
brakeman</pre>
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
<pre>brakeman your_rails_app</pre>
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:
<pre>brakeman -o output_file</pre>
====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:
<pre>brakeman -o report.html</pre>
===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:
<pre>brakeman -q</pre>
===Debugging Information===
To see all kinds of debugging information:
<pre>brakeman -d</pre>
===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.
<pre>brakeman --path your_rails_app -o report.html</pre>
====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):
<pre>brakeman -x DefaultRoutes</pre>
Multiple checks should be separated by a comma:
<pre>brakeman -x DefaultRoutes,Redirect</pre>
To do the opposite and only run a certain set of tests:
<pre>brakeman -t SQL,ValidationRegex</pre>
====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”:
<pre>brakeman -s benign_method,totally_safe</pre>
====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):
<pre><%= some_method(:option => params[:input]) %></pre>
To only raise warnings only when untrusted data is being directly used:
<pre>brakeman -r</pre>
====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.
#Weak confidence
#Medium confidence
#High confidence
For example, to only show high confidence warnings:
<pre>brakeman -w3</pre>
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.
*[http://brakemanscanner.org/docs/warning_types/cross_site_scripting Cross Site Scripting]
*[http://brakemanscanner.org/docs/warning_types/cross_site_scripting_to_json Cross Site Scripting (JSON)]
*[http://brakemanscanner.org/docs/warning_types/content_tag Cross Site Scripting (Content Tag)]
*[http://brakemanscanner.org/docs/warning_types/sql_injection SQL Injection]
*[http://brakemanscanner.org/docs/warning_types/command_injection Command Injection]
*[http://brakemanscanner.org/docs/warning_types/mass_assignment Mass Assignment]
*[http://brakemanscanner.org/docs/warning_types/attribute_restriction Attribute Restriction]
*[http://brakemanscanner.org/docs/warning_types/cross-site_request_forgery Cross-Site Request Forgery]
*[http://brakemanscanner.org/docs/warning_types/redirect Unsafe Redirects]
*[http://brakemanscanner.org/docs/warning_types/default_routes Default Routes]
*[http://brakemanscanner.org/docs/warning_types/format_validation Format Validation]
*[http://brakemanscanner.org/docs/warning_types/denial_of_service Denial of Service]
*[http://brakemanscanner.org/docs/warning_types/dynamic_render_paths Dynamic Render Paths]
*[http://brakemanscanner.org/docs/warning_types/dangerous_evaluation Dangerous Evaluation]
*[http://brakemanscanner.org/docs/warning_types/unsafe_deserialization Unsafe Deserialization]
*[http://brakemanscanner.org/docs/warning_types/file_access File Access]
*[http://brakemanscanner.org/docs/warning_types/basic_authentication Basic Authentication]
*[http://brakemanscanner.org/docs/warning_types/session_setting Session Settings]
*[http://brakemanscanner.org/docs/warning_types/information_disclosure Information Disclosure]
*[http://brakemanscanner.org/docs/warning_types/dangerous_send Dangerous Send]
*[http://brakemanscanner.org/docs/warning_types/CVE-2011-0446 Mail Link]
*[http://brakemanscanner.org/docs/warning_types/remote_code_execution Remote Code Execution]
*[http://brakemanscanner.org/docs/warning_types/remote_code_execution_yaml_load Remote Execution in YAML.load]
*[http://brakemanscanner.org/docs/warning_types/ssl_verification_bypass 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:
<pre>brakeman --test CheckSQL,CheckCrossSiteScripting</pre>
One can also specify Brakeman to exclude certain checks/test using --except.
To exclude checks for dynamic render paths:
<pre>brakeman --except CheckRender</pre>
(‘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.
<pre>brakeman --checks</pre>
===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.
<pre>brakeman –w2</pre>
===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:
<pre>brakeman --safe-methods this_one,that_one,totally_safe,my_sanitizer</pre>
===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:
<pre><%= some_method(params[:blah]) %></pre>
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==
==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.
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.
<code><br>
<pre>
require 'brakeman'<br>
require 'brakeman'
tracker = Brakeman.run "my/app"<br>
tracker = Brakeman.run "my/app"
puts tracker.report<br>
puts tracker.report
</code>
</pre>


This code runs Brakeman against the Rails application in ‘my/app’ and prints out the report.<ref name=brakeman>[http://brakemanscanner.org/docs/introduction/ 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.
This code runs Brakeman against the Rails application in ‘my/app’ and prints out the report.<ref name=brakeman>[http://brakemanscanner.org/docs/introduction/ 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 can be run with a host of command-line options:


<code><br>
<pre>
Brakeman.run :app_path => "my/app"<br>
Brakeman.run :app_path => "my/app"
</code>
</pre>


*app_path - path to root of Rails app (required)
*app_path - path to root of Rails app (required)

Revision as of 06:35, 6 October 2014

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.

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>