yara-ffi 3.1.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8093d210271e152cfd1d66f69169f9efaf46838ad93dd5473a0b11a242bc0164
-  data.tar.gz: a73687b9d7a3e7d098d4706c7c558954f1963a8bf8b3206984cdccd8dd757d2d
+  metadata.gz: f964b7eb475719ea6ceb456125b6ead06be8d9263a8839267ee96cdbe072b470
+  data.tar.gz: 36cc2f79374b0d00f245329f5d3e18423b6f16740e92f893c07d662f2183ce67
 SHA512:
-  metadata.gz: 879454866631eb296874a07aed2848a3252d547b45b593245114a0bb57404b5bea0badfecb553f77bd0029727112bfd9cde527f8722c3dfcf55e73f16a0cb6f7
-  data.tar.gz: 6cc31a9d0e330897c3133fd17d90ddac3e7b54a1b073af31235185e3e70a2738fa8041e9adc8c087e5867d34dc4ffaed3f75c7c54d4be08bdfe60059d5c0e672
+  metadata.gz: 5636bffbece91a2b3d48568e7bcac3e75d0f7713231c1a0abfbcbf83a0436b1d950ca5dccb5dae98b82c6ab3686521f61b561a2802f1c26145f887ea64fccf37
+  data.tar.gz: b10394734d3c00d986a5f12a6a2682087a7641e2abb62108728fc699f1e79f395f4bf2c5d94842c440fb15c960690773760907be56b4f14edbe5c86c3589aa3c

data/.github/copilot-instructions.md

