Brakeman is a static analysis security scanner specifically designed for Ruby on Rails applications. Unlike generic SAST tools that treat Rails code as just another Ruby program, Brakeman understands Rails conventions: MVC patterns, routing, ActiveRecord queries, ERB templates, and the security mechanisms Rails provides. This framework awareness dramatically reduces false positives and catches Rails-specific vulnerability patterns.
What Makes Brakeman Different
Most static analysis tools operate on the abstract syntax tree of a programming language. They understand Ruby syntax but not Rails semantics. Brakeman understands both.
When Brakeman sees params[:name], it knows that value came from user input. When it sees that value passed to User.where("name = '#{params[:name]}'"), it knows that is SQL injection even though a generic Ruby analyzer might not trace the data flow through Rails' parameter handling.
When Brakeman sees <%= @user.name %>, it knows that ERB's <%= escapes HTML by default. But when it sees <%= raw @user.bio %> or <%== @user.bio %>, it knows the output is unescaped and flags a potential cross-site scripting vulnerability.
This framework awareness is Brakeman's core strength. It understands what is safe in Rails and what is not, which keeps the false positive rate manageable.
Detection Categories
SQL Injection. Brakeman detects SQL injection through string interpolation in ActiveRecord queries, raw SQL fragments, and unsafe use of order(), pluck(), group(), and other query methods that accept raw SQL.
Cross-Site Scripting (XSS). Brakeman tracks data flow from user input through controllers to views. It understands Rails' automatic escaping and flags cases where escaping is bypassed through raw, html_safe, sanitize with insufficient options, or rendering user content in JavaScript contexts.
Command Injection. Brakeman flags backtick execution, system(), exec(), IO.popen(), and other shell execution methods when they receive user-controlled input.
Mass Assignment. Although Rails 4+ requires strong parameters by default, Brakeman still catches cases where permit! is used (which allows all parameters) or where strong parameters are configured too broadly.
Dangerous Deserialization. Ruby's Marshal.load, YAML.load (before Ruby 3.1's safe default), and other deserialization methods are flagged when used on untrusted data. Ruby deserialization vulnerabilities have led to remote code execution in multiple high-profile incidents.
Cross-Site Request Forgery. Brakeman checks that CSRF protection is enabled and flags controllers that skip it.
File Access. Path traversal through user-controlled file paths in send_file, File.read, and similar operations.
Redirect. Open redirect vulnerabilities where user input controls the redirect destination.
Running Brakeman
Basic usage is straightforward:
brakeman -p /path/to/rails/app
For CI integration with machine-readable output:
brakeman -p . -f json -o brakeman-results.json --no-pager
Useful flags:
--confidence-level 2 shows only high-confidence findings, useful when first adopting Brakeman.
--except CheckSQL,CheckCrossSiteScripting excludes specific check types if they are too noisy for your codebase.
--only CheckSQL,CheckExecute runs only specific checks, useful for focused security reviews.
-A runs all checks including optional ones that are disabled by default.
Managing Results
Brakeman supports an ignore file (config/brakeman.ignore) for false positives:
brakeman -I config/brakeman.ignore
When you ignore a finding, Brakeman records the file, line, code snippet, and a note explaining why it was ignored. If the code changes, the ignore entry no longer matches and the finding reappears, which prevents stale suppressions from hiding new issues.
Review ignore files during security audits. Each entry should have a clear justification. Entries without justification or with justifications like "not a real issue" should be re-examined.
CI Pipeline Integration
Add Brakeman as a required CI check. Configure it to fail on high-confidence findings:
- name: Brakeman Security Scan
run: |
gem install brakeman
brakeman -p . --confidence-level 2 --exit-on-warn
The --exit-on-warn flag causes Brakeman to return a non-zero exit code if any warnings are found at or above the specified confidence level.
For GitHub Actions, Brakeman can output SARIF format for integration with GitHub's Security tab:
brakeman -f sarif -o brakeman.sarif
Keeping Brakeman Current
Brakeman's detection rules are updated to cover new Rails features and newly discovered vulnerability patterns. Pin to a specific version in CI for reproducibility, but regularly update to get new detectors.
When upgrading Rails versions, re-run Brakeman at the lowest confidence level to check for patterns that the new version introduces. Rails security defaults change between major versions, and Brakeman may detect configurations that were safe in one version but risky in another.
Limitations
Brakeman is Rails-specific. It does not analyze Sinatra, Hanami, or other Ruby web frameworks effectively.
Brakeman performs local analysis. It does not check the security of gems you depend on. For that, use bundler-audit or bundle audit to check for known vulnerabilities in your Gemfile.lock.
Brakeman's data flow analysis has depth limits. Complex data transformations across many method calls may not be traced completely.
How Safeguard.sh Helps
Safeguard.sh monitors your Ruby gem dependencies for known vulnerabilities, complementing Brakeman's source code analysis. While Brakeman finds security issues in your Rails application code, Safeguard.sh tracks CVEs across your Gemfile dependency tree, generates SBOMs for your Ruby projects, and provides early warning when a gem you depend on is compromised or found to contain a vulnerability. This dual coverage ensures both your code and your supply chain are monitored.