Brakeman Commandline Options
Comprehensive list of Brakeman options, with explanations.
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.
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.
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.
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.
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
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.
Specify a custom CSS stylesheet to use for HTML output to make reports spiffier! See the default stylesheet for an example.
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.
Force Brakeman to escape view output by default, like Rails 3 does.
This option is probably never needed.
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
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.
Displays all these options, although not with as much detail.
Turn highlighting of "troublesome" code in HTML reports on or off. On by default.
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.
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.
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.
List available checks with a short description for each one.
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.
Show detected controller information and which methods are considered actions.
Limits length of truncated warning messages in HTML reports.
This option is probably never needed and likely should be removed.
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.
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.
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
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.
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.
Use this option to turn off the "x/y things processed" output. This is useful if dumping all output to a file.
Generate no output except the report.
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.
Generate a Rake task to run Brakeman and put it in lib/tasks/brakeman.rake. This allows one to run Brakeman with Rake, if that's something you are into.
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.
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.
List files to skip during the scan. Useful if a small number of files are causing problems of some kind.
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.
Only generate a summary of the report instead of the whole thing. Good for quickly comparing reports.
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.
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.
Displays Brakeman version and exits. Does not run Brakeman or even load anything.
Limit warnings to those at the given confidence level:
- Weak, medium, and high confidence warnings...so basically all of them
- Medium and high confidence warnings only
- High confidence warnings only
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.
If any warnings are found, exit with a non-zero (i.e. "error") code. AKA "hardcore mode".