@@ -0,0 +1,266 @@
+# yara-ffi AI Coding Instructions
+
+This Ruby gem provides FFI bindings to YARA-X (Rust-based YARA implementation) for malware/pattern detection with advanced pattern matching analysis, rule compilation, serialization, and metadata support.
+
+## Quick Development Guide
+
+**Start Here for New Features:**
+1. Run `script/test` (if Docker image missing, run `script/bootstrap` first)
+2. Follow **Red-Green-Refactor** cycle with small semantic commits after each cycle
+3. Scanner lifecycle: `add_rule()` → `compile()` → `scan()` → `close()`
+4. Always use resource-safe patterns: `Scanner.open { |s| ... }` or manual `close()`
+5. Interactive testing: `docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bin/console`
+6. **Documentation**: See `USAGE.md` for comprehensive examples and patterns
+
+## Core Components (Read These Files First)
+
+- `lib/yara/scanner.rb`: Main API - compile-then-scan workflow, resource management, global variables
+- `lib/yara/compiler.rb`: Advanced rule compilation with globals, error diagnostics, serialization
+- `lib/yara/scan_result.rb`: Enhanced result parsing with pattern matches, metadata, tags, namespaces
+- `lib/yara/pattern_match.rb`: Detailed pattern match information with offsets and data extraction
+- `lib/yara/ffi.rb`: Raw FFI bindings with error codes (`YRX_SUCCESS = 0`)
+- Tests in `test/`: Comprehensive test coverage for all features
+  - `test/scanner_test.rb`: Basic scanner patterns
+  - `test/scanner_pattern_match_test.rb`: Pattern matching analysis
+  - `test/compiler_test.rb`: Advanced compilation features
+  - `test/serialize_test.rb`: Rule serialization/deserialization
+  - `test/metadata_test.rb`: Metadata extraction
+  - `test/tags_test.rb`: Tag support
+  - `test/namespace_test.rb`: Namespace functionality
+
+## Key Features & APIs
+
+### Pattern Matching Analysis (NEW)
+```ruby
+# Detailed pattern match information
+results = scanner.scan(data)
+result = results.first
+
+# Access specific pattern matches
+matches = result.matches_for_pattern(:$suspicious)
+matches.each do |match|
+  puts "At offset #{match.offset}: #{match.matched_data(data)}"
+end
+
+# Pattern match convenience methods
+result.pattern_matched?(:$api_call)  # => true/false
+result.total_matches                 # => 5
+result.all_matches                   # => [PatternMatch, ...]
+```
+
+### Advanced Rule Compilation (NEW)
+```ruby
+# Use Compiler for complex scenarios
+compiler = Yara::Compiler.new
+compiler.define_global_str("ENV", "production")
+compiler.define_global_bool("DEBUG", false)
+compiler.add_source(rule1, "rule1.yar")
+compiler.add_source(rule2, "rule2.yar")
+
+# Build and serialize
+serialized = compiler.build_serialized
+scanner = Yara::Scanner.from_serialized(serialized)
+```
+
+### Global Variables (NEW)
+```ruby
+# Set individual globals
+scanner.set_global_str("ENV", "production")
+scanner.set_global_int("MAX_SIZE", 1000)
+scanner.set_global_bool("DEBUG", false)
+
+# Bulk setting with error handling
+scanner.set_globals({
+  "ENV" => "production",
+  "RETRIES" => 3
+}, strict: false)
+```
+
+### Metadata & Tags (NEW)
+```ruby
+# Access metadata with type safety
+result.rule_meta[:author]           # Raw access
+result.metadata_string(:author)     # Type-safe String
+result.metadata_int(:severity)      # Type-safe Integer
+
+# Tag support
+result.tags                         # => ["malware", "trojan"]
+result.has_tag?("malware")         # => true
+result.qualified_name               # => "namespace.rule_name"
+```
+
+## Critical FFI Patterns
+
+**Memory Management (ALWAYS Required):**
+```ruby
+# Preferred - auto-cleanup
+Scanner.open(rule_string) do |scanner|
+  scanner.compile
+  results = scanner.scan(data)
+end
+
+# Manual - MUST call close()
+scanner = Scanner.new
+# ... use scanner
+scanner.close  # Memory leak without this!
+```
+
+**Error Handling - Check These First:**
+```ruby
+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: #{error_msg}"
+end
+```
+
+**Library Loading Strategy (Multiple Fallbacks):**
+```ruby
+ffi_lib "/usr/local/lib/aarch64-linux-gnu/libyara_x_capi.so"  # Specific first
+ffi_lib "yara_x_capi"  # System library fallback
+```
+
+## Development Environment
+
+**Docker-First Development:** All development happens in Docker container with YARA-X pre-built:
+- `script/test` - runs tests (builds image automatically if needed)
+- `script/bootstrap` - only run if `script/test` fails due to missing Docker image
+- Interactive: `docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bin/console`
+
+**TDD Workflow:** Follow Red-Green-Refactor with small semantic commits:
+1. **Red**: Write failing test
+2. **Green**: Make test pass with minimal code
+3. **Refactor**: Clean up while keeping tests green
+4. **Commit**: Small semantic commit describing the feature/fix
+
+**Testing:** Uses Minitest. Tests in `test/` directory focus on Scanner lifecycle and rule matching.
+
+## Common YARA Rule Patterns
+
+**Basic Rule Template:**
+```ruby
+rule = <<-RULE
+rule ExampleRule
+{
+  meta:
+    description = "Example rule"
+    author = "test"
+
+  strings:
+    $text = "pattern"
+    $regex = /regex pattern/
+
+  condition:
+    $text or $regex
+}
+RULE
+```
+
+**Multiple Rules Pattern:**
+```ruby
+scanner = Scanner.new
+scanner.add_rule(rule1)
+scanner.add_rule(rule2)
+scanner.compile
+results = scanner.scan(data)  # Returns array of ScanResult objects
+```
+
+## Code Patterns
+
+**Resource Management:**
+```ruby
+# Preferred block pattern
+Scanner.open(rule_string) do |scanner|
+  scanner.compile
+  results = scanner.scan(data)
+end  # Auto-cleanup
+
+# Manual pattern - must call close()
+scanner = Scanner.new
+scanner.add_rule(rule)
+scanner.compile
+# ... use scanner
+scanner.close  # Required!
+```
+
+**Error Handling:** Custom exceptions for different failure modes:
+- `Scanner::CompilationError` - YARA rule syntax issues
+- `Scanner::ScanError` - Runtime scanning failures
+- `Scanner::NotCompiledError` - Scanning before compilation
+- `Compiler::CompileError` - Compilation errors with structured diagnostics
+
+**Enhanced Result Processing:** ScanResult now provides:
+- Structured metadata access via YARA-X API
+- Detailed pattern match information with offsets/lengths
+- Tag extraction and querying
+- Namespace support
+- Pattern match convenience methods
+
+## Performance & Advanced Features
+
+**Rule Serialization for Production:**
+```ruby
+# Compile once, use many times
+compiler = Yara::Compiler.new
+compiler.add_source(ruleset)
+serialized = compiler.build_serialized
+
+# Create multiple scanners from same rules
+scanners = 10.times.map { Yara::Scanner.from_serialized(serialized) }
+```
+
+**Timeout Configuration:**
+```ruby
+scanner.set_timeout(10000)  # 10 seconds
+```
+
+**Error Diagnostics:**
+```ruby
+begin
+  compiler.build
+rescue Yara::Compiler::CompileError
+  errors = compiler.errors_json
+  warnings = compiler.warnings_json
+end
+```
+
+## Adding New FFI Functions
+
+**Pattern to Follow:**
+```ruby
+# In lib/yara/ffi.rb
+attach_function :yrx_new_function, [:param_types], :return_type
+
+# In lib/yara/scanner.rb - always check return codes
+result = Yara::FFI.yrx_new_function(params)
+if result != Yara::FFI::YRX_SUCCESS
+  error_msg = Yara::FFI.yrx_last_error
+  raise ScanError, "Operation failed: #{error_msg}"
+end
+```
+
+**Available FFI Functions (key ones):**
+- `yrx_compile(src, rules_ptr)` - Compile rules from string
+- `yrx_scanner_create(rules, scanner_ptr)` - Create scanner from compiled rules
+- `yrx_scanner_scan(scanner, data, len)` - Scan data
+- `yrx_scanner_set_global_*()` - Set global variables on scanner
+- `yrx_scanner_set_timeout()` - Configure scan timeout
+- `yrx_compiler_*()` - Advanced compilation functions
+- `yrx_rules_serialize/deserialize()` - Rule serialization
+- `yrx_rule_iter_*()` - Iterate rule components (patterns, metadata, tags)
+- `yrx_pattern_iter_matches()` - Extract pattern match details
+- `yrx_last_error()` - Get last error message
+- Cleanup: `yrx_rules_destroy()`, `yrx_scanner_destroy()`, `yrx_compiler_destroy()`
+
+## Documentation Structure
+
+- `README.md`: Project overview, installation, minimal usage example
+- `USAGE.md`: Comprehensive usage guide with quick reference + detailed examples
+- `DEVELOPMENT.md`: Development setup and contribution workflow
+- `.github/copilot-instructions.md`: This file - AI coding guidance
+
+## Dependencies & Constraints
+
+**Docker Dependencies:** Container includes Rust toolchain + cargo-c for building YARA-X from source.
+
+When adding features, maintain the resource-managed Scanner pattern and ensure proper C memory cleanup.

