brakeman

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Brakeman Security Scanner

Brakeman安全扫描器

Overview

概述

Brakeman is a static analysis tool that checks Ruby on Rails applications for security vulnerabilities without requiring a running application. It analyzes source code to detect common security issues including SQL injection, cross-site scripting (XSS), command injection, mass assignment, and many other vulnerability types.

Brakeman是一款静态分析工具，无需运行应用即可检查Ruby on Rails应用的安全漏洞。它通过分析源代码来检测常见的安全问题，包括SQL注入、跨站脚本（XSS）、命令注入、批量赋值等多种漏洞类型。

Installation

安装

Verify Brakeman is installed before running scans. If not present, install using one of these methods:

bash

undefined

在运行扫描前请确认已安装Brakeman。若未安装，可通过以下方式之一进行安装：

bash

undefined

Using RubyGems (recommended)

使用RubyGems（推荐）

gem install brakeman

Using Bundler (add to Gemfile)

使用Bundler（添加到Gemfile）

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

Using Docker

使用Docker

docker pull presidentbeef/brakeman


Brakeman requires Ruby 3.0.0+ to run, but can analyze code written with Ruby 2.0+ syntax. It works with Rails 2.3.x through 8.x.

docker pull presidentbeef/brakeman


Brakeman运行需要Ruby 3.0.0+，但可以分析使用Ruby 2.0+语法编写的代码。它兼容Rails 2.3.x至8.x版本。

Basic Usage

基础用法

Quick Scan

快速扫描

Run a basic security scan from the Rails application root:

bash

brakeman

From outside the Rails root:

bash

brakeman /path/to/rails/application

从Rails应用根目录运行基础安全扫描：

bash

brakeman

从Rails根目录外部运行：

bash

brakeman /path/to/rails/application

Output Formats

输出格式

Generate reports in various formats:

bash

undefined

生成多种格式的报告：

bash

undefined

HTML report

HTML报告

brakeman -o report.html

JSON report (useful for comparison and automation)

JSON报告（适用于对比和自动化场景）

brakeman -o report.json

Multiple output formats simultaneously

同时生成多种输出格式

brakeman -o report.html -o report.json

Output to console with color and file

带颜色输出到控制台并保存到文件

brakeman --color -o /dev/stdout -o report.json

Quiet mode (suppress informational messages)

静默模式（抑制信息性消息）

brakeman -q


Available output formats: `text`, `html`, `tabs`, `json`, `junit`, `markdown`, `csv`, `codeclimate`, `sonar`

brakeman -q


支持的输出格式：`text`, `html`, `tabs`, `json`, `junit`, `markdown`, `csv`, `codeclimate`, `sonar`

Workflow Decision Tree

工作流决策树

Is Brakeman already installed?
├─ No → Install using gem, bundler, or docker
└─ Yes → Continue

What is the goal?
├─ Initial security assessment → Run basic scan: `brakeman`
├─ Generate report for review → Choose format: `brakeman -o report.html`
├─ CI/CD integration → Use JSON output: `brakeman -o report.json`
├─ Too many warnings → Adjust confidence level or filter checks
├─ False positives → Use interactive ignore tool: `brakeman -I`
├─ Compare with previous scan → Use --compare flag
└─ Configuration needed → Create config/brakeman.yml

是否已安装Brakeman？
├─ 否 → 使用gem、bundler或docker安装
└─ 是 → 继续

你的目标是什么？
├─ 初始安全评估 → 运行基础扫描：`brakeman`
├─ 生成供审核的报告 → 选择格式：`brakeman -o report.html`
├─ CI/CD集成 → 使用JSON输出：`brakeman -o report.json`
├─ 警告过多 → 调整置信度等级或过滤检查项
├─ 误报 → 使用交互式忽略工具：`brakeman -I`
├─ 与之前的扫描结果对比 → 使用--compare参数
└─ 需要配置 → 创建config/brakeman.yml

Confidence Levels

置信度等级

Brakeman assigns confidence levels to each warning:

High: Simple warning or user input very likely being used unsafely
Medium: Unsafe use of variable that may or may not be user input
Weak: User input indirectly used in potentially unsafe manner

Filter warnings by confidence level:

bash

undefined

Brakeman会为每个警告分配置信度等级：

高：简单明确的警告，或用户输入极有可能被不安全使用
中：变量被不安全使用，但该变量可能是也可能不是用户输入
低：用户输入被间接用于潜在不安全的场景

