How to resolve brakeman warnings

Updated October 23, 2025

Brakeman is a static code analyzer gem for security vulnerabilities on Vets-API. Brakeman scans Ruby on Rails applications looking for vulnerabilities such as SQL injections. This is different from another security focused gem bundle-audit which checks gems for CVE issues. Brakeman is typically run automatically through the CI Code Check workflow. Occasionally, this will result in a warning and Lint Failure label on a PR. This documentation will show to resolve such warnings.

Brakeman Warnings

Brakeman has the following warning types: https://brakemanscanner.org/docs/warning_types/

Each warning also contains the following attributes:

• Confidence

• Category

• Check

• Message

• Code

• File

• Line

Brakeman assigns each warning a confidence level. This rating is intended to indicate how certain Brakeman is that the given warning is a real problem.

The following guidelines are used:

• High - Either this is a simple warning or user input is very likely being used in unsafe ways.

• Medium - This generally indicates an unsafe use of a variable, but the variable may or may not be user input.

• Weak - Typically means user input was indirectly used in a potentially unsafe manner.

Example

# in CI Code Check - Run Brakeman Job

> Run bundle exec brakeman --ensure-latest --confidence-level=2 --format github

Notice:  Using Prism parser
Loading scanner...
Processing application in /home/runner/work/vets-api/vets-api

# omit most of the output

Checks finished, collecting results...
Filtering warnings...
Notice:  Using '/home/runner/work/vets-api/vets-api/config/brakeman.ignore' to filter warnings
Generating report...
Warning: Specify exact keys allowed for mass assignment instead of using `permit!` which allows any keys
Error: Process completed with exit code 3.

At this point the CI has given us a “mass assignment” warning, which corresponds with this doc: https://brakemanscanner.org/docs/warning_types/mass_assignment/.

Brakeman reports issues in order of “confidence”. You can think of this as a combination of “how likely is this to be a problem?” and “how big of a problem is it?” Keep in mind Brakeman can only guess at the meaning of your code. There is plenty of room for “false positives” - warnings reported that are not truly security issues.

Steps to resolve

1. Run Brakeman locally

 brakeman --ensure-latest --confidence-level=2

2. Identity the warning in the report

Confidence: Medium
Category: Mass Assignment
Check: MassAssignment
Message: Specify exact keys allowed for mass assignment instead of using `permit!` which allows any keys
Code: params.require(:form).permit!
File: app/controllers/v0/form214192_controller.rb
Line: 76

3. Locate the issue in code

def download_form_params
  params.require(:form).permit!
end

At this point we know what the warning is (MassAssignment) and where it’s located (V0::Form214192Controller#L76)

4. Determine why we are getting the warning

permit! allows any key/value to be passed to the code

5. Evaluate for accuracy and correctness

In this case, form contains a hash of complex, nested keys of an unknown and differing structure. It would be difficult to explicitly permit. download_form_params are not used in any database operations. A PDF is created based on the params submitted by the user.

6. Evaluate for workarounds or alternative approaches

Ideally we would explicitly allow all the keys for the params. If only the top-level keys are known we can explicitly allow those.

params.require(:form).permit(:form_id, :submitted_by, known_nested_hash: {}) 

If none of the keys in the hash are known, we can’t explicitly permit them. If necessary, explore alternative approaches or implementations at a higher level. For example, can the params passed to controller be arranged in a uniform or consistent way to allow for permitting parameters?

Difficultly, shouldn’t considered when ignoring Brakeman warnings. ONLY false positives should be ignored. Alternative approaches or workarounds should be exhausted and the implementation scope should be expanded until a resolution is found.

7. Implement alternatives

8. (optional) Add to ignore list if false positive

For the above situation we aren’t performing any database operations, so it’s appropriate to add to the ignore list and add a comment where the warning was flagged. The comment should describe why the warning is a false-positive.

It’s important to remember that you aren’t the only person working in a particular area. You may not be using the code in a dangerous way, but the next person might not realize they are. Make sure you add comments to code that could potentially be dangerous so the next person doesn’t misuse the code and expose a potential vulnerability.

False positive warnings

Let’s take a look at a false positive for SQL injections

== Warnings ==
Confidence: Medium
Category: SQL Injection
Check: SQL
Message: Possible SQL injection
Code: connection(:server_url => Settings.travel_pay.base_url).delete("api/v1/claims/#{claim_id}/documents/#{document_id}")
File: modules/travel_pay/app/services/travel_pay/documents_client.rb
Line: 102

def delete_document(veis_token, btsss_token, params = {})
  log_to_statsd('documents', 'delete_document') do
    connection(server_url: btsss_url).delete("api/v1/claims/#{claim_id}/documents/#{document_id}") do |req|
      req.headers['Authorization'] = "Bearer #{veis_token}"
      req.headers.merge!(claim_headers)
    end
  end
end

Brakeman sees delete and claim_id and thinks SQL injection. This is for two reasons:

1. It views delete as a the ActiveRecord delete method (source)

2. It views claim_id as a route parameter as in params[:claim_id]

In order to evaluate if you have a false positive, it’s important to read and understand the corresponding warning type on the Brakeman documentation. It may also be useful to read the code for the check https://github.com/presidentbeef/brakeman/tree/main/lib/brakeman/checks

In the above case, neither assumption is correct. This tells us that it is a false positive.

Ignore false positives

To ignore false positives they must be added to the brakeman.ignore file in the root directory of the API.

For more information on how to ignore false positives review the Brakeman documentation: https://brakemanscanner.org/docs/ignoring_false_positives/

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.