ruzzy skill
✓ OfficialSets up and runs a coverage-guided Ruby fuzzer to test pure Ruby code and native C extensions for memory safety and undefined behavior.
- GitHub stars
- 8,136
- Files
- 3
- Last commit
- Nov 11, 2026
- License
- CC-BY-SA-4.0
- Allowed tools
- —
What does the ruzzy skill do?
ruzzy sets up and runs a coverage-guided Ruby fuzzer to test pure Ruby code and native C extensions for memory safety and undefined behavior.
Summary generated from the skill's SKILL.md.
About the ruzzy skill
Testing Ruby applications and gems for memory corruption and undefined behavior is what Ruzzy enables for developers. This coverage-guided fuzzer, built on libFuzzer, allows you to target both pure Ruby code and native C extensions. It is particularly useful when you need to verify the memory safety of Ruby gems that utilize native extensions or when you are performing general security testing on Ruby libraries.
To use this skill, an agent should load it when tasked with finding crashes or memory errors in a Ruby environment. The tool relies on clang for compilation and uses AddressSanitizer or UndefinedBehaviorSanitizer to detect issues like heap buffer overflows, use-after-free, and null pointer dereferences. When fuzzing pure Ruby, the process requires a specific tracer script and a harness script to manage interpreter implementation details, whereas C extensions can be tested with a single harness file.
What an agent can do with it
- 1Fuzzing Ruby C extensionsVerify that a Ruby gem with native components is safe from memory corruption.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the ruzzy skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the ruzzy skill in Plugin
/plugin marketplace add trailofbits/skills /plugin install testing-handbook-skills@trailofbits
Install the ruzzy skill in Claude Code
~/.claude/skills/ruzzy/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy ~/.claude/skills/ruzzyInstall the ruzzy skill in Claude Code (project)
.claude/skills/ruzzy/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy .claude/skills/ruzzyInstall the ruzzy skill in Codex
~/.agents/skills/ruzzy/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy ~/.agents/skills/ruzzyInstall the ruzzy skill in Gemini CLI
~/.gemini/skills/ruzzy/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy ~/.gemini/skills/ruzzyInstall the ruzzy skill in Claude.ai
npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy ruzzy && zip -r ruzzy.zip ruzzy # claude.ai → Customize → Skills → + → Create skill → Upload a skill → ruzzy.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/testing-hand ↗Pass
- Open source license (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Finding
- Commit or release in the last yearLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 442 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
SKILL.md
View on GitHubRuzzy
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:
export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"
Test with the included toy example:
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:
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 variablesCC,CXX,LDSHARED,LDSHAREDXX: Ensure proper clang binaries are used for latest features
Troubleshooting Installation
If installation fails, enable debug output:
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):
# frozen_string_literal: true
require 'ruzzy'
Ruzzy.trace('test_harness.rb')
Harness script (test_harness.rb):
# 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:
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):
# 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:
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby fuzz_msgpack.rb
Harness Rules
| Do | Don't |
|---|---|
| Catch Ruby exceptions if testing C extensions | Let Ruby exceptions crash the fuzzer |
| Return 0 from test_one_input lambda | Return other values |
| Keep harness deterministic | Use randomness or time-based logic |
| Use tracer script for pure Ruby | Skip 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:
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
| Flag | Purpose |
|---|---|
-fsanitize=address,fuzzer-no-link |
Enable AddressSanitizer and fuzzer instrumentation |
-fno-omit-frame-pointer |
Improve stack trace quality |
-fno-common |
Better compatibility with sanitizers |
-fPIC |
Position-independent code for shared libraries |
-g |
Include debug symbols |
Running Campaigns
Environment Setup
Before running any fuzzing campaign, set ASAN_OPTIONS:
export ASAN_OPTIONS="allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0"
Options explained:
allocator_may_return_null=1: Skip common low-impact allocation failures (DoS)detect_leaks=0: Ruby interpreter leaks data, ignore these for nowuse_sigaltstack=0: Ruby recommends disabling sigaltstack with ASan
Basic Run
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
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:
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:
LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') \
ruby harness.rb ./crash-253420c1158bc6382093d409ce2e9cff5806e980
Interpreting Output
| Output | Meaning |
|---|---|
INFO: Running with entropic power schedule |
Fuzzing campaign started |
ERROR: AddressSanitizer: heap-use-after-free |
Memory corruption detected |
SUMMARY: libFuzzer: fuzz target exited |
Ruby 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:
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:
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
| Issue | Solution |
|---|---|
| Ruby interpreter leak warnings | Use ASAN_OPTIONS=detect_leaks=0 |
| Sigaltstack conflicts | Use ASAN_OPTIONS=use_sigaltstack=0 |
| Allocation failure spam | Use ASAN_OPTIONS=allocator_may_return_null=1 |
| LD_PRELOAD interferes with tools | Don'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:
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
# We're looking for memory corruption, not Ruby exceptions
end
return 0
end
Ruzzy.fuzz(test_one_input)
Run:
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):
# 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
# Expected exceptions from malformed input
end
return 0
end
Ruzzy.fuzz(test_one_input)
Run:
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
| Problem | Cause | Solution |
|---|---|---|
| Installation fails | Wrong clang version or path | Verify clang path, use clang 14.0.0+ |
cannot open shared object file |
LD_PRELOAD not set | Set LD_PRELOAD inline with ruby command |
| Fuzzer immediately exits | Missing corpus directory | Create corpus directory or pass as argument |
| No coverage progress | Pure Ruby needs tracer | Use tracer script for pure Ruby code |
| Leak detection spam | Ruby interpreter leaks | Set ASAN_OPTIONS=detect_leaks=0 |
| Installation debug needed | Compilation errors | Use RUZZY_DEBUG=1 gem install --verbose ruzzy |
Related Skills
Technique Skills
| Skill | Use Case |
|---|---|
| fuzz-harness-writing | Detailed guidance on writing effective harnesses |
| address-sanitizer | Memory error detection during fuzzing |
| undefined-behavior-sanitizer | Detecting undefined behavior in C extensions |
| libfuzzer | Understanding libFuzzer options (Ruzzy is built on libFuzzer) |
Related Fuzzers
| Skill | When to Consider |
|---|---|
| libfuzzer | When fuzzing Ruby C extension code directly in C/C++ |
| aflpp | Alternative 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.
Files in this skill
3ruzzy skill questions
How do I install the ruzzy skill in Claude Code?
Run npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/ruzzy ~/.claude/skills/ruzzy. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the ruzzy skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I fuzz pure Ruby code with Ruzzy?
Pure Ruby fuzzing requires a two-script setup consisting of a tracer script and a harness script.
Can Ruzzy detect memory corruption in Ruby C extensions?
Yes, Ruzzy supports fuzzing Ruby C extensions with sanitizer support to detect memory corruption and undefined behavior.