按置信度等级过滤警告：

bash

undefined

Only high confidence warnings

仅显示高置信度警告

brakeman -w3

High and medium confidence warnings

显示高和中置信度警告

brakeman -w2

All warnings (default)

显示所有警告（默认）

brakeman -w1

undefined

brakeman -w1

undefined

Managing Warnings

警告管理

Filtering Checks

过滤检查项

Run only specific checks:

bash

undefined

仅运行特定的检查项：

bash

undefined

Run only SQL and XSS checks

仅运行SQL和XSS检查

brakeman -t SQL,CrossSiteScripting

Skip specific checks

跳过特定检查项

brakeman -x DefaultRoutes,Redirect

Skip multiple checks

跳过多个检查项

brakeman -x DefaultRoutes,Redirect,SQL


Use `brakeman --checks` to list all available check names (case-sensitive).

brakeman -x DefaultRoutes,Redirect,SQL


使用`brakeman --checks`查看所有可用的检查项名称（区分大小写）。

Interactive Ignore Configuration

交互式忽略配置

Manage false positives interactively:

bash

brakeman -I

This launches an interactive tool that:

Presents each warning with context
Allows you to ignore, skip, or add notes
Saves configuration to
```
config/brakeman.ignore
```

Options during interactive review:

```
i
```
- Add warning to ignore list
```
n
```
- Add warning to ignore list with note (recommended)
```
s
```
- Skip this warning
```
u
```
- Remove from ignore list
```
a
```
- Ignore remaining warnings
```
k
```
- Skip remaining warnings
```
q
```
- Quit without saving

Always add notes when ignoring warnings to document why they're false positives.

以交互方式管理误报：

bash

brakeman -I

这会启动一个交互式工具，功能如下：

展示每个警告及上下文信息
允许你忽略、跳过或添加备注
将配置保存到
```
config/brakeman.ignore
```

交互式审核中的操作选项：

```
i
```
- 将警告添加到忽略列表
```
n
```
- 将警告添加到忽略列表并添加备注（推荐）
```
s
```
- 跳过此警告
```
u
```
- 从忽略列表中移除
```
a
```
- 忽略剩余所有警告
```
k
```
- 跳过剩余所有警告
```
q
```
- 不保存并退出

忽略警告时务必添加备注，说明标记为误报的原因。

Show Ignored Warnings

查看已忽略的警告

Temporarily view ignored warnings without affecting exit code:

bash

brakeman --show-ignored

临时查看已忽略的警告，且不影响退出码：

bash

brakeman --show-ignored

Comparing Scans

扫描结果对比

Track security improvements or regressions by comparing scans:

bash

undefined

通过对比扫描结果来跟踪安全状况的改进或倒退：

bash

undefined

Generate baseline report

生成基准报告

brakeman -o baseline.json

Run new scan and compare

运行新扫描并对比

brakeman --compare baseline.json


Output shows:
- Fixed warnings (resolved since baseline)
- New warnings (introduced since baseline)

brakeman --compare baseline.json


输出内容包括：
- 已修复的警告（自基准扫描后解决的问题）
- 新增的警告（自基准扫描后出现的问题）

Configuration

配置

Configuration Files

配置文件

Store Brakeman options in YAML configuration files. Default locations (checked in order):

```
./config/brakeman.yml
```
```
~/.brakeman/config.yml
```
```
/etc/brakeman/config.yml
```

Specify a custom configuration file:

bash

brakeman -c custom_config.yml

可将Brakeman的选项存储在YAML配置文件中。默认检查顺序如下：

```
./config/brakeman.yml
```
```
~/.brakeman/config.yml
```
```
/etc/brakeman/config.yml
```

指定自定义配置文件：

bash

brakeman -c custom_config.yml

Generate Configuration

生成配置

Output current options to create a configuration file:

bash

brakeman -C --skip-files plugins/ > config/brakeman.yml

Command-line options override configuration file settings.

将当前选项输出到文件以创建配置文件：

bash

brakeman -C --skip-files plugins/ > config/brakeman.yml

命令行选项会覆盖配置文件中的设置。

Example Configuration

配置示例

yaml

---
:skip_files:
  - vendor/
  - lib/legacy/
:confidence_level: 2
:output_files:
  - reports/brakeman.html
  - reports/brakeman.json
:quiet: true

yaml

---
:skip_files:
  - vendor/
  - lib/legacy/
