Communitygithub.com

bg-szy/TOP-SKILLS

設置並執行 Ruzzy,Trail of Bits 開發的覆蓋引導 Ruby 模糊測試工具,也是目前唯一生產就緒的 Ruby 模糊測試器。涵蓋 harness 結構、模糊測試純 Ruby 程式碼與 Gem 中的原生 C 擴充、以及 sanitizer 建置。適用於模糊測試 Ruby 函式庫或 Gem、測試 Ruby C 擴充的記憶體安全性、或詢問如何對 Ruby 進行模糊測試。

TOP-SKILLS 是什麼?

Ruzzy 是基於 libFuzzer 的覆蓋引導模糊測試器,專為 Ruby 生態系統設計,目前是唯一生產就緒的 Ruby 模糊測試工具。它支援對純 Ruby 程式碼和 Ruby C 擴充進行模糊測試,並整合了 AddressSanitizer (ASan) 與 UndefinedBehaviorSanitizer (UBSan),能夠有效偵測記憶體毀損和未定義行為。 此技能提供完整的操作指南,包括在 Linux x86-64 與 AArch64/ARM64 上安裝 Ruzzy、編寫 harness(針對純 Ruby 需使用追蹤器腳本,針對 C 擴充則可直接編寫單一 harness)、執行模糊測試戰役、處理 Corpus、重現崩潰,以及解讀輸出資訊。 對於 C 擴充的記憶體安全測試,Ruzzy 尤其關鍵,因為 Ruby 層的異常可以被 harness 捕獲,而底層 C 語言的緩衝區溢位或釋放後使用等問題則會由 Sanitizer 直接攔截並回報。 此技能也涵蓋了常見問題排解(例如 LD_PRELOAD 未設置或洩漏偵測干擾)以及與其他相關技能(如 fuzz-harness-writing、address-sanitizer)的整合參考,讓開發者能快速上手並進行有效的 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 安裝 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"

選項說明:

  1. allocator_may_return_null=1:跳過常見的低影響配置失敗(阻斷服務)
  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

注意: 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 模糊測試所需追蹤器模式的詳細指南。

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.

相關技能