yara-ffi 3.1.0 → 4.1.0

data/lib/yara/scan_result.rb

@@ -1,101 +1,603 @@
 module Yara
+  # Public: Represents a single rule match result from YARA scanning.
+  #
+  # A ScanResult contains information about a YARA rule that matched during
+  # scanning, including the rule name, metadata, string patterns, and detailed
+  # pattern match information. This class provides access to rule information
+  # extracted from both the YARA-X API and parsed rule source code.
+  #
+  # The enhanced version provides detailed pattern match information including
+  # exact offsets and lengths of each pattern match, allowing for precise
+  # forensic analysis and data extraction.
+  #
+  # Examples
+  #
+  #   # Typically created by Scanner during scanning
+  #   scanner.scan(data) do |result|
+  #     puts "Matched rule: #{result.rule_name}"
+  #     puts "Author: #{result.rule_meta[:author]}"
+  #
+  #     # New: Access detailed pattern matches
+  #     result.pattern_matches.each do |pattern_name, matches|
+  #       puts "Pattern #{pattern_name}: #{matches.size} matches"
+  #       matches.each do |match|
+  #         matched_text = data[match.offset, match.length]
+  #         puts "  At offset #{match.offset}: '#{matched_text}'"
+  #       end
+  #     end
+  #   end
   class ScanResult
-    RULE_MATCHING     = 1
-    RULE_NOT_MATCHING = 2
+    # Public: The name identifier of the matched rule.
+    attr_reader :rule_name
 
-    META_FLAGS_LAST_IN_RULE = 1
+    # Public: FFI pointer to the underlying YRX_RULE structure.
+    attr_reader :rule_ptr
 
-    META_TYPE_INTEGER = 1
-    # META_TYPE_STRING  = 2
-    META_TYPE_BOOLEAN = 3
+    # Public: Hash of metadata key-value pairs extracted from the rule.
+    attr_reader :rule_meta
 
-    STRING_FLAGS_LAST_IN_RULE = 0
+    # Public: Hash of string pattern names and their values from the rule.
+    attr_reader :rule_strings
 
-    attr_reader :callback_type, :rule
+    # Public: Hash of pattern names to arrays of PatternMatch objects.
+    #
+    # This provides detailed information about exactly where each pattern
+    # matched in the scanned data, including offset and length information.
+    attr_reader :pattern_matches
 
-    def initialize(callback_type, rule, user_data)
-      @callback_type = callback_type
-      @rule = rule
-      @rule_meta = extract_rule_meta
-      @rule_strings = extract_rule_strings
-      @user_data_number = user_data[:number]
+    # Public: Array of rule tags for categorization and organization.
+    #
+    # Tags are labels attached to rules that help categorize and organize
+    # rule sets. Common tags include malware family names, platforms,
+    # or behavior categories.
+    attr_reader :tags
+
+    # Public: Namespace of the rule, if defined.
+    #
+    # YARA rules can be organized into namespaces to avoid naming conflicts
+    # and provide logical grouping. This contains the namespace name or
+    # nil if the rule is in the default namespace.
+    attr_reader :namespace
+
+    # Public: Initialize a new ScanResult.
+    #
+    # This constructor is typically called internally by Scanner when a rule
+    # matches during scanning. It extracts available information from both
+    # the YARA-X API and the original rule source code, including detailed
+    # pattern match information.
+    #
+    # rule_name      - A String containing the rule identifier/name
+    # rule_ptr       - An FFI Pointer to the YRX_RULE structure
+    # is_match       - A Boolean indicating if this represents a match (default true)
+    # rule_source    - An optional String containing the original rule source for parsing
+    # scanned_data   - An optional String containing the data that was scanned (needed for pattern matches)
+    #
+    # Examples
+    #
+    #   # Typically created internally by Scanner
+    #   result = ScanResult.new("MyRule", rule_ptr, true, rule_source, scanned_data)
+    def initialize(rule_name, rule_ptr, is_match = true, rule_source = nil, scanned_data = nil)
+      @rule_name = rule_name
+      @rule_ptr = rule_ptr
+      @is_match = is_match
+      @rule_source = rule_source
+      @scanned_data = scanned_data
+      @rule_meta = {}
+      @rule_strings = {}
+      @pattern_matches = {}
+      @tags = []
+      @namespace = nil
+
+      # Extract information using YARA-X API when rule pointer is available
+      if @rule_ptr && !@rule_ptr.null?
+        # TODO: Re-enable structured metadata after fixing union handling
+        # extract_structured_metadata
+        extract_tags
+        extract_namespace
+        extract_pattern_matches
+      end
+
+      # Parse metadata and strings from source (primary method for now)
+      if @rule_source
+        parse_metadata_from_source
+        parse_strings_from_source
+      end
     end
 
