Ruzzy

Ruzzy は libFuzzer 上に構築された Ruby 用のカバレッジガイド型ファザーです。メモリ破損と未定義動作を検出するためのサニタイザーサポート付きで、純粋な Ruby コードと Ruby C 拡張の両方をファジングできます。

使用場面

Ruzzy は現在、Ruby 向けの唯一の本番対応カバレッジガイド型ファザーです。

Ruzzy を選択する場合:

• Ruby アプリケーションやライブラリをファジングしている
• Ruby C 拡張のメモリ安全性の問題をテストしている
• Ruby コード用のカバレッジガイド型ファジングが必要である
• ネイティブ拡張を持つ Ruby gem を使用している

クイックスタート

環境をセットアップ:

export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"

付属のサンプル例でテスト:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby -e 'require "ruzzy"; Ruzzy.dummy'

これにより Ruzzy が正しく動作していることを示すクラッシュがすぐに見つかるはずです。

インストール

プラットフォームサポート

Ruzzy は Linux x86-64 と AArch64/ARM64 をサポートしています。macOS または Windows の場合は、Dockerfile または開発環境を使用してください。

前提条件

• Linux x86-64 または AArch64/ARM64
• 最近のバージョンの clang (14.0.0 までテスト済み、最新リリース推奨)
• gem がインストールされた Ruby

インストールコマンド

clang コンパイラフラグで Ruzzy をインストール:

MAKE="make --environment-overrides V=1" \
CC="/path/to/clang" \
CXX="/path/to/clang++" \
LDSHARED="/path/to/clang -shared" \
LDSHAREDXX="/path/to/clang++ -shared" \
    gem install ruzzy

環境変数の説明:

• MAKE: make をオーバーライドして後続の環境変数を尊重させる
• CC, CXX, LDSHARED, LDSHAREDXX: 最新機能のために適切な clang バイナリが使用されることを確認

インストールのトラブルシューティング

インストールが失敗する場合、デバッグ出力を有効にする:

RUZZY_DEBUG=1 gem install --verbose ruzzy

検証

サンプル例を実行してインストールを検証 (「クイックスタート」セクションを参照)。

ハーネスの作成

純粋な Ruby コードのファジング

Ruby インタープリタの実装の詳細のため、純粋な Ruby ファジングには 2 つのスクリプトが必要です。

トレーサースクリプト (test_tracer.rb):

# frozen_string_literal: true

require 'ruzzy'

Ruzzy.trace('test_harness.rb')

ハーネススクリプト (test_harness.rb):

# frozen_string_literal: true

require 'ruzzy'

def fuzzing_target(input)
  # ここにファジングするコードを記述
  if input.length == 4
    if input[0] == 'F'
      if input[1] == 'U'
        if input[2] == 'Z'
          if input[3] == 'Z'
            raise
          end
        end
      end
    end
  end
end

test_one_input = lambda do |data|
  fuzzing_target(data)
  return 0
end

Ruzzy.fuzz(test_one_input)

実行:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby test_tracer.rb

Ruby C 拡張のファジング

C 拡張は単一のハーネスファイルでファジングでき、トレーサーは不要です。

msgpack のハーネス例 (fuzz_msgpack.rb):

# frozen_string_literal: true

require 'msgpack'
require 'ruzzy'

test_one_input = lambda do |data|
  begin
    MessagePack.unpack(data)
  rescue Exception
    # メモリ破損を探しており、Ruby 例外ではない
  end
  return 0
end

Ruzzy.fuzz(test_one_input)

実行:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby fuzz_msgpack.rb

ハーネスルール

する	しない
C 拡張をテストする場合は Ruby 例外をキャッチ	Ruby 例外でファザーをクラッシュさせる
test_one_input ラムダから 0 を返す	他の値を返す
ハーネスを決定的に保つ	ランダムネスや時間ベースのロジックを使用
純粋 Ruby にトレーサースクリプトを使用	純粋 Ruby コードのトレーサーをスキップ

参照: ハーネス作成の詳細なテクニック、複雑な入力の処理パターン、 高度な戦略については、fuzz-harness-writing テクニックスキルを参照してください。

コンパイル

サニタイザー付き gem のインストール

ファジング用の C 拡張を含む Ruby gem をインストールする場合、サニタイザーフラグでコンパイル:

MAKE="make --environment-overrides V=1" \
CC="/path/to/clang" \
CXX="/path/to/clang++" \
LDSHARED="/path/to/clang -shared" \
LDSHAREDXX="/path/to/clang++ -shared" \
CFLAGS="-fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g" \
CXXFLAGS="-fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g" \
    gem install <gem-name>

ビルドフラグ

フラグ	目的
-fsanitize=address,fuzzer-no-link	AddressSanitizer とファザーインストルメンテーションを有効化
-fno-omit-frame-pointer	スタックトレース品質を改善
-fno-common	サニタイザーとの互換性向上
-fPIC	位置独立コード (共有ライブラリ向け)
-g	デバッグシンボルを含める

キャンペーンの実行

環境セットアップ

ファジングキャンペーンを実行する前に、ASAN_OPTIONS を設定:

export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"

オプションの説明:

1. allocator_may_return_null=1: 一般的な低影響のアロケーション失敗 (DoS) をスキップ
2. detect_leaks=0: Ruby インタープリタはデータをリーク、これらは今のところ無視
3. use_sigaltstack=0: Ruby は ASan で sigaltstack を無効にすることを推奨

基本実行

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby harness.rb

注: LD_PRELOAD はサニタイザー注入に必須です。ASAN_OPTIONS と異なり、他のプログラムに干渉する可能性があるためエクスポートしないでください。

コーパス付き

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby harness.rb /path/to/corpus

