# Brakeman: static security analysis for Ruby on Rails applications

> Brakeman scans Rails source code for security vulnerabilities without running the application. It is free for non-commercial use, installs as a Ruby gem or a Docker image, and reports findings as text, HTML, JSON, SARIF and several CI-oriented formats.

**presidentbeef/brakeman** — A static analysis security vulnerability scanner for Ruby on Rails applications

- Repository: https://github.com/presidentbeef/brakeman
- Website: https://brakemanscanner.org/
- Stars: 7,274 · Forks: 778
- Language: Ruby
- License: NOASSERTION
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/presidentbeef-brakeman

## What Brakeman scans and who it is aimed at

Brakeman is a static analysis tool that checks Ruby on Rails applications for security vulnerabilities. Static here means it reads the code rather than executing it. That matters for adoption: you can point it at a repository you cannot boot, a legacy app with missing credentials, or a branch in CI before any database exists.

The audience is Rails teams. The README states compatibility with any version of Rails from 2.3.x to 8.x, which covers a wide span of maintained and unmaintained applications, and says Brakeman can analyze code written with Ruby 2.0 syntax and newer. Running it is a different requirement: the tool itself needs at least Ruby 3.2.0. So an old application can be scanned, but the machine doing the scanning needs a modern Ruby or the Docker image.

It is not a general Ruby security scanner. The stated scope is Rails applications, and the checks are organized around Rails concepts such as default routes, SQL construction, and validation regexes. A plain Ruby gem or a Sinatra service falls outside what the README claims.

## How the analysis works and what the warnings mean

Brakeman parses the application source and looks for patterns that indicate unsafe handling of input. The README describes the output in terms of warnings, each carrying a confidence level. There are three: High, Medium, and Weak. High means either a simple boolean-style warning or user input very likely being used in unsafe ways. Medium generally indicates an unsafe use of a variable that may or may not be user input. Weak typically means user input was used indirectly in a potentially unsafe manner.

The README is explicit that these ratings should not be taken as absolute truth. That is the honest framing of a static analyzer and it shapes how you should use the tool. A High-confidence warning is worth fixing. A Weak one is a pointer to code worth reading, not a defect.

Filtering happens at the command line. The -w switch takes a number from 1 to 3, where 1 is low (all warnings) and 3 is high (only the highest-confidence warnings). Checks can also be selected or excluded by name, in the correct case, with -t and -x. The README gives DefaultRoutes and Redirect as examples of check names, and SQL and ValidationRegex as examples for -t.

The HTML report includes an excerpt of the application source where a warning was triggered. The README warns that, because of the processing done while looking for vulnerabilities, the excerpt may not resemble the reported warning and reported line numbers may be slightly off. Treat the context as a quick look at the code, not as a precise location.

## Installing Brakeman and running a first scan

The README lists four installation paths: RubyGems, Bundler, a prebuilt Docker image, and building the Docker image from source. For a one-off scan, RubyGems is the shortest route. Run this and you get the brakeman executable on your PATH.

```bash
gem install brakeman
```

For a project, the README shows adding it to the development group in the Gemfile with require set to false, so the library is not loaded by the application at boot.

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

From a Rails application's root directory, the command is just the tool name. The scan runs, informational output goes to stderr, and the report is printed. Note the README's statement that all Brakeman output except reports is sent to stderr, which is why redirecting stdout to a file gives you only the report.

```bash
brakeman
```

To keep a machine-readable copy, pass -o with a filename. The format is chosen from the file extension or set explicitly with -f; the README lists text, html, tabs, json, junit, markdown, csv, codeclimate, github, sarif, and sonar. Multiple output files can be requested in one run.

```bash
brakeman -o output.html -o output.json
```

If you prefer not to install Ruby, the prebuilt image mounts the current directory at /code, which is the working directory the Dockerfile sets. The --color flag is the README's example of nicer terminal output.

```bash
docker run -v "$(pwd)":/code presidentbeef/brakeman --color
```

One behaviour to plan around: by default Brakeman returns a non-zero exit code if any security warnings are found or scanning errors are encountered. That is what makes it usable as a CI gate, and also what will fail your build the first time you run it on an existing application. The README documents --no-exit-on-warn and --no-exit-on-error to disable that.

## Ignoring warnings, comparing scans, and the speed trade-off

A first run on a mature application produces a backlog. Brakeman handles this with an ignore file. By default it looks for config/brakeman.ignore, and the -I option creates and manages that file. To see what you have ignored without changing the exit code, use --show-ignored. This is the mechanism that lets a team adopt the tool without fixing everything at once, and it is also the mechanism that can quietly hide a real finding if nobody reviews the file.

For incremental adoption, the --compare option takes a previous JSON report and outputs two lists: fixed warnings and new warnings. That is a better fit for a pull request check than a full-repository pass, because it answers whether this change introduced something rather than whether the codebase has ever had problems.

Brakeman also offers --faster, which the README says disables some features and is currently the same as --skip-libs --no-branching. The README adds a warning in capitals: this may cause Brakeman to miss some vulnerabilities. That is a real trade-off, not a free speedup, and it should be a deliberate choice on large codebases rather than a default.

Options can live in YAML configuration files instead of the command line. The -C option prints the currently set options in that format, which is the documented way to write the file without guessing key names. The default locations are ./config/brakeman.yml, ~/.brakeman/config.yml, and /etc/brakeman/config.yml, and -c selects a specific file. Options passed on the command line take priority over configuration files.

## Where Brakeman is the wrong tool

