yara-ffi 4.0.0 → 4.1.0

data/lib/yara/compiler.rb

@@ -0,0 +1,161 @@
+module Yara
+  # Public: Wrapper around the YARA-X YRX_COMPILER API.
+  #
+  # This class allows adding multiple sources, defining globals before
+  # compilation, and building a YRX_RULES object that can be used by
+  # {Yara::Scanner}.
+  class Compiler
+    class CompileError < StandardError; end
+
+    def initialize(flags = 0)
+      @compiler_ptr_holder = ::FFI::MemoryPointer.new(:pointer)
+      result = Yara::FFI.yrx_compiler_create(flags, @compiler_ptr_holder)
+      if result != Yara::FFI.yrx_last_error && result != Yara::FFI::YRX_SUCCESS
+        # Defensive: use yrx_last_error for message but prefer success check
+      end
+
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to create compiler: #{Yara::FFI.yrx_last_error}"
+      end
+      @compiler = @compiler_ptr_holder.get_pointer(0)
+    end
+
+    def add_source(src, origin = nil)
+      if origin
+        result = Yara::FFI.yrx_compiler_add_source_with_origin(@compiler, src, origin)
+      else
+        result = Yara::FFI.yrx_compiler_add_source(@compiler, src)
+      end
+
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to add source: #{Yara::FFI.yrx_last_error}"
+      end
+      nil
+    end
+
+    def define_global_str(ident, value)
+      result = Yara::FFI.yrx_compiler_define_global_str(@compiler, ident, value)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to define global str #{ident}: #{Yara::FFI.yrx_last_error}"
+      end
+      nil
+    end
+
+    def define_global_bool(ident, value)
+      result = Yara::FFI.yrx_compiler_define_global_bool(@compiler, ident, !!value)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to define global bool #{ident}: #{Yara::FFI.yrx_last_error}"
+      end
+      nil
+    end
+
+    def define_global_int(ident, value)
+      result = Yara::FFI.yrx_compiler_define_global_int(@compiler, ident, value)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to define global int #{ident}: #{Yara::FFI.yrx_last_error}"
+      end
+      nil
+    end
+
+    def define_global_float(ident, value)
+      result = Yara::FFI.yrx_compiler_define_global_float(@compiler, ident, value)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to define global float #{ident}: #{Yara::FFI.yrx_last_error}"
+      end
+      nil
+    end
+
+    # Build and return a pointer to YRX_RULES. The caller is responsible for
+    # calling yrx_rules_destroy on the returned pointer when finished.
+    def build
+      rules_ptr = Yara::FFI.yrx_compiler_build(@compiler)
+      if rules_ptr.nil? || rules_ptr.null?
+        raise CompileError, "Failed to build rules: #{Yara::FFI.yrx_last_error}"
+      end
+      rules_ptr
+    end
+
+    # Public: Build and return a serialized representation of compiled rules.
+    #
+    # Compiles the currently added sources (via add_source) into a YRX_RULES
+    # object and serializes it into a binary blob suitable for persistence or
+    # transport. The returned String contains the serialized rules and can be
+    # deserialized later with Yara::Scanner.from_serialized or the underlying
+    # yrx_rules_deserialize FFI call.
+    #
+    # Returns a String containing binary serialized rules (raw bytes).
+    # Raises CompileError if compilation or serialization fails.
+    def build_serialized
+      rules_ptr = build
+
+      buf_ptr_holder = ::FFI::MemoryPointer.new(:pointer)
+      result = Yara::FFI.yrx_rules_serialize(rules_ptr, buf_ptr_holder)
+
+      # Destroy the rules pointer after serialization (we own it from build)
+      Yara::FFI.yrx_rules_destroy(rules_ptr)
+
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to serialize rules: #{Yara::FFI.yrx_last_error}"
+      end
+
+      buf_ptr = buf_ptr_holder.get_pointer(0)
+      buffer = Yara::FFI::YRX_BUFFER.new(buf_ptr)
+      begin
+        data_ptr = buffer[:data]
+        length = buffer[:length]
+        str = data_ptr.get_bytes(0, length)
+        return str
+      ensure
+        Yara::FFI.yrx_buffer_destroy(buf_ptr)
+      end
+    end
+
+    # Return compilation errors as a parsed JSON object (Array of error objects).
+    # This uses yrx_compiler_errors_json which returns a YRX_BUFFER containing
+    # the JSON serialization. The buffer is destroyed after being converted.
+    def errors_json
+      buf_ptr_holder = ::FFI::MemoryPointer.new(:pointer)
+      result = Yara::FFI.yrx_compiler_errors_json(@compiler, buf_ptr_holder)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to get errors JSON: #{Yara::FFI.yrx_last_error}"
+      end
+
+      buf_ptr = buf_ptr_holder.get_pointer(0)
+      buffer = Yara::FFI::YRX_BUFFER.new(buf_ptr)
+      data_ptr = buffer[:data]
+      length = buffer[:length]
+      json_str = data_ptr.read_string_length(length)
+      Yara::FFI.yrx_buffer_destroy(buf_ptr)
+
+      JSON.parse(json_str)
+    end
+
+    # Return compilation warnings as parsed JSON (Array of warning objects).
+    def warnings_json
+      buf_ptr_holder = ::FFI::MemoryPointer.new(:pointer)
+      result = Yara::FFI.yrx_compiler_warnings_json(@compiler, buf_ptr_holder)
+      if result != Yara::FFI::YRX_SUCCESS
+        raise CompileError, "Failed to get warnings JSON: #{Yara::FFI.yrx_last_error}"
+      end
+
+      buf_ptr = buf_ptr_holder.get_pointer(0)
+      buffer = Yara::FFI::YRX_BUFFER.new(buf_ptr)
+      data_ptr = buffer[:data]
+      length = buffer[:length]
+      json_str = data_ptr.read_string_length(length)
+      Yara::FFI.yrx_buffer_destroy(buf_ptr)
+
+      JSON.parse(json_str)
+    end
+
+    def destroy
+      Yara::FFI.yrx_compiler_destroy(@compiler) if @compiler
+      @compiler = nil
+    end
+
+    # Ensure resources are cleaned up.
+    def finalize
+      destroy
+    end
+  end
+end

