Skip to content

Brakeman Commandline Options

Scott Bartell edited this page Feb 20, 2020 · 4 revisions

Comprehensive list of Brakeman options, with explanations.


-3, --rails3

Force Brakeman to assume the application uses Rails 3 (or Rails 4). This implies Rails 3 routing, use of Erubis to escape view output by default, and other Rails 3 (or 4) behavior.

This option is probably never needed.

-a, --assume-routes, --no-assume-routes

Brakeman only uses route information for two purposes: to determine if default routes are used, and to determine when to do an implicit render in an action (i.e., render was not called, but the method is a controller action).

Starting with version 1.9.0, Brakeman switched to assuming all controller methods are actions, since actually figuring out Rails routes is hard. This behavior can be turned off with --no-assume-routes, in which case it will only do implicit renders for methods it is sure are actions.

--absolute-paths

This option really only applies to JSON output. Starting with version 2.0.0, Brakeman uses relative paths for warning file names in JSON reports. This option reverts back to reporting absolute paths.

Note that HTML reports show relative paths and tab separated output always uses absolute paths to work with Jenkins, while CSV and text reports do not include paths for warnings.

-C FILE, --create-config FILE

Instead of running a scan, dump commandline configuration options in YAML format to the file specified. If not file name is provided, it will dump to standard output.

-c FILE, --config-file FILE

Load YAML format file containing Brakeman configuration settings, probably generated with -C.

Brakeman searches these files for configuration settings by default this option is not used:

  • ./config/brakeman.yml
  • ~/.brakeman/config.yml
  • /etc/brakeman/config.yml
--compare FILE

Instead of generating a normal report, this option produces a comparison with a previous report in the given file. The file must be a JSON report.

The output from this option is JSON containing a "new" and "fixed" array of warnings. The "new" array contains warnings not found in the previous report. The "fixed" array contains the warnings found in the old report, but not the current scan.

The report is written to standard output and the -f and -o options are ignored. This should change soon, though.

--css-file FILE

Specify a custom CSS stylesheet to use for HTML output to make reports spiffier! See the default stylesheet for an example.

-d, --debug

Enable debug mode, which dumps a lot more information during the scan and in the report.

In addition to output from debug calls in Brakeman, backtraces for exceptions are shown (and expanded in HTML reports), route/controller information is reported, and rendered versions of all templates are added to the report. This can be good for debugging issues related to views.

-e, --escape-html

Force Brakeman to escape view output by default, like Rails 3 does.

This option is probably never needed.

-f TYPE, --format TYPE

Specify output format. This will override the format type detected when using -o.

Valid types are:

  • html
  • json
  • csv
  • tabs
  • text

Example: brakeman -f json > my_cool_report.json

--faster

At the moment, this is the same as --no-branching --skip-libs. This makes Brakeman go faster, but it may miss some vulnerabilities it would otherwise detect.

-h, --help

Displays all these options, although not with as much detail.

--highlights, --no-highlights

Turn highlighting of "troublesome" code in HTML reports on or off. On by default.

--ignore-model-output

By default, anything from the database is considered dangerous. In particular, Brakeman will warn when model values or attributes are used in dangerous situations, like being rendered without escaping.

This option is not always respected like it should be.

--ignore-protected

Don't warn about models which use attr_protected instead of attr_accessible.

But really you shouldn't use attr_protected: it's a bad idea with a not-so-great implementation.

--interprocedural

Enables deeper data flow analysis by allowing Brakeman to inspect called methods and attempt to determine the return value of the call. Normally Brakeman only does local analysis (inside a single method). This sometimes leads to people exclaiming "but can't it see what I'm doing right there!"

This option currently only affects controller methods.

This option is experimental and may cause strange things to happen.

-k, --checks

List available checks with a short description for each one.

-l, --combine-locations

Only generate a given warning type once for a given code location. Sometimes a code (views in particular) can generate more than a single warning because different values are used.

This option is probably never needed and likely should be removed.

-m, --routes

Show detected controller information and which methods are considered actions.

--message-limit LIMIT

Limits length of truncated warning messages in HTML reports.

This option is probably never needed and likely should be removed.

-n, --no-threads

By default, Brakeman runs each check in a separate thread. Due to performance improvements, there is hardly any difference between using threads and not. For debugging purposes, it is sometimes helpful to not use threads.

--no-branching

Brakeman is "sort of" flow sensitive by default. This means if a variable is assigned different values in different branches of a control flow statement, Brakeman will track each value. Sometimes, however, this can cause significant performance issues. This option will make Brakeman "flow insensitive" in that it will treat branches as if they were sequential code.

-o FILE, --output FILE

Use this option to specify an output file. If the file name has an extension Brakeman recognizes, it will automatically set the output format type.

Recognized extensions are:

  • .html
  • .json
  • .csv
  • .tabs
  • .text

Example: brakeman -o report.html

--only-files FILES

Use this option to specify the files or paths Brakeman should scan. This is the counterpart to --skip-files. However, since Brakeman is very dependent on having a "typical" Rails structure available, it is very easy to mess up a scan with this option, so use carefully.

Multiple files/paths can be specified, separated by commas.

-p PATH, --path PATH

Use this option to explicitly specify the path to the Rails application. It is not strictly necessary, however, as Brakeman will use any leftover argument as the path.

Example: brakeman -p /right/here is the same as brakeman /right/here.

--progress, --no-progress

Use this option to turn off the "x/y things processed" output. This is useful if dumping all output to a file.

-q, --quiet, --no-quiet

Generate no output except the report.

-r, --report-direct

Use this option to only report on direct, obvious uses of dangerous values. Otherwise, Brakeman warns about things like using the result of a method call with a dangerous value as an argument.

This option is not always respected like it should be.

-s METHODS, --safe-methods METHODS

Mark the given methods as XSS safe.

This option was originally intended to ignore methods that take potentially dangerous values as arguments but return something safe. However, the name is a little vague, so this may be made more useful in the future.

--separate-models

Instead of listing all models not using attr_protected in one big long warning, issue a warning for each model separately. This is good when using an external tool to track warnings, since fixing a model fixes a warning.

--skip-files FILES

List files to skip during the scan. Useful if a small number of files are causing problems of some kind.

--skip-libs

Skips scanning the lib/ directory entirely. At the moment, not much is done with files in lib/, and it tends to have a lot of big, complicated files, so skipping it can save a lot of time.

--summary

Only generate a summary of the report instead of the whole thing. Good for quickly comparing reports.

-t CHECKS, --test CHECKS

Run only the specified check(s) and no others. Check names must be proper "UpperCamelCase", but the "Check" prefix may be omitted. Multiple checks should be separated by a comma.

Invalid check names are silently ignored.

--url-safe-methods METHODS

List methods which are safe for use in link_to URLs. This methods should ideally check for things like javascript: at the beginning of a URL.

-v, --version

Displays Brakeman version and exits. Does not run Brakeman or even load anything.

-w LEVEL, --confidence-level LEVEL

Limit warnings to those at the given confidence level:

  1. Weak, medium, and high confidence warnings...so basically all of them
  2. Medium and high confidence warnings only
  3. High confidence warnings only
-x CHECKS, --except CHECKS

Do not run the listed checks, but run all the others. Check names must be proper "UpperCamelCase", but the "Check" prefix may be omitted. Multiple checks should be separated by a comma. Invalid check names are silently ignored.

-z, --exit-on-warn

If any warnings are found, exit with a non-zero (i.e. "error") code. AKA "hardcore mode".