DOCSEARCHbyAlgolia
Submit Docs

Brakeman Static Analysis Security Scanner

repository·main·Indexed 27 days ago

https://github.com/presidentbeef/brakeman

A static analysis security scanner specifically designed for Ruby on Rails applications. Brakeman helps developers identify potential vulnerabilities—including XSS, CSRF, command injection, and hardcoded passwords—during the development lifecycle. It supports Rails versions 2.3.x through 8.x and requires Ruby 3.2.0 or newer to run. The tool provides a CLI for scanning, supports multiple output formats (JSON, HTML, SARIF, etc.), and includes specialized integrations for Code Climate.

Tokens
8.5K
Snippets
6
Records
72
Agent score
92%

What's inside Brakeman

  1. Mitigate Link to HREF warnings

    main

    Brakeman issues warnings when user-controlled values are used as the HREF argument in Rails link_to helpers, or when such values are interpolated at the start of a string. This is because values starting with javascript: or data: are unescaped by Rails and can lead to XSS.

    You can mitigate these warnings by using the --url-safe-methods CLI option to specify methods that you trust to sanitize or validate URLs, making them safe for use in links.

  2. Understand Cross-Site Scripting (XSS) warnings

    main

    Brakeman identifies Cross-Site Scripting (XSS) vulnerabilities where user-controlled values (from params, cookies, or database models) are displayed on a web page without proper escaping. This allows attackers to inject malicious JavaScript or HTML.

    Common triggers include:

    • Directly outputting params or cookies using methods like html_safe or raw.
    • Passing params or cookies into methods that are subsequently output unescaped.
    • Outputting model attributes that Brakeman mistrusts by default.

  3. Avoid Dangerous Send with Unfiltered User Data

    main

    Brakeman flags the use of unfiltered user data to select a Class or Method for dynamic dispatch via Object#send as a security risk. To mitigate this, avoid passing raw parameters directly as the method or target. Instead, use a whitelist to map user input to specific, safe symbols or classes.

    Unsafe Patterns:

    • Passing params directly as the method name to send.
    • Using params to dynamically constantize a class (e.g., via .classify.constantize) and then calling send on that class.

    Safe Patterns:

    • Using a conditional or a lookup table to select a specific method symbol based on user input.
    • Using a conditional to select a specific Class based on user input.
    • Passing user data as arguments to a method, provided the method itself is designed to handle potentially untrusted data safely.
    # Unsafe use of method
method = params[:method]
@result = User.send(method.to_sym)

# Safe use of method (whitelisting)
method = params[:method] == 1 ? :method_a : :method_b
@result = User.send(method, *args)

# Unsafe use of target
table = params[:table]
model = table.classify.constantize
@result = model.send(:method)

# Safe use of target (whitelisting)
target = params[:target] == 1 ? Account : User
@result = target.send(:method, *args)

# Safe use of arguments (if the method handles data safely)
args = params["args"] || []
@result = User.send(:method, *args)

  4. Prevent Session Manipulation vulnerabilities

    main

    Session manipulation occurs when an application uses user-supplied input (e.g., from params) as keys for the session hash. Because sessions are often treated as a source of truth for authentication or CSRF protection, an attacker can manipulate these keys to overwrite or access sensitive session values (like _csrf_token or user_id), potentially leading to account takeover or privilege escalation.

    To prevent this, never use user-supplied input directly as a session key.

  6. Remediate Mass Assignment vulnerabilities

    main

    To resolve Mass Assignment warnings, use one of the following strategies:

    • Use attr_accessible: Explicitly define which attributes are allowed for mass assignment in your models. Brakeman will continue to warn if attr_accessible is not used or if mass assignment is not completely disabled.
    • Disable mass assignment (Rails 3.1+): Enable attribute whitelisting in your configuration:
      config.active_record.whitelist_attributes = true
    • Avoid without_protection: Brakeman will flag any instance where mass assignment protection is explicitly bypassed, such as:
      User.new(params[:user], :without_protection => true)

  7. Identify and fix SQL Injection warnings

    main

    Brakeman detects SQL injection vulnerabilities when ActiveRecord methods are used to build SQL statements using unsafe string interpolation or concatenation of user-controlled input.

    To resolve these warnings, replace string interpolation or direct concatenation with parameterized queries (using ? placeholders) to ensure input is properly escaped by the database driver.

  8. Remediate Unscoped find warnings

    main

    Brakeman flags unscoped find calls (and related methods) as a potential Insecure Direct Object Reference (IDOR) vulnerability. This occurs when a model that belongs to another model is accessed directly via its ID without verifying ownership through a scoped query.

    To fix this, instead of calling find on the model class directly, call it through the association of the currently authenticated user or owner.

    # UNSAFE: Allows access to any account by ID
Account.find(params[:id])

# SAFE: Scopes the search to the current user's accounts
current_user = User.find(session[:user_id])
current_user.accounts.find(params[:id])

  12. Identify Remote Code Execution (RCE) vulnerabilities

    main

    Brakeman identifies several patterns that lead to Remote Code Execution (RCE), where an attacker can execute unintended code. Key patterns include:

    • Direct use of eval with user-controlled input.
    • Dangerous use of send to call arbitrary methods.
    • Dangerous use of constantize to create arbitrary objects.
    • Other methods that allow for arbitrary method calls or object instantiation.