yara-ffi 3.1.0 → 4.0.0

data/lib/yara/scan_result.rb

@@ -1,101 +1,190 @@
 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, and string patterns. This
+  # class provides access to rule information extracted from both the YARA-X
+  # API and parsed rule source code.
+  #
+  # Currently, metadata and string parsing is implemented by parsing the
+  # original rule source code using regular expressions. This is a temporary
+  # solution until YARA-X provides more complete API access to rule internals.
+  #
+  # Examples
+  #
+  #   # Typically created by Scanner during scanning
+  #   scanner.scan(data) do |result|
+  #     puts "Matched rule: #{result.rule_name}"
+  #     puts "Author: #{result.rule_meta[:author]}"
+  #     puts "Patterns: #{result.rule_strings.keys}"
+  #   end
   class ScanResult
-    RULE_MATCHING     = 1
-    RULE_NOT_MATCHING = 2
-
-    META_FLAGS_LAST_IN_RULE = 1
-
-    META_TYPE_INTEGER = 1
-    # META_TYPE_STRING  = 2
-    META_TYPE_BOOLEAN = 3
-
-    STRING_FLAGS_LAST_IN_RULE = 0
-
-    attr_reader :callback_type, :rule
-
-    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]
-    end
-
-    attr_reader :rule_meta, :rule_strings, :user_data_number
-
-    def rule_name
-      @rule[:identifier]
-    end
-
-    def scan_complete?
-      callback_type == SCAN_FINISHED
-    end
-
-    def rule_outcome?
-      [RULE_MATCHING, RULE_NOT_MATCHING].include?(callback_type)
+    # Public: The name identifier of the matched rule.
+    attr_reader :rule_name
+
+    # Public: FFI pointer to the underlying YRX_RULE structure.
+    attr_reader :rule_ptr
+
+    # Public: Hash of metadata key-value pairs extracted from the rule.
+    attr_reader :rule_meta
+
+    # Public: Hash of string pattern names and their values from the rule.
+    attr_reader :rule_strings
+
+    # 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.
+    #
+    # 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
+    #
+    # Examples
+    #
+    #   # Typically created internally by Scanner
+    #   result = ScanResult.new("MyRule", rule_ptr, true, rule_source)
+    def initialize(rule_name, rule_ptr, is_match = true, rule_source = nil)
+      @rule_name = rule_name
+      @rule_ptr = rule_ptr
+      @is_match = is_match
+      @rule_source = rule_source
+      @rule_meta = {}
+      @rule_strings = {}
+
+      # For now, parse metadata and strings from source as a temporary solution
+      if @rule_source
+        parse_metadata_from_source
+        parse_strings_from_source
+      end
     end
 
+    # 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?
-      callback_type == RULE_MATCHING
+      @is_match
     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
+    # 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
-      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
+    # 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
-      strings
-    end
-
-    def meta_as_hash(meta)
-      value = meta_value(meta[:string], meta[:integer], meta[:type])
-      { meta[:identifier].to_sym => value }
-    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 }
     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

data/lib/yara/scan_results.rb