The first limitation is scope. Brakeman analyzes Rails applications. If your service is plain Ruby, or the risky code lives in a JavaScript front end, or the vulnerability is in how a dependency behaves at runtime, the README's description does not claim to cover it. Static analysis of your own source will not tell you that a gem you depend on has a published advisory.

The second is precision. The confidence levels exist because the analysis cannot always tell whether a variable holds user input. Medium and Weak warnings require a human to read the code, and the HTML context excerpt may not match the reported line numbers. A team that treats every warning as a confirmed vulnerability will spend time on false positives; a team that filters to -w3 only will miss the indirect cases the tool is designed to surface.

The third is the exit code. Returning non-zero on any warning is the right default for a new project and an obstacle for an old one. The documented escapes are the ignore file, --no-exit-on-warn, or the --compare workflow. Each of those weakens the gate, so the choice is about where you want the friction.

Finally, --faster explicitly trades detection for speed. If you enable it to keep a large repository under a time budget, you have accepted that some vulnerabilities will not be reported, and the README says so.

## Brakeman compared with a general-purpose CI security tool

The obvious alternative for many teams is a hosted code analysis service that covers many languages under one dashboard. The difference in approach is not just language support. Brakeman is a single-purpose Rails analyzer you run yourself, from a gem or a container, against a local path. Its output formats include codeclimate, github, sarif, and sonar precisely so that a hosted platform can consume its results rather than replace it. The README names Code Climate and GitHub among organizations using Brakeman, which is consistent with that role: the tool feeds the platform.

A second alternative is a dependency scanner. That answers a different question. Brakeman reads your application code for unsafe patterns; a dependency scanner reads your lockfile for known-vulnerable packages. Neither substitutes for the other, and a Rails team with a security requirement usually ends up with both.

A third comparison is to a runtime or dynamic scanner that exercises the application. Brakeman does not need the application to run, which is its advantage in CI and on legacy code, and also the reason it cannot observe anything that only appears at runtime.

There is also a build-from-source path for the container, documented in the README as cloning the repository, changing into it, and running docker build. The Dockerfile shows the image is based on ruby:3.3-alpine, installs build-base, runs bundle install without the development and test groups, and sets the entry point to /usr/src/app/bin/brakeman with /code as the working directory. That layout explains why the run examples mount the application at /code.

## Maintenance, licence, and what to check before adopting

The repository is not archived, and the last push was on 2026-09-18. Recent releases in the repository's history are v8.0.6 on 2026-08-12, v8.0.5 on 2026-06-12, and v8.0.3 on 2026-02-26. The cadence is regular enough that pinning a version and reviewing release notes between upgrades is a reasonable practice. The CHANGES.md file at the repository root is where those notes live.

The licence needs attention before you commit to the tool. The README states that Brakeman is free for non-commercial use and points to COPYING.md for details. The repository metadata reports the licence as NOASSERTION, and both LICENSE.md and MIT-LICENSE are present at the top level. That combination is a signal to read the actual licence text rather than assume a standard permissive licence applies. This is not legal advice; if your organization has a policy on tooling licences, route COPYING.md through it. The practical consequence is that a commercial team should confirm its use is permitted before making Brakeman a required build step.

Upgrade cost is mostly operational. The tool requires Ruby 3.2.0 or newer to run, so the scanner's environment has its own Ruby floor independent of the application being scanned. If you run it from a Gemfile, a version bump lands with your normal bundle update. If you run the Docker image, upgrading means pulling a new tag. Either way, an existing config/brakeman.ignore file carries forward, and a new release with added checks can surface warnings that were not reported before, which is exactly when the exit code will fail a previously green build.

## Conclusion

Adopt Brakeman if you maintain a Rails application and want vulnerability warnings produced from source alone, with output that CI systems can consume. Do not adopt it expecting coverage of non-Rails Ruby code, JavaScript front ends, or runtime-only issues, and do not treat its confidence levels as absolute truth. Before wiring it into a pipeline, verify two things yourself: whether your use is commercial, since the README says Brakeman is free for non-commercial use and points to COPYING.md, and how your repository handles config/brakeman.ignore, because ignored warnings affect the exit code unless you pass --show-ignored.

## FAQ

### What is the Brakeman gem?

It is a static analysis security vulnerability scanner for Ruby on Rails applications, installable with gem install brakeman. It reads application source instead of running the app, and the README states it works with any version of Rails from 2.3.x to 8.x.

### How do I use Brakeman on a Rails application?

Run the brakeman command from the Rails application's root directory, or pass a path such as brakeman /path/to/rails/application from elsewhere. Add -o output.html or -o output.json to write a report, and note that all output except reports goes to stderr.

### What is Brakeman for Rails?

Brakeman checks Rails applications for security vulnerabilities by static analysis, and its checks are named after Rails concepts such as DefaultRoutes and Redirect. It requires at least Ruby 3.2.0 to run.

### What is Brakeman in Ruby?

It is a Ruby tool distributed as a gem and as a Docker image, used to scan Rails code for security vulnerabilities. The README notes it can analyze code written with Ruby 2.0 syntax and newer, but needs at least Ruby 3.2.0 to run.

### What does Brakeman do?

Brakeman performs static analysis on Ruby on Rails applications and reports security warnings at three confidence levels: High, Medium, and Weak. It can output reports in formats including text, html, json, junit, sarif, and codeclimate.

## Sources

- [Issues](https://github.com/presidentbeef/brakeman/issues)
- [presidentbeef/brakeman on GitHub](https://github.com/presidentbeef/brakeman)
- [Project website](https://brakemanscanner.org/)
- [README](https://github.com/presidentbeef/brakeman/blob/main/README.md)
- [Releases](https://github.com/presidentbeef/brakeman/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/presidentbeef-brakeman