Communitygithub.com

bg-szy/TOP-SKILLS

设置并运行 Trail of Bits 的 Ruzzy——Ruby 语言中唯一一个生产就绪的覆盖引导模糊测试工具。涵盖 harness 结构、模糊测试纯 Ruby 代码以及 gem 中的原生 C 扩展,并支持 sanitizer 构建。当需要模糊测试 Ruby 库或 gem、测试 Ruby C 扩展的内存安全性,或询问如何对 Ruby 进行模糊测试时使用。

TOP-SKILLS 是什么?

该技能用于配置和运行 Ruzzy,这是 Trail of Bits 开发的、基于 libFuzzer 的覆盖引导模糊测试工具,也是目前 Ruby 语言中唯一一个生产就绪的此类工具。它支持对纯 Ruby 代码和 Ruby C 扩展进行模糊测试,并通过集成 AddressSanitizer 和 UndefinedBehaviorSanitizer 来检测内存损坏和未定义行为。用户可以为需要模糊测试的 gem 安装带有 sanitizer 标志的构建版本,编写 harness 脚本(纯 Ruby 代码需要跟踪脚本模式,C 扩展则只需单个文件),并使用 libFuzzer 选项设置模糊测试活动。该技能涵盖了从安装和编译、运行活动到崩溃复现和结果解读的完整工作流。它适用于 Linux x86-64 和 AArch64/ARM64 平台(macOS 和 Windows 用户可通过 Docker 使用),并提供了真实示例(如 msgpack-ruby)来演示内存安全测试。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bg-szy/TOP-SKILLS/tree/HEAD/skills/skills/ruzzy

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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"

选项说明:

  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

注意: 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 exitedRuby 异常发生
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 模糊测试所需跟踪模式的详细指南。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

bg-szy/TOP-SKILLS

Brand-first landing page designer — runs a brand-identity interview (colors, typography, shape language), then generates and iterates on a polished landing page via Stitch with deployment-ready HTML. Use when the user asks to create, design, or build a landing page, homepage, or marketing page and has no established visual direction. Skip when they have a design mockup, need a dashboard or app UI, are working at component level, building a multi-page app, or restyling with known design tokens — use frontend-design instead.

bg-szy/TOP-SKILLS

Fill out Microsoft Azure Landing Zone (ALZ) Accelerator checklists by interviewing the user, mapping their Azure subscriptions, integrating IP addressing documentation, and applying Microsoft Cloud Adoption Framework best practices. Produces a completed Excel checklist (.xlsx) ready for ALZ deployment. Use this skill whenever the user mentions Azure Landing Zone, ALZ checklist, landing zone accelerator, platform landing zone configuration, ALZ bootstrap, hub-and-spoke setup, Azure network topology planning, or wants to fill out any ALZ-related checklist or configuration file. Also trigger when the user uploads an Excel file that contains tabs like "Accelerator - Bootstrap", "Accelerator - Bicep", or "Accelerator - Terraform".

bg-szy/TOP-SKILLS

Compose a premium, animated landing page section by section in Next.js + Tailwind + Motion (Framer Motion) — built on a real design system, with editorial copy and motion that feels human-crafted, not template-generated. Use when building or rebuilding a landing page, marketing site, or hero/feature/pricing/CTA sections that need to look production-ready and bespoke from day one.

bg-szy/TOP-SKILLS

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

bg-szy/TOP-SKILLS

Optimize landing pages for conversions, performance, and SEO. Use when improving landing pages, increasing conversions, or optimizing page performance.

bg-szy/TOP-SKILLS

Review investment portfolios for risk, diversification, fees. Asset allocation recommendations, tax-loss harvesting, rebalancing.

bg-szy/TOP-SKILLS

Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.

bg-szy/TOP-SKILLS

CI red? Call us. Pipeline fire brigade deploys. Use when user mentions CI failures, build errors, test failures, or pipeline issues. Do NOT load for: local builds, standard implementation work, reviews, or setup.

bg-szy/TOP-SKILLS

CASS Memory System - procedural memory for AI coding agents. Three-layer cognitive architecture with confidence decay, anti-pattern learning, cross-agent knowledge transfer, trauma guard safety system. Bun/TypeScript CLI.

bg-szy/TOP-SKILLS

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

bg-szy/TOP-SKILLS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

bg-szy/TOP-SKILLS

Use when the user asks to "pre-launch check the landing page", "run a Quality-Score preflight", or "verify ad-to-page message match before launch"; produces an ad↔page continuity report — message-match gaps, above-the-fold check, page-speed read, form-friction count, mobile-render flags — as a pass/fix punch list. Not for redesigning or rewriting the page — use landing-optimizer; not for scoring the account or the RQS — use ad-account-auditor. 落地页体验预检/广告落地页一致性检查

bg-szy/TOP-SKILLS

Use when the user asks to "optimize our landing page for influencer traffic", "fix our promo-code landing page", or "improve conversion from a creator campaign"; produces a message-match audit, page-structure and social-proof recommendations, a promo-code/CTA conversion plan, and an A/B test roadmap. Not for measuring campaign results after launch — use performance-analyzer.

bg-szy/TOP-SKILLS

Audit a landing page, sales page or checkout page for conversion leaks and return a fix list ordered by expected revenue impact. Use when asked to review, critique or improve a landing page, sales page, opt-in page, product page or checkout flow, when conversion rate is low, when paid traffic is not converting, or when someone asks "why isn't this page converting" or wants a CRO / landing page review.

bg-szy/TOP-SKILLS

Landing page conversion optimization with layout rules, hero section design, and CTA psychology. Covers above-the-fold formula, social proof placement, mobile design, and F-pattern reading. Use for: startup landing pages, product pages, SaaS marketing, conversion optimization. Triggers: landing page, hero section, above the fold, conversion optimization, landing page design, cta button, hero image, landing page layout, saas landing page, product page design, conversion rate, landing page best practices

bg-szy/TOP-SKILLS

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

bg-szy/TOP-SKILLS

Landing page conversion optimization with layout rules, hero section design, and CTA psychology. Covers above-the-fold formula, social proof placement, mobile design, and F-pattern reading. Use for: startup landing pages, product pages, SaaS marketing, conversion optimization. Triggers: landing page, hero section, above the fold, conversion optimization, landing page design, cta button, hero image, landing page layout, saas landing page, product page design, conversion rate, landing page best practices

bg-szy/TOP-SKILLS

Account assets, equity and fund positions, P&L, cash flow records, account statements, margin ratios, buy-power estimates, order management, and DCA recurring investments via Longbridge (most require Trade permission). Frameworks: portfolio diagnosis, rebalancing, asset allocation, risk analysis (VaR/CVaR), performance attribution, and tax-loss harvesting. Triggers: "持仓", "账户", "盈亏", "资产", "对账单", "下单", "买入", "卖出", "撤单", "定投", "组合诊断", "再平衡", "资产配置", "风险分析", "绩效归因", "税损收割", "持倉", "賬戶", "盈虧", "對賬單", "下單", "買入", "賣出", "組合診斷", "再平衡", "稅損收割", "positions", "portfolio", "P&L", "order", "buy", "sell", "DCA", "statement", "risk analysis", "rebalancing", "tax harvesting", "我的风险", "持仓风险", "风险敞口", "資產", "資產配置", "風險分析", "績效歸因", "撤單

bg-szy/TOP-SKILLS

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

bg-szy/TOP-SKILLS

Process video files with audio extraction, format conversion (mp4, webm), and Whisper transcription. Use when user mentions video conversion, audio extraction, transcription, mp4, webm, ffmpeg, or whisper transcription.

相关技能