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.