Upcoming Changes in Brakeman 3.1

Some changes in Brakeman 3.1.0 may affect users in breaking ways.

Dropping Ruby 1.8 Support

Brakeman will still parse and operate on Ruby 1.8 code just fine (thanks to ruby_parser), but will no longer officially support being run with Ruby 1.8.

Actually, Brakeman 3.1 will probably run just fine on Ruby 1.8, but dependency management is becoming too difficult. Latest versions of HighLine and Slim no longer support 1.8.

(changes)

Render Paths in JSON Reports

Currently, render paths are arrays of strings. The strings represent the locations of calls to render (implicit or explicit), either in the form <Controller>#<method> or Template:<template/path>. While the information was somewhat useful to humans, it was not easily manipulated by computers and it was difficult to link the strings back to application code.

In 3.1, render paths are arrays of hashes. The hash has a type key with a value of either controller or template.

For controllers, the hash includes class, method, line, and file.

For templates, the hash includes name, line, and file.

Example:

[
  {
    "type": "controller",
    "class": "ProductsController",
    "method": "create",
    "line": 50,
    "file": "app/controllers/products_controller.rb"
  },
  {
    "type": "template",
    "name": "products/new",
    "line": 2,
    "file": "app/views/products/new.html.erb"
  }
]

Implicit renders from controller actions point to the line at the end of the method.

(changes)

Template Names in JSON Reports

Rendered templates in JSON reports include the render location as well.

For example:

"location": {
  "type": "template",
  "template": "home/index (HomeController#index)"
}

Since this information is redundant with the render path, it will be removed.

S-Expression Names

Brakeman rewrites several S-Expression names for no reason other than clarity (for example, dstr becomes string_interp). However, not all nodes get changed, leading to code that must check for both the original name from ruby_parser and Brakeman's name. This leads to messy code and subtle bugs.

The following node names are removed: string_interp, string_eval, methdef, selfdef, call_with_block.

Unfortunately, this will change any fingerprints containing these node types. A quick script is available to migrate ignore files without having to manually update the fingerprints.

(changes)

Tracker Classes

Internally, most of the information Brakeman tracks is kept in hash tables. This is changing, starting with the addition of Controller, Model, Template, and Config classes.

Unfortunately, this is probably going to break any code that relies on Brakeman's internals (such as custom checks).

Fortunately, in almost all cases it will simplify code and in many cases it just means changing a hash access (like template[:name]) to a method call (template.name).

See the pull request for examples.

Also note this is just the beginning of these internal changes...sorry! Hopefully this leads to improvements and makes it easier to write Brakeman code.