:confidence_level: 2
:output_files:
  - reports/brakeman.html
  - reports/brakeman.json
:quiet: true

Performance Optimization

性能优化

Speed up scans with faster mode (skips some features):

bash

brakeman --faster

Equivalent to:

--skip-libs --no-branching

Warning: May miss some vulnerabilities. Use only when scan speed is critical.

Skip problematic files or directories:

bash

brakeman --skip-files file1.rb,vendor/,legacy/

使用快速模式加速扫描（会跳过部分功能）：

bash

brakeman --faster

等效于：

--skip-libs --no-branching

注意：可能会遗漏部分漏洞。仅在扫描速度至关重要时使用。

跳过有问题的文件或目录：

bash

brakeman --skip-files file1.rb,vendor/,legacy/

Advanced Options

高级选项

Safe Methods

安全方法

Mark custom sanitizing methods as safe to reduce false positives:

bash

brakeman --safe-methods sanitize_input,clean_html

将自定义的清理方法标记为安全，以减少误报：

bash

brakeman --safe-methods sanitize_input,clean_html

Exit Codes

退出码

Control exit code behavior:

bash

undefined

控制退出码的行为：

bash

undefined

Don't exit with error on warnings

发现警告时不返回错误退出码

brakeman --no-exit-on-warn

Don't exit with error on scanning errors

扫描出错时不返回错误退出码

brakeman --no-exit-on-error

Both

同时启用上述两项

brakeman --no-exit-on-warn --no-exit-on-error


Default behavior: Non-zero exit code if warnings found or errors encountered.

brakeman --no-exit-on-warn --no-exit-on-error


默认行为：如果发现警告或遇到错误，返回非零退出码。

Debugging

调试

Enable verbose debugging output:

bash

brakeman -d

启用详细的调试输出：

bash

brakeman -d

CI/CD Integration

CI/CD集成

GitHub Actions

Several Brakeman actions available on GitHub Marketplace. Search for "brakeman" in GitHub Actions.

GitHub Marketplace上有多个Brakeman相关的Action。在GitHub Actions中搜索“brakeman”即可找到。

Jenkins

Brakeman plugin available for Jenkins/Hudson integration. See documentation at brakemanscanner.org/docs/jenkins/

有适用于Jenkins/Hudson的Brakeman插件。请查看brakemanscanner.org/docs/jenkins/上的文档。

Guard

For continuous testing during development:

bash

gem install guard-brakeman

用于开发过程中的持续测试：

bash

gem install guard-brakeman

Generic CI Integration

通用CI集成

bash

#!/bin/bash

bash

#!/bin/bash

Example CI script

CI脚本示例

Run Brakeman and save results

运行Brakeman并保存结果

brakeman -o brakeman-report.json -o brakeman-report.html --no-exit-on-warn

Check if there are any high confidence warnings

检查是否存在高置信度警告

if brakeman -w3 --quiet; then echo "No high confidence security warnings found" exit 0 else echo "High confidence security warnings detected!" exit 1 fi

undefined

if brakeman -w3 --quiet; then echo "未发现高置信度安全警告" exit 0 else echo "检测到高置信度安全警告！" exit 1 fi

undefined

Warning Types Reference

警告类型参考

Brakeman detects 30+ vulnerability types. For detailed descriptions and remediation guidance, see

references/warning_types.md

Common warning types include:

SQL Injection
Cross-Site Scripting (XSS)
Command Injection
Mass Assignment
Cross-Site Request Forgery (CSRF)
Remote Code Execution
Path Traversal
Unsafe Redirects
File Access
Authentication Issues
SSL Verification Bypass
Unmaintained Dependencies
And many more...

Brakeman可检测30多种漏洞类型。如需详细描述和修复指导，请查看

references/warning_types.md

。

常见的警告类型包括：

SQL注入
跨站脚本（XSS）
命令注入
批量赋值
跨站请求伪造（CSRF）
远程代码执行
路径遍历
不安全重定向
文件访问
认证问题
SSL验证绕过
未维护的依赖
以及更多...

Command Reference

命令参考

For comprehensive option reference including less common flags and detailed explanations, see

references/command_options.md

如需包含冷门参数和详细说明的完整选项参考，请查看

references/command_options.md

。

Best Practices

最佳实践

