鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

ruzzy

提供面向 Ruby 代码的覆盖率引导式模糊测试能力,支持纯 Ruby 脚本与 C 扩展的内存安全缺陷挖掘,集成 AddressSanitizer 和 UndefinedBehaviorSanitizer 检测堆栈溢出、use-after-free、整数溢出等深层问题。

测试与安全
访问 GitHub
文档Skills.MD
name
ruzzy
type
fuzzer
description
Ruzzy is a coverage-guided Ruby fuzzer by Trail of Bits. Use for fuzzing pure Ruby code and Ruby C extensions.

Ruzzy

Ruzzy is a coverage-guided fuzzer for Ruby built on libFuzzer. It enables fuzzing both pure Ruby code and Ruby C extensions with sanitizer support for detecting memory corruption and undefined behavior.

When to Use

Ruzzy is currently the only production-ready coverage-guided fuzzer for Ruby.

Choose Ruzzy when:

  • Fuzzing Ruby applications or libraries
  • Testing Ruby C extensions for memory safety issues
  • You need coverage-guided fuzzing for Ruby code
  • Working with Ruby gems that have native extensions

Quick Start

Set up environment:

▼
bash
复制代码
export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"

Test with the included toy example:

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \ ruby -e 'require "ruzzy"; Ruzzy.dummy'

This should quickly find a crash demonstrating that Ruzzy is working correctly.

Installation

Platform Support

Ruzzy supports Linux x86-64 and AArch64/ARM64. For macOS or Windows, use the Dockerfile or development environment.

Prerequisites

  • Linux x86-64 or AArch64/ARM64
  • Recent version of clang (tested back to 14.0.0, latest release recommended)
  • Ruby with gem installed

Installation Command

Install Ruzzy with clang compiler flags:

▼
bash
复制代码
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

Environment variables explained:

  • MAKE: Overrides make to respect subsequent environment variables
  • CC, CXX, LDSHARED, LDSHAREDXX: Ensure proper clang binaries are used for latest features

Troubleshooting Installation

If installation fails, enable debug output:

▼
bash
复制代码
RUZZY_DEBUG=1 gem install --verbose ruzzy

Verification

Verify installation by running the toy example (see Quick Start section).

Writing a Harness

Fuzzing Pure Ruby Code

Pure Ruby fuzzing requires two scripts due to Ruby interpreter implementation details.

Tracer script (test_tracer.rb):

▼
ruby
复制代码
# frozen_string_literal: true require 'ruzzy' Ruzzy.trace('test_harness.rb')

Harness script (test_harness.rb):

▼
ruby
复制代码
# frozen_string_literal: true require 'ruzzy' def fuzzing_target(input) # Your code to fuzz here 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)

Run with:

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \ ruby test_tracer.rb

Fuzzing Ruby C Extensions

C extensions can be fuzzed with a single harness file, no tracer needed.

Example harness for msgpack (fuzz_msgpack.rb):

▼
ruby
复制代码
# frozen_string_literal: true require 'msgpack' require 'ruzzy' test_one_input = lambda do |data| begin MessagePack.unpack(data) rescue Exception # We're looking for memory corruption, not Ruby exceptions end return 0 end Ruzzy.fuzz(test_one_input)

Run with:

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \ ruby fuzz_msgpack.rb

Harness Rules

DoDon't
Catch Ruby exceptions if testing C extensionsLet Ruby exceptions crash the fuzzer
Return 0 from test_one_input lambdaReturn other values
Keep harness deterministicUse randomness or time-based logic
Use tracer script for pure RubySkip tracer for pure Ruby code

See Also: For detailed harness writing techniques, patterns for handling complex inputs, and advanced strategies, see the fuzz-harness-writing technique skill.

Compilation

Installing Gems with Sanitizers

When installing Ruby gems with C extensions for fuzzing, compile with sanitizer flags:

▼
bash
复制代码
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>

Build Flags

FlagPurpose
-fsanitize=address,fuzzer-no-linkEnable AddressSanitizer and fuzzer instrumentation
-fno-omit-frame-pointerImprove stack trace quality
-fno-commonBetter compatibility with sanitizers
-fPICPosition-independent code for shared libraries
-gInclude debug symbols

Running Campaigns

Environment Setup

Before running any fuzzing campaign, set ASAN_OPTIONS:

▼
bash
复制代码
export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"

Options explained:

  1. allocator_may_return_null=1: Skip common low-impact allocation failures (DoS)
  2. detect_leaks=0: Ruby interpreter leaks data, ignore these for now
  3. use_sigaltstack=0: Ruby recommends disabling sigaltstack with ASan

Basic Run

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \ ruby harness.rb

Note: LD_PRELOAD is required for sanitizer injection. Unlike ASAN_OPTIONS, do not export it as it may interfere with other programs.

With Corpus

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

Passing libFuzzer Options

All libFuzzer options can be passed as arguments:

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

See libFuzzer options for full reference.

Reproducing Crashes

Re-run a crash case by passing the crash file:

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

Interpreting Output