@@ -0,0 +1,224 @@
+module Yara
+  # Public: Collection of ScanResult objects from YARA scanning operations.
+  #
+  # ScanResults acts as an enumerable container for individual rule matches,
+  # providing convenient methods for accessing and querying scan results. It
+  # supports standard collection operations and offers specialized methods for
+  # common YARA use cases like checking for any matches or extracting rule names.
+  #
+  # This class is typically returned by Scanner#scan when no block is provided,
+  # containing all rules that matched during the scanning operation.
+  #
+  # Examples
+  #
+  #   results = scanner.scan(data)
+  #
+  #   if results.matched?
+  #     puts "Found #{results.size} matches"
+  #     results.each { |match| puts match.rule_name }
+  #   end
+  #
+  #   rule_names = results.matching_rules
+  #   first_match = results.first
+  class ScanResults
+    include Enumerable
+
+    # Public: Initialize a new ScanResults collection.
+    #
+    # Creates an empty results collection that can be populated with ScanResult
+    # objects. This is typically called internally by Scanner during scanning
+    # operations.
+    #
+    # results - An optional Array of ScanResult objects (default: empty array)
+    #
+    # Examples
+    #
+    #   # Typically created internally by Scanner
+    #   results = ScanResults.new
+    #   results << scan_result
+    def initialize(results = [])
+      @results = results
+    end
+
+    # Public: Enumerate over all scan results.
+    #
+    # Implements the Enumerable interface, allowing standard collection methods
+    # like map, select, reject, etc. to be used on the results collection.
+    #
+    # block - Block that receives each ScanResult object
+    #
+    # Examples
+    #
+    #   results.each { |result| puts result.rule_name }
+    #   matched_names = results.map(&:rule_name)
+    #   malware_results = results.select { |r| r.rule_meta[:category] == 'malware' }
+    #
+    # Returns an Enumerator when no block given, otherwise returns self.
+    def each(&block)
+      @results.each(&block)
+    end
+
+    # Public: Add a ScanResult to this collection.
+    #
+    # This method is used internally during scanning to accumulate matching
+    # rules. It appends the result to the internal results array.
+    #
+    # result - A ScanResult object to add to the collection
+    #
+    # Examples
+    #
+    #   results = ScanResults.new
+    #   results << ScanResult.new("MyRule", rule_ptr)
+    #
+    # Returns self for method chaining.
+    def <<(result)
+      @results << result
+    end
+
+    # Public: Get all scan results as an array.
+    #
+    # Returns the internal array of ScanResult objects. This method is provided
+    # for compatibility and direct access to the underlying collection.
+    #
+    # Examples
+    #
+    #   all_results = results.matches
+    #   puts "Found #{all_results.length} matches"
+    #
+    # Returns an Array of ScanResult objects.
+    def matches
+      @results
+    end
+
+    # Public: Extract the names of all matching rules.
+    #
+    # This convenience method returns just the rule names from all results,
+    # which is commonly needed for logging, reporting, or further processing
+    # of scan results.
+    #
+    # Examples
+    #
+    #   rule_names = results.matching_rules
+    #   puts "Matched: #{rule_names.join(', ')}"
+    #
+    # Returns an Array of String rule names.
+    def matching_rules
+      @results.map(&:rule_name)
+    end
+
+    # Public: Check if any rules matched during scanning.
+    #
+    # This is a convenience method to test whether the scan found any matches
+    # without needing to check the size or examine individual results.
+    #
+    # Examples
+    #
+    #   if results.matched?
+    #     puts "Scan found matches!"
+    #   else
+    #     puts "No matches found"
+    #   end
+    #
+    # Returns true if there are any results, false otherwise.
+    def matched?
+      !@results.empty?
+    end
+
+    # Public: Alias for matched? method.
+    #
+    # Provides an alternative method name that may be more natural in some
+    # contexts, particularly when used in conditional expressions.
+    #
+    # Examples
+    #
+    #   puts "Clean file" unless results.match?
+    #
+    # Returns true if there are any results, false otherwise.
+    alias_method :match?, :matched?
+
+    # Public: Get the number of matching rules.
+    #
+    # Returns the count of ScanResult objects in this collection, indicating
+    # how many rules matched during the scan operation.
+    #
+    # Examples
+    #
+    #   puts "#{results.size} rules matched"
+    #   alert_count = results.size
+    #
+    # Returns an Integer count of results.
+    def size
+      @results.size
+    end
+
+    # Public: Aliases for size method.
+    #
+    # These provide alternative method names for getting the collection size,
+    # maintaining compatibility with standard Ruby collection interfaces.
+    alias_method :length, :size
+    alias_method :count, :size
+
+    # Public: Get the first scan result.
+    #
+    # Returns the first ScanResult object in the collection, or nil if the
+    # collection is empty. Useful when you expect only one match or want to
+    # examine the first match found.
+    #
+    # Examples
+    #
+    #   first_match = results.first
+    #   puts first_match.rule_name if first_match
+    #
+    # Returns a ScanResult object or nil if collection is empty.
+    def first
+      @results.first
+    end
+
+    # Public: Get the last scan result.
+    #
+    # Returns the last ScanResult object in the collection, or nil if the
+    # collection is empty. The order depends on the sequence in which rules
+    # matched during scanning.
+    #
+    # Examples
+    #
+    #   last_match = results.last
+    #   puts "Final match: #{last_match.rule_name}" if last_match
+    #
+    # Returns a ScanResult object or nil if collection is empty.
+    def last
+      @results.last
+    end
+
+    # Public: Check if the results collection is empty.
+    #
+    # Returns true if no rules matched during scanning, false otherwise.
+    # This is the inverse of matched? and can be useful for control flow.
+    #
+    # Examples
+    #
+    #   puts "No threats detected" if results.empty?
+    #   process_results unless results.empty?
+    #
+    # Returns true if no results exist, false otherwise.
+    def empty?
+      @results.empty?
+    end
+
+    # Public: Convert results to a plain array.
+    #
+    # Returns a duplicate of the internal results array, allowing manipulation
+    # without affecting the original ScanResults object. This is useful when
+    # you need to work with the results as a standard Ruby array.
+    #
+    # Examples
+    #
+    #   array_copy = results.to_a
+    #   sorted_results = results.to_a.sort_by(&:rule_name)
+    #
+    # Returns a new Array containing all ScanResult objects.
+    def to_a
+      @results.dup
+    end
+  end
+end