Initial release

FEATURES

@@ -0,0 +1,16 @@
+Can detect:
+-Possibly unescaped model attributes or parameters in views (Cross Site Scripting)
+-Bad string interpolation in calls to Model.find, Model.last, Model.first, etc., as well as chained calls (SQL Injection)
+-String interpolation in find_by_sql (SQL Injection)
+-String interpolation or params in calls to system, exec, and syscall and `` (Command Injection)
+-Unrestricted mass assignments
+-Global restriction of mass assignment
+-Missing call to protect_from_forgery in ApplicationController (CSRF protection)
+-Default routes, per-controller and globally
+-Redirects based on params (probably too broad currently)
+-Validation regexes not using \A and \z
+-Calls to render with dynamic paths
+
+General capabilities:
+-Search for method calls based on target class and/or method name
+-Determine 'output' of templates using ERB, Erubis, or HAML. Can handle automatic escaping

LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010, YELLOWPAGES.COM, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,112 @@
+# Brakeman
+
+Brakeman is a static analysis tool which checks Ruby on Rails applications for security vulnerabilities.
+
+It targets Rails versions > 2.0 and < 3.0.
+
+# Installation
+
+    gem build brakeman.gemspec
+    gem install brakeman*.gem
+
+# Usage
+
+    brakeman path/to/rails/app/root
+
+# Options
+
+To specify an output file for the results:
+
+    brakeman -o output_file path/to/rails/app/root
+
+The output format is determined by the file extension or by using the `-f` option. Current options are: `text`, `html`, and `csv`.
+
+To suppress informational warnings and just output the report:
+
+    brakeman -q path/to/rails/app/root
+
+To see all kinds of debugging information:
+
+    brakeman -d path/to/rails/app/root
+
+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 path/to/rails/app/root
+
+Multiple checks should be separated by a comma:
+
+    brakeman -x DefaultRoutes,Redirect path/to/rails/app/root
+
+To do the opposite and only run a certain set of tests:
+
+    brakeman -t Find,ValidationRegex path/to/rails/app/root
+
+To indicate certain methods are "safe":
+
+    brakeman -s benign_method,totally_safe path/to/rails/app/root
+
+By default, brakeman will assume that unknown methods involving untrusted data are dangerous. For example, this would a warning:
+
+    <%= some_method(:option => params[:input]) %>
+
+To only raise warnings only when untrusted data is being directly used:
+
+    brakeman -r path/to/rails/app/root
+
+# Warning information
+
+See WARNING_TYPES for more information on the warnings reported by this tool.
+
+# Warning context
+
+The HTML output format provides an excerpt from the original application source where a warning was triggered. Due to the processing done while looking for vulnerabilities, the source may not resemble the reported warning and reported line numbers may be slightly off. However, the context still provides a quick look into the code which raised the warning.
+
+# Confidence levels
+
+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 /path/to/rails/app/root
+
+The `-w` switch takes a number from 1 to 3, with 1 being low (all warnings) and 3 being high (only high confidence warnings).
+
+# Configuration files
+
+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 commandline have priority over configuration files.
+
+The default config locations are `./config.yaml`, `~/.brakeman/`, and `/etc/brakeman/config.yaml`
+
+The `-c` option can be used to specify a configuration file to use.
+
+# License
+
+The MIT License
+
+Copyright (c) 2010, YELLOWPAGES.COM, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

WARNING_TYPES

@@ -0,0 +1,69 @@
+This file describes the various warning types reported by this tool.
+
+# Cross Site Scripting
+
+Cross site scripting warnings are raised when a parameter or model attribute is output through a view without being escaped.
+
+See http://guides.rubyonrails.org/security.html#cross-site-scripting-xss for details.
+
+# SQL Injection
+
+String interpolation or concatenation has been detected in an SQL query. Use parameterized queries instead.
+
+See http://guides.rubyonrails.org/security.html#sql-injection for details.
+
+# Command Injection
+
+Request parameters or string interpolation has been detected in a `system` call. This can lead to someone executing arbitrary commands. Use the safe form of `system` instead, which will pass in arguments safely.
+
+See http://guides.rubyonrails.org/security.html#command-line-injection for details.
+
+# Mass Assignment
+
+Mass assignment is a method for initializing models. If the attributes which are set is not restricted, someone may set the attributes to any value they wish.
+
+Mass assignment can be disabled globally.
+
+Please see http://railspikes.com/2008/9/22/is-your-rails-application-safe-from-mass-assignment for more details.
+
+# Attribute Restriction
+
+This warning comes up if a model does not limit what attributes can be set through mass assignment.
+
+In particular, this check looks for `attr_accessible` inside model definitions. If it is not found, this warning will be issued.
+
+Note that disabling mass assignment globally will suppress these warnings.
+
+# Cross-Site Request Forgery
+
+No call to `protect_from_forgery` was found in `ApplicationController`. This method prevents CSRF.
+
+See http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf for details.
+
+# Redirect
+
+Redirects which rely on user-supplied values can be used to "spoof" websites or hide malicious links in otherwise harmless-looking URLs. They can also allow access to restricted areas of a site if the destination is not validated.
+
+This warning is shown when request parameters are used inside a call to `redirect_to`.
+
+See http://www.owasp.org/index.php/Top_10_2010-A10 for more information.
+
+# Default Routes
+
+The general default routes warning means there is a call to `map.connect ":controller/:action/:id"` in config/routes.rb. This allows any public method on any controller to be called as an action.
+
+If this warning is reported for a particular controller, it means there is a route to that controller containing `:action`.
+
+Default routes can be dangerous if methods are made public which are not intended to be used as URLs or actions.
+
+# Format Validation
+
+Calls to `validates_format_of ..., :with => //` which do not use `\A` and `\z` as anchors will cause this warning. Using `^` and `$` is not sufficient, as `$` will only match up to a new line. This allows an attacker to put whatever malicious input they would like after a new line character.
+
+See http://guides.rubyonrails.org/security.html#regular-expressions for details.
+
+# Dynamic Render Path
+
+When a call to `render` uses a dynamically generated path, template name, file name, or action, there is the possibility that a user can access templates that should be restricted. The issue may be worse if those templates execute code or modify the database.
+
+This warning is shown whenever the path to be rendered is not a static string or symbol.