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 安装 Gems
在安装带有 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:跳过常见的低影响分配失败(DoS)detect_leaks=0:Ruby 解释器会泄漏数据,暂时忽略这些use_sigaltstack=0:Ruby 建议在使用 ASan 时禁用 sigaltstack
基本运行
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby harness.rb
注意: sanitizer 注入需要 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 编码 |
Sanitizer 集成
AddressSanitizer (ASan)
Ruzzy 包含一个预编译的 AddressSanitizer 库:
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby harness.rb
使用 ASan 检测:
- 堆缓冲区溢出
- 栈缓冲区溢出
- 释放后使用
- 双重释放
- 内存泄漏(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 |
| 模糊测试器立即退出 | 缺少语料库目录 | 创建语料库目录或将其作为参数传递 |
| 无覆盖率进展 | 纯 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 解释器来模糊测试 Ruby 的替代方法 |
资源
关键外部资源
介绍 Ruzzy,一个覆盖引导的 Ruby 模糊测试工具 Trail of Bits 的官方博客文章宣布了 Ruzzy,涵盖了动机、架构和初步结果。
Ruzzy GitHub 仓库 源代码、更多示例以及开发说明。
libFuzzer 文档 由于 Ruzzy 基于 libFuzzer,了解 libFuzzer 的选项和行为非常有用。
模糊测试 Ruby C 扩展 关于使用编译标志和示例进行 C 扩展模糊测试的详细指南。
模糊测试纯 Ruby 代码 关于纯 Ruby 模糊测试所需跟踪模式的详细指南。