brakeman

Brakeman 安全扫描器

概述

Brakeman 是一款静态分析工具，可在无需运行应用程序的情况下检查 Ruby on Rails 应用程序中的安全漏洞。它会分析源代码，以检测 SQL 注入、跨站脚本（XSS）、命令注入、批量赋值以及许多其他类型的漏洞。

安装

运行扫描前，请确认已安装 Brakeman。如果尚未安装，请使用以下方法之一进行安装：

# Using RubyGems (recommended)
gem install brakeman

# Using Bundler (add to Gemfile)
group :development do
  gem 'brakeman', require: false
end

# Using Docker
docker pull presidentbeef/brakeman

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

基本用法

快速扫描

在 Rails 应用程序根目录下运行基本安全扫描：

brakeman

在 Rails 根目录之外运行：

brakeman /path/to/rails/application

输出格式

生成各种格式的报告：

# HTML report
brakeman -o report.html

# JSON report (useful for comparison and automation)
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

可用的输出格式：text、html、tabs、json、junit、markdown、csv、codeclimate、sonar

工作流决策树

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 会为每条警告指定置信度级别：

• 高：简单警告，或很可能以不安全方式使用了用户输入
• 中：以不安全方式使用了变量，但该变量是否为用户输入尚不确定
• 弱：以间接方式使用用户输入，可能导致不安全行为

按置信度级别筛选警告：

# Only high confidence warnings
brakeman -w3

# High and medium confidence warnings
brakeman -w2

# All warnings (default)
brakeman -w1

管理警告

筛选检查项

仅运行特定检查项：

# Run only SQL and XSS checks
brakeman -t SQL,CrossSiteScripting

# Skip specific checks
brakeman -x DefaultRoutes,Redirect

# Skip multiple checks
brakeman -x DefaultRoutes,Redirect,SQL

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

交互式忽略配置

以交互方式管理误报：

brakeman -I

这会启动一个交互式工具，该工具将：

1. 显示每条警告及其上下文
2. 允许你忽略、跳过警告或添加备注
3. 将配置保存到 config/brakeman.ignore

交互式审查期间可用的选项：

• i - 将警告添加到忽略列表
• n - 将警告连同备注一起添加到忽略列表（推荐）
• s - 跳过此警告
• u - 从忽略列表中移除
• a - 忽略剩余警告
• k - 跳过剩余警告
• q - 退出且不保存

忽略警告时，请务必添加备注，说明它们为何属于误报。

显示已忽略的警告

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

brakeman --show-ignored

比较扫描结果

通过比较扫描结果来跟踪安全性改进或退化：

# Generate baseline report
brakeman -o baseline.json

# Run new scan and compare
brakeman --compare baseline.json

输出显示：

• 已修复的警告（自基准扫描以来已解决）
• 新增的警告（自基准扫描以来引入）

配置

配置文件

将 Brakeman 选项存储在 YAML 配置文件中。默认位置（按顺序检查）：

1. ./config/brakeman.yml
2. ~/.brakeman/config.yml
3. /etc/brakeman/config.yml

指定自定义配置文件：

brakeman -c custom_config.yml

生成配置

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

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

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

配置示例

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

性能优化

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

brakeman --faster

等同于：--skip-libs --no-branching

警告：可能会漏掉部分漏洞。仅在扫描速度至关重要时使用。

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

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

高级选项

安全方法

将自定义净化方法标记为安全，以减少误报：

brakeman --safe-methods sanitize_input,clean_html

退出代码

控制退出代码行为：

# 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

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

调试

启用详细的调试输出：

brakeman -d

CI/CD 集成

GitHub Actions

GitHub Marketplace 上提供了多个 Brakeman Actions。在 GitHub Actions 中搜索“brakeman”。

Jenkins

提供用于与 Jenkins/Hudson 集成的 Brakeman 插件。请参阅 brakemanscanner.org/docs/jenkins/ 上的文档。

Guard

在开发期间进行持续测试：

gem install guard-brakeman

通用 CI 集成

#!/bin/bash
# Example CI script

# Run Brakeman and save results
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

警告类型参考

Brakeman 可检测 30 多种漏洞类型。有关详细说明和修复指南，请参阅 references/warning_types.md。

常见警告类型包括：

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

命令参考

有关完整的选项参考，包括较少使用的标志和详细说明，请参阅 references/command_options.md。

最佳实践

1. 定期运行：将其集成到开发工作流和 CI/CD 流水线中
2. 从高置信度开始：初始使用 -w3，重点关注关键问题
3. 记录忽略的警告：始终添加说明，解释忽略警告的原因
4. 比较扫描结果：使用 --compare 跟踪安全状况随时间的变化
5. 检查所有警告：即使是低置信度警告，也可能表明存在真实漏洞
6. 保持 Brakeman 为最新版本：每次发布都会改进安全检查
7. 不要盲目忽略：将警告标记为误报前，先逐一调查
8. 使用配置文件：在团队内保持扫描设置一致
9. 生成多种格式：使用 HTML 格式进行审查，使用 JSON 格式进行自动化处理
10. 定期检查被忽略的警告：使用 --show-ignored 重新审查

常见工作流

初始安全审计

# 1. Run comprehensive scan
brakeman -o initial-audit.html -o initial-audit.json

# 2. Review high confidence warnings first
brakeman -w3 -o high-confidence.html

# 3. Interactively manage false positives
brakeman -I

# 4. Save configuration for future scans
brakeman -C > config/brakeman.yml

CI/CD 安全门禁

# Fail build only on high confidence warnings
brakeman -w3 --no-exit-on-error

跟踪改进情况

# Baseline scan
brakeman -o baseline.json

# After fixes, compare
brakeman --compare baseline.json -o improvements.json

减少噪声

# Focus on specific vulnerability types
brakeman -t SQL,CrossSiteScripting,CommandInjection -w2

# Or exclude noisy checks
brakeman -x DefaultRoutes,Redirect -w2

故障排除

问题：低置信度警告过多
解决方案：使用 -w2 或 -w3 按置信度级别筛选

问题：扫描速度很慢
解决方案：使用 --faster 标志，或使用 --skip-files 排除大型目录

问题：自定义净化处理出现误报
解决方案：使用 --safe-methods 将方法标记为安全

问题：数据库值相关警告
解决方案：考虑数据库值是否确实安全；如果安全，可使用 --interprocedural 或配置进行调整

问题：无法解析某些文件
解决方案：使用 --skip-files 排除有问题的文件

资源

references/warning_types.md

全面介绍 Brakeman 可检测的 30 多种漏洞类型，包括示例和修复指南。

references/command_options.md

完整的命令行参考，详细说明所有可用选项和标志。

references/reducing_false_positives.md

在维持安全覆盖范围的同时，尽量减少误报的策略和方法。