data/.github/workflows/ruby.yml

@@ -1,10 +1,4 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
-# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
-
+# GitHub Actions workflow for Ruby gem testing and validation
 name: Ruby
 
 on:
@@ -13,28 +7,86 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
 jobs:
   test:
-
+    name: Test Ruby ${{ matrix.ruby-version }}
     runs-on: ubuntu-latest
+
     strategy:
+      fail-fast: false
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0']
+        ruby-version: ['3.2', '3.3']
 
     steps:
-    - uses: actions/checkout@v2
+    - name: Checkout code
+      uses: actions/checkout@v4
+
     - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-    - name: Install dependencies
+
+    - name: Install system dependencies
       run: |
         sudo apt-get update -y
-        sudo apt-get install -y libyara-dev
-        sudo gem install bundler -v 2.2.14
-        bundle install
+        sudo apt-get install -y curl git unzip build-essential
+
+    - name: Install Rust, cargo-c, and build YARA-X C API library
+      run: |
+        # Install Rust
+        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+        source $HOME/.cargo/env
+
+        # Set default Rust toolchain
+        rustup default stable
+
+        # Install cargo-c
+        cargo install cargo-c
+
+        # Build and install YARA-X C API library
+        git clone --depth 1 --branch v1.5.0 https://github.com/VirusTotal/yara-x.git /tmp/yara-x
+        cd /tmp/yara-x
+
+        # Ensure rustup default is set before running cargo with sudo
+        source $HOME/.cargo/env
+        rustup default stable
+        sudo env "PATH=$HOME/.cargo/bin:$PATH" "RUSTUP_HOME=$HOME/.rustup" "CARGO_HOME=$HOME/.cargo" $HOME/.cargo/bin/cargo cinstall -p yara-x-capi --release
+        sudo ldconfig
     - name: Run tests
