ruzzy 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64fa385ff3dca5a231ebc02511f7240143838b4cf4314a8ced35a57127ac2dc2
-  data.tar.gz: 1cd94db1a0b30debdc03caddf39394b3759b11f85d0b2ef78037e5769b0761ed
+  metadata.gz: 7d564227ec95d197cadc085f2190a7089fbe5610d4e6f7c9d9ff5a84a4243208
+  data.tar.gz: aa7c37d65b75d202e650832ffad9589c3a6a750d162760d0af934256268115aa
 SHA512:
-  metadata.gz: ed77800fbbe359a7b2be3e215b00d052b2bf8f1038da0e2ad88c6a8ea9d66bcf2d875ed5658592262ef35a18a23c4b1f5fcc9d44e7f669fc81817310dda96122
-  data.tar.gz: 80ef311558dd4c4aa88697014e08a6b06a164d182a16d5c4718ce9355bc6b2f82c52bce11d3eaa1d1071df2a900eef9ef46148013ad7099ed1fbf07df173b6c3
+  metadata.gz: 54cc91f765a3622756e3925f62e29003ef3169a8a413af4b450b320bdea979125ede2a203be2b2fac52114abf52b3b735f8d97e395f9181eb01f080b09648988
+  data.tar.gz: cc8895f40905092d68bbdad2557fd691c189b04f336bb360c0f0a1b3f82a52d0227f82e966248b2b70cfd694b35e464ecd967a76d0e0426e45f5ffa2e941444f

data/ext/cruzzy/extconf.rb

@@ -19,6 +19,7 @@ LOGGER.level = ENV.key?('RUZZY_DEBUG') ? Logger::DEBUG : Logger::INFO
 CC = ENV.fetch('CC', 'clang')
 CXX = ENV.fetch('CXX', 'clang++')
 AR = ENV.fetch('AR', 'ar')
+LD = ENV.fetch('LD', 'ld')
 FUZZER_NO_MAIN_LIB_ENV = 'FUZZER_NO_MAIN_LIB'
 
 LOGGER.debug("Ruby CC: #{RbConfig::CONFIG['CC']}")
@@ -66,6 +67,7 @@ def merge_sanitizer_libfuzzer_lib(sanitizer_lib, fuzzer_no_main_lib, merged_outp
       '-ldl',
       '-lstdc++',
       '-shared',
+      "-fuse-ld=#{LD}",
       '-o',
       merged_output
     )
