Forem: Sam Partington

How to integrate Brakeman Security Scanner with GitHub Code Scanning

Sam Partington — Mon, 22 Dec 2025 10:11:50 +0000

GitHub Code Scanning automatically scans your repository for security vulnerabilities and alerts you in Pull Requests and on a dedicated alert backlog accessible via a repository's Security tab.

Out of the box, GitHub Code Scanning uses a tool called CodeQL, but you can also display alerts produced by any tool that can output its results in the SARIF format.

The Rails security scanner Brakeman supports the SARIF format, but I couldn't find any documentation about how to join all the pieces together and see Brakeman results in GitHub Code Scanning. This blog post is my answer to the question of how you do it.

Pre-requisites

This guide assumes that you already have GitHub Code Scanning turned on for your repository. Your project will also need to have Brakeman installed. You don't need it running on your local machine - you could do the install explicitly in the Actions workflow you'll be creating, but this guide assumes you instead have something like the following in your Gemfile:

group :development, :test do
  gem 'brakeman', require: false
end

Creating a GitHub Actions workflow

To upload results to Code Scanning, you'll need to create an GitHub Actions workflow. rails new creates an existing workflow which you could modify, but for simplicity I'm showing here a fresh workflow just for Brakeman.

Here's the full workflow; I'll explain it step-by-step below:

name: "Run brakeman and upload results to Code Scanning"

on:
  push:
    branches: [main]
  pull_request:

jobs:
  brakeman:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true

      - name: Run brakeman
        # Without --no-exit-on-warn, brakeman returns a non-zero error code when alerts
        # are found, failing the check. We want the check to pass as results are handled
        # via GitHub Code Scanning's UI.
        run: bundle exec brakeman --no-exit-on-warn -f sarif > brakeman-results.sarif

      - name: Upload scan results to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: "brakeman-results.sarif"