libFuzzer オプションの引き渡し

すべての libFuzzer オプションを引数として渡すことができます:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby harness.rb /path/to/corpus -max_len=1024 -timeout=10

完全な参照は libFuzzer オプション を参照してください。

クラッシュの再現

クラッシュファイルを渡してクラッシュケースを再実行:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby harness.rb ./crash-253420c1158bc6382093d409ce2e9cff5806e980

出力の解釈

出力	意味
INFO: Running with entropic power schedule	ファジングキャンペーン開始
ERROR: AddressSanitizer: heap-use-after-free	メモリ破損検出
SUMMARY: libFuzzer: fuzz target exited	Ruby 例外が発生
artifact_prefix='./'; Test unit written to ./crash-*	クラッシュ入力保存
Base64: ...	クラッシュ入力の Base64 エンコーディング

サニタイザーの統合

AddressSanitizer (ASan)

Ruzzy には事前コンパイルされた AddressSanitizer ライブラリが含まれます:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby harness.rb

ASan を使用して検出:

• ヒープバッファオーバーフロー
• スタックバッファオーバーフロー
• Use-after-free
• Double-free
• メモリリーク (Ruzzy ではデフォルトで無効)

UndefinedBehaviorSanitizer (UBSan)

Ruzzy には UBSan も含まれます:

LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::UBSAN_PATH') \
    ruby harness.rb

UBSan を使用して検出:

• 符号付き整数オーバーフロー
• ヌルポインタの逆参照
• メモリ不整列アクセス
• ゼロ除算

よくあるサニタイザーの問題

問題	解決方法
Ruby インタープリタリーク警告	ASAN_OPTIONS=detect_leaks=0 を使用
Sigaltstack 競合	ASAN_OPTIONS=use_sigaltstack=0 を使用
アロケーション失敗スパム	ASAN_OPTIONS=allocator_may_return_null=1 を使用
LD_PRELOAD がツールに干渉	エクスポートしない、ruby コマンドでインラインに設定

参照: サニタイザーの詳細な設定、よくある問題、高度なフラグについては、 address-sanitizer と undefined-behavior-sanitizer テクニックスキルを参照してください。

実例

例: msgpack-ruby

メモリ破損について msgpack MessagePack パーサーをファジング。

サニタイザー付きでインストール:

MAKE="make --environment-overrides V=1" \
CC="/path/to/clang" \
CXX="/path/to/clang++" \
LDSHARED="/path/to/clang -shared" \
LDSHAREDXX="/path/to/clang++ -shared" \
CFLAGS="-fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g" \
CXXFLAGS="-fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g" \
    gem install msgpack

ハーネス (fuzz_msgpack.rb):

# frozen_string_literal: true

require 'msgpack'
require 'ruzzy'

test_one_input = lambda do |data|
  begin
    MessagePack.unpack(data)
  rescue Exception
    # メモリ破損を探しており、Ruby 例外ではない
  end
  return 0
end

Ruzzy.fuzz(test_one_input)

実行:

export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby fuzz_msgpack.rb

例: 純粋 Ruby ターゲット

カスタムパーサーで純粋な Ruby コードをファジング。

トレーサー (test_tracer.rb):

# frozen_string_literal: true

require 'ruzzy'

Ruzzy.trace('test_harness.rb')

ハーネス (test_harness.rb):

# frozen_string_literal: true

require 'ruzzy'
require_relative 'my_parser'

test_one_input = lambda do |data|
  begin
    MyParser.parse(data)
  rescue StandardError
    # 不正な入力からの予期される例外
  end
  return 0
end

Ruzzy.fuzz(test_one_input)

実行:

export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
    ruby test_tracer.rb

トラブルシューティング

問題	原因	解決方法
インストール失敗	不正な clang バージョンまたはパス	clang パスを確認、clang 14.0.0+ を使用
cannot open shared object file	LD_PRELOAD が設定されていない	ruby コマンドでインラインに LD_PRELOAD を設定
ファザーが即座に終了	コーパスディレクトリが見つからない	コーパスディレクトリを作成または引数として渡す
カバレッジの進行がない	純粋 Ruby にトレーサーが必要	純粋 Ruby コードにトレーサースクリプトを使用
リーク検出スパム	Ruby インタープリタがリーク	ASAN_OPTIONS=detect_leaks=0 を設定
インストールデバッグが必要	コンパイルエラー	RUZZY_DEBUG=1 gem install --verbose ruzzy を使用

関連スキル

テクニックスキル

スキル	使用例
fuzz-harness-writing	効果的なハーネス作成の詳細なガイダンス
address-sanitizer	ファジング中のメモリエラー検出
undefined-behavior-sanitizer	C 拡張での未定義動作の検出
libfuzzer	libFuzzer オプションの理解 (Ruzzy は libFuzzer 上に構築)

関連ファザー

スキル	検討する場合
libfuzzer	Ruby C 拡張コードを直接 C/C++ でファジング
aflpp	Ruby インタープリタをインストルメンテーションすることで Ruby をファジングする別のアプローチ

リソース

主要な外部リソース

Introducing Ruzzy, a coverage-guided Ruby fuzzer Ruzzy を発表する Trail of Bits 公式ブログ記事、動機、アーキテクチャ、初期結果をカバー。

Ruzzy GitHub Repository ソースコード、追加の例、開発手順。

libFuzzer Documentation Ruzzy は libFuzzer 上に構築されているため、libFuzzer オプションと動作を理解することは有用です。

Fuzzing Ruby C extensions コンパイルフラグと例を使用した C 拡張のファジング詳細ガイド。

Fuzzing pure Ruby code 純粋 Ruby ファジングに必要なトレーサーパターンの詳細ガイド。