Brakeman Security Scanner

Overview

Brakeman is a static analysis tool that checks Ruby on Rails applications for security vulnerabilities without requiring a running application. It analyzes source code to detect common security issues including SQL injection, cross-site scripting (XSS), command injection, mass assignment, and many other vulnerability types.

Installation

Verify Brakeman is installed before running scans. If not present, install using one of these methods:

Using RubyGems (recommended)

gem install brakeman

Using Bundler (add to Gemfile)

group :development do gem 'brakeman', require: false end

Using Docker

docker pull presidentbeef/brakeman

Brakeman requires Ruby 3.0.0+ to run, but can analyze code written with Ruby 2.0+ syntax. It works with Rails 2.3.x through 8.x.

Basic Usage

Quick Scan

Run a basic security scan from the Rails application root:

brakeman

From outside the Rails root:

brakeman /path/to/rails/application

Output Formats

Generate reports in various formats:

HTML report

brakeman -o report.html

JSON report (useful for comparison and automation)

brakeman -o report.json

Multiple output formats simultaneously

brakeman -o report.html -o report.json

Output to console with color and file

brakeman --color -o /dev/stdout -o report.json

Quiet mode (suppress informational messages)

brakeman -q

Available output formats: text , html , tabs , json , junit , markdown , csv , codeclimate , sonar

Workflow Decision Tree

Is Brakeman already installed? ├─ No → Install using gem, bundler, or docker └─ Yes → Continue

What is the goal? ├─ Initial security assessment → Run basic scan: brakeman ├─ Generate report for review → Choose format: brakeman -o report.html ├─ CI/CD integration → Use JSON output: brakeman -o report.json ├─ Too many warnings → Adjust confidence level or filter checks ├─ False positives → Use interactive ignore tool: brakeman -I ├─ Compare with previous scan → Use --compare flag └─ Configuration needed → Create config/brakeman.yml

Confidence Levels

Brakeman assigns confidence levels to each warning:

• High: Simple warning or user input very likely being used unsafely

• Medium: Unsafe use of variable that may or may not be user input

• Weak: User input indirectly used in potentially unsafe manner

Filter warnings by confidence level:

Only high confidence warnings

brakeman -w3

High and medium confidence warnings

brakeman -w2

All warnings (default)

brakeman -w1

Managing Warnings

Filtering Checks

Run only specific checks:

Run only SQL and XSS checks

brakeman -t SQL,CrossSiteScripting

Skip specific checks

brakeman -x DefaultRoutes,Redirect

Skip multiple checks

brakeman -x DefaultRoutes,Redirect,SQL

Use brakeman --checks to list all available check names (case-sensitive).

Interactive Ignore Configuration

Manage false positives interactively:

brakeman -I

This launches an interactive tool that:

• Presents each warning with context

• Allows you to ignore, skip, or add notes

• Saves configuration to config/brakeman.ignore

Options during interactive review:

• i

• Add warning to ignore list

• n

• Add warning to ignore list with note (recommended)

• s

• Skip this warning

• u

• Remove from ignore list

• a

• Ignore remaining warnings

• k

• Skip remaining warnings

• q

• Quit without saving

Always add notes when ignoring warnings to document why they're false positives.

Show Ignored Warnings

Temporarily view ignored warnings without affecting exit code:

brakeman --show-ignored

Comparing Scans

Track security improvements or regressions by comparing scans:

Generate baseline report

brakeman -o baseline.json

Run new scan and compare

brakeman --compare baseline.json

Output shows:

• Fixed warnings (resolved since baseline)

• New warnings (introduced since baseline)

Configuration

Configuration Files

Store Brakeman options in YAML configuration files. Default locations (checked in order):

• ./config/brakeman.yml

• ~/.brakeman/config.yml

• /etc/brakeman/config.yml

Specify a custom configuration file:

brakeman -c custom_config.yml

Generate Configuration

Output current options to create a configuration file:

brakeman -C --skip-files plugins/ > config/brakeman.yml

Command-line options override configuration file settings.

Example Configuration

:skip_files:

• vendor/
• lib/legacy/ :confidence_level: 2 :output_files:
• reports/brakeman.html
• reports/brakeman.json :quiet: true

Performance Optimization

Speed up scans with faster mode (skips some features):

brakeman --faster