-    attr_reader :rule_meta, :rule_strings, :user_data_number
+    # Public: Check if this result represents a rule match.
+    #
+    # Examples
+    #
+    #   if result.match?
+    #     puts "Rule #{result.rule_name} matched!"
+    #   end
+    #
+    # Returns a Boolean indicating whether the rule matched.
+    def match?
+      @is_match
+    end
 
-    def rule_name
-      @rule[:identifier]
+    # Public: Get all matches for a specific pattern by name.
+    #
+    # This method returns an array of PatternMatch objects for the specified
+    # pattern identifier, or an empty array if the pattern didn't match or
+    # doesn't exist.
+    #
+    # pattern_name - A String or Symbol identifying the pattern (e.g., "$text1")
+    #
+    # Examples
+    #
+    #   # Get matches for a specific pattern
+    #   matches = result.matches_for_pattern("$suspicious_string")
+    #   matches.each { |m| puts "Found at offset #{m.offset}" }
+    #
+    # Returns an Array of PatternMatch objects.
+    def matches_for_pattern(pattern_name)
+      key = pattern_name.is_a?(Symbol) ? pattern_name : pattern_name.to_sym
+      @pattern_matches[key] || []
     end
 
-    def scan_complete?
-      callback_type == SCAN_FINISHED
+    # Public: Get the total number of pattern matches across all patterns.
+    #
+    # This convenience method counts the total matches across all patterns
+    # that triggered for this rule.
+    #
+    # Examples
+    #
+    #   puts "Rule matched with #{result.total_matches} pattern matches"
+    #
+    # Returns an Integer count of total matches.
+    def total_matches
+      @pattern_matches.values.map(&:size).sum
     end
 
-    def rule_outcome?
-      [RULE_MATCHING, RULE_NOT_MATCHING].include?(callback_type)
+    # Public: Get all match locations as a flattened array.
+    #
+    # This method returns all pattern matches across all patterns as a single
+    # array, sorted by offset. Useful for getting an overview of all match
+    # locations in the data.
+    #
+    # Examples
+    #
+    #   # Get all matches sorted by location
+    #   all_matches = result.all_matches.sort_by(&:offset)
+    #   all_matches.each { |m| puts "Match at #{m.offset}" }
+    #
+    # Returns an Array of PatternMatch objects sorted by offset.
+    def all_matches
+      @pattern_matches.values.flatten.sort_by(&:offset)
     end
 