-      run: bundle exec rake
+      run: bundle exec rake test
+
+    - name: Run RuboCop (if present)
+      run: |
+        if bundle list rubocop > /dev/null 2>&1; then
+          bundle exec rubocop
+        else
+          echo "RuboCop not found, skipping..."
+        fi
+      continue-on-error: true
+
+  # lint:
+  #   name: Lint and Security Check
+  #   runs-on: ubuntu-latest
+
+  #   steps:
+  #   - name: Checkout code
+  #     uses: actions/checkout@v4
+
+  #   - name: Set up Ruby
+  #     uses: ruby/setup-ruby@v1
+  #     with:
+  #       ruby-version: '3.3'
+  #       bundler-cache: true
+
+  #   - name: Run bundle audit (if present)
+  #     run: |
+  #       if bundle list bundle-audit > /dev/null 2>&1; then
+  #         bundle exec bundle-audit check --update
+  #       else
+  #         echo "bundle-audit not found, skipping..."
+  #       fi
+  #     continue-on-error: true

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 ## [Unreleased]
 
+## [4.1.0] - 2025-08-20
+
+- **NEW**: Added advanced `Yara::Compiler` API for complex rule compilation scenarios
+  - `Compiler.new` - Create a new compiler instance
+  - `Compiler#define_global_*` methods for setting globals before compilation
+  - `Compiler#add_source` for adding rules from multiple sources
+  - `Compiler#build` and `Compiler#build_serialized` for creating compiled rules
+  - `Compiler#errors_json` and `Compiler#warnings_json` for detailed diagnostics
+- **NEW**: Added rule serialization and deserialization support
+  - `Scanner.from_serialized` - Create scanner from serialized rules
+  - `Scanner.from_rules` - Create scanner from pre-compiled rules
+  - Enables compile-once, use-many-times pattern for production deployments
+- **NEW**: Enhanced pattern matching analysis with `Yara::PatternMatch`
+  - Detailed pattern match information with offsets and lengths
+  - `PatternMatch#offset`, `PatternMatch#length`, `PatternMatch#matched_data`
+  - `ScanResult#matches_for_pattern` - Get matches for specific patterns
+  - `ScanResult#pattern_matched?` - Check if specific pattern matched
+  - `ScanResult#total_matches` and `ScanResult#all_matches` for match analysis
+- **NEW**: Added comprehensive metadata and tag support
+  - Type-safe metadata accessors: `metadata_string`, `metadata_int`, `metadata_bool`
+  - `ScanResult#tags` - Access rule tags as array
+  - `ScanResult#has_tag?` - Check for specific tags
+  - `ScanResult#qualified_name` - Get namespaced rule name
+- **NEW**: Added global variable support for scanners
+  - `Scanner#set_global_str`, `Scanner#set_global_int`, `Scanner#set_global_bool`, `Scanner#set_global_float`
+  - `Scanner#set_globals` - Bulk setting with error handling options
+  - Enable dynamic rule behavior based on runtime variables
+- **NEW**: Added scanner timeout configuration via `Scanner#set_timeout`
+- **IMPROVED**: Enhanced documentation with comprehensive usage examples in `USAGE.md`
+- **IMPROVED**: Updated development documentation and AI coding instructions
+
+## [4.0.0] - 2025-08-19
+
+- **BREAKING**: Migrated from legacy libyara FFI bindings to YARA-X C API (`libyara_x_capi.so`) ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+  - Removed all legacy FFI struct definitions (`YrRule`, `YrMeta`, `YrString`, etc.)
+  - Replaced incremental rule compilation with single-step compilation via `yrx_compile`
+  - Eliminated dependency on `Yara.start` and `Yara.stop` lifecycle methods
+- **BREAKING**: Changed `Scanner#call` to `Scanner#scan` method ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- **BREAKING**: Require Ruby >= 3.0.0 ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- **BREAKING**: Remove `ScanResult` return for non-matching scans ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Added `Yara::ScanResults` enumerable collection for managing scan results ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Added `Scanner.open` for block-based resource management ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Added streaming scan API support with block yielding ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Modernized CI workflow with Ruby 3.0-3.3 matrix testing and YARA-X build support ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Added comprehensive development documentation in `DEVELOPMENT.md` ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Updated Docker environment to Ruby 3.3 with YARA-X v1.5.0 ([#24](https://github.com/jonmagic/yara-ffi/pull/24))
+- Improved error handling for compilation and scanning with better exception handling
+- Preserved backward compatibility in `ScanResult` interface via fallback parsing
+- Removed obsolete helper files: `user_data.rb`, `yr_meta.rb`, `yr_string.rb`, `yr_namespace.rb`, `yr_rule.rb`
+
+## [3.1.0] - 2022-04-18
+
+- Minor documentation fix for `Scanner::call` return value ([#20](https://github.com/jonmagic/yara-ffi/pull/20))
+- Fix FFI type compatibility issues on ARM64 Linux by converting integer types ([#21](https://github.com/jonmagic/yara-ffi/pull/21))
+
+## [3.0.0] - 2021-10-21
+
+- **BREAKING**: Introduced new `Yara::Scanner` API for better memory management and control ([#17](https://github.com/jonmagic/yara-ffi/pull/17))
+- Added proper memory cleanup with `yr_compiler_destroy` and `yr_rules_destroy` calls
+- Moved core functionality to `Yara::Scanner` class
+
+## [2.1.1] - 2021-08-31
+
+- Fix memory leak by calling destroy methods ([#11](https://github.com/jonmagic/yara-ffi/pull/11))
+
+## [2.1.0] - 2021-08-30
+
+- Use struct hash access and `Struct.ptr` where possible ([#14](https://github.com/jonmagic/yara-ffi/pull/14))
+- Improved struct member access and performance optimizations
+
+## [2.0.1] - 2021-08-30
+
+- Bug fixes and improvements
+
+## [2.0.0] - 2021-08-24
+
+- **BREAKING**: Changed interface to support rule metas ([#4](https://github.com/jonmagic/yara-ffi/pull/4))
+- `Yara.test` now returns `Yara::ScanResult` objects instead of rule names
+- Added support for accessing rule metadata as hash of name => value
+- Return rule metas in scan results
+
+## [1.0.0] - 2021-08-16
+
+- Wire up basic Yara functionality ([#3](https://github.com/jonmagic/yara-ffi/pull/3))
+- Added `Yara.test(rules_string, string_to_scan)` functionality
+- Initial FFI bindings to libyara
+
 ## [0.1.0] - 2021-03-11
 
-- Initial release
+- Initial release with project structure ([#1](https://github.com/jonmagic/yara-ffi/pull/1), [#2](https://github.com/jonmagic/yara-ffi/pull/2))
+- Set up GitHub Actions CI
+- Configured RuboCop

data/DEVELOPMENT.md

@@ -0,0 +1,188 @@
+# Development Guide
+
+This guide covers setting up the development environment and working on the yara-ffi gem.
+
+## Requirements
+
+- Docker (for containerized development environment)
+
+## Quick Start
+
+After checking out the repo, run the bootstrap script to set up the development environment:
+
+```bash
+script/bootstrap
+```
+
+This will build a Docker image with all the necessary dependencies, including the YARA-X C API library.
+
+## Development Scripts
+
+The project includes several convenience scripts in the `script/` directory:
+
+- `script/bootstrap` - Sets up the development environment (builds Docker image)
+- `script/test` - Runs the test suite in the Docker container
+
+## Running Tests
+
+To run the full test suite:
+
+```bash
+script/test
+```
+
+This runs `bundle exec rake` inside the Docker container with all dependencies properly configured.
+
+You can also run tests manually inside the container:
+
+```bash
+docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bundle exec rake
+```
+
+Or run specific test files:
+
+```bash
+docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bundle exec ruby -Itest test/scanner_test.rb
+```
+
+Alternatively, you can use rake to run specific tests:
+
+```bash
+docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bundle exec rake test TEST=test/scanner_test.rb
+```
+
+## Interactive Development
+
+For an interactive development session, you can start a console in the container:
+
+```bash
+docker run -it --mount type=bind,src="$(pwd)",dst=/app yara-ffi bin/console
+```
+
+This gives you an IRB session with the gem loaded for experimentation.
+
+## Development Environment Details
+
+The development environment uses Docker to provide a consistent setup with:
+
+- Ruby 3.3 (latest stable)
+- YARA-X C API library v1.5.0 built from source
+- All necessary system dependencies
+- Bundler with locked gem versions
+
+### Docker Image
+
+The `Dockerfile` sets up:
+
+1. Base Ruby 3.3 image
+2. System dependencies (curl, git, unzip)
+3. Rust toolchain and cargo-c for building YARA-X
+4. YARA-X C API library compiled and installed
+5. Ruby gem dependencies via Bundler
+
+### Manual Setup (without Docker)
+
+If you prefer not to use Docker, you'll need to manually install:
+
+1. Ruby 3.0+
+2. YARA-X C API library (see [Installation section in README](README.md#installing-yara-x))
+3. System dependencies for building native gems
+
+Then run:
+
+```bash
+bundle install
+rake test
+```
+
+## Code Structure
+
+The gem is organized as follows:
+
+- `lib/yara.rb` - Main entry point and convenience methods
+- `lib/yara/ffi.rb` - FFI bindings to YARA-X C API
+- `lib/yara/scanner.rb` - Scanner class for rule compilation and scanning
+- `lib/yara/scan_result.rb` - Individual scan result wrapper
+- `lib/yara/scan_results.rb` - Collection of scan results
+- `lib/yara/version.rb` - Gem version constant
+
+## Testing
+
+Tests are located in the `test/` directory:
+
+- `test/yara_test.rb` - Tests for main module convenience methods
+- `test/scanner_test.rb` - Tests for Scanner class functionality
+- `test/test_helper.rb` - Shared test setup and utilities
+
+The test suite uses Minitest and includes tests for:
+
+- Rule compilation and validation
+- Data scanning with various rule types
+- Memory management and resource cleanup
+- Error handling and edge cases
+
+## Release Process
+
+To release a new version of the gem:
+
+1. Update the version number in `lib/yara/version.rb`
+2. Update the `CHANGELOG.md` with release notes
+3. Commit the changes
+4. Create and push a git tag:
+   ```bash
+   git tag v<version>
+   git push origin v<version>
+   ```
+5. Build and push the gem:
+   ```bash
+   gem build yara-ffi.gemspec
+   gem push yara-ffi-<version>.gem
+   ```
+
+## Contributing Guidelines
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-new-feature`)
+3. Make your changes with appropriate tests
+4. Run the test suite (`script/test`) to ensure all tests pass
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a Pull Request
+
+Please ensure your code follows the existing style and includes tests for new functionality.
+
+## Debugging
+
+For debugging FFI-related issues:
+
+1. Enable FFI debugging by setting the `RUBY_FFI_DEBUG` environment variable
+2. Use `puts` statements or `binding.pry` (if pry is available) for Ruby debugging
+3. Check YARA-X C API documentation for expected behavior
+4. Verify memory management - ensure all resources are properly freed
+
+## Common Issues
+
+### YARA-X Library Not Found
+
+If you see errors about missing YARA-X libraries, ensure:
+
+1. The YARA-X C API library is properly installed
+2. The library path is in your system's library search path
+3. You're using the correct version (v1.5.0 is tested)
+
+### Docker Build Issues
+
+If Docker builds fail:
+
+1. Ensure you have sufficient disk space
+2. Try rebuilding without cache: `docker build --no-cache . -t yara-ffi`
+3. Check internet connectivity for downloading dependencies
+
+### Test Failures
+
+If tests fail:
+
+1. Ensure all dependencies are properly installed
+2. Check that YARA-X C API library is available
+3. Verify Ruby version compatibility (3.0+ required)
+4. Run tests individually to isolate issues