This file may or may not be up-to-date. For best results but less information, run `brakeman --help`.
## Scanning Options
Each check will be run in a separate thread by default. To disable this behavior:
brakeman -n
By default, Brakeman scans the current directory. A path can also be specified as a bare argument, like:
brakeman some/path/to/app
But to be even more specific, the `-p` or `--path` option may be used:
brakeman -p path/to/app
To suppress informational warnings and just output the report:
brakeman -q
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:
brakeman -z
To force Brakeman into Rails 3 mode:
brakeman -3
This is basically the same as Rails 4 mode, too. But beware some things rely on knowing the exact version name. This shouldn't be a problem with any modern Rails app using a `Gemfile.lock` though.
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:
brakeman --no-assume-routes
While this shouldn't be necessary, it is possible to force Brakeman to assume output is escaped by default:
brakeman --escape-html
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.
To disable flow sensitivity in `if` expressions:
brakeman --no-branching
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` but `--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 `lib/` directory:
brakeman --skip-libs
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
## Output Options
To see all kinds of debugging information:
brakeman -d
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`, `tabs`, `json`, `markdown` and `csv`.
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
brakeman --no-combine-locations
To disable highlighting of "dangerous" or "user input" values in warnings:
brakeman --no-highlights
To report controller and route information:
brakeman --routes
However, if you really want to know what routes an app has, use
rake routes
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
By default, there is no limit.
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
brakeman --separate-models
Sometimes you don't need a big report, just the summary:
brakeman --summary
Reports show relative paths by default. To use absolute paths instead:
brakeman --absolute-paths
This does not affect HTML or tab-separated reports.
To output Markdown with nice links to files on Github, use
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 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
The `-w` switch takes a number from 1 to 3, with 1 being low (all warnings) and 3 being high (only highest 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/brakeman.yml`, `~/.brakeman/config.yml`, and `/etc/brakeman/config.yml`
The `-c` option can be used to specify a configuration file to use.
## Miscellaneous
To list available checks with short descriptions:
brakeman --checks
To generate a Rake task to run Brakeman:
brakeman --rake
Note this is not recommended, since Rake will load your entire Rails app, which is not necessary for Brakeman and may cause library conflicts.
It is simplest to run Brakeman from the root directory of the Rails application. A path may also be supplied.
# Options
# Basic Options
For a full list of options, use `brakeman --help` or see the OPTIONS.md file.
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`, `tabs`, `json` and `csv`.
The output format is determined by the file extension or by using the `-f` option. Current options are: `text`, `html`, `tabs`, `json`, `markdown`, and `csv`.
Multiple output files can be specified:
...
...
@@ -62,6 +64,8 @@ To suppress informational warnings and just output the report:
brakeman -q
Note all Brakeman output except reports are sent to stderr, making it simple to redirect stdout to a file and just get the report.
To see all kinds of debugging information:
brakeman -d
...
...
@@ -78,28 +82,6 @@ To do the opposite and only run a certain set of tests:
brakeman -t SQL,ValidationRegex
To indicate certain methods are "safe":
brakeman -s benign_method,totally_safe
By default, 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:
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
...
...
@@ -114,10 +96,6 @@ 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:
