Class: Yara::ScanResults

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/yara/scan_results.rb

Overview

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

Instance Method Summary collapse

Constructor Details

#initialize(results = []) ⇒ ScanResults

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



39
40
41
 
# File 'lib/yara/scan_results.rb', line 39

def initialize(results = [])
  @results = results
end

Instance Method Details

#<<(result) ⇒ Object

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.



74
75
76
 
# File 'lib/yara/scan_results.rb', line 74

def <<(result)
  @results << result
end

#each(&block) ⇒ Object

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.



57
58
59
 
# File 'lib/yara/scan_results.rb', line 57

def each(&block)
  @results.each(&block)
end

#empty? ⇒ Boolean

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.

Returns:

  • (Boolean) 


204
205
206
 
# File 'lib/yara/scan_results.rb', line 204

def empty?
  @results.empty?
end

#first ⇒ Object

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.



173
174
175
 
# File 'lib/yara/scan_results.rb', line 173

def first
  @results.first
end

#last ⇒ Object

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.



189
190
191
 
# File 'lib/yara/scan_results.rb', line 189

def last
  @results.last
end

#matched? ⇒ Boolean Also known as: match?

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.

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/yara/scan_results.rb', line 123

def matched?
  !@results.empty?
end

#matches ⇒ Object

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.



89
90
91
 
# File 'lib/yara/scan_results.rb', line 89

def matches
  @results
end

#matching_rules ⇒ Object

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.



105
106
107
 
# File 'lib/yara/scan_results.rb', line 105

def matching_rules
  @results.map(&:rule_name)
end

#size ⇒ Object Also known as: length, count

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.



150
151
152
 
# File 'lib/yara/scan_results.rb', line 150

def size
  @results.size
end

#to_a ⇒ Object

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.



220
221
222
 
# File 'lib/yara/scan_results.rb', line 220

def to_a
  @results.dup
end