yara-ffi 3.1.0 → 4.1.0

data/lib/yara/ffi.rb

@@ -1,116 +1,505 @@
-require_relative "yr_meta"
-require_relative "yr_namespace"
-require_relative "yr_string"
-require_relative "yr_rule"
-require_relative "user_data"
-
 module Yara
-  # FFI bindings to libyara.
+  # Internal: Low-level FFI bindings to the YARA-X C API.
+  #
+  # This module provides direct Ruby FFI bindings to the yara_x_capi library.
+  # It handles dynamic library loading with multiple fallback paths and exposes
+  # the raw C functions for rule compilation, scanning, and resource management.
+  #
+  # The FFI module is primarily used internally by higher-level classes like
+  # Scanner. Direct usage requires careful memory management and error handling.
+  #
+  # Examples
+  #
+  #   # Direct FFI usage (not recommended for normal use)
+  #   rules_ptr = FFI::MemoryPointer.new(:pointer)
+  #   result = Yara::FFI.yrx_compile("rule test { condition: true }", rules_ptr)
+  #   raise "Error: #{Yara::FFI.yrx_last_error}" unless result == Yara::FFI::YRX_SUCCESS
   module FFI
     extend ::FFI::Library
-    ffi_lib "libyara"
-
-    # int yr_initialize(void)
-    attach_function :yr_initialize, [], :int
-
-    # int yr_finalize(void)
-    attach_function :yr_finalize, [], :int
-
-    # Creates a new compiler and assigns a pointer to that compiler
-    # to the pointer passed into the method. To access the complier
-    # get the pointer from the pointer you passed in.
-    #
-    # Usage:
-    # > compiler_pointer = FFI::MemoryPointer.new(:pointer)
-    # > Yara::FFI.yr_compiler_create(compiler_pointer)
-    # > compiler_pointer = compiler_pointer.get_pointer(0)
-    #
-    # int yr_compiler_create(YR_COMPILER** compiler)
-    attach_function :yr_compiler_create, [
-      :pointer, # compiler_pointer*
-    ], :int
-
-    # int yr_compiler_destroy(YR_COMPILER* compiler)
-    attach_function :yr_compiler_destroy, [
-      :pointer, # compiler_pointer
-    ], :void
-
-    # int yr_rules_destroy(YR_RULES* rules)
-    attach_function :yr_rules_destroy, [
-      :pointer, # rules_pointer
-    ], :void
-
-    # void callback_function(
-    #   int error_level,
-    #   const char* file_name,
-    #   int line_number,
-    #   const YR_RULE* rule,
-    #   const char* message,
-    #   void* user_data)
-    callback :add_rule_error_callback, [
-      :int,       # error_level
-      :string,    # file_name
-      :int,       # line_number
-      YrRule.by_ref, # YrRule*
-      :string,    # message
-      :pointer,   # user_data_pointer
-    ], :void
-
-    # void yr_compiler_set_callback(
-    #   YR_COMPILER* compiler,
-    #   YR_COMPILER_CALLBACK_FUNC callback,
-    #   void* user_data)
-    attach_function :yr_compiler_set_callback, [
-      :pointer,                 # compiler_pointer*
-      :add_rule_error_callback, # proc
-      :pointer,                 # user_data_pointer
-    ], :void
-
-    # int yr_compiler_add_string(
-    #   YR_COMPILER* compiler,
-    #   const char* string,
-    #   const char* namespace_)
-    attach_function :yr_compiler_add_string, [
-      :pointer,   # compiler_pointer*
-      :string,    # rule string
-      :string,    # namespace
-    ], :int
-
-    # int yr_compiler_get_rules(
-    #   YR_COMPILER* compiler,
-    #   YR_RULES** rules)
-    attach_function :yr_compiler_get_rules, [
-      :pointer, # compiler_pointer*
-      :pointer, # rules_pointer*
-    ], :int
-
-    # int callback_function(
-    #   int message,
-    #   void* message_data,
-    #   void* user_data)
-    callback :scan_callback, [
-      :pointer,       # YR_SCAN_CONTEXT*
-      :int,           # callback_type
-      YrRule.ptr,     # rule
-      UserData.ptr,   # user_data
-    ], :int
-
-    # int yr_rules_scan_mem(
-    #   YR_RULES* rules,
-    #   const uint8_t* buffer,
-    #   size_t buffer_size,
-    #   int flags,
-    #   YR_CALLBACK_FUNC callback,
-    #   void* user_data,
-    #   int timeout)
-    attach_function :yr_rules_scan_mem, [
-      :pointer,       # rules_pointer*
-      :pointer,       # buffer (aka test subject)
-      :size_t,        # buffer size (String#bytesize)
-      :int,           # flags
-      :scan_callback, # proc
-      :pointer,       # user_data_pointer
-      :int,           # timeout in seconds
-    ], :int
+
+    # Internal: Library search paths for yara_x_capi shared library.
+    #
+    # These paths are tried in order to locate the YARA-X C API library.
+    # The first successful load is used. This supports various deployment
+    # scenarios including system packages, Docker containers, and CI environments.
+    library_paths = [
+      "yara_x_capi",                                          # System library (preferred)
+      "/usr/local/lib/x86_64-linux-gnu/libyara_x_capi.so",    # GitHub Actions/CI
+      "/usr/local/lib/aarch64-linux-gnu/libyara_x_capi.so",   # Local Docker (ARM)
+      "/usr/local/lib/libyara_x_capi.so",                     # Generic fallback
+      "libyara_x_capi"                                        # Final fallback
+    ]
+
+    library_loaded = false
+    library_paths.each do |path|
+      begin
+        ffi_lib path
+        library_loaded = true
+        break
+      rescue LoadError
+        next
+      end
+    end
+
+    raise LoadError, "Could not load yara_x_capi library from any of: #{library_paths.join(', ')}" unless library_loaded
+
+    # Public: Compile YARA rule source into executable rules object.
+    #
+    # This is the primary compilation function that parses YARA rule source code
+    # and creates an optimized rules object for scanning. The rules object must
+    # be freed with yrx_rules_destroy when no longer needed.
+    #
+    # src   - A String containing YARA rule source code
+    # rules - A FFI::MemoryPointer that will receive the rules object pointer
+    #
+    # Examples
+    #
+    #   rules_ptr = FFI::MemoryPointer.new(:pointer)
+    #   result = Yara::FFI.yrx_compile(rule_source, rules_ptr)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_compile(const char *src, struct YRX_RULES **rules)
+    attach_function :yrx_compile, [:string, :pointer], :int
+
+    # Public: Get the last error message from YARA-X operations.
+    #
+    # When any YARA-X function returns an error code, this function provides
+    # a human-readable description of what went wrong. The returned string
+    # is managed by YARA-X and should not be freed.
+    #
+    # Examples
+    #
+    #   if result != YRX_SUCCESS
+    #     error_msg = Yara::FFI.yrx_last_error
+    #     raise "YARA Error: #{error_msg}"
+    #   end
+    #
+    # Returns a String containing the last error message.
+    # C Signature: const char* yrx_last_error(void)
+    attach_function :yrx_last_error, [], :string
+
+    # Public: Free memory associated with a compiled rules object.
+    #
+    # This function must be called to free the memory allocated by yrx_compile.
+    # After calling this function, the rules pointer becomes invalid and should
+    # not be used.
+    #
+    # rules - A Pointer to the rules object to destroy
+    #
+    # Examples
+    #
+    #   Yara::FFI.yrx_rules_destroy(rules_ptr)
+    #
+    # Returns nothing.
+    # C Signature: void yrx_rules_destroy(struct YRX_RULES *rules)
+    attach_function :yrx_rules_destroy, [:pointer], :void
+
+    # Public: Create a scanner object from compiled rules.
+    #
+    # A scanner is needed to perform actual pattern matching against data.
+    # Multiple scanners can be created from the same rules object to enable
+    # concurrent scanning. The scanner must be freed with yrx_scanner_destroy.
+    #
+    # rules   - A Pointer to compiled rules object
+    # scanner - A FFI::MemoryPointer that will receive the scanner object pointer
+    #
+    # Examples
+    #
+    #   scanner_ptr = FFI::MemoryPointer.new(:pointer)
+    #   result = Yara::FFI.yrx_scanner_create(rules_ptr, scanner_ptr)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_scanner_create(const struct YRX_RULES *rules, struct YRX_SCANNER **scanner)
+    attach_function :yrx_scanner_create, [:pointer, :pointer], :int
+
+    # Public: Free memory associated with a scanner object.
+    #
+    # This function must be called to free the memory allocated by
+    # yrx_scanner_create. After calling this function, the scanner pointer
+    # becomes invalid and should not be used.
+    #
+    # scanner - A Pointer to the scanner object to destroy
+    #
+    # Examples
+    #
+    #   Yara::FFI.yrx_scanner_destroy(scanner_ptr)
+    #
+    # Returns nothing.
+    # C Signature: void yrx_scanner_destroy(struct YRX_SCANNER *scanner)
+    attach_function :yrx_scanner_destroy, [:pointer], :void
+
+    # Internal: Callback function type for rule matching events.
+    #
+    # This callback is invoked for each rule that matches during scanning.
+    # The callback receives pointers to the matching rule and optional user data.
+    #
+    # rule      - A Pointer to the YRX_RULE structure
+    # user_data - A Pointer to optional user-provided data
+    #
+    # C Signature: typedef void (*YRX_ON_MATCHING_RULE)(const struct YRX_RULE *rule, void *user_data)
+    callback :matching_rule_callback, [:pointer, :pointer], :void
+
+    # Public: Set callback for handling rule matches during scanning.
+    #
+    # This function registers a callback that will be invoked each time a rule
+    # matches during scanning. The callback can extract information about the
+    # matching rule and optionally halt scanning.
+    #
+    # scanner   - A Pointer to the scanner object
+    # callback  - A Proc matching the matching_rule_callback signature
+    # user_data - A Pointer to optional data passed to callback (can be nil)
+    #
+    # Examples
+    #
+    #   callback = proc { |rule_ptr, user_data| puts "Rule matched!" }
+    #   result = Yara::FFI.yrx_scanner_on_matching_rule(scanner_ptr, callback, nil)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_scanner_on_matching_rule(struct YRX_SCANNER *scanner, YRX_ON_MATCHING_RULE callback, void *user_data)
+    attach_function :yrx_scanner_on_matching_rule, [:pointer, :matching_rule_callback, :pointer], :int
+
+    # Public: Scan data using the configured scanner and rules.
+    #
+    # This function performs pattern matching against the provided data using
+    # all rules in the scanner. Any matching rules trigger the registered
+    # callback function. The data is scanned as binary regardless of content.
+    #
+    # scanner - A Pointer to the scanner object
+    # data    - A Pointer to the data buffer to scan
+    # len     - A size_t indicating the length of data in bytes
+    #
+    # Examples
+    #
+    #   data_ptr = FFI::MemoryPointer.new(:char, data.bytesize)
+    #   data_ptr.put_bytes(0, data)
+    #   result = Yara::FFI.yrx_scanner_scan(scanner_ptr, data_ptr, data.bytesize)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # 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
+    # called from within a matching rule callback. The identifier is returned
+    # as a pointer and length rather than a null-terminated string.
+    #
+    # rule  - A Pointer to the YRX_RULE structure
+    # ident - A FFI::MemoryPointer that will receive the identifier pointer
+    # len   - A FFI::MemoryPointer that will receive the identifier length
+    #
+    # Examples
+    #
+    #   ident_ptr = FFI::MemoryPointer.new(:pointer)
+    #   len_ptr = FFI::MemoryPointer.new(:size_t)
+    #   result = Yara::FFI.yrx_rule_identifier(rule_ptr, ident_ptr, len_ptr)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_rule_identifier(const struct YRX_RULE *rule, const uint8_t **ident, size_t *len)
+    attach_function :yrx_rule_identifier, [:pointer, :pointer, :pointer], :int
+
+    # Internal: Callback function type for metadata iteration.
+    #
+    # This callback is invoked for each metadata entry during rule metadata
+    # iteration. The callback receives pointers to the metadata and user data.
+    #
+    # metadata  - A Pointer to the YRX_METADATA structure
+    # user_data - A Pointer to optional user-provided data
+    #
+    # C Signature: typedef void (*YRX_METADATA_CALLBACK)(const struct YRX_METADATA *metadata, void *user_data)
+    callback :metadata_callback, [:pointer, :pointer], :void
+
+    # Public: Iterate through all metadata entries in a rule.
+    #
+    # This function calls the provided callback for each metadata key-value pair
+    # defined in the rule. Metadata includes information like author, description,
+    # and custom tags defined in the rule's meta section.
+    #
+    # rule      - A Pointer to the YRX_RULE structure
+    # callback  - A Proc matching the metadata_callback signature
+    # user_data - A Pointer to optional data passed to callback (can be nil)
+    #
+    # Examples
+    #
+    #   callback = proc { |metadata_ptr, user_data| puts "Found metadata" }
+    #   result = Yara::FFI.yrx_rule_iter_metadata(rule_ptr, callback, nil)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_rule_iter_metadata(const struct YRX_RULE *rule, YRX_METADATA_CALLBACK callback, void *user_data)
+    attach_function :yrx_rule_iter_metadata, [:pointer, :metadata_callback, :pointer], :int
+
+    # Internal: Callback function type for pattern iteration.
+    #
+    # This callback is invoked for each pattern (string) during rule pattern
+    # iteration. The callback receives pointers to the pattern and user data.
+    #
+    # pattern   - A Pointer to the YRX_PATTERN structure
+    # user_data - A Pointer to optional user-provided data
+    #
+    # C Signature: typedef void (*YRX_PATTERN_CALLBACK)(const struct YRX_PATTERN *pattern, void *user_data)
+    callback :pattern_callback, [:pointer, :pointer], :void
+
+    # Public: Iterate through all patterns (strings) in a rule.
+    #
+    # This function calls the provided callback for each string pattern defined
+    # in the rule. Patterns are the actual search terms that YARA looks for
+    # during scanning, defined in the rule's strings section.
+    #
+    # rule      - A Pointer to the YRX_RULE structure
+    # callback  - A Proc matching the pattern_callback signature
+    # user_data - A Pointer to optional data passed to callback (can be nil)
+    #
+    # Examples
+    #
+    #   callback = proc { |pattern_ptr, user_data| puts "Found pattern" }
+    #   result = Yara::FFI.yrx_rule_iter_patterns(rule_ptr, callback, nil)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # C Signature: enum YRX_RESULT yrx_rule_iter_patterns(const struct YRX_RULE *rule, YRX_PATTERN_CALLBACK callback, void *user_data)
+    attach_function :yrx_rule_iter_patterns, [:pointer, :pattern_callback, :pointer], :int
+
+    # Public: Extract the identifier (name) from a pattern object.
+    #
+    # This function retrieves the pattern identifier from a YRX_PATTERN pointer,
+    # typically called from within a pattern iteration callback. Pattern
+    # identifiers are the variable names like $string1, $hex_pattern, etc.
+    #
+    # pattern - A Pointer to the YRX_PATTERN structure
+    # ident   - A FFI::MemoryPointer that will receive the identifier pointer
+    # len     - A FFI::MemoryPointer that will receive the identifier length
+    #
+    # Examples
+    #
+    #   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)
+    #
+    # Returns an Integer result code (YRX_SUCCESS on success).
+    # 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.
+    # YRX_SUCCESS (0) indicates successful operation, while other values indicate
+    # various error conditions that can be interpreted using yrx_last_error.
+
+    # Public: Operation completed successfully.
+    YRX_SUCCESS = 0
+
+    # Public: YARA rule syntax error during compilation.
+    YRX_SYNTAX_ERROR = 1
+
+    # Public: Variable definition or reference error.
+    YRX_VARIABLE_ERROR = 2
+
+    # Public: Error during scanning operation.
+    YRX_SCAN_ERROR = 3
+
+    # Public: Scanning operation timed out.
+    YRX_SCAN_TIMEOUT = 4
+
+    # 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