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 アクションを利用できます。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

セキュリティのカバレッジを維持しながら、誤検知を最小限に抑えるための戦略と手法です。