This page may or may not be entirely up-to-date. For best results but less information, run
Please note some options below are shown as the short (
-) or long (
--) forms, but all options have long forms.
There are some checks which are not run by default. To run all checks, use:
Each check will be run in a separate thread by default. To disable this behavior:
By default, Brakeman scans the current directory. A path can also be specified as a bare argument, like:
But to be even more specific, the
--path option may be used:
brakeman -p path/to/app
To suppress informational warnings and just output the report:
Note all Brakeman output except reports are sent to stderr, making it simple to redirect stdout to a file and just get the report.
Brakeman returns 0 as an exit code unless something went very wrong. To return an error code when warnings were found:
To force Brakeman into Rails 3 mode:
Or to force Brakeman into Rails 4 mode:
Beware some behavior and checks rely on knowing the exact version name. This shouldn’t be a problem with any modern Rails app using a
Brakeman used to parse
routes.rb and attempt to infer which controller methods are used as actions. However, this is not perfect (especially for Rails 3/4), so now it assumes all controller methods are actions. To disable this behavior:
While this shouldn’t be necessary, it is possible to force Brakeman to assume output is escaped by default:
If Brakeman is running a bit slow, try
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.
To disable flow sensitivity in
To instead limit the number of branches tracked for a given value:
brakeman --branch-limit LIMIT
LIMIT should be an integer value.
0 is almost the same as
--no-branching is preferred. The default value is
5. Lower values generally make Brakeman go faster.
-1 is the same as unlimited.
To skip certain files use:
brakeman --skip-files file1,file2,etc
Note Brakeman does “whole program” analysis, therefore skipping a file may affect warning results from more than just that one file.
The inverse but even more dangerous option is to specific which files to scan:
brakeman --only-files some_file,some_dir
Again, since Brakeman looks at the whole program, it is very likely not going to behave as expected when scanning a subset of files. Also, if certain files are excluded Brakeman may not function at all.
To skip processing of the
To run a subset of checks:
brakeman --test Check1,Check2,etc
To exclude certain checks:
brakeman --except Check1,Check2,etc
Note it is not necessary to include the
Check part of the check. For example, these are equivalent:
brakeman --test CheckSQL brakeman --test SQL
To see all kinds of debugging information:
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:
Multiple output files can be specified:
brakeman -o output.html -o output.json
To specify a CSS stylesheet to use with the HTML report:
brakeman --css-file my_cool_styling
By default, Brakeman will only report a single warning of a given type for the same line of code. This can be disabled using
To disable highlighting of “dangerous” or “user input” values in warnings:
To report controller and route information:
However, if you really want to know what routes an app has, use
To set the limit on message length in HTML reports, use
brakeman --message-limit LIMIT
The default LIMIT is 100.
To limit width of the tables output in text reports, use
brakeman --table-width LIMIT
If no option is provided, Brakeman will attempt to guess the width of the terminal, otherwise it will limit the table width to 80 characters.
Brakeman will bundle all warnings about models without
attr_accessible into one warning. This was problem a mistake. It’s more useful to get one warning per model with
Sometimes you don’t need a big report, just the summary:
Reports show relative paths by default. To use absolute paths instead:
This does not affect HTML or tab-separated reports.
To output Markdown with nice links to files on Github, use
brakeman --github-repo USER/REPO[/PATH][@REF]
brakeman --github-repo presidentbeef/inject-some-sql
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
To specify a file to use:
brakeman -i path/to/config.ignore
To create and manage this file, use:
To ignore possible XSS from model attributes:
Brakeman will raise warnings on models that use
attr_protected. To suppress these warnings:
Brakeman will assume that unknown methods involving untrusted data are dangerous. For example, this would cause a warning (Rails 2):
<%= some_method(:option => params[:input]) %>
To only raise warnings only when untrusted data is being directly used:
This option is not supported very consistently, though.
To indicate certain methods return properly escaped output and should not be warned about in XSS checks:
brakeman --safe-methods benign_method_escapes_output,totally_safe_from_xss
Brakeman warns about use of user input in URLs generated with
link_to. Since Rails does not provide anyway of making these URLs really safe (e.g. limiting protocols to HTTP(S)), safe methods can be ignored with
brakeman --url-safe-methods ensure_safe_protocol_or_something
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:
-w switch takes a number from 1 to 3, with 1 being low (all warnings) and 3 being high (only highest confidence warnings).
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
-c option can be used to specify a configuration file to use.
To list available checks with short descriptions:
To show checks which are optional (not run by default):
To generate a Rake task to run Brakeman:
Note this is not recommended, since Rake will load your entire Rails app, which is not necessary for Brakeman and may cause library conflicts.
To see Brakeman’s version:
To see the real list of options: