yara-ffi 3.1.0 → 4.0.0

data/lib/yara/scanner.rb

@@ -1,81 +1,269 @@
 module Yara
+  # Public: High-level interface for compiling YARA rules and scanning data.
+  #
+  # The Scanner class provides a Ruby-friendly interface to YARA-X functionality.
+  # It manages the complete lifecycle of rule compilation, scanner creation, data
+  # scanning, and proper resource cleanup. Use this class for all normal YARA
+  # operations rather than the low-level FFI bindings.
+  #
+  # The scanner follows a compile-then-scan workflow:
+  # 1. Create scanner and add rules with add_rule()
+  # 2. Compile rules with compile()
+  # 3. Scan data with scan()
+  # 4. Clean up resources with close() or use block syntax for automatic cleanup
+  #
+  # Examples
+  #
+  #   # Automatic resource management (recommended)
+  #   rule = 'rule test { strings: $a = "hello" condition: $a }'
+  #   Scanner.open(rule) do |scanner|
+  #     scanner.compile
+  #     results = scanner.scan("hello world")
+  #   end
+  #
+  #   # Manual resource management
+  #   scanner = Scanner.new
+  #   scanner.add_rule(rule)
+  #   scanner.compile
+  #   results = scanner.scan(data)
+  #   scanner.close  # Required to prevent memory leaks
   class Scanner
-    class NotCompiledError < StandardError; end
+    # Public: Raised when YARA rule compilation fails.
+    #
+    # This exception indicates syntax errors, undefined variables, or other
+    # issues that prevent successful rule compilation. The message includes
+    # details from YARA-X about what went wrong.
+    class CompilationError < StandardError; end
 
-    ERROR_CALLBACK = proc do |error_level, file_name, line_number, rule, message, user_data|
-      # noop
-    end
+    # Public: Raised when scanning operations fail.
+    #
+    # This exception indicates runtime errors during data scanning, such as
+    # I/O errors, memory issues, or internal YARA-X failures.
+    class ScanError < StandardError; end
 
-    SCAN_FINISHED = 3
+    # Public: Raised when attempting to scan before compiling rules.
+    #
+    # This exception indicates a programming error where scan() was called
+    # before compile(). Rules must be compiled before scanning can occur.
+    class NotCompiledError < StandardError; end
 
-    # Public: Initializes instance of scanner. Under the hood this creates a pointer,
-    # then calls yr_compiler_create with that pointer.
+    # Public: Initialize a new Scanner instance.
+    #
+    # Creates a new scanner in an empty state. Rules must be added with
+    # add_rule() and compiled with compile() before scanning can occur.
     #
-    # error_callback: (optional) Proc to be called when an error occurs.
-    # user_data: (optional) Instance of UserData to store and pass information.
-    def initialize(error_callback: ERROR_CALLBACK, user_data: UserData.new)
-      @error_callback = error_callback
-      @user_data = user_data
-      @compiler_pointer = ::FFI::MemoryPointer.new(:pointer)
-      Yara::FFI.yr_compiler_create(@compiler_pointer)
-      @compiler_pointer = @compiler_pointer.get_pointer(0)
-      Yara::FFI.yr_compiler_set_callback(@compiler_pointer, error_callback, user_data)
+    # Examples
+    #
+    #   scanner = Scanner.new
+    #   scanner.add_rule('rule test { condition: true }')
+    #   scanner.compile
+    def initialize
+      @rules_pointer = nil
+      @scanner_pointer = nil
+      @rule_source = ""
     end
 
-    # Public: Adds a rule to the scanner and returns the namespace value. If a namespace
-    # is not provided it will default to nil and use the global namespace.
+    # Public: Add a YARA rule to the scanner for later compilation.
+    #
+    # Rules are accumulated as source code and compiled together when compile()
+    # is called. Multiple rules can be added to create rule sets. Optional
+    # namespacing allows logical grouping of related rules.
+    #
+    # rule_string - A String containing a complete YARA rule definition
+    # namespace   - An optional String namespace to contain the rule
+    #
+    # Examples
     #
-    # rule_string - String containing the Yara rule to be added.
-    # namespace:    (optional) String containing the namespace to be used for the rule.
+    #   scanner.add_rule('rule test1 { condition: true }')
+    #   scanner.add_rule('rule test2 { condition: false }', namespace: 'testing')
+    #
+    # Returns nothing.
     def add_rule(rule_string, namespace: nil)
-      Yara::FFI.yr_compiler_add_string(@compiler_pointer, rule_string, namespace)
+      # For now, we'll just store the rule source and compile later
+      # yara-x doesn't have separate add_rule like libyara
+      if namespace
+        @rule_source += "\nnamespace #{namespace} {\n#{rule_string}\n}\n"
+      else
+        @rule_source += "\n#{rule_string}\n"
+      end
     end
 
+    # Public: Compile all added rules into an executable scanner.
+    #
+    # This method compiles all rules added via add_rule() into an optimized
+    # form suitable for scanning. Compilation must succeed before any scanning
+    # operations can be performed. The compiled rules are used to create an
+    # internal scanner object for efficient data processing.
+    #
+    # Examples
+    #
+    #   scanner = Scanner.new
+    #   scanner.add_rule('rule test { condition: true }')
+    #   scanner.compile
+    #
+    # Returns nothing.
+    # Raises CompilationError if rule compilation fails.
     def compile
+      raise CompilationError, "No rules added" if @rule_source.empty?
+
       @rules_pointer = ::FFI::MemoryPointer.new(:pointer)
-      Yara::FFI.yr_compiler_get_rules(@compiler_pointer, @rules_pointer)
+      result = Yara::FFI.yrx_compile(@rule_source, @rules_pointer)
+
+      if result != Yara::FFI::YRX_SUCCESS
+        error_msg = Yara::FFI.yrx_last_error
+        raise CompilationError, "Failed to compile rules: #{error_msg}"
+      end
+
       @rules_pointer = @rules_pointer.get_pointer(0)
-      Yara::FFI.yr_compiler_destroy(@compiler_pointer)
+
+      # Create scanner
+      @scanner_pointer_holder = ::FFI::MemoryPointer.new(:pointer)
+      result = Yara::FFI.yrx_scanner_create(@rules_pointer, @scanner_pointer_holder)
+
+      if result != Yara::FFI::YRX_SUCCESS
+        error_msg = Yara::FFI.yrx_last_error
+        raise CompilationError, "Failed to create scanner: #{error_msg}"
+      end
+
+      @scanner_pointer = @scanner_pointer_holder.get_pointer(0)
     end
 
-    def call(test_string)
-      raise NotCompiledError unless @rules_pointer
-
-      results = []
-      scanning = true
-      result_callback = proc do |context_ptr, callback_type, rule, user_data|
-        if callback_type == SCAN_FINISHED
-          scanning = false
-        else
-          result = ScanResult.new(callback_type, rule, user_data)
-          results << result if result.rule_outcome?
+    # Public: Scan data against compiled rules.
+    #
+    # This method scans the provided data using all compiled rules, returning
+    # information about any matches found. When a block is provided, each
+    # matching rule is yielded immediately as it's discovered during scanning.
+    #
+    # Scanning treats the input as binary data regardless of content type.
+    # String encoding is preserved but pattern matching occurs at the byte level.
+    #
+    # test_string - A String containing the data to scan
+    # block       - Optional block that receives each ScanResult as found
+    #
+    # Examples
+    #
+    #   # Collect all results
+    #   results = scanner.scan("data to scan")
+    #   results.each { |match| puts match.rule_name }
+    #
+    #   # Process matches immediately
+    #   scanner.scan("data to scan") do |match|
+    #     puts "Found: #{match.rule_name}"
+    #   end
+    #
+    # Returns a ScanResults object containing matches when no block given.
+    # Returns nil when a block is provided (matches are yielded instead).
+    # Raises NotCompiledError if compile() has not been called.
+    # Raises ScanError if scanning fails.
+    def scan(test_string)
+      raise NotCompiledError, "Rules not compiled. Call compile() first." unless @scanner_pointer
+
+      results = ScanResults.new
+
+      # Set up callback for matching rules
+      callback = proc do |rule_ptr, user_data|
+        # Extract rule identifier
+        ident_ptr = ::FFI::MemoryPointer.new(:pointer)
+        len_ptr = ::FFI::MemoryPointer.new(:size_t)
+
+        if Yara::FFI.yrx_rule_identifier(rule_ptr, ident_ptr, len_ptr) == Yara::FFI::YRX_SUCCESS
+          identifier_ptr = ident_ptr.get_pointer(0)
+          identifier_len = len_ptr.get_ulong(0)
+          rule_name = identifier_ptr.read_string(identifier_len)
+
+          # Create a result with the rule source for metadata/string parsing
+          result = ScanResult.new(rule_name, rule_ptr, true, @rule_source)
+          results << result
+
+          yield result if block_given?
         end
+      end
 
-        0 # ERROR_SUCCESS
+      # Set the callback
+      result = Yara::FFI.yrx_scanner_on_matching_rule(@scanner_pointer, callback, nil)
+      if result != Yara::FFI::YRX_SUCCESS
+        error_msg = Yara::FFI.yrx_last_error
+        raise ScanError, "Failed to set callback: #{error_msg}"
       end
 
+      # Scan the data
       test_string_bytesize = test_string.bytesize
       test_string_pointer = ::FFI::MemoryPointer.new(:char, test_string_bytesize)
       test_string_pointer.put_bytes(0, test_string)
 
-      Yara::FFI.yr_rules_scan_mem(
-        @rules_pointer,
-        test_string_pointer,
-        test_string_bytesize,
-        0,
-        result_callback,
-        @user_data,
-        1,
-      )
-
-      while scanning do
+      result = Yara::FFI.yrx_scanner_scan(@scanner_pointer, test_string_pointer, test_string_bytesize)
+      if result != Yara::FFI::YRX_SUCCESS
+        error_msg = Yara::FFI.yrx_last_error
+        raise ScanError, "Scan failed: #{error_msg}"
       end
 
-      results
+      block_given? ? nil : results
     end
 
+    # Public: Free all resources associated with this scanner.
+    #
+    # This method releases memory allocated by YARA-X for the compiled rules
+    # and scanner objects. It must be called to prevent memory leaks when
+    # using manual resource management. After calling close(), the scanner
+    # cannot be used for further operations.
+    #
+    # The open() class method with a block automatically calls close() to
+    # ensure proper cleanup even if exceptions occur.
+    #
+    # Examples
+    #
+    #   scanner = Scanner.new
+    #   # ... use scanner
+    #   scanner.close  # Required for cleanup
+    #
+    # Returns nothing.
     def close
-      Yara::FFI.yr_rules_destroy(@rules_pointer)
+      Yara::FFI.yrx_scanner_destroy(@scanner_pointer) if @scanner_pointer
+      Yara::FFI.yrx_rules_destroy(@rules_pointer) if @rules_pointer
+      @scanner_pointer = nil
+      @rules_pointer = nil
+    end
+
+    # Public: Create a scanner with automatic resource management.
+    #
+    # This class method creates a Scanner instance and optionally adds an
+    # initial rule. When used with a block, it ensures proper resource cleanup
+    # by automatically calling close() even if exceptions occur during scanning.
+    # This is the recommended way to use Scanner for most applications.
+    #
+    # rule_string - An optional String containing a YARA rule definition
+    # namespace   - An optional String namespace for the initial rule
+    # block       - Block that receives the scanner instance
+    #
+    # Examples
+    #
+    #   # Block syntax with automatic cleanup (recommended)
+    #   Scanner.open(rule) do |scanner|
+    #     scanner.compile
+    #     results = scanner.scan(data)
+    #   end
+    #
+    #   # Without block (manual cleanup required)
+    #   scanner = Scanner.open(rule)
+    #   scanner.compile
+    #   # ... use scanner
+    #   scanner.close
+    #
+    # Returns the result of the block when block given.
+    # Returns a new Scanner instance when no block given.
+    def self.open(rule_string = nil, namespace: nil)
+      scanner = new
+      scanner.add_rule(rule_string, namespace: namespace) if rule_string
+
+      if block_given?
+        begin
+          yield scanner
+        ensure
+          scanner.close
+        end
+      else
+        scanner
+      end
     end
   end
 end

data/lib/yara/version.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
 module Yara
-  VERSION = "3.1.0"
+  # Public: Version information for the yara-ffi gem.
+  #
+  # This constant holds the current version of the Ruby gem, not the underlying
+  # YARA-X library version. The gem version follows semantic versioning.
+  VERSION = "4.0.0"
 end

data/lib/yara.rb

@@ -4,26 +4,81 @@ require "ffi"
 require "pry"
 require_relative "yara/ffi"
 require_relative "yara/scan_result"
+require_relative "yara/scan_results"
 require_relative "yara/scanner"
 require_relative "yara/version"
 
+# Public: Main module providing Ruby FFI bindings to YARA-X for pattern
+# matching and malware detection.
+#
+# This gem provides a Ruby interface to the YARA-X library (Rust-based YARA
+# implementation) for scanning files, strings, and binary data using YARA rules.
+# It offers both high-level convenience methods and low-level scanner control.
+#
+# Examples
+#
+#   # Quick scanning with automatic resource cleanup
+#   rule = 'rule test { strings: $a = "hello" condition: $a }'
+#   results = Yara.scan(rule, "hello world")
+#
+#   # Manual scanner control for advanced use cases
+#   Yara::Scanner.open(rule) do |scanner|
+#     scanner.compile
+#     results = scanner.scan(data)
+#   end
 module Yara
-  def self.start
-    Yara::FFI.yr_initialize
-  end
-
-  def self.stop
-    Yara::FFI.yr_finalize
+  # Public: Test a YARA rule against data with automatic cleanup.
+  #
+  # This is a convenience method that handles the complete scan lifecycle:
+  # rule compilation, scanning, and resource cleanup. Use this for simple
+  # one-off scans where you don't need fine-grained control.
+  #
+  # rule_string - A String containing the YARA rule definition
+  # test_string - A String containing the data to scan
+  #
+  # Examples
+  #
+  #   rule = 'rule test { strings: $a = "malware" condition: $a }'
+  #   results = Yara.test(rule, "potential malware signature")
+  #   # => #<Yara::ScanResults:0x... @results=[...]>
+  #
+  # Returns a Yara::ScanResults object containing any matching rules.
+  # Raises Yara::Scanner::CompilationError if the rule is invalid.
+  # Raises Yara::Scanner::ScanError if scanning fails.
+  def self.test(rule_string, test_string)
+    Scanner.open(rule_string) do |scanner|
+      scanner.compile
+      scanner.scan(test_string)
+    end
   end
 
-  def self.test(rule_string, test_string)
-    start
-    scanner = Yara::Scanner.new
-    scanner.add_rule(rule_string)
-    scanner.compile
-    scanner.call(test_string)
-  ensure
-    scanner.close
-    stop
+  # Public: Scan data with a YARA rule, optionally yielding each match.
+  #
+  # This is a convenience method for scanning with optional block-based
+  # processing of results. When a block is provided, each matching rule
+  # is yielded as it's found during scanning.
+  #
+  # rule_string - A String containing the YARA rule definition
+  # data        - A String containing the data to scan
+  # block       - Optional block that receives each ScanResult as found
+  #
+  # Examples
+  #
+  #   # Collect all results
+  #   results = Yara.scan(rule, data)
+  #
+  #   # Process matches as they're found
+  #   Yara.scan(rule, data) do |match|
+  #     puts "Found: #{match.rule_name}"
+  #   end
+  #
+  # Returns a Yara::ScanResults object when no block given, nil when block given.
+  # Raises Yara::Scanner::CompilationError if the rule is invalid.
+  # Raises Yara::Scanner::ScanError if scanning fails.
+  def self.scan(rule_string, data, &block)
+    Scanner.open(rule_string) do |scanner|
+      scanner.compile
+      scanner.scan(data, &block)
+    end
   end
 end

data/yara-ffi.gemspec

@@ -8,11 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors = ["Jonathan Hoyt"]
   spec.email = ["jonmagic@gmail.com"]
 
-  spec.summary = "A Ruby API to libyara."
-  spec.description = "Use libyara from Ruby via ffi bindings."
+  spec.summary = "A Ruby API to YARA-X."
+  spec.description = "Use YARA-X from Ruby via FFI bindings."
   spec.homepage = "https://github.com/jonmagic/yara-ffi"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/jonmagic/yara-ffi"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: yara-ffi
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Jonathan Hoyt
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -24,18 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Use libyara from Ruby via ffi bindings.
+description: Use YARA-X from Ruby via FFI bindings.
 email:
 - jonmagic@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/copilot-instructions.md"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- DEVELOPMENT.md
 - Dockerfile
 - Gemfile
 - Gemfile.lock
@@ -47,13 +48,9 @@ files:
 - lib/yara.rb
 - lib/yara/ffi.rb
 - lib/yara/scan_result.rb
+- lib/yara/scan_results.rb
 - lib/yara/scanner.rb
-- lib/yara/user_data.rb
 - lib/yara/version.rb
-- lib/yara/yr_meta.rb
-- lib/yara/yr_namespace.rb
-- lib/yara/yr_rule.rb
-- lib/yara/yr_string.rb
 - script/bootstrap
 - script/test
 - yara-ffi.gemspec
@@ -64,7 +61,6 @@ metadata:
   homepage_uri: https://github.com/jonmagic/yara-ffi
   source_code_uri: https://github.com/jonmagic/yara-ffi
   changelog_uri: https://github.com/jonmagic/yara-ffi/main/CHANGELOG.md,
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -72,15 +68,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: A Ruby API to libyara.
+summary: A Ruby API to YARA-X.
 test_files: []

data/lib/yara/user_data.rb

@@ -1,5 +0,0 @@
-module Yara
-  class UserData < FFI::Struct
-    layout :number, :int
-  end
-end

data/lib/yara/yr_meta.rb

@@ -1,10 +0,0 @@
-module Yara
-  class YrMeta < FFI::Struct
-    layout \
-      :identifier, :string,
-      :string, :string,
-      :integer, :ulong_long,
-      :type, :int,
-      :flags, :int
-  end
-end

data/lib/yara/yr_namespace.rb

@@ -1,5 +0,0 @@
-module Yara
-  class YrNamespace < FFI::Struct
-    layout :name, :string
-  end
-end

data/lib/yara/yr_rule.rb

@@ -1,11 +0,0 @@
-module Yara
-  class YrRule < FFI::Struct
-    layout \
-      :flags, :int,
-      :identifier, :string,
-      :tags, :string,
-      :metas, :pointer,
-      :strings, :pointer,
-      :ns, YrNamespace.ptr
-  end
-end

data/lib/yara/yr_string.rb

@@ -1,15 +0,0 @@
-module Yara
-  class YrString < FFI::Struct
-    layout \
-      :flags, :uint,
-      :idx, :uint,
-      :fixed_offset, :ulong_long,
-      :rule_idx, :uint,
-      :length, :uint,
-      :string, :pointer,
-      :chained_to, :pointer,
-      :chain_gap_min, :uint,
-      :chain_gap_max, :uint,
-      :identifier, :string
-  end
-end