data/lib/yara/ffi.rb

@@ -178,6 +178,99 @@ module Yara
     # C Signature: enum YRX_RESULT yrx_scanner_scan(struct YRX_SCANNER *scanner, const uint8_t *data, size_t len)
     attach_function :yrx_scanner_scan, [:pointer, :pointer, :size_t], :int
 
+    # Public: Set timeout (in milliseconds) for a scanner.
+    #
+    # scanner - A Pointer to the scanner object
+    # timeout - A uint64_t value representing timeout in milliseconds
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_scanner_set_timeout(struct YRX_SCANNER *scanner, uint64_t timeout)
+    attach_function :yrx_scanner_set_timeout, [:pointer, :ulong_long], :int
+
+    # Public: Set a global string variable for the scanner.
+    # C Signature: enum YRX_RESULT yrx_scanner_set_global_str(struct YRX_SCANNER *scanner, const char *ident, const char *value)
+    attach_function :yrx_scanner_set_global_str, [:pointer, :string, :string], :int
+
+    # Public: Set a global boolean variable for the scanner.
+    # C Signature: enum YRX_RESULT yrx_scanner_set_global_bool(struct YRX_SCANNER *scanner, const char *ident, bool value)
+    attach_function :yrx_scanner_set_global_bool, [:pointer, :string, :bool], :int
+
+    # Public: Set a global integer variable for the scanner.
+    # C Signature: enum YRX_RESULT yrx_scanner_set_global_int(struct YRX_SCANNER *scanner, const char *ident, int64_t value)
+    attach_function :yrx_scanner_set_global_int, [:pointer, :string, :long_long], :int
+
+    # Public: Set a global float variable for the scanner.
+    # C Signature: enum YRX_RESULT yrx_scanner_set_global_float(struct YRX_SCANNER *scanner, const char *ident, double value)
+    attach_function :yrx_scanner_set_global_float, [:pointer, :string, :double], :int
+
+    # YRX_COMPILER APIs
+    # Create a compiler: enum YRX_RESULT yrx_compiler_create(uint32_t flags, struct YRX_COMPILER **compiler)
+    attach_function :yrx_compiler_create, [:uint32, :pointer], :int
+
+    # Destroy a compiler: void yrx_compiler_destroy(struct YRX_COMPILER *compiler)
+    attach_function :yrx_compiler_destroy, [:pointer], :void
+
+    # Add source: enum YRX_RESULT yrx_compiler_add_source(struct YRX_COMPILER *compiler, const char *src)
+    attach_function :yrx_compiler_add_source, [:pointer, :string], :int
+
+    # Add source with origin: enum YRX_RESULT yrx_compiler_add_source_with_origin(struct YRX_COMPILER *compiler, const char *src, const char *origin)
+    attach_function :yrx_compiler_add_source_with_origin, [:pointer, :string, :string], :int
+
+    # Define globals on compiler
+    attach_function :yrx_compiler_define_global_str, [:pointer, :string, :string], :int
+    attach_function :yrx_compiler_define_global_bool, [:pointer, :string, :bool], :int
+    attach_function :yrx_compiler_define_global_int, [:pointer, :string, :long_long], :int
+    attach_function :yrx_compiler_define_global_float, [:pointer, :string, :double], :int
+
+    # Build compiler into rules: struct YRX_RULES *yrx_compiler_build(struct YRX_COMPILER *compiler)
+    attach_function :yrx_compiler_build, [:pointer], :pointer
+
+    # YRX_BUFFER utilities
+    # C Signature: void yrx_buffer_destroy(struct YRX_BUFFER *buf)
+    attach_function :yrx_buffer_destroy, [:pointer], :void
+
+    # Compiler diagnostics as JSON
+    # C Signature: enum YRX_RESULT yrx_compiler_errors_json(struct YRX_COMPILER *compiler, struct YRX_BUFFER **buf)
+    attach_function :yrx_compiler_errors_json, [:pointer, :pointer], :int
+
+    # C Signature: enum YRX_RESULT yrx_compiler_warnings_json(struct YRX_COMPILER *compiler, struct YRX_BUFFER **buf)
+    attach_function :yrx_compiler_warnings_json, [:pointer, :pointer], :int
+
+    # Serialize rules into a YRX_BUFFER
+    # C Signature: enum YRX_RESULT yrx_rules_serialize(const struct YRX_RULES *rules, struct YRX_BUFFER **buf)
+    attach_function :yrx_rules_serialize, [:pointer, :pointer], :int
+
+    # Deserialize rules from bytes
+    # C Signature: enum YRX_RESULT yrx_rules_deserialize(const uint8_t *data, size_t len, struct YRX_RULES **rules)
+    attach_function :yrx_rules_deserialize, [:pointer, :size_t, :pointer], :int
+
+    # Struct mapping for YRX_BUFFER
+    class YRX_BUFFER < ::FFI::Struct
+      layout :data, :pointer,
+             :length, :size_t
+    end
+
+    # Struct mapping for YRX_MATCH
+    class YRX_MATCH < ::FFI::Struct
+      layout :offset, :size_t,
+             :length, :size_t
+    end
+
+    # Struct mapping for YRX_METADATA
+    # Note: The value field is a union. We'll use a simple approach
+    # and access the value as a pointer, then interpret based on type.
+    class YRX_METADATA < ::FFI::Struct
+      layout :identifier, :pointer,
+             :value_type, :int,
+             :value, [:char, 16]  # Union represented as byte array (largest possible union member)
+    end
+
+    # Struct mapping for YRX_METADATA_BYTES
+    class YRX_METADATA_BYTES < ::FFI::Struct
+      layout :length, :size_t,
+             :data, :pointer
+    end
+
     # Public: Extract the identifier (name) from a rule object.
     #
     # This function retrieves the rule name from a YRX_RULE pointer, typically
