How do I share a Brakeman report?

Run `brakeman -f html -o brakeman.html`, then drag the file into Comma or PATCH it to the API from CI. You get a URL where each warning can be discussed in place instead of pasted into a channel.

How do I publish it from CI?

Add a step after the scan that PATCHes the same report id. Brakeman exits non-zero when it finds warnings, so run the publish step with `if: always()` — otherwise the only runs that publish are the clean ones.

Can I mark a finding as a false positive where everyone can see it?

That is the main reason to publish rather than screenshot. Anchored threads sit on the warning, so 'this is a false positive, the input is an enum' is attached to that finding and still there on the next scan.

Does the filtering UI still work at the URL?

Yes. Report HTML renders with scripts enabled inside a sandboxed iframe, so the confidence filters and the expandable warning details behave as they do locally.

Share a Brakeman report

Brakeman is the rare security tool whose output people actually read — when they can get to it. The default path is:

brakeman -f html -o brakeman.html

One self-contained file, sitting in a CI workspace that expires in 30 days, summarized in a channel as "brakeman found 14 things, mostly noise".

Nobody triages "mostly noise". That is how a real finding stays open for a quarter.

Publish it

Drag brakeman.html into the app, or from CI:

brakeman -f html -o brakeman.html || true

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html brakeman.html \
        --arg title "Brakeman — $GITHUB_SHA" '{title: $title, html: $html}')"

Brakeman exits non-zero when it finds warnings. Either tolerate that exit code on the scan step (as above) or run the publish step with if: always() — otherwise the runs that publish are exactly the ones with nothing to read.

Keep it private

A Brakeman report is a list of your application's soft spots with file paths and line numbers attached. Reports uploaded in the app start private; API publishes are link-viewable unless they pass "visibility": "private" — pass it. The options, in the sharing model: team-wide, gated to your email domain, opened to named reviewers, or — if you must send it outside the company, to an auditor or a client — password-protected rather than a bare link.

Triage in place

The value of a published scan is that triage becomes a record:

Anchored threads on the individual warning — "false positive, the param is an enum", "real, ticketed as SEC-114". See commenting on HTML.
Revisions — PATCH one report id per repo and each scan appends a revision, so a new warning is visibly new rather than lost in a list of 14.
Resolved threads keep the decision attached to the finding, which is what you want the next time an auditor asks why it is still there.

On a schedule

Security scans age badly. A routine can run the scan and PATCH the report on a cron, so the URL you handed to the security reviewer last quarter reflects this week's code — see monthly compliance digest.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a scan report →