Brakeman

Brakeman Integration with DefectDojo

Brakeman is the definitive static analysis security scanner for Ruby on Rails applications — purpose-built for the framework, deeply integrated with Rails conventions, and capable of finding vulnerabilities that generic SAST tools consistently miss because they don't understand how Rails routing, ActiveRecord, and view rendering actually work. For security teams with Rails in their stack, Brakeman is typically the first SAST tool deployed and the one with the highest signal-to-noise ratio for Rails-specific risk. The operational gap is the same one every point-in-time scanner faces: Brakeman findings live in JSON reports and CI logs unless a workflow platform manages them. Integrating Brakeman with DefectDojo moves those findings into a persistent lifecycle — deduplicated, tracked, assigned, SLA-enforced, and reportable across every Rails application in your portfolio.

Why Brakeman Matters

Brakeman's value comes directly from its Rails specificity — it understands the framework deeply enough to find vulnerabilities that require framework context to detect accurately.

• Brakeman understands Rails routing, strong parameters, ActiveRecord query construction, ERB and Haml template rendering, and Rails helper methods — allowing it to trace user-controlled input from routes and controllers through to database queries, shell commands, file operations, and rendered output with framework-aware accuracy that generic AST scanners cannot match
• Its vulnerability coverage includes SQL injection (including Rails-specific query methods like where, find_by_sql, and order), XSS via unescaped template output, command injection, mass assignment vulnerabilities, insecure deserialization, CSRF weaknesses, session security issues, redirect vulnerabilities, and Rails-specific misconfigurations in config/application.rb and environment files
• Confidence levels (High, Medium, Weak) are reported independently from severity, allowing teams to triage realistically — a High severity / Weak confidence finding warrants a different response than High / High
• Brakeman produces JSON output via --format json that includes file paths, line numbers, code context, vulnerability class, and confidence ratings — structured data that DefectDojo consumes directly without preprocessing
• It runs against Rails source code without requiring a running application, database connection, or test environment — making it practical to integrate into CI pipelines at the point of code commit rather than as a later-stage check
• As a gem with active maintenance aligned to Rails version releases, Brakeman stays current with framework changes — new Rails patterns that introduce security risks are typically covered in close proximity to the framework release

Advantages of This Integration

Brakeman identifies security issues in Rails code with framework-level precision. DefectDojo tracks what the team did about them and whether fixes stuck.

• Persistent finding records across Rails scan cycles: Each time Brakeman scans a Rails application, reimporting into DefectDojo updates existing findings rather than generating a fresh, disconnected record set. You can see which SQL injection or XSS findings have persisted across multiple CI runs, which were resolved between scans, and which have been open for 45 days without action — context that CI pipeline output doesn't preserve.
• SLA enforcement by severity and confidence: DefectDojo applies configurable SLA policies across imported Brakeman findings. High severity / High confidence findings get the tightest remediation targets; Weak confidence findings can be handled on a slower review cadence or batched for periodic triage. Breach tracking surfaces overdue items in dashboards without manual status chasing.
• Deduplication across Rails services: The same unsafe query pattern or unescaped output method appearing across multiple Rails services — in a microservices fleet built on a shared internal gem or application template — surfaces in DefectDojo as a portfolio-level pattern worth addressing at the library or template level, not just service-by-service.
• False positive management that survives reimports: Brakeman produces false positives, particularly for patterns it can't fully trace at the static analysis level. Findings marked as false positives in DefectDojo are retained across reimports — the next Brakeman scan won't re-open them, and the documented rationale is auditable rather than relying on Brakeman's own ignore configuration alone.
• Cross-application Rails portfolio visibility: Security teams managing multiple Rails applications get aggregated metrics in DefectDojo — open findings by severity, vulnerability class, application, age, and SLA status — without manually reviewing individual Brakeman reports per application. This aggregate view drives security training decisions, shared library updates, and framework configuration hardening initiatives.
• Developer-facing remediation tickets with Rails context: Triaged Brakeman findings push from DefectDojo to Jira, GitHub Issues, or ServiceNow with vulnerability type, affected controller or model, file path, line number, code context, and remediation guidance — giving Rails developers the specific context they need to understand and fix the issue without needing Brakeman access.
• Trend analysis across the Rails application lifecycle: DefectDojo retains scan history across reimports, enabling trend analysis — whether Brakeman findings are increasing as the application grows, decreasing after security training, or cycling between open and re-introduced, which suggests systemic patterns in how the team writes code.

How This Integration Works

Brakeman produces JSON output via its CLI that DefectDojo's Brakeman parser consumes directly.

Step 1 — Install Brakeman and run a scan

Add Brakeman to your Gemfile (development/security group) or install as a standalone gem:

# Install as standalone gem

gem install brakeman

# Or add to Gemfile

# gem 'brakeman', require: false

Run against a Rails application and capture JSON output:

# Basic scan with JSON output

brakeman --format json --output brakeman-results.json

# Run from outside the application directory

brakeman /path/to/rails/app --format json --output brakeman-results.json

# Include only high-severity findings

brakeman --format json --output brakeman-results.json \

--minimum-severity high

# Exclude specific warning types (e.g., exclude CheckWeakHash in a context

# where the hash usage is non-security-relevant)

brakeman --format json --output brakeman-results.json \

--skip-checks CheckWeakHash

# Run with a Brakeman configuration file

brakeman --format json --output brakeman-results.json \

--config-file config/brakeman.yml

# Quiet mode for CI (suppress progress output, keep JSON clean)

brakeman --format json --output brakeman-results.json --quiet

For CI pipeline integration:

# Capture output regardless of exit code