@@ -278,6 +371,85 @@ module Yara
     # C Signature: enum YRX_RESULT yrx_pattern_identifier(const struct YRX_PATTERN *pattern, const uint8_t **ident, size_t *len)
     attach_function :yrx_pattern_identifier, [:pointer, :pointer, :pointer], :int
 
+    # Internal: Callback function type for match iteration.
+    #
+    # This callback is invoked for each match found during pattern match
+    # iteration. The callback receives pointers to the match and user data.
+    #
+    # match     - A Pointer to the YRX_MATCH structure
+    # user_data - A Pointer to optional user-provided data
+    #
+    # C Signature: typedef void (*YRX_MATCH_CALLBACK)(const struct YRX_MATCH *match, void *user_data)
+    callback :match_callback, [:pointer, :pointer], :void
+
+    # Internal: Callback function type for tag iteration.
+    #
+    # This callback is invoked for each tag during rule tag iteration.
+    # The callback receives a pointer to the tag string and user data.
+    #
+    # tag       - A Pointer to null-terminated string representing the tag
+    # user_data - A Pointer to optional user-provided data
+    #
+    # C Signature: typedef void (*YRX_TAG_CALLBACK)(const char *tag, void *user_data)
+    callback :tag_callback, [:pointer, :pointer], :void
+
+    # Public: Iterate through all matches for a specific pattern.
+    #
+    # This function calls the provided callback for each match found for the
+    # given pattern during scanning. Each match provides the offset and length
+    # of where the pattern matched in the scanned data.
+    #
+    # pattern   - A Pointer to the YRX_PATTERN structure
+    # callback  - A Proc matching the match_callback signature
+    # user_data - A Pointer to optional data passed to callback (can be nil)
+    #
+    # Examples
+    #
+    #   callback = proc { |match_ptr, user_data| puts "Found match" }
+    #   result = Yara::FFI.yrx_pattern_iter_matches(pattern_ptr, callback, nil)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_pattern_iter_matches(const struct YRX_PATTERN *pattern, YRX_MATCH_CALLBACK callback, void *user_data)
+    attach_function :yrx_pattern_iter_matches, [:pointer, :match_callback, :pointer], :int
+
+    # Public: Extract the namespace from a rule object.
+    #
+    # This function retrieves the rule namespace from a YRX_RULE pointer.
+    # The namespace is returned as a pointer and length rather than a
+    # null-terminated string.
+    #
+    # rule - A Pointer to the YRX_RULE structure
+    # ns   - A FFI::MemoryPointer that will receive the namespace pointer
+    # len  - A FFI::MemoryPointer that will receive the namespace length
+    #
+    # Examples
+    #
+    #   ns_ptr = FFI::MemoryPointer.new(:pointer)
+    #   len_ptr = FFI::MemoryPointer.new(:size_t)
+    #   result = Yara::FFI.yrx_rule_namespace(rule_ptr, ns_ptr, len_ptr)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_rule_namespace(const struct YRX_RULE *rule, const uint8_t **ns, size_t *len)
+    attach_function :yrx_rule_namespace, [:pointer, :pointer, :pointer], :int
+
+    # Public: Iterate through all tags in a rule.
+    #
+    # This function calls the provided callback for each tag defined
+    # in the rule. Tags are used for categorizing and organizing rules.
+    #
+    # rule      - A Pointer to the YRX_RULE structure
+    # callback  - A Proc matching the tag_callback signature
+    # user_data - A Pointer to optional data passed to callback (can be nil)
+    #
+    # Examples
+    #
+    #   callback = proc { |tag_ptr, user_data| puts "Found tag: #{tag_ptr.read_string}" }
+    #   result = Yara::FFI.yrx_rule_iter_tags(rule_ptr, callback, nil)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_rule_iter_tags(const struct YRX_RULE *rule, YRX_TAG_CALLBACK callback, void *user_data)
+    attach_function :yrx_rule_iter_tags, [:pointer, :tag_callback, :pointer], :int
+
     # Public: YARA-X result codes for operation status.
     #
     # These constants represent the possible return values from YARA-X functions.
