Brakeman — Static Security Scanner for Ruby on Rails

Introduction

Brakeman is an open-source static analysis security scanner specifically designed for Ruby on Rails applications. It examines your source code without running the application, detecting common vulnerabilities early in the development cycle before they reach production.

What Brakeman Does

• Scans Rails application code for over 20 categories of security vulnerabilities
• Detects SQL injection, cross-site scripting (XSS), and command injection patterns
• Identifies insecure direct object references and mass assignment risks
• Checks for unsafe redirects, file access issues, and session handling flaws
• Produces reports in HTML, JSON, CSV, Markdown, and other formats for CI integration

Architecture Overview

Brakeman parses Ruby and ERB source files into an abstract syntax tree using the ruby_parser gem. It then builds a model of the Rails application including controllers, models, routes, and views. Multiple security checks run against this model using data flow analysis to trace user input from params through the application to potentially dangerous sinks like database queries or rendered output.

Self-Hosting & Configuration

• Install as a gem (gem install brakeman) or add to your Gemfile under development/test
• Run from the Rails application root directory; Brakeman auto-detects the app structure
• Create a config/brakeman.yml to set default options, skip files, or ignore specific warnings
• Use --confidence-level to filter results by high, medium, or weak confidence
• Integrate into CI pipelines with brakeman --no-pager --exit-on-warn for non-zero exit on findings

Key Features

• Zero-configuration scanning that understands Rails conventions out of the box
• Incremental scanning mode for faster re-checks on changed files only
• Interactive ignore file management with brakeman -I to triage false positives
• GitHub Actions, GitLab CI, and Jenkins integration with SARIF output support
• Fingerprinted warnings that remain stable across scans for tracking resolution

Comparison with Similar Tools

• Semgrep — Language-agnostic pattern matching; Brakeman has deeper Rails-specific understanding
• RuboCop — Style and code quality linter; Brakeman focuses exclusively on security
• Bundler Audit — Checks gem dependencies for known CVEs; Brakeman scans application code
• OWASP ZAP — Dynamic runtime scanner; Brakeman works statically without running the app
• CodeQL — Powerful multi-language analysis; Brakeman is simpler to set up for Rails projects

FAQ

Q: Does Brakeman work with non-Rails Ruby applications? A: No. Brakeman is specifically designed for Rails and relies on Rails conventions for its analysis.

Q: How do I handle false positives? A: Run brakeman -I to interactively review warnings and add them to config/brakeman.ignore with notes.

Q: Can I use Brakeman in a pre-commit hook? A: Yes. Use the --only-files flag with changed files for fast incremental checks before each commit.

Q: Does it support Rails 7 and newer? A: Yes. Brakeman actively tracks Rails releases and supports the latest versions including Rails 7 and 8.

Sources

• https://github.com/presidentbeef/brakeman
• https://brakemanscanner.org/