The workflow begins with metadata - a name, and when it should run (that empty pull_request: key isn't a typo, despite appearances). We then declare a job and state that it should run on Ubuntu. Other runner types are available, or you can host your own.

The first step in the job uses actions/checkout to clone the repo it runs in. We then run the ruby/setup-ruby action which installs Ruby and runs Bundler. If Brakeman is in your Gemfile (see above), that'll be installed at this stage.

The next step actually runs Brakeman, using the run command to run the following terminal command:

bundle exec brakeman --no-exit-on-warn -f sarif > brakeman-results.sarif

The first part of this command is fairly self-explanatory, we're running Brakeman via Bundler: bundle exec brakeman.

--no-exit-on-warn is important. Normally, if Brakeman finds any alerts, it will return a non-zero return code. On UNIX-like systems (including Linux or Mac), that indicates a failure and so the workflow will fail. If you weren't uploading results to Code Scanning, that'd be the correct behaviour -- a failing workflow would indicate problems found. However, that's not what we want here -- we'll be showing alerts through the Code Scanning UI instead.

-f sarif tells Brakeman to use the SARIF format format, which is what GitHub Code Scanning needs.

Finally, we redirect the output into a file ready for the next step to upload.

The final step in the workflow uploads the results to GitHub Code Scanning.

What you get

Once this is running, results from Brakeman will appear in the Code Scanning UI:

Newly-introduced alerts will also show up as annotations on Pull Requests.

If you create the new workflow in a Pull Request, you might also see a helpful comment automatically posted on it, like this:

Troubleshooting

Not working? Try these...

Take a look at the log output from the workflow; chances are, you'll see an error here that helps explain what's wrong.
Run the Brakeman command locally and see what happens. Take away the redirection if you want to see output, and remove -f sarif to get results in a more human-readable format. You might not actually have any alerts in your project, of course!
Look at the Code Scanning results page for your repository (/security/code-scanning). You should see a "tool status" banner at the top, which will tell you the health of the Code Scanning tools that your repository is using. You might see Brakeman errors or warnings here; if not then press the "Tools" button and see if Brakeman is listed at all. If it's not, then the upload or a previous step is failing.
You could experiment with uploading results manually using the Code Scanning API. Run the workflow Brakeman command, upload results and see what status or error you get back.

What actually are .tt files in Ruby?

Sam Partington — Wed, 05 Nov 2025 12:43:48 +0000

tl;dr .tt files aren't a special syntax; they're ERB (Embedded Ruby) files. You might see unusual syntax if they're ERB files which generate other ERB files.

If you're working with Ruby, particularly Rails and its generators, you're likely to come across files with a .tt extension. But what actually are .tt files?

Rails generators use the Thor toolkit¹ which helps with building CLIs and manipulating files. So you could think of "tt" as standing for "Thor template".

If that's the case then you might reasonably ask, "What's Thor template syntax?" It took me a long time to work out that this is the wrong question. We call a tt file a Thor template file not because it's a template using Thor syntax (there's no such thing) but because it's a template used in Thor commands.

I'll say that again: A "Thor template" means "a template used in a Thor command", not "a template using ‘Thor syntax'".

The syntax which .tt files use is actually Embedded Ruby (aka ERB, or eRuby).

One thing which led me to mistakenly believe that Thor syntax was its own language is the <%% and %%> tags I sometimes see in .tt files. If this is just ERB, what are those?

To answer that, remember that in Rails generators you'll find .tt files that are used to generate ERB files. As the Rails generator docs briefly mention,

Note that [this example template] is an ERB template that renders another ERB template. So any <% that should appear in the resulting template must be escaped as <%% in the generator template.

(Some .tt files generate Ruby code, like controllers, so they wouldn't need to use this syntax.)

<%% is actually ERB syntax, although there isn't really canonical documentation for ERB syntax, and docs on this particular tag are hard to find. I couldn't find anything about it in the current rdoc for the ERB class², but in this old version, we find:

<%% or %%> -- replace with <% or %> respectively

To conclude, then, .tt files are used by the Thor templating engine, but their syntax is ERB. You might find some odd-looking <%% tags, but that is also ERB syntax, albeit poorly-documented, and it converts to <% in the resulting output. This allows you to create ERB templates which themselves produce ERB!

Note: You might also find files with the .tt extension if you're working with Visual Studio text templates and their T4 text template language. That looks a bit like ERB, but uses tags like <# instead. It's nothing to do with Ruby!

See also http://whatisthor.com ↩
Rails actually uses https://github.com/jeremyevans/erubi for parsing embedded Ruby rather than the ERB class from the standard library. For an overview of embedded Ruby tools and libraries and their associated documentation, check out this Stack Overflow answer. ↩

Combining multiple forms in Flask-WTForms but validating independently

Sam Partington — Thu, 17 Jan 2019 12:07:04 +0000

Introduction

We have a Flask project coming up at White October which will include a user profile form. This form can be considered as one big form or as multiple smaller forms and can also be submitted as a whole or section-by-section.

As part of planning for this work, we did a proof-of-concept around combining multiple subforms together in Flask-WTForms and validating them.

Note that this is a slightly different pattern to "nested forms". Nested forms are often used for dynamic repeated elements - like adding multiple addresses to a profile using a single nested address form repeatedly. But our use case was several forms combined together in a non-dynamic way and potentially processed independently. This article also doesn't consider the situation of having multiple separate HTML forms on one page.

This document explains the key things you need to know to combine forms together in Flask-WTF, whether you're using AJAX or plain postback.

Subforms

The first thing to know is how to combine multiple WTForms forms into one. For that, use the FormField field type (aka "field enclosure"). Here's an example:

from flask_wtf import FlaskForm
import wtforms

class AboutYouForm(FlaskForm):
    first_name = wtforms.StringField(
        label="First name", validators=[wtforms.validators.DataRequired()]
    )
    last_name = wtforms.StringField(label="Last name")

class ContactDetailsForm(FlaskForm):
    address_1 = wtforms.StringField(
        label="Address 1", validators=[wtforms.validators.DataRequired()]
    )
    address_2 = wtforms.StringField(label="Address 2")

class GiantForm(FlaskForm):
    about_you = wtforms.FormField(AboutYouForm)
    contact_details = wtforms.FormField(ContactDetailsForm)

As you can see, the third form here is made by combining the first two.

You can render these subforms just like any other form field:

{{ form.about_you }}

(Form rendering is discussed in more detail below.)

Validating a subform

Once we'd combined our forms, the second thing we wanted to prove was that they could be validated independently.

Normally, you'd validate a (whole) form like this:

if form.validate_on_submit()
    # do something

(validate_on_submit returns true if the form has been submitted and is valid.)

It turns out that you can validate an individual form field quite easily. For our about_you field (which is a subform), it just looks like this:

form.about_you.validate(form)

Determining what to validate

We added multiple submit buttons to the form so that either individual subforms or the whole thing could be processed. If you give the submit buttons different names, you can easily check which one was pressed and validate and save appropriately (make sure you only save the data you've validated):

<input type="submit" name="submit-about-you" value="Just submit About You subform">
<input type="submit" name="submit-whole-form" value="Submit whole form">

And then:

if "submit-about-you" in request.form and form.about_you.validate(form):
    # save About You data here
elif "submit-whole-form" in request.form and form.validate():
    # save all data here

If you have one route method handling both HTTP GET and POST methods, there's no need to explicitly check whether this is a postback before running the above checks - neither button will be in request.form if it's not a POST.

Alternative approaches

You could alternatively give both submit buttons the same name and differentiate on value. However, this means that changes to the user-facing wording on your buttons (as this is their value property) may break the if-statements in your code, which isn't ideal, hence why different names is our recommended approach.

If you want to include your submit buttons in your WTForms form classes themselves rather than hard-coding the HTML, you can check which one was submitted by checking the relevant field's data property - see here for a small worked example of that.

Gotcha: Browser-based validation and multiple submit buttons

There's one snag you'll hit if you're using multiple submit buttons to validate/save data from just one subform of a larger form.

If your form fields have the required property set (which WTForms will do if you use the DataRequired validator, for example), then the browser will stop you submitting the form until all required fields are filled in - it doesn't know that you're only concerned with part of the form (since this partial-submission is implemented server-side).

Therefore, assuming that you want to keep using the required property (which you should), you'll need to add some Javascript to dynamically alter the form field properties on submission.

This is not a problem if you're using AJAX rather than postbacks for your form submissions; see below how to do that.

Rendering subforms in a template

The examples in this section use explicit field names. In practice, you'll want to create a field-rendering macro to which you can pass each form field rather than repeating this code for every form field you have. That link also shows how to render a field's label and widget separately, which gives you more control over your markup.

As mentioned above, the subforms can be rendered with a single line, just like any other field:

{{ form.about_you }}

If you want to render fields from your subforms individually, it'll look something like this:

<label for="{{ form.about_you.first_name.id }}">{{ form.about_you.first_name.label }}</label>
{{ form.about_you.first_name }}

As you see, you can't do single-line rendering of form fields and their labels for individual fields within subforms - you have to explicitly render the label.

Displaying subform errors

For a normal form field, you can display associated errors by iterating over the errors property like this:

{% if form.your_field_name.errors %}
    <ul class=errors>
        {% for error in field.errors %}
            <li>{{ error }}</li>
        {% endfor %}
    </ul>
{% endif %}

In this case, errors is just a list of error strings for the field.

For a subform where you're using the FormField field type, however, errors is a dictionary mapping field names to lists of errors. For example:

{
    'first_name': ['This field is required.'],
    'last_name': ['This field is required.'],
}

Therefore, iterating over it in your template is more complicated. Here's an example which displays errors for all fields in a subform (notice the use of the items method):

{% if form.about_you.errors %}
    <ul class="errors">
        {% for error_field, errors in form.about_you.errors.items() %}
            <li>{{ error_field }}: {{ errors|join(', ') }}</li>
        {% endfor %}
    </ul>
{% endif %}

Doing it with AJAX

So far, we've considered the case of validating subforms when data is submitted via a full-page postback. However, you're likely to want to do subform validation using AJAX, asynchronously posting form data back to the Flask application using JavaScript.

There's already an excellent article by Anthony Plunkett entitled "Posting a WTForm via AJAX with Flask", which contains almost everything you need to know in order to do this.

In this article, therefore, I'll just finish by elaborating on the one problem you'll have if doing this with multiple submit buttons - determining the submit button pressed

Determining the submit button pressed

When posting data back to the server with JavaScript, you're likely to use a method like jQuery's serialize. However, the data produced by this method doesn't include details of the button clicked to submit the form.

There are various ways you can work around this limitation. The approach I found most helpful was to dynamically add a hidden field to the form with the same name and value as the submit button (see here). That way, Python code like if "submit-about-you" in request.form (see above) can remain unchanged whether you're using AJAX or postbacks.