ruzzy 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0abba0ffb63d4c50fbbb33fb3624299f8421293a02d65e199525c75b4dbd5f46
-  data.tar.gz: 4787489da1373bb820cd66d62a913a4c9c33c49bda68f251dae25745ccac3679
+  metadata.gz: 7d564227ec95d197cadc085f2190a7089fbe5610d4e6f7c9d9ff5a84a4243208
+  data.tar.gz: aa7c37d65b75d202e650832ffad9589c3a6a750d162760d0af934256268115aa
 SHA512:
-  metadata.gz: c029eca231fbeb0d8b19b469a6cb2de99117a939e35c9f42622f803d06a0b4ad85ceacc25dff1bba9e56b1179358ec8fff054a35d894faa11398727891697216
-  data.tar.gz: cb761ff27a1fa8d462295d9022d03490338d2608d94cddc8454fb2919fd308e8ee7ea18b4735e601574ca1366de266607c2966be18e27af21ab1c3e243f60237
+  metadata.gz: 54cc91f765a3622756e3925f62e29003ef3169a8a413af4b450b320bdea979125ede2a203be2b2fac52114abf52b3b735f8d97e395f9181eb01f080b09648988
+  data.tar.gz: cc8895f40905092d68bbdad2557fd691c189b04f336bb360c0f0a1b3f82a52d0227f82e966248b2b70cfd694b35e464ecd967a76d0e0426e45f5ffa2e941444f

data/ext/cruzzy/cruzzy.c

@@ -194,11 +194,11 @@ static void event_hook_branch(VALUE counter_hash, rb_trace_arg_t *tracearg) {
 
 static void enable_branch_coverage_hooks()
 {
-    // Call Coverage.setup(branches: true) to activate branch coverage hooks.
+    // Call Coverage.start(branches: true) to activate branch coverage hooks.
     // Branch coverage hooks will not be activated without this call despite
     // adding the event hooks. I suspect rb_set_coverages must be called
     // first, which initializes some global state that we do not have direct
-    // access to. Calling setup initializes coverage state here:
+    // access to. Calling start initializes coverage state here:
     // https://github.com/ruby/ruby/blob/v3_3_0/ext/coverage/coverage.c#L112-L120
     // If rb_set_coverages is not called, then rb_get_coverages returns a NULL
     // pointer, which appears to effectively disable coverage collection here:
@@ -207,10 +207,10 @@ static void enable_branch_coverage_hooks()
     VALUE coverage_mod = rb_const_get(rb_cObject, rb_intern("Coverage"));
     VALUE hash_arg = rb_hash_new();
     rb_hash_aset(hash_arg, ID2SYM(rb_intern("branches")), Qtrue);
-    rb_funcall(coverage_mod, rb_intern("setup"), 1, hash_arg);
+    rb_funcall(coverage_mod, rb_intern("start"), 1, hash_arg);
 }
 
-static VALUE c_trace_branch(VALUE self)
+static VALUE c_trace(VALUE self, VALUE harness_path)
 {
     VALUE counter_hash = rb_hash_new();
 
@@ -230,7 +230,7 @@ static VALUE c_trace_branch(VALUE self)
 
     enable_branch_coverage_hooks();
 
-    return Qnil;
+    return rb_require(StringValueCStr(harness_path));
 }
 
 void Init_cruzzy()
@@ -245,5 +245,5 @@ void Init_cruzzy()
     rb_define_module_function(ruzzy, "c_libfuzzer_is_loaded", &c_libfuzzer_is_loaded, 0);
     rb_define_module_function(ruzzy, "c_trace_cmp8", &c_trace_cmp8, 2);
     rb_define_module_function(ruzzy, "c_trace_div8", &c_trace_div8, 1);
-    rb_define_module_function(ruzzy, "c_trace_branch", &c_trace_branch, 0);
+    rb_define_module_function(ruzzy, "c_trace", &c_trace, 1);
 }

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']}")
@@ -64,7 +65,9 @@ def merge_sanitizer_libfuzzer_lib(sanitizer_lib, fuzzer_no_main_lib, merged_outp
       '-Wl,--no-whole-archive',
       '-lpthread',
       '-ldl',
+      '-lstdc++',
       '-shared',
+      "-fuse-ld=#{LD}",
       '-o',
       merged_output
     )
@@ -75,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
@@ -137,4 +146,7 @@ merge_sanitizer_libfuzzer_lib(
 # For more information, see https://github.com/ruby/ruby/blob/master/lib/mkmf.rb.
 $LOCAL_LIBS = fuzzer_no_main_lib
 
+$LIBS << ' -lstdc++'
+$DLDFLAGS << " -fuse-ld=#{LD}"
+
 create_makefile('cruzzy/cruzzy')

data/ext/dummy/dummy.c

@@ -6,17 +6,18 @@
 // https://llvm.org/docs/LibFuzzer.html#toy-example
 static int _c_dummy_test_one_input(const uint8_t *data, size_t size)
 {
-    char test[] = {'a', 'b', 'c'};
+    volatile char boom = 'x';
 
-    if (size > 0 && data[0] == 'H') {
-        if (size > 1 && data[1] == 'I') {
-            // This code exists specifically to test the driver and ensure
-            // libFuzzer is functioning as expected, so we can safely ignore
-            // the warning.
-            #pragma clang diagnostic push
-            #pragma clang diagnostic ignored "-Warray-bounds"
-            test[1024] = 'd';
-            #pragma clang diagnostic pop
+    if (size == 2) {
+        if (data[0] == 'H') {
+            if (data[1] == 'I') {
+                // Intentional heap-use-after-free for testing purposes
+                char * volatile ptr = malloc(128);
+                ptr[0] = 'x';
+                free(ptr);
+                boom = ptr[0];
+                (void) boom;
+            }
         }
     }
 

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,8 +1,9 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'ruzzy/fuzzed_data_provider'
 
-# A Ruby C extension fuzzer
+# A coverage-guided fuzzer for pure Ruby code and Ruby C extensions
 module Ruzzy
   require 'cruzzy/cruzzy'
 
@@ -15,10 +16,6 @@ module Ruzzy
     c_fuzz(test_one_input, args)
   end
 
-  def dummy
-    fuzz(->(data) { Ruzzy.dummy_test_one_input(data) })
-  end
-
   def dummy_test_one_input(data)
     # This 'require' depends on LD_PRELOAD, so it's placed inside the function
     # scope. This allows us to access EXT_PATH for LD_PRELOAD and not have a
@@ -28,9 +25,33 @@ module Ruzzy
     c_dummy_test_one_input(data)
   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
+
+  def trace(harness_script)
+    harness_path = Pathname.new(harness_script)
+
+    # Mimic require_relative. If harness script is provided as an absolute path,
+    # then use that. If not, then assume the script is in the same directory as
+    # as the tracer script, i.e. the caller.
+    if !harness_path.absolute?
+      caller_path = Pathname.new(caller_locations.first.path)
+      harness_path = (caller_path.parent / harness_path).realpath
+    end
+
+    c_trace(harness_path.to_s)
+  end
+
   module_function :fuzz
-  module_function :dummy
   module_function :dummy_test_one_input
+  module_function :dummy
+  module_function :trace
 end
 
 # Hook Integer operations for tracing in SantizerCoverage

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruzzy
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Trail of Bits
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-13 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 Ruby C extension fuzzer
+summary: A coverage-guided fuzzer for pure Ruby code and Ruby C extensions
 test_files: []