OutputMeaning
INFO: Running with entropic power scheduleFuzzing campaign started
ERROR: AddressSanitizer: heap-use-after-freeMemory corruption detected
SUMMARY: libFuzzer: fuzz target exitedRuby exception occurred
artifact_prefix='./'; Test unit written to ./crash-*Crash input saved
Base64: ...Base64 encoding of crash input

Sanitizer Integration

AddressSanitizer (ASan)

Ruzzy includes a pre-compiled AddressSanitizer library:

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \ ruby harness.rb

Use ASan for detecting:

  • Heap buffer overflows
  • Stack buffer overflows
  • Use-after-free
  • Double-free
  • Memory leaks (disabled by default in Ruzzy)

UndefinedBehaviorSanitizer (UBSan)

Ruzzy also includes UBSan:

▼
bash
复制代码
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::UBSAN_PATH') \ ruby harness.rb

Use UBSan for detecting:

  • Signed integer overflow
  • Null pointer dereferences
  • Misaligned memory access
  • Division by zero

Common Sanitizer Issues

IssueSolution
Ruby interpreter leak warningsUse ASAN_OPTIONS=detect_leaks=0
Sigaltstack conflictsUse ASAN_OPTIONS=use_sigaltstack=0
Allocation failure spamUse ASAN_OPTIONS=allocator_may_return_null=1
LD_PRELOAD interferes with toolsDon't export it; set inline with ruby command

See Also: For detailed sanitizer configuration, common issues, and advanced flags, see the address-sanitizer and undefined-behavior-sanitizer technique skills.

Real-World Examples

Example: msgpack-ruby

Fuzzing the msgpack MessagePack parser for memory corruption.

Install with sanitizers:

▼
bash
复制代码
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):

▼
ruby
复制代码
# frozen_string_literal: true require 'msgpack' require 'ruzzy' test_one_input = lambda do |data| begin MessagePack.unpack(data) rescue Exception # We're looking for memory corruption, not Ruby exceptions end return 0 end Ruzzy.fuzz(test_one_input)

Run:

▼
bash
复制代码
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

Example: Pure Ruby Target

Fuzzing pure Ruby code with a custom parser.

Tracer (test_tracer.rb):

▼
ruby
复制代码
# frozen_string_literal: true require 'ruzzy' Ruzzy.trace('test_harness.rb')

Harness (test_harness.rb):

▼
ruby
复制代码
# frozen_string_literal: true require 'ruzzy' require_relative 'my_parser' test_one_input = lambda do |data| begin MyParser.parse(data) rescue StandardError # Expected exceptions from malformed input end return 0 end Ruzzy.fuzz(test_one_input)

Run:

▼
bash
复制代码
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

Troubleshooting

ProblemCauseSolution
Installation failsWrong clang version or pathVerify clang path, use clang 14.0.0+
cannot open shared object fileLD_PRELOAD not setSet LD_PRELOAD inline with ruby command
Fuzzer immediately exitsMissing corpus directoryCreate corpus directory or pass as argument
No coverage progressPure Ruby needs tracerUse tracer script for pure Ruby code
Leak detection spamRuby interpreter leaksSet ASAN_OPTIONS=detect_leaks=0
Installation debug neededCompilation errorsUse RUZZY_DEBUG=1 gem install --verbose ruzzy

Related Skills

Technique Skills

SkillUse Case
fuzz-harness-writingDetailed guidance on writing effective harnesses
address-sanitizerMemory error detection during fuzzing
undefined-behavior-sanitizerDetecting undefined behavior in C extensions
libfuzzerUnderstanding libFuzzer options (Ruzzy is built on libFuzzer)

Related Fuzzers

SkillWhen to Consider
libfuzzerWhen fuzzing Ruby C extension code directly in C/C++
aflppAlternative approach for fuzzing Ruby by instrumenting Ruby interpreter

Resources

Key External Resources

Introducing Ruzzy, a coverage-guided Ruby fuzzer Official Trail of Bits blog post announcing Ruzzy, covering motivation, architecture, and initial results.

Ruzzy GitHub Repository Source code, additional examples, and development instructions.

libFuzzer Documentation Since Ruzzy is built on libFuzzer, understanding libFuzzer options and behavior is valuable.

Fuzzing Ruby C extensions Detailed guide on fuzzing C extensions with compilation flags and examples.

Fuzzing pure Ruby code Detailed guide on the tracer pattern required for pure Ruby fuzzing.

测试与安全

快捷安装

复制到终端去安装 Skill

npxskillsaddtrailofbits/skills--skill"ruzzy"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
tdd-process
严格遵循测试驱动开发的红绿重构循环,强制执行先写测试、失败要有意义、实现最小化、验证全覆盖的全流程,确保每次代码变更都由可执行的测试用例驱动并经编译、检查与全量验证确认。
smoke-test
自动化创建 Mastra 项目并完成 Studio 全流程冒烟测试,涵盖项目初始化、环境配置、本地服务启动及 Chrome 浏览器中对 Agents、Tools、Workflows、Scorers 等核心模块的功能验证与截图记录。
property-based-testing
通过生成随机输入验证代码在各类边界条件下的行为一致性,适用于序列化、解析、归一化及纯函数等场景,能有效发现隐含缺陷并提升测试覆盖率,尤其适合需要高可靠性的算法与智能合约验证。