Run regularly: Integrate into development workflow and CI/CD pipeline
Start with high confidence: Use
```
-w3
```
initially to focus on critical issues
Document ignored warnings: Always add notes explaining why warnings are ignored
Compare scans: Use
```
--compare
```
to track security posture over time
Review all warnings: Even weak warnings can indicate real vulnerabilities
Keep Brakeman updated: Security checks improve with each release
Don't ignore blindly: Investigate each warning before marking as false positive
Use configuration files: Maintain consistent scan settings across team
Generate multiple formats: HTML for review, JSON for automation
Test ignored warnings periodically: Re-review with
```
--show-ignored
```

定期运行：集成到开发工作流和CI/CD流水线中
从高置信度开始：初始使用
```
-w3
```
来聚焦关键问题
记录忽略的警告：始终添加备注说明忽略警告的原因
对比扫描结果：使用
```
--compare
```
跟踪安全状况的变化
审核所有警告：即使是低置信度警告也可能指向真实漏洞
保持Brakeman更新：每次版本更新都会优化安全检查能力
不要盲目忽略：在标记为误报前先调查每个警告
使用配置文件：在团队中保持一致的扫描设置
生成多种格式：HTML格式用于审核，JSON格式用于自动化
定期复查已忽略的警告：使用
```
--show-ignored
```
重新审核

Common Workflows

常见工作流

Initial Security Audit

初始安全审计

bash

undefined

bash

undefined

1. Run comprehensive scan

1. 运行全面扫描

brakeman -o initial-audit.html -o initial-audit.json

2. Review high confidence warnings first

2. 先查看高置信度警告

brakeman -w3 -o high-confidence.html

3. Interactively manage false positives

3. 以交互方式管理误报

brakeman -I

4. Save configuration for future scans

4. 保存配置供后续扫描使用

brakeman -C > config/brakeman.yml

undefined

brakeman -C > config/brakeman.yml

undefined

CI/CD Security Gate

CI/CD安全门禁

bash

undefined

bash

undefined

Fail build only on high confidence warnings

仅在发现高置信度警告时构建失败

brakeman -w3 --no-exit-on-error

undefined

brakeman -w3 --no-exit-on-error

undefined

Tracking Improvements

跟踪改进情况

bash

undefined

bash

undefined

Baseline scan

基准扫描

brakeman -o baseline.json

After fixes, compare

修复后进行对比

brakeman --compare baseline.json -o improvements.json

undefined

brakeman --compare baseline.json -o improvements.json

undefined

Reducing Noise

减少无效警告

bash

undefined

bash

undefined

Focus on specific vulnerability types

聚焦特定漏洞类型

brakeman -t SQL,CrossSiteScripting,CommandInjection -w2

Or exclude noisy checks

或排除易产生噪音的检查项

brakeman -x DefaultRoutes,Redirect -w2

undefined

brakeman -x DefaultRoutes,Redirect -w2

undefined

Troubleshooting

故障排除

Problem: Too many weak confidence warnings Solution: Use

-w2

-w3

to filter by confidence level

Problem: Scanning is very slow Solution: Use

--faster

flag or

--skip-files

to exclude large directories

Problem: False positives for custom sanitization Solution: Use

--safe-methods

to mark methods as safe

Problem: Warnings about database values Solution: Consider if database values truly safe; if yes, adjust with

--interprocedural

or configuration

Problem: Can't parse certain files Solution: Use

--skip-files

to exclude problematic files

问题：低置信度警告过多 解决方案：使用

-w2

或

-w3

按置信度等级过滤

问题：扫描速度极慢 解决方案：使用

--faster

参数或

--skip-files

排除大型目录

问题：自定义清理方法被误报 解决方案：使用

--safe-methods

将方法标记为安全

问题：出现关于数据库值的警告 解决方案：确认数据库值是否真的安全；若安全，可使用

--interprocedural

或配置文件调整

问题：无法解析某些文件 解决方案：使用

--skip-files

排除有问题的文件

Resources

资源

references/warning_types.md

Comprehensive descriptions of all 30+ vulnerability types Brakeman can detect, including examples and remediation guidance.

包含Brakeman可检测的30多种漏洞类型的详细描述、示例和修复指导。

references/command_options.md

Complete command-line reference with detailed explanations of all available options and flags.

完整的命令行参考，包含所有可用参数和详细说明。

references/reducing_false_positives.md

Strategies and techniques for minimizing false positives while maintaining security coverage.

减少误报的策略和技巧，同时保持安全覆盖范围。