brakeman-min 0.5.2 → 2.1.0

data/README.md

@@ -1,8 +1,27 @@
+![Brakeman Logo](http://brakemanscanner.org/images/logo_medium.png)
+
+[![Travis CI
+Status](https://secure.travis-ci.org/presidentbeef/brakeman.png)](https://travis-ci.org/presidentbeef/brakeman)
+[![Code
+Climate](https://codeclimate.com/github/presidentbeef/brakeman.png)](https://codeclimate.com/github/presidentbeef/brakeman)
+
 # Brakeman
 
 Brakeman is a static analysis tool which checks Ruby on Rails applications for security vulnerabilities.
 
-It targets Rails versions > 2.0 with experimental support for Rails 3.x
+It works with Rails 2.x, 3.x, and 4.x.
+
+There is also a [plugin available](http://brakemanscanner.org/docs/jenkins/) for Jenkins/Hudson.
+
+For even more continuous testing, try the [Guard plugin](https://github.com/oreoshake/guard-brakeman).
+
+# Homepage/News
+
+Website: http://brakemanscanner.org/
+
+Twitter: http://twitter.com/brakeman
+
+Mailing list: brakeman@librelist.com
 
 # Installation
 
@@ -10,6 +29,12 @@ Using RubyGems:
 
     gem install brakeman
 
+Using Bundler, add to development group in Gemfile:
+
+    group :development do
+      gem 'brakeman', :require => false
+    end
+
 From source:
 
     gem build brakeman.gemspec
@@ -19,7 +44,7 @@ From source:
 
     brakeman [app_path]
 
-It is simplest to run brakeman from the root directory of the Rails application. A path may also be supplied.
+It is simplest to run Brakeman from the root directory of the Rails application. A path may also be supplied.
 
 # Options
 
@@ -27,7 +52,11 @@ 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`, `csv`, and `tabs`.
+The output format is determined by the file extension or by using the `-f` option. Current options are: `text`, `html`, `tabs`, `json` and `csv`.
+
+Multiple output files can be specified:
+
+    brakeman -o output.html -o output.json
 
 To suppress informational warnings and just output the report:
 
@@ -61,9 +90,48 @@ To only raise warnings only when untrusted data is being directly used:
 
     brakeman -r
 
+By default, each check will be run in a separate thread. To disable this behavior:
+
+    brakeman -n
+
+Normally Brakeman will parse `routes.rb` and attempt to infer which controller methods are used as actions. However, this is not perfect (especially for Rails 3). To ignore the automatically inferred routes and assume all methods are actions:
+
+    brakeman -a
+
+Note that this will be enabled automatically if Brakeman runs into an error while parsing the routes.
+
+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 that Brakeman may have trouble parsing, use:
+
+    brakeman --skip-files file1,file2,etc
+
+Brakeman will raise warnings on models that use `attr_protected`. To suppress these warnings:
+
+    brakeman --ignore-protected
+
+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
+
 # Warning information
 
-See WARNING_TYPES for more information on the warnings reported by this tool.
+See WARNING\_TYPES for more information on the warnings reported by this tool.
 
 # Warning context
 
@@ -91,30 +159,8 @@ Brakeman options can stored and read from YAML files. To simplify the process of
 
 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 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.
 
-# 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.
+# License see MIT-LICENSE

data/bin/brakeman

@@ -1,294 +1,88 @@
 #!/usr/bin/env ruby
-require "optparse"
-require 'set'
-require 'yaml'
-
+#Adjust path in case called directly and not through gem
 $:.unshift "#{File.expand_path(File.dirname(__FILE__))}/../lib"
 
-require 'version'
+require 'brakeman'
+require 'brakeman/options'
+require 'brakeman/version'
 
-trap("INT") do
-  $stderr.puts "\nInterrupted - exiting."
-  exit!
+#Parse options
+begin
+  options, parser = Brakeman::Options.parse! ARGV
+rescue OptionParser::ParseError => e
+  $stderr.puts e.message.capitalize
+  $stderr.puts "Please see `brakeman --help` for valid options"
+  exit -1
 end
 
-def list_checks
-  require 'scanner'
-  $stderr.puts "Available Checks:"
-  $stderr.puts "-" * 30
-  $stderr.puts Checks.checks.map { |c| c.to_s }.sort.join "\n"
+#Exit early for these options
+if options[:list_checks]
+  Brakeman.list_checks
+  exit
+elsif options[:create_config]
+  Brakeman.dump_config options
+  exit
+elsif options[:show_help]
+  puts parser
+  exit
+elsif options[:show_version]
+  puts "brakeman #{Brakeman::Version}"
+  exit
+elsif options[:install_rake_task]
+  Brakeman.install_rake_task
   exit
 end
 
-#Parse command line options
-options = {}
-
-OptionParser.new do |opts|
-  opts.banner = "Usage: brakeman [options] rails/root/path"
-
-  opts.on "-p", "--path PATH", "Specify path to Rails application" do |path|
-    options[:app_path] = File.expand_path path
-  end
-
-  opts.on "-q", "--quiet", "Suppress informational messages" do
-    options[:quiet] = true
-    $VERBOSE = nil
-  end
-
-  opts.separator ""
-  opts.separator "Scanning options:"
-
-  opts.on "--ignore-model-output", "Consider model attributes XSS-safe" do
-    options[:ignore_model_output] = true
+#Set application path according to the commandline arguments
+unless options[:app_path]
+  if ARGV[-1].nil?
+    options[:app_path] = File.expand_path "."
+  else
+    options[:app_path] = File.expand_path ARGV[-1]
   end
+end
 
-  opts.on "-e", "--escape-html", "Escape HTML by default" do
-    options[:escape_html] = true
-  end
+trap("INT") do
+  $stderr.puts "\nInterrupted - exiting."
 
-  opts.on "-r", "--report-direct", "Only report direct use of untrusted data" do |option|
-    options[:check_arguments] = !option
+  if options[:debug]
+    $stderr.puts caller
   end
 
-  opts.on "-s", "--safe-methods meth1,meth2,etc", Array, "Consider the specified methods safe" do |methods|
-    options[:safe_methods] ||= Set.new
-    options[:safe_methods].merge methods.map {|e| e.to_sym }
-  end
+  exit!
+end
 
-  opts.on "-t", "--test Check1,Check2,etc", Array, "Only run the specified checks" do |checks|
-    checks.each_with_index do |s, index|
-      if s[0,5] != "Check"
-        checks[index] = "Check" << s
-      end
-    end
+if options[:quiet].nil?
+  options[:quiet] = :command_line
+end
 
-    options[:run_checks] ||= Set.new
-    options[:run_checks].merge checks
-  end
+begin
+  if options[:previous_results_json]
+    vulns = Brakeman.compare options.merge(:quiet => options[:quiet])
 
-  opts.on "-x", "--except Check1,Check2,etc", Array, "Skip the specified checks" do |skip|
-    skip.each do |s|
-      if s[0,5] != "Check"
-        s = "Check" << s
+    if options[:comparison_output_file]
+      File.open options[:comparison_output_file], "w" do |f|
+        f.puts MultiJson.dump(vulns, :pretty => true)
       end
 
-      options[:skip_checks] ||= Set.new
-      options[:skip_checks] << s
-    end
-  end
-
-  opts.separator ""
-  opts.separator "Output options:"
-
-  opts.on "-d", "--debug", "Lots of output" do
-    options[:debug] = true 
-  end
-
-  opts.on "-f", 
-    "--format TYPE", 
-    [:pdf, :text, :html, :csv, :tabs], 
-    "Specify output format. Default is tabs" do |type|
-    
-    type = "s" if type == :text
-    options[:output_format] = ("to_" << type.to_s).to_sym
-  end
-
-  opts.on "-l", "--[no]-combine-locations", "Combine warning locations (Default)" do |combine|
-    options[:combine_locations] = combine
-  end
-
-  opts.on "-m", "--routes", "Report controller information" do
-    options[:report_routes] = true
-  end
-
-  opts.on "--message-limit LENGTH", "Limit message length in HTML report" do |limit|
-    options[:message_limit] = limit.to_i
-  end
-
-  opts.on "-o", "--output FILE", "Specify file for output. Defaults to stdout" do |file|
-    options[:output_file] = file
-  end
-
-  opts.on "-w", 
-    "--confidence-level LEVEL", 
-    ["1", "2", "3"], 
-    "Set minimal confidence level (1 - 3). Default: 1" do |level|
-
-    options[:min_confidence] =  3 - level.to_i
-  end
-
-  opts.separator ""
-  opts.separator "Configuration files:"
-
-  opts.on "-c", "--config-file FILE", "Use specified configuration file" do |file|
-    options[:config_file] = File.expand_path(file)
-  end
-
-  opts.on "-C", "--create-config [FILE]", "Output configuration file based on options" do |file|
-    if file
-      options[:create_config] = file
+      Brakeman.notify "Comparison saved in '#{options[:comparison_output_file]}'"
     else
-      options[:create_config] = true
+      puts MultiJson.dump(vulns, :pretty => true)
     end
-  end
-
-  opts.separator ""
-
-  opts.on "-k", "--checks", "List all available vulnerability checks" do
-    options[:list_checks] = true
-  end
-
-  opts.on_tail "-h", "--help", "Display this message" do
-    puts opts
-    exit
-  end
-end.parse!(ARGV)
 
-#Load configuation file
-[File.expand_path(options[:config_file].to_s),
-  File.expand_path("./config.yaml"),
-  File.expand_path("~/.brakeman/config.yaml"),
-  File.expand_path("/etc/brakeman/config.yaml"),
-  "#{File.expand_path(File.dirname(__FILE__))}/../lib/config.yaml"].each do |f|
-
-  if File.exist? f and not File.directory? f
-    warn "[Notice] Using configuration in #{f}" unless options[:quiet]
-    OPTIONS = YAML.load_file f
-    OPTIONS.merge! options
-    OPTIONS.each do |k,v|
-      if v.is_a? Array
-        OPTIONS[k] = Set.new v
-      end
+    if options[:exit_on_warn] and (vulns[:new].count + vulns[:fixed].count > 0)
+      exit Brakeman::Warnings_Found_Exit_Code
     end
-    break
-  end
-end
-  
-OPTIONS = options unless defined? OPTIONS
-
-#List available checks and exits
-list_checks if OPTIONS[:list_checks]
-
-#Set defaults just in case
-{ :skip_checks => Set.new, 
-  :check_arguments => true, 
-  :safe_methods => Set.new,
-  :min_confidence => 2,
-  :combine_locations => true,
-  :collapse_mass_assignment => true,
-  :ignore_redirect_to_model => true,
-  :ignore_model_output => false,
-  :message_limit => 100,
-  :html_style => "#{File.expand_path(File.dirname(__FILE__))}/../lib/format/style.css" 
-}.each do |k,v|
-  OPTIONS[k] = v if OPTIONS[k].nil?
-end
-
-
-#Set output format
-if OPTIONS[:output_format]
-  case OPTIONS[:output_format]
-  when :html, :to_html
-    OPTIONS[:output_format] = :to_html
-  when :csv, :to_csv
-    OPTIONS[:output_format] = :to_csv
-  when :pdf, :to_pdf
-    OPTIONS[:output_format] = :to_pdf
-  when :tabs, :to_tabs
-    OPTIONS[:output_format] = :to_tabs
-  when OPTIONS[:output_format] = :to_s
-    OPTIONS[:output_format] = :to_s
-  else
-    OPTIONS[:output_format] = :to_tabs
-  end
-else
-  case OPTIONS[:output_file]
-  when /\.html$/i
-    OPTIONS[:output_format] = :to_html
-  when /\.csv$/i
-    OPTIONS[:output_format] = :to_csv
-  when /\.pdf$/i
-    OPTIONS[:output_format] = :to_pdf
-  when /\.tabs$/i
-    OPTIONS[:output_format] = :to_tabs
-  when /\.text$/i
-    OPTIONS[:output_format] = :to_s
-  else
-    OPTIONS[:output_format] = :to_tabs
-  end
-end
-
-#Output configuration if requested
-if OPTIONS[:create_config]
-
-  if OPTIONS[:create_config].is_a? String
-    file = OPTIONS[:create_config]
   else
-    file = nil
-  end
-
-  OPTIONS.delete :create_config
+    #Run scan and output a report
+    tracker = Brakeman.run options.merge(:print_report => true, :quiet => options[:quiet])
 
-  OPTIONS.each do |k,v|
-    if v.is_a? Set
-      OPTIONS[k] = v.to_a
+    #Return error code if --exit-on-warn is used and warnings were found
+    if options[:exit_on_warn] and not tracker.warnings.empty?
+      exit Brakeman::Warnings_Found_Exit_Code
     end
   end
-
-  if file
-    File.open file, "w" do |f|
-      YAML.dump OPTIONS, f
-    end
-    puts "Output configuration to #{file}"
-  else
-    puts YAML.dump(OPTIONS)
-  end
-  exit
-end
-
-
-#Check application path
-unless OPTIONS[:app_path]
-  if ARGV[-1].nil?
-    OPTIONS[:app_path] = File.expand_path "."
-  else
-    OPTIONS[:app_path] = File.expand_path ARGV[-1]
-  end
-end
-
-app_path = OPTIONS[:app_path]
-
-abort("Please supply the path to a Rails application.") unless app_path and File.exist? app_path + "/app"
-
-warn "[Notice] Using Ruby #{RUBY_VERSION}. Please make sure this matches the one used to run your Rails application."
-
-if File.exist? app_path + "/script/rails"
-  OPTIONS[:rails3] = true
-  warn "[Notice] Detected Rails 3 application. Enabling experimental Rails 3 support." 
-end
-
-#Load scanner
-begin
-  require 'scanner'
-rescue LoadError
-  abort "Cannot find lib/ directory."
-end
-
-#Start scanning
-scanner = Scanner.new app_path
-
-warn "Processing application in #{app_path}"
-tracker = scanner.process
-
-warn "Running checks..."
-tracker.run_checks
-
-warn "Generating report..."
-if OPTIONS[:output_file]
-  File.open OPTIONS[:output_file], "w" do |f|
-    f.puts tracker.report.send(OPTIONS[:output_format])
-  end
-  warn "Report saved in '#{OPTIONS[:output_file]}'"
-else
-  puts tracker.report.send(OPTIONS[:output_format])
+rescue Brakeman::NoApplication => e
+  $stderr.puts e.message
+  exit 1
 end