Brakeman Integration with DefectDojo

Brakeman Integration with DefectDojo

Brakeman is an open source static analysis security scanner built specifically for Ruby on Rails applications, created by Justin Collins. It reads a Rails application's source code, including controllers, models, views, routes, and configuration, without running it, and reports warnings such as SQL injection, cross-site scripting, mass assignment, unsafe redirects, command injection, and insecure Rails settings. Brakeman can write its results as text, HTML, JSON, CSV, SARIF, and other formats. DefectDojo imports the JSON report.

Brakeman Integration with DefectDojo

Brakeman is the first scanner we add to any Rails repository, because it understands Rails conventions that generic SAST tools miss. What it doesn't do is remember anything between runs. Importing Brakeman results into DefectDojo gives each warning a home on the Asset that owns the app, an owner, a status history, and an SLA. When a developer fixes a flagged controller action, the next reimport closes the Finding, and the team can see the backlog shrink instead of rereading the same report every week.

Why Brakeman Matters

Rails makes a lot of decisions implicitly, and many security bugs in Rails apps come from those defaults being bypassed or misused. Brakeman is written for that framework.

• It follows Rails-specific data flow, such as parameters flowing from a controller into a rendered view or a query, and shows the render path when a template is involved.
• It needs no running application, database, or dependencies installed, so it fits early in CI.
• Every warning links to Brakeman's documentation for that warning type, which explains the risk and the fix in Rails terms.
• Brakeman rates each warning by confidence (High, Medium, Weak), which tells reviewers how sure it is, but on its own it has no way to track which warnings were reviewed, accepted, or fixed.

Advantages of This Integration

What we gained by running Brakeman through DefectDojo:

• History across commits. Reimporting into the same Test mitigates warnings that disappear, adds new ones, and reactivates any that return after a regression.
• Deduplication. Brakeman findings use DefectDojo's legacy deduplication on title, CWE, line, file path, and description, so rescanning unchanged code doesn't create duplicates.
• A severity your team chooses. Brakeman doesn't assign severity, so every finding arrives as Medium. Triage in DefectDojo sets the real severity, which then drives SLAs and dashboards.
• False positives that stay closed. Marking a warning as a false positive in DefectDojo keeps it from resurfacing as new on the next scan of the same code.
• Ownership and ticketing. Findings can be assigned, annotated, risk-accepted, or pushed to Jira like findings from any other tool.
• Rails findings next to the rest. Brakeman results sit alongside dependency and container findings for the same Asset, which gives one view of an application's risk.

How This Integration Works

DefectDojo imports Brakeman results with the Brakeman Scan scan type, which reads Brakeman's JSON output.

1. Produce a JSON report. Run Brakeman from the root of the Rails application:

brakeman -f json -o brakeman-report.json

The parser reads the scan_info block for the scan end time and the warnings array for findings. Brakeman's own ignore file (managed with brakeman -I) removes ignored warnings from the report before DefectDojo sees it.

2. Import it. In the UI, open the Engagement, choose Import Scan Results, select Brakeman Scan, and upload the file. For automation, use the API, available in Community Edition and DefectDojo Pro:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" \
  -H "Authorization: Token $DD_API_TOKEN" \
  -F "scan_type=Brakeman Scan" \
  -F "file=@brakeman-report.json" \
  -F "product_name=storefront" \
  -F "engagement_name=CI" \
  -F "auto_create_context=true"

DefectDojo Pro users can run the same import from a pipeline with Universal Importer:

universal-importer import \
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
  --scan-type "Brakeman Scan" \
  --report-path "./brakeman-report.json" \
  --product-name "storefront" \
  --engagement-name "CI" \
  --auto-create-context

3. Reimport on each run. Send later reports to /api/v2/reimport-scan/ against the same Test, so fixed warnings are mitigated and the branch keeps one history.

Data Granularity: What Gets Imported

Within one report, the parser keeps a single Finding per Brakeman fingerprint, so a warning listed more than once is imported once. Brakeman's confidence level appears in the description text but is not stored in a separate field.

Use Cases

In a pull request pipeline: CI runs Brakeman on every pull request and reimports into the main branch Test after merge. Developers see new warnings tied to their change, and a policy check can look for new findings that triage has raised to High.

Across a portfolio of Rails apps: A company running a dozen Rails services imports each one into its own Asset. Security leads see which apps carry the most open Brakeman findings and which teams are closing them inside SLA.

During a Rails upgrade: Upgrading Rails can change which warnings Brakeman reports, as some checks depend on the framework version. Reimporting after the upgrade shows exactly which warnings were resolved and which are new.

For audit evidence: DefectDojo keeps the discovery date, status changes, and closure date for each finding, which answers secure development questions without digging through CI logs.

Operational Tips

• Plan for the uniform severity. Every Brakeman finding arrives as Medium, so set severity during triage before SLA reports depend on it, or apply an SLA policy that reflects that default.
• Use the confidence line in the description to prioritize. Weak confidence warnings are often worth a quick review before assigning them to a developer.
• Expect some churn when code moves. Line and description (which includes the line number and code snippet) are part of the dedupe key, so refactors can close one finding and open another for the same issue.
• Run Brakeman from the application root every time so file paths stay consistent between scans.
• Decide where you suppress noise. Brakeman's ignore file stops warnings at the source, while DefectDojo's false positive and risk acceptance keep a record of the decision. Pick one approach per team so nobody wonders why a warning vanished.
• Tag imports with the branch or Rails version (for example tags=main,rails-7) to compare results over time.