Equivalent to: --skip-libs --no-branching

Warning: May miss some vulnerabilities. Use only when scan speed is critical.

Skip problematic files or directories:

brakeman --skip-files file1.rb,vendor/,legacy/

Advanced Options

Safe Methods

Mark custom sanitizing methods as safe to reduce false positives:

brakeman --safe-methods sanitize_input,clean_html

Exit Codes

Control exit code behavior:

Don't exit with error on warnings

brakeman --no-exit-on-warn

Don't exit with error on scanning errors

brakeman --no-exit-on-error

Both

brakeman --no-exit-on-warn --no-exit-on-error

Default behavior: Non-zero exit code if warnings found or errors encountered.

Debugging

Enable verbose debugging output:

brakeman -d

CI/CD Integration

GitHub Actions

Several Brakeman actions available on GitHub Marketplace. Search for "brakeman" in GitHub Actions.

Jenkins

Brakeman plugin available for Jenkins/Hudson integration. See documentation at brakemanscanner.org/docs/jenkins/

Guard

For continuous testing during development:

gem install guard-brakeman

Generic CI Integration

#!/bin/bash

Example CI script

Run Brakeman and save results

brakeman -o brakeman-report.json -o brakeman-report.html --no-exit-on-warn

Check if there are any high confidence warnings

if brakeman -w3 --quiet; then echo "No high confidence security warnings found" exit 0 else echo "High confidence security warnings detected!" exit 1 fi

Warning Types Reference

Brakeman detects 30+ vulnerability types. For detailed descriptions and remediation guidance, see references/warning_types.md .

Common warning types include:

• SQL Injection

• Cross-Site Scripting (XSS)

• Command Injection

• Mass Assignment

• Cross-Site Request Forgery (CSRF)

• Remote Code Execution

• Path Traversal

• Unsafe Redirects

• File Access

• Authentication Issues

• SSL Verification Bypass

• Unmaintained Dependencies

• And many more...

Command Reference

For comprehensive option reference including less common flags and detailed explanations, see references/command_options.md .

Best Practices

• Run regularly: Integrate into development workflow and CI/CD pipeline

• Start with high confidence: Use -w3 initially to focus on critical issues

• Document ignored warnings: Always add notes explaining why warnings are ignored

• Compare scans: Use --compare to track security posture over time

• Review all warnings: Even weak warnings can indicate real vulnerabilities

• Keep Brakeman updated: Security checks improve with each release

• Don't ignore blindly: Investigate each warning before marking as false positive

• Use configuration files: Maintain consistent scan settings across team

• Generate multiple formats: HTML for review, JSON for automation

• Test ignored warnings periodically: Re-review with --show-ignored

Common Workflows

Initial Security Audit

1. Run comprehensive scan

brakeman -o initial-audit.html -o initial-audit.json

2. Review high confidence warnings first

brakeman -w3 -o high-confidence.html

3. Interactively manage false positives

brakeman -I

4. Save configuration for future scans

brakeman -C > config/brakeman.yml

CI/CD Security Gate

Fail build only on high confidence warnings

brakeman -w3 --no-exit-on-error

Tracking Improvements

Baseline scan

brakeman -o baseline.json

After fixes, compare

brakeman --compare baseline.json -o improvements.json

Reducing Noise

Focus on specific vulnerability types

brakeman -t SQL,CrossSiteScripting,CommandInjection -w2

Or exclude noisy checks

brakeman -x DefaultRoutes,Redirect -w2

Troubleshooting

Problem: Too many weak confidence warnings Solution: Use -w2 or -w3 to filter by confidence level

Problem: Scanning is very slow Solution: Use --faster flag or --skip-files to exclude large directories

Problem: False positives for custom sanitization Solution: Use --safe-methods to mark methods as safe

Problem: Warnings about database values Solution: Consider if database values truly safe; if yes, adjust with --interprocedural or configuration

Problem: Can't parse certain files Solution: Use --skip-files to exclude problematic files

Resources

references/warning_types.md

Comprehensive descriptions of all 30+ vulnerability types Brakeman can detect, including examples and remediation guidance.

references/command_options.md

Complete command-line reference with detailed explanations of all available options and flags.

references/reducing_false_positives.md

Strategies and techniques for minimizing false positives while maintaining security coverage.