@@ -301,5 +473,33 @@ module Yara
 
     # Public: Invalid argument passed to function.
     YRX_INVALID_ARGUMENT = 5
+
+    # Public: Metadata type constants for YRX_METADATA_TYPE enum.
+    #
+    # These constants represent the possible types of metadata values in YARA-X.
+    # They correspond to the YRX_METADATA_TYPE enum values in the C API.
+
+    # Public: 64-bit signed integer metadata value.
+    YRX_METADATA_TYPE_I64 = 0
+
+    # Public: 64-bit floating point metadata value.
+    YRX_METADATA_TYPE_F64 = 1
+
+    # Public: Boolean metadata value.
+    YRX_METADATA_TYPE_BOOLEAN = 2
+
+    # Public: String metadata value.
+    YRX_METADATA_TYPE_STRING = 3
+
+    # Public: Bytes metadata value.
+    YRX_METADATA_TYPE_BYTES = 4
+
+    # Public: Alternative naming following YARA-X C API documentation.
+    # Maps to the same values as above for compatibility.
+    YRX_I64 = 0
+    YRX_F64 = 1
+    YRX_BOOLEAN = 2
+    YRX_STRING = 3
+    YRX_BYTES = 4
   end
 end

data/lib/yara/pattern_match.rb

@@ -0,0 +1,178 @@
+module Yara
+  # Public: Represents a single pattern match found during YARA scanning.
+  #
+  # A PatternMatch contains detailed information about where and how a specific
+  # YARA pattern matched within the scanned data. This includes the exact offset
+  # and length of the match, allowing for precise forensic analysis and data
+  # extraction.
+  #
+  # PatternMatch instances are typically created internally during the scanning
+  # process and accessed through ScanResult methods like pattern_matches.
+  #
+  # Examples
+  #
+  #   # Access pattern matches through scan results
+  #   results.each do |result|
+  #     result.pattern_matches.each do |pattern_name, matches|
+  #       matches.each do |match|
+  #         puts "Pattern #{pattern_name} matched at offset #{match.offset}"
+  #         puts "Matched text: '#{match.matched_data(scanned_data)}'"
+  #       end
+  #     end
+  #   end
+  class PatternMatch
+    # Public: The byte offset where this pattern match begins in the scanned data.
+    attr_reader :offset
+
+    # Public: The length in bytes of this pattern match.
+    attr_reader :length
+
+    # Public: Initialize a new PatternMatch.
+    #
+    # This constructor is typically called internally when processing YARA-X
+    # match results. It captures the precise location and size of a pattern
+    # match within scanned data.
+    #
+    # offset - An Integer byte offset where the match begins
+    # length - An Integer length in bytes of the match
+    #
+    # Examples
+    #
+    #   # Typically created internally during scanning
+    #   match = PatternMatch.new(42, 10)
+    #   match.offset  # => 42
+    #   match.length  # => 10
+    def initialize(offset, length)
+      @offset = offset
+      @length = length
+    end
+
+    # Public: Extract the actual matched data from the scanned content.
+    #
+    # This method returns the exact bytes that matched the pattern by extracting
+    # the appropriate slice from the original scanned data. This is useful for
+    # forensic analysis, debugging rules, and understanding what triggered a match.
+    #
+    # data - A String containing the original data that was scanned
+    #
+    # Examples
+    #
+    #   # Extract what actually matched
+    #   scan_data = "hello world test data"
+    #   match = PatternMatch.new(6, 5)  # matches "world"
+    #   match.matched_data(scan_data)   # => "world"
+    #
+    # Returns a String containing the matched bytes.
+    # Returns empty String if offset/length are outside data bounds.
+    def matched_data(data)
+      return "" if offset < 0 || offset >= data.bytesize
+      return "" if length <= 0 || offset + length > data.bytesize
+
+      data.byteslice(offset, length)
+    end
+
+    # Public: Get the end offset of this match (exclusive).
+    #
+    # This convenience method calculates the byte position immediately after
+    # the last byte of this match, which is useful for range operations and
+    # avoiding overlapping matches.
+    #
+    # Examples
+    #
+    #   match = PatternMatch.new(10, 5)
+    #   match.end_offset  # => 15
+    #
+    # Returns an Integer representing the end offset (exclusive).
+    def end_offset
+      offset + length
+    end
+
+    # Public: Check if this match overlaps with another match.
+    #
+    # This method determines whether two pattern matches have any overlapping
+    # bytes. This is useful for analyzing complex rules with multiple patterns
+    # or detecting redundant matches.
+    #
+    # other - Another PatternMatch instance to compare against
+    #
+    # Examples
+    #
+    #   match1 = PatternMatch.new(10, 5)  # bytes 10-14
+    #   match2 = PatternMatch.new(12, 5)  # bytes 12-16
+    #   match1.overlaps?(match2)  # => true
+    #
+    #   match3 = PatternMatch.new(20, 5)  # bytes 20-24
+    #   match1.overlaps?(match3)  # => false
+    #
+    # Returns a Boolean indicating whether the matches overlap.
+    def overlaps?(other)
+      offset < other.end_offset && end_offset > other.offset
+    end
+
+    # Public: Get a human-readable string representation of this match.
+    #
+    # This method provides a concise string representation showing the key
+    # details of the match, useful for debugging and logging purposes.
+    #
+    # Examples
+    #
+    #   match = PatternMatch.new(42, 10)
+    #   match.to_s  # => "PatternMatch(offset: 42, length: 10)"
+    #
+    # Returns a String representation of this match.
+    def to_s
+      "PatternMatch(offset: #{offset}, length: #{length})"
+    end
+
+    # Public: Detailed inspection string with all attributes.
+    #
+    # Provides a complete string representation including all match attributes,
+    # useful for debugging and development purposes.
+    #
+    # Examples
+    #
+    #   match = PatternMatch.new(42, 10)
+    #   match.inspect  # => "#<Yara::PatternMatch:0x... @offset=42, @length=10>"
+    #
+    # Returns a String with detailed object information.
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} @offset=#{@offset}, @length=#{@length}>"
+    end
+
+    # Public: Compare two PatternMatch objects for equality.
+    #
+    # Two matches are considered equal if they have the same offset and length.
+    # This is useful for deduplicating matches or comparing results.
+    #
+    # other - Another PatternMatch instance to compare against
+    #
+    # Examples
+    #
+    #   match1 = PatternMatch.new(10, 5)
+    #   match2 = PatternMatch.new(10, 5)
+    #   match1 == match2  # => true
+    #
+    # Returns a Boolean indicating equality.
+    def ==(other)
+      other.is_a?(PatternMatch) && offset == other.offset && length == other.length
+    end
+
+    # Public: Generate hash code for this match.
+    #
+    # Uses offset and length to generate a hash code, enabling PatternMatch
+    # instances to be used as hash keys or in sets.
+    #
+    # Examples
+    #
+    #   match = PatternMatch.new(42, 10)
+    #   {match => "info"}  # Can be used as hash key
+    #
+    # Returns an Integer hash code.
+    def hash
+      [offset, length].hash
+    end
+
+    # Public: Enable hash equality based on hash code.
+    alias_method :eql?, :==
+  end
+end