# Brakeman exits non-zero when findings are present

brakeman --format json --output brakeman-results.json --quiet || true

Step 2 — Import into DefectDojo

Use Brakeman Scan as the scan type:

curl -X POST https://<defectdojo-host>/api/v2/import-scan/ \

-H "Authorization: Token <your-api-token>" \

-F "scan_type=Brakeman Scan" \

-F "file=@brakeman-results.json" \

-F "engagement=<engagement-id>" \

-F "product=<product-id>" \

-F "active=true" \

-F "verified=false"

Step 3 — Reimport for recurring scans

For Rails applications scanned on every CI run or merge to main, use the reimport endpoint to update existing findings rather than accumulate redundant test records:

curl -X POST https://<defectdojo-host>/api/v2/reimport-scan/ \

-H "Authorization: Token <your-api-token>" \

-F "scan_type=Brakeman Scan" \

-F "file=@brakeman-results.json" \

-F "test=<test-id>"

DefectDojo marks findings absent from the new scan as resolved, creates records for new findings, and leaves previously false-positived or risk-accepted findings untouched.

Data Granularity: What Gets Imported

Use Cases

In a CI/CD pipeline for a Rails monolith: Brakeman runs on every pull request against a mature Rails application. Results import into DefectDojo via the API at the end of the scan stage. Security engineers triage new findings weekly — High confidence SQL injection and XSS findings are assigned immediately to the responsible controller owner; Medium confidence findings are reviewed in batch and either assigned or documented as false positives. Previously false-positived findings don't re-appear on subsequent scans, keeping the active queue focused on genuine risk.

Across a fleet of Rails microservices: An organization running 20 Rails services — each a bounded context in a larger system — runs Brakeman in every service's CI pipeline. DefectDojo aggregates findings across all 20 products. The security team identifies that find_by_sql SQL injection patterns appear in 8 services, all of which were scaffolded from the same internal service template. Rather than addressing each service independently, the team updates the template and tracks remediation across all affected services from a single DefectDojo view — a response the individual scan reports would never have surfaced as a coordinated pattern.

During a Rails upgrade security review: When upgrading a Rails application from 6.x to 7.x, security behavior changes in certain defaults — notably around cookie serialization, query interface behavior, and CSRF token handling. Brakeman scans run before and after the upgrade, with both sets of results imported into a dedicated DefectDojo engagement for the upgrade review. New findings introduced by the upgrade are immediately visible; findings resolved by the upgrade's default hardening are automatically closed in DefectDojo on reimport. The engagement record documents the security state of the application at each upgrade milestone.

For a legacy Rails application security remediation program: A Rails application that hasn't had dedicated security review accumulates Brakeman findings that need to be triaged, prioritized, and systematically addressed over a multi-sprint remediation effort. Brakeman's initial scan results import into DefectDojo as the program's baseline. Findings are triaged by severity and confidence, assigned to sprint teams, and tracked through to closure across weekly reimports. The program has a defined start state, measurable progress metrics in DefectDojo, and a documented record of every risk acceptance decision made along the way — managed as a security program, not a backlog of unconnected tickets.

Operational Tips

• Use --quiet in CI to keep JSON output clean: Brakeman's progress output goes to stdout alongside the JSON result when not in quiet mode, which can corrupt the JSON file if output is redirected carelessly. Always use --quiet with --output <file> in CI to ensure the JSON file is valid and importable into DefectDojo without preprocessing.
• Use || true to decouple scan exit code from pipeline failure: Brakeman exits non-zero when any findings are present, which fails CI pipeline stages by default. Capture the JSON output regardless of exit code using || true and handle gate logic separately — for example, failing the build only on new High confidence findings that aren't already tracked in DefectDojo as false positives or accepted risk.
• Map confidence to severity intentionally during triage: Brakeman's confidence (High, Medium, Weak) is imported as severity in DefectDojo. During triage, always review confidence alongside the mapped severity — a finding that imports as High severity because of a High confidence rating warrants different urgency than one that imports as High because of warning type alone. Document the confidence context in DefectDojo finding notes when accepting or assigning findings.
• Maintain a config/brakeman.yml for shared exclusions: Brakeman's configuration file supports skipping specific checks, ignoring specific files, and setting false positive annotations. Maintaining this file in version control alongside the application gives the team a shared, auditable record of scanner-side tuning decisions — but pair it with DefectDojo risk acceptances for decisions that warrant documented rationale beyond a config file comment.
• Prefer DefectDojo risk acceptances over Brakeman's ignore file for documented decisions: Brakeman supports an ignore file (brakeman.ignore) that silences specific findings from future scans. For findings where the decision to accept risk is business-significant — an intentional use of send or eval in a controlled context, for example — document the decision in DefectDojo instead. The rationale is tied to an approver, carries an expiration date, and is auditable in the vulnerability management platform rather than silently embedded in a project config file.
• Tag findings by Rails layer on import: Brakeman findings originate in different layers of the Rails stack — controllers, models, views, helpers, initializers, and configuration files. Tagging DefectDojo findings with the Rails layer (controller, model, view, config) enables filtering and trend analysis by layer — useful for determining whether SQL injection risk is concentrated in a specific team's controller code or whether XSS findings are systemic across the view layer.
• Run Brakeman alongside a dependency scanner for complete coverage: Brakeman covers security issues in application code; it does not scan gem dependencies for known CVEs. Pairing Brakeman with bundler-audit or a commercial SCA tool and importing both into DefectDojo under the same or adjacent engagements gives complete Rails application security coverage — code-level SAST alongside dependency vulnerability management — in a single tracked workflow.