Ruzzy
Ruzzy 是一款基於 libFuzzer 的覆蓋引導式 Ruby 模糊測試器。它能夠對純 Ruby 程式碼和 Ruby C 擴充進行模糊測試,並提供 sanitizer 支援以偵測記憶體毀損與未定義行為。
使用時機
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
驗證
執行玩具範例來驗證安裝(請見快速開始章節)。
撰寫 Harness
模糊測試純 Ruby 程式碼
由於 Ruby 直譯器的實作細節,純 Ruby 模糊測試需要兩個腳本。
追蹤器腳本(test_tracer.rb):
# frozen_string_literal: true
require 'ruzzy'
Ruzzy.trace('test_harness.rb')
Harness 腳本(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 擴充可以使用單一 harness 檔案進行模糊測試,無需追蹤器。
msgpack 的範例 harness(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
Harness 規則
| 要點 | 避免事項 |
|---|---|
| 若測試 C 擴充,請捕獲 Ruby 異常 | 讓 Ruby 異常導致模糊測試器崩潰 |
| 從 test_one_input lambda 回傳 0 | 回傳其他值 |
| 保持 harness 確定性 | 使用隨機性或基於時間的邏輯 |
| 針對純 Ruby 使用追蹤器腳本 | 為純 Ruby 程式碼省略追蹤器 |
另請參閱: 關於詳細的 harness 撰寫技巧、處理複雜輸入的模式, 以及進階策略,請見 fuzz-harness-writing 技巧技能。
編譯
使用 Sanitizer 安裝 Gem
在安裝含有 C 擴充的 Ruby Gem 以進行模糊測試時,請使用 sanitizer 標記編譯:
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 | 提升與 sanitizer 的相容性 |
-fPIC | 產生位置無關程式碼供共享函式庫使用 |
-g | 包含除錯符號 |
執行戰役
環境設定
在執行任何模糊測試戰役之前,設定 ASAN_OPTIONS:
export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"
選項說明:
allocator_may_return_null=1:跳過常見的低影響配置失敗(阻斷服務)detect_leaks=0:Ruby 直譯器會洩漏資料,暫時忽略這些use_sigaltstack=0:Ruby 建議在使用 ASan 時停用 sigaltstack
基本執行
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby harness.rb
注意: LD_PRELOAD 是 sanitizer 注入所必需的。與 ASAN_OPTIONS 不同,請勿將其匯出,因為它可能會干擾其他程式。
搭配 Corpus
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 編碼 |
Sanitizer 整合
AddressSanitizer (ASan)
Ruzzy 包含預先編譯的 AddressSanitizer 函式庫:
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby harness.rb
使用 ASan 偵測:
- 堆積緩衝區溢位
- 堆疊緩衝區溢位
- 釋放後使用(Use-After-Free)
- 雙重釋放
- 記憶體洩漏(Ruzzy 預設停用)
UndefinedBehaviorSanitizer (UBSan)
Ruzzy 也包含 UBSan:
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::UBSAN_PATH') \
ruby harness.rb
使用 UBSan 偵測:
- 有號整數溢位
- 空指標解參考
- 未對齊的記憶體存取
- 除零錯誤
常見 Sanitizer 問題
| 問題 | 解決方案 |
|---|---|
| Ruby 直譯器洩漏警告 | 使用 ASAN_OPTIONS=detect_leaks=0 |
| Sigaltstack 衝突 | 使用 ASAN_OPTIONS=use_sigaltstack=0 |
| 配置失敗訊息過多 | 使用 ASAN_OPTIONS=allocator_may_return_null=1 |
| LD_PRELOAD 干擾工具 | 不要匯出;在 ruby 指令中內聯設定 |
另請參閱: 關於詳細的 sanitizer 配置、常見問題及進階標記, 請見 address-sanitizer 與 undefined-behavior-sanitizer 技巧技能。
真實世界範例
範例:msgpack-ruby
對 msgpack MessagePack 解析器進行模糊測試以找出記憶體毀損。
使用 sanitizer 安裝:
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
Harness(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')
Harness(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 |
| 模糊測試器立即退出 | 缺少 corpus 目錄 | 建立 corpus 目錄或將其作為引數傳遞 |
| 無覆蓋進度 | 純 Ruby 需要追蹤器 | 為純 Ruby 程式碼使用追蹤器腳本 |
| 洩漏偵測訊息過多 | Ruby 直譯器洩漏 | 設定 ASAN_OPTIONS=detect_leaks=0 |
| 需要安裝除錯 | 編譯錯誤 | 使用 RUZZY_DEBUG=1 gem install --verbose ruzzy |
相關技能
技巧技能
| 技能 | 使用案例 |
|---|---|
| fuzz-harness-writing | 撰寫有效 harness 的詳細指導 |
| address-sanitizer | 模糊測試期間的記憶體錯誤偵測 |
| undefined-behavior-sanitizer | 偵測 C 擴充中的未定義行為 |
| libfuzzer | 了解 libFuzzer 選項(Ruzzy 基於 libFuzzer) |
相關模糊測試器
| 技能 | 何時考慮 |
|---|---|
| libfuzzer | 直接在 C/C++ 中模糊測試 Ruby C 擴充程式碼時 |
| aflpp | 透過儀器化 Ruby 直譯器進行模糊測試的替代方法 |
資源
主要外部資源
Introducing Ruzzy, a coverage-guided Ruby fuzzer Trail of Bits 官方部落格文章宣布 Ruzzy,涵蓋動機、架構與初步結果。
Ruzzy GitHub 儲存庫 原始碼、額外範例與開發說明。
libFuzzer 文件 由於 Ruzzy 基於 libFuzzer,了解 libFuzzer 選項與行為非常有價值。
模糊測試 Ruby C 擴充 關於使用編譯標記與範例模糊測試 C 擴充的詳細指南。
模糊測試純 Ruby 程式碼 關於純 Ruby 模糊測試所需追蹤器模式的詳細指南。