@@ -76,18 +78,24 @@ def merge_sanitizer_libfuzzer_lib(sanitizer_lib, fuzzer_no_main_lib, merged_outp
   end
 end
 
-fuzzer_no_main_libs = [
-  'libclang_rt.fuzzer_no_main.a',
-  'libclang_rt.fuzzer_no_main-aarch64.a',
-  'libclang_rt.fuzzer_no_main-x86_64.a'
-]
-fuzzer_no_main_lib = fuzzer_no_main_libs.map { |lib| get_clang_file_name(lib) }.find(&:itself)
+fuzzer_no_main_lib = ENV.fetch(FUZZER_NO_MAIN_LIB_ENV, nil)
 
-unless fuzzer_no_main_lib
-  LOGGER.warn("Could not find fuzzer_no_main using #{CC}.")
-  fuzzer_no_main_lib = ENV.fetch(FUZZER_NO_MAIN_LIB_ENV, nil)
-  if fuzzer_no_main_lib.nil?
-    LOGGER.error("Could not find fuzzer_no_main in #{FUZZER_NO_MAIN_LIB_ENV}.")
+if fuzzer_no_main_lib
+  LOGGER.info("Using #{FUZZER_NO_MAIN_LIB_ENV}=#{fuzzer_no_main_lib}")
+  unless File.exist?(fuzzer_no_main_lib)
+    LOGGER.error("#{FUZZER_NO_MAIN_LIB_ENV} file does not exist: #{fuzzer_no_main_lib}")
+    exit(1)
+  end
+else
+  fuzzer_no_main_libs = [
+    'libclang_rt.fuzzer_no_main.a',
+    'libclang_rt.fuzzer_no_main-aarch64.a',
+    'libclang_rt.fuzzer_no_main-x86_64.a'
+  ]
+  fuzzer_no_main_lib = fuzzer_no_main_libs.map { |lib| get_clang_file_name(lib) }.find(&:itself)
+
+  unless fuzzer_no_main_lib
+    LOGGER.error("Could not find fuzzer_no_main using #{CC}.")
     LOGGER.error("Please include #{CC} in your path or specify #{FUZZER_NO_MAIN_LIB_ENV} ENV variable.")
     exit(1)
   end
@@ -139,5 +147,6 @@ merge_sanitizer_libfuzzer_lib(
 $LOCAL_LIBS = fuzzer_no_main_lib
 
 $LIBS << ' -lstdc++'
+$DLDFLAGS << " -fuse-ld=#{LD}"
 
 create_makefile('cruzzy/cruzzy')

data/lib/ruzzy/fuzzed_data_provider.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Ruzzy
+  # Splits raw fuzzer bytes into typed Ruby values.
+  #
+  # FuzzedDataProvider wraps a binary string (typically from libFuzzer via
+  # Ruzzy.fuzz) and provides methods to consume typed values from it. This
+  # enables fuzz targets that test APIs accepting typed arguments rather than
+  # raw byte strings.
+  #
+  # Following libFuzzer's FuzzedDataProvider.h design, strings and raw bytes
+  # are consumed from the *front* of the buffer, while integers are consumed
+  # from the *end*. This bidirectional consumption lets the fuzzer modify
+  # structural decisions (integers controlling lengths, indices, variant
+  # selection) independently from content (string payloads, raw bytes),
+  # improving mutation quality.
+  #
+  # @example Basic usage in a fuzz target
+  #   test_one_input = lambda do |data|
+  #     fdp = Ruzzy::FuzzedDataProvider.new(data)
+  #     name = fdp.consume_random_length_string(50)
+  #     age = fdp.consume_int_in_range(0, 150)
+  #     score = fdp.consume_float_in_range(0.0, 100.0)
+  #     role = fdp.pick_value_in_list(['admin', 'user', 'guest'])
+  #     User.new(name: name, age: age, score: score, role: role).validate!
+  #   end
+  #   Ruzzy.fuzz(test_one_input)
+  class FuzzedDataProvider
+    def initialize(data)
+      @data = data
+      # Front cursor for strings/bytes (advances forward)
+      @front = 0
+      # Back cursor for integers (advances backward)
+      @back = @data.bytesize
+    end
+
+    # Returns the number of unconsumed bytes remaining.
+    def remaining_bytes
+      @back - @front
+    end
+
+    # --- Byte and String methods (consume from front) ---
+
+    # Consume up to +count+ raw bytes from the front of the buffer.
+    # Returns a binary-encoded String.
+    def consume_bytes(count)
+      count = clamp_count(count)
+      result = @data.byteslice(@front, count)
+      @front += count
+      result.force_encoding(Encoding::BINARY)
+    end
+
+    # Consume a variable-length string from the front of the buffer.
+    # The string terminates when a backslash followed by a non-backslash
+    # byte is encountered, or when +max_length+ characters are consumed.
+    # This encoding lets the fuzzer easily control string length through
+    # single-byte mutations.
+    #
+    # Matches libFuzzer's ConsumeRandomLengthString.
+    def consume_random_length_string(max_length = remaining_bytes)
+      result = +''
+      max_length.times do
+        break if remaining_bytes.zero?
+
+        byte = consume_front_byte
+        char = byte.chr(Encoding::BINARY)
+
+        if char == '\\' && remaining_bytes.positive?
+          next_byte = consume_front_byte
+          next_char = next_byte.chr(Encoding::BINARY)
+          break if next_char != '\\'
+
+          result << '\\'
+        else
+          result << char
+        end
+      end
+      result
+    end
+
+    # Consume all remaining bytes. Returns a binary-encoded String.
+    def consume_remaining_bytes
+      consume_bytes(remaining_bytes)
+    end
+
+    # Consume all remaining bytes as a String.
+    def consume_remaining_as_string
+      consume_remaining_bytes
+    end
+
+    # --- Integer methods (consume from end) ---
+
+    # Consume an unsigned integer from the end of the buffer.
+    # Reads up to +count+ bytes in little-endian order from the back.
+    # Returns 0 when no data remains.
+    def consume_uint(count)
+      return 0 if count <= 0 || remaining_bytes.zero?
+
+      actual = [count, remaining_bytes].min
+      result = 0
+      actual.times do |i|
+        @back -= 1
+        result |= @data.getbyte(@back) << (i * 8)
+      end
+      result
+    end
+
+    # Consume a signed integer from the end of the buffer.
+    # Reads +count+ bytes and interprets as two's complement.
+    # Returns 0 when no data remains.
+    def consume_int(count)
+      unsigned = consume_uint(count)
+      return 0 if count.zero?
+
+      bits = count * 8
+      max_unsigned = 1 << bits
+      half = max_unsigned >> 1
+
+      unsigned >= half ? unsigned - max_unsigned : unsigned
+    end
+
+    # Consume an integer in [min, max] from the end of the buffer.
+    # Returns +min+ when no data remains.
+    # Raises ArgumentError if min > max.
+    #
+    # Matches libFuzzer's ConsumeIntegralInRange: consumes only as many
+    # bytes from the end as needed to cover the range.
+    def consume_int_in_range(min, max)
+      raise ArgumentError, "min (#{min}) must be <= max (#{max})" if min > max
+
+      range = max - min
+      return min if range.zero?
+
+      # Consume bytes from the end, one at a time, until we've covered the range.
+      # This matches libFuzzer: only consume bytes while (range >> offset) > 0.
+      result = 0
+      offset = 0
+      while offset < 64 && (range >> offset).positive? && remaining_bytes.positive?
+        @back -= 1
+        result = (result << 8) | @data.getbyte(@back)
+        offset += 8
+      end
+
+      if range == (1 << offset) - 1
+        # range+1 is a power of 2, modulo is identity
+        min + result
+      else
+        min + (result % (range + 1))
+      end
+    end
+
+    # Consume a boolean from the end of the buffer.
+    # Returns false when no data remains.
+    def consume_bool
+      (consume_uint(1) & 1) == 1
+    end
+
+    # --- Float methods (consume from end) ---
+
+    # Consume a Float in [0.0, 1.0] from the end of the buffer.
+    # Returns 0.0 when no data remains.
+    def consume_probability
+      raw = consume_uint(8)
+      raw.to_f / 18_446_744_073_709_551_615.0 # 2^64 - 1
+    end
+
+    # Consume a Float in [min, max] from the end of the buffer.
+    # Returns +min+ when no data remains.
+    # Raises ArgumentError if min > max.
+    def consume_float_in_range(min, max)
+      raise ArgumentError, 'min must be <= max' if min > max
+      return min if min == max
+
+      range = max - min
+      if range.infinite?
+        # Overflow: split the range and recurse
+        mid = min / 2.0 + max / 2.0
+        if consume_bool
+          consume_float_in_range(mid, max)
+        else
+          consume_float_in_range(min, mid)
+        end
+      else
+        min + range * consume_probability
+      end
+    end
+
+    # Consume a Float spanning the full double range.
+    # Matches libFuzzer's ConsumeFloatingPoint.
+    def consume_float
+      consume_float_in_range(-Float::MAX, Float::MAX)
+    end
+
+    # --- Selection methods ---
+
+    # Return a random element from +list+, consuming bytes from the end.
+    # Raises ArgumentError if the list is empty.
+    def pick_value_in_list(list)
+      raise ArgumentError, 'list must not be empty' if list.empty?
+
+      list[consume_int_in_range(0, list.length - 1)]
+    end
+
+    private
+
+    # Consume a single byte from the front.
+    def consume_front_byte
+      return 0 if remaining_bytes.zero?
+
+      byte = @data.getbyte(@front)
+      @front += 1
+      byte
+    end
+
+    def clamp_count(count)
+      count = 0 if count.negative?
+      count = remaining_bytes if count > remaining_bytes
+      count
+    end
+  end
+end

data/lib/ruzzy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'ruzzy/fuzzed_data_provider'
 
 # A coverage-guided fuzzer for pure Ruby code and Ruby C extensions
 module Ruzzy
@@ -25,6 +26,11 @@ module Ruzzy
   end
 
   def dummy
+    # Load the instrumented shared object before calling fuzz so its coverage
+    # maps are registered before LLVMFuzzerRunDriver starts. Some fuzzer
+    # runtimes (e.g. LibAFL) require coverage maps to exist upfront.
+    require 'dummy/dummy'
+
     fuzz(->(data) { dummy_test_one_input(data) })
   end
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruzzy
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Trail of Bits
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-03-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,7 +65,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.60'
-description: 
 email: support@trailofbits.com
 executables: []
 extensions:
@@ -79,11 +77,11 @@ files:
 - ext/dummy/dummy.c
 - ext/dummy/extconf.rb
 - lib/ruzzy.rb
+- lib/ruzzy/fuzzed_data_provider.rb
 homepage: https://rubygems.org/gems/ruzzy
 licenses:
 - AGPL-3.0-only
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -98,8 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key: 
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A coverage-guided fuzzer for pure Ruby code and Ruby C extensions
 test_files: []