-    def match?
-      callback_type == RULE_MATCHING
-    end
-
-    private
-
-    def extract_rule_meta
-      metas = {}
-      reading_metas = true
-      meta_index = 0
-      meta_pointer = @rule[:metas]
-      while reading_metas do
-        meta = YrMeta.new(meta_pointer + meta_index * YrMeta.size)
-        metas.merge!(meta_as_hash(meta))
-        flags = meta[:flags]
-        if flags == META_FLAGS_LAST_IN_RULE
-          reading_metas = false
-        else
-          meta_index += 1
+    # Public: Check if a specific pattern had any matches.
+    #
+    # This convenience method checks whether the specified pattern identifier
+    # had any matches during scanning.
+    #
+    # pattern_name - A String or Symbol identifying the pattern
+    #
+    # Examples
+    #
+    #   if result.pattern_matched?("$malware_signature")
+    #     puts "Malware signature detected!"
+    #   end
+    #
+    # Returns a Boolean indicating whether the pattern matched.
+    def pattern_matched?(pattern_name)
+      matches_for_pattern(pattern_name).any?
+    end
+
+    # Public: Check if the rule has a specific tag.
+    #
+    # This method checks whether the rule includes the specified tag.
+    # Tag comparison is case-sensitive.
+    #
+    # tag - A String representing the tag to check for
+    #
+    # Examples
+    #
+    #   if result.has_tag?("malware")
+    #     puts "This rule is tagged as malware"
+    #   end
+    #
+    # Returns a Boolean indicating whether the rule has the tag.
+    def has_tag?(tag)
+      return false if tag.nil?
+      @tags.include?(tag.to_s)
+    end
+
+    # Public: Get the qualified rule name including namespace.
+    #
+    # This method returns the fully qualified rule name, including the
+    # namespace if present. For rules in the default namespace, this
+    # is the same as rule_name.
+    #
+    # Examples
+    #
+    #   result.qualified_name  # => "malware.suspicious_behavior"
+    #   # or just "rule_name" if no namespace
+    #
+    # Returns a String containing the qualified rule name.
+    def qualified_name
+      if @namespace && !@namespace.empty?
+        "#{@namespace}.#{@rule_name}"
+      else
+        @rule_name
+      end
+    end
+
+    # Public: Get a typed metadata value by key.
+    #
+    # This method provides type-safe access to metadata values, returning
+    # the actual Ruby type (String, Integer, Boolean, Float) instead of
+    # requiring manual type conversion.
+    #
+    # key - A String or Symbol identifying the metadata key
+    #
+    # Examples
+    #
+    #   result.metadata_value(:severity)    # => 8 (Integer)
+    #   result.metadata_value("author")     # => "Security Team" (String)
+    #   result.metadata_value(:active)      # => true (Boolean)
+    #
+    # Returns the metadata value in its native Ruby type, or nil if not found.
+    def metadata_value(key)
+      return nil if key.nil?
+      @rule_meta[key.to_sym]
+    end
+
+    # Public: Get an integer metadata value by key.
+    #
+    # This method provides a convenient way to access integer metadata
+    # with automatic type checking.
+    #
+    # key - A String or Symbol identifying the metadata key
+    #
+    # Examples
+    #
+    #   result.metadata_int(:severity)   # => 8
+    #   result.metadata_int(:version)    # => 2
+    #
+    # Returns an Integer value, or nil if key doesn't exist or isn't an integer.
+    def metadata_int(key)
+      value = metadata_value(key)
+      value.is_a?(Integer) ? value : nil
+    end
+
+    # Public: Get a string metadata value by key.
+    #
+    # This method provides a convenient way to access string metadata
+    # with automatic type checking.
+    #
+    # key - A String or Symbol identifying the metadata key
+    #
+    # Examples
+    #
+    #   result.metadata_string(:author)      # => "Security Team"
+    #   result.metadata_string(:description) # => "Detects malware"
+    #
+    # Returns a String value, or nil if key doesn't exist or isn't a string.
+    def metadata_string(key)
+      value = metadata_value(key)
+      value.is_a?(String) ? value : nil
+    end
+
+    # Public: Get a boolean metadata value by key.
+    #
+    # This method provides a convenient way to access boolean metadata
+    # with automatic type checking.
+    #
+    # key - A String or Symbol identifying the metadata key
+    #
+    # Examples
+    #
+    #   result.metadata_bool(:active)  # => true
+    #   result.metadata_bool(:enabled) # => false
+    #
+    # Returns a Boolean value, or nil if key doesn't exist or isn't a boolean.
+    def metadata_bool(key)
+      value = metadata_value(key)
+      [true, false].include?(value) ? value : nil
+    end
+
+    # Public: Get a float metadata value by key.
+    #
+    # This method provides a convenient way to access float metadata
+    # with automatic type checking.
+    #
+    # key - A String or Symbol identifying the metadata key
+    #
+    # Examples
+    #
+    #   result.metadata_float(:confidence) # => 0.95
+    #   result.metadata_float(:ratio)      # => 3.14
+    #
+    # Returns a Float value, or nil if key doesn't exist or isn't a float.
+    def metadata_float(key)
+      value = metadata_value(key)
+      value.is_a?(Float) ? value : nil
+    end
+
+    # Internal: Extract detailed pattern match information using YARA-X API.
+    #
+    # This method uses the YARA-X C API to iterate through all patterns defined
+    # in the matched rule and collect detailed match information including exact
+    # offsets and lengths for each match.
+    #
+    # This replaces the need to parse pattern information from rule source code
+    # and provides precise forensic data about what matched and where.
+    #
+    # Returns nothing (modifies @pattern_matches hash).
+    def extract_pattern_matches
+      return unless @rule_ptr && !@rule_ptr.null?
+
+      # Collect pattern match data by iterating through patterns
+      pattern_callback = proc do |pattern_ptr, user_data|
+        next if pattern_ptr.nil? || pattern_ptr.null?
+
+        # Get pattern identifier
+        ident_ptr = ::FFI::MemoryPointer.new(:pointer)
+        len_ptr = ::FFI::MemoryPointer.new(:size_t)
+
+        result = Yara::FFI.yrx_pattern_identifier(pattern_ptr, ident_ptr, len_ptr)
+        next unless result == Yara::FFI::YRX_SUCCESS
+
+        identifier_ptr = ident_ptr.get_pointer(0)
+        next if identifier_ptr.nil? || identifier_ptr.null?
+
+        identifier_len = len_ptr.get_ulong(0)
+        pattern_name = identifier_ptr.read_string(identifier_len).to_sym
+
+        # Initialize match array for this pattern
+        @pattern_matches[pattern_name] ||= []
+
+        # Iterate through matches for this pattern
+        match_callback = proc do |match_ptr, match_user_data|
+          next if match_ptr.nil? || match_ptr.null?
+
+          # Extract match details using FFI struct
+          match = Yara::FFI::YRX_MATCH.new(match_ptr)
+          pattern_match = PatternMatch.new(match[:offset], match[:length])
+          @pattern_matches[pattern_name] << pattern_match
         end
+
+        # Iterate through all matches for this pattern
+        Yara::FFI.yrx_pattern_iter_matches(pattern_ptr, match_callback, nil)
       end
-      metas
-    end
-
-    def extract_rule_strings
-      strings = {}
-      reading_strings = true
-      string_index = 0
-      string_pointer = @rule[:strings]
-      while reading_strings do
-        string = YrString.new(string_pointer + string_index * YrString.size)
-        string_length = string[:length]
-        flags = string[:flags]
-        if flags == STRING_FLAGS_LAST_IN_RULE
-          reading_strings = false
-        else
-          strings.merge!(string_as_hash(string)) unless string_length == 0
-          string_index += 1
+
+      # Iterate through all patterns in the rule
+      Yara::FFI.yrx_rule_iter_patterns(@rule_ptr, pattern_callback, nil)
+    end
+
+    # Internal: Extract structured metadata using YARA-X API.
+    #
+    # This method uses the YARA-X C API to access rule metadata with proper
+    # type information, replacing the regex-based parsing approach with
+    # reliable structured access.
+    #
+    # Returns nothing (modifies @rule_meta hash).
+    def extract_structured_metadata
+      return unless @rule_ptr && !@rule_ptr.null?
+
+      # Callback to process each metadata entry
+      metadata_callback = proc do |metadata_ptr, user_data|
+        next if metadata_ptr.nil? || metadata_ptr.null?
+
+        begin
+          # Extract metadata using FFI struct
+          metadata = Yara::FFI::YRX_METADATA.new(metadata_ptr)
+          identifier_ptr = metadata[:identifier]
+          next if identifier_ptr.nil? || identifier_ptr.null?
+
+          identifier = identifier_ptr.read_string.to_sym
+          value_type = metadata[:value_type]
+
+          # Extract value based on type using union access
+          # Note: We need to read from the value union at the correct offset
+          value_ptr = metadata.pointer + metadata.offset_of(:value)
+
+          case value_type
+          when Yara::FFI::YRX_I64
+            value = value_ptr.read_long_long
+          when Yara::FFI::YRX_F64
+            value = value_ptr.read_double
+          when Yara::FFI::YRX_BOOLEAN
+            value = value_ptr.read_char != 0
+          when Yara::FFI::YRX_STRING
+            string_ptr_ptr = value_ptr.read_pointer
+            value = string_ptr_ptr.nil? || string_ptr_ptr.null? ? "" : string_ptr_ptr.read_string
+          when Yara::FFI::YRX_BYTES
+            bytes_ptr = value_ptr.read_pointer
+            if bytes_ptr.nil? || bytes_ptr.null?
+              value = ""
+            else
+              # Read the YRX_METADATA_BYTES struct
+              length = bytes_ptr.read_size_t
+              data_ptr = bytes_ptr.read_pointer(8) # offset past the length field
+              value = length > 0 && !data_ptr.null? ? data_ptr.read_string(length) : ""
+            end
+          else
+            value = nil  # Unknown type
+          end
+
+          @rule_meta[identifier] = value unless value.nil?
+        rescue
+          # Skip problematic metadata entries rather than failing entirely
+          # This ensures partial extraction works even if some entries have issues
         end
       end
-      strings
+
+      # Iterate through all metadata entries
+      Yara::FFI.yrx_rule_iter_metadata(@rule_ptr, metadata_callback, nil)
+    rescue
+      # If structured metadata extraction fails, fall back to source parsing
+      # This ensures backwards compatibility
     end
 
-    def meta_as_hash(meta)
-      value = meta_value(meta[:string], meta[:integer], meta[:type])
-      { meta[:identifier].to_sym => value }
+    # Internal: Extract rule tags using YARA-X API.
+    #
+    # This method uses the YARA-X C API to access all tags defined for the rule.
+    # Tags provide categorization and organization capabilities for rule sets.
+    #
+    # Returns nothing (modifies @tags array).
+    def extract_tags
+      return unless @rule_ptr && !@rule_ptr.null?
+
+      # Callback to process each tag
+      tag_callback = proc do |tag_ptr, user_data|
+        next if tag_ptr.nil? || tag_ptr.null?
+
+        begin
+          tag = tag_ptr.read_string
+          @tags << tag unless tag.empty?
+        rescue
+          # Skip problematic tags rather than failing entirely
+        end
+      end
+
+      # Iterate through all tags
+      Yara::FFI.yrx_rule_iter_tags(@rule_ptr, tag_callback, nil)
+
+      # If iteration fails, ensure @tags is at least an empty array
+      @tags ||= []
     end
 
-    def string_as_hash(yr_string)
-      string_pointer = yr_string[:string]
-      string_identifier = yr_string[:identifier]
-      { string_identifier.to_sym => string_pointer.read_string }
+    # Internal: Extract rule namespace using YARA-X API.
+    #
+    # This method uses the YARA-X C API to access the namespace that contains
+    # this rule. Namespaces provide logical grouping and avoid naming conflicts.
+    #
+    # Returns nothing (modifies @namespace attribute).
+    def extract_namespace
+      return unless @rule_ptr && !@rule_ptr.null?
+
+      # Get namespace information
+      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)
+      return unless result == Yara::FFI::YRX_SUCCESS
+
+      namespace_ptr = ns_ptr.get_pointer(0)
+      return if namespace_ptr.nil? || namespace_ptr.null?
+
+      namespace_len = len_ptr.get_ulong(0)
+      @namespace = namespace_len > 0 ? namespace_ptr.read_string(namespace_len) : nil
+    rescue
+      # Set to nil if extraction fails
+      @namespace = nil
+    end
+
+    # Internal: Parse metadata from the original rule source code.
+    #
+    # This method uses regular expressions to extract key-value pairs from
+    # the rule's meta section. It handles string, boolean, and numeric values
+    # with basic type conversion. This is a temporary implementation until
+    # YARA-X provides direct API access to rule metadata.
+    #
+    # Examples
+    #
+    #   # Given rule source with:
+    #   # meta:
+    #   #   author = "security_team"
+    #   #   version = 1
+    #   #   active = true
+    #
+    #   result.rule_meta[:author]  # => "security_team"
+    #   result.rule_meta[:version] # => 1
+    #   result.rule_meta[:active]  # => true
+    #
+    # Returns nothing (modifies @rule_meta hash).
+    def parse_metadata_from_source
+      return unless @rule_source
+
+      # Extract metadata section more carefully
+      if @rule_source =~ /meta:\s*(.*?)(?:strings:|condition:)/m
+        meta_section = $1.strip
+
+        # Parse each line in the meta section
+        meta_section.split("\n").each do |line|
+          line = line.strip
+          next if line.empty?
+
+          if line =~ /^(\w+)\s*=\s*(.+)$/
+            key, value = $1, $2
+            parsed_value = parse_meta_value(value.strip)
+            @rule_meta[key.to_sym] = parsed_value
+          end
+        end
+      end
+    end
+
+    # Internal: Parse string patterns from the original rule source code.
+    #
+    # This method uses regular expressions to extract pattern definitions from
+    # the rule's strings section. It captures both the pattern variable names
+    # (like $string1) and their values, cleaning up quotes and regex delimiters.
+    # This is a temporary implementation until YARA-X provides direct API access.
+    #
+    # Examples
+    #
+    #   # Given rule source with:
+    #   # strings:
+    #   #   $text = "hello world"
+    #   #   $regex = /pattern[0-9]+/
+    #   #   $hex = { 41 42 43 }
+    #
+    #   result.rule_strings[:$text]  # => "hello world"
+    #   result.rule_strings[:$regex] # => "pattern[0-9]+"
+    #   result.rule_strings[:$hex]   # => "{ 41 42 43 }"
+    #
+    # Returns nothing (modifies @rule_strings hash).
+    def parse_strings_from_source
+      return unless @rule_source
+
+      # Extract strings section more carefully
+      if @rule_source =~ /strings:\s*(.*?)(?:condition:)/m
+        strings_section = $1.strip
+
+        # Parse each line in the strings section
+        strings_section.split("\n").each do |line|
+          line = line.strip
+          next if line.empty?
+
+          if line =~ /^(\$\w+)\s*=\s*(.+)$/
+            name, pattern = $1, $2
+            # Clean up the pattern (remove quotes, regex delimiters)
+            cleaned_pattern = pattern.strip.gsub(/^["\/]|["\/]$/, '')
+            @rule_strings[name.to_sym] = cleaned_pattern
+          end
+        end
+      end
     end
 
-    def meta_value(string_value, int_value, type)
-      if type == META_TYPE_INTEGER
-        int_value
-      elsif type == META_TYPE_BOOLEAN
-        int_value == 1
+    # Internal: Parse and convert metadata values to appropriate Ruby types.
+    #
+    # This method handles basic type conversion for metadata values extracted
+    # from rule source code. It recognizes quoted strings, boolean literals,
+    # and numeric values, converting them to appropriate Ruby types.
+    #
+    # value - A String containing the raw metadata value from rule source
+    #
+    # Examples
+    #
+    #   parse_meta_value('"hello"')  # => "hello"
+    #   parse_meta_value('true')     # => true
+    #   parse_meta_value('42')       # => 42
+    #   parse_meta_value('other')    # => "other"
+    #
+    # Returns the parsed value in the appropriate Ruby type.
+    def parse_meta_value(value)
+      case value
+      when /^".*"$/
+        value[1...-1] # Remove quotes
+      when /^true$/i
+        true
+      when /^false$/i
+        false
+      when /^\d+$/
+        value.to_i
       else
-        string_value
+        value
       end
     end
   end