YARA-X Documentation

YARA-X is a pattern matching tool designed for malware researchers to describe malware families or other entities using textual or binary patterns. It is a modern re-incarnation of YARA, designed to be faster, safer, and more user-friendly.

Rules in YARA-X consist of a set of patterns (strings) and a boolean expression (condition) that determines the logic for matching. Rules can include metadata for context, such as descriptions or threat levels.

The YARA Language Server is the official implementation of the Language Server Protocol (LSP) for the YARA language. It consists of two main components:

1. LSP Server: Written in Rust, providing the core language intelligence.
2. LSP Client: A Visual Studio Code extension written in TypeScript (located in editors/code).

The macho module enables the creation of fine-grained YARA-X rules targeting specific attributes and features of the Mach-O file format. It exposes Mach-O header fields and provides helper functions to inspect entitlements, dynamic libraries (dylibs), rpaths, imports, and exports.

To use it, import the module at the top of your rule file:

import "macho"

import "macho"

rule cpu_type {
  condition:
    macho.cputype == macho.CPU_TYPE_X86_64
}

rule frameworks_rpath {
  condition:
    macho.has_rpath("@loader_path/../Frameworks")
}

rule dylib_hash {
  condition:
    macho.dylib_hash() == "c92070ad210458d5b3e8f048b1578e6d"
}

The YARA-X Language Server implements the Language Server Protocol (LSP) to provide the following features in supported editors:

• Real-time diagnostics: Provides on-the-fly syntax error highlighting and descriptive error messages as you type.
• Advanced autocompletion: Offers intelligent suggestions for keywords and module identifiers (e.g., pe., cuckoo.).
• Go to definition: Allows instant navigation to the definition of rules or patterns across multiple files.
• Automatic formatting: Automatically formats YARA code to maintain consistency and readability according to best practices.

The crx module allows you to parse Chrome Extension (CRX) files and create YARA rules based on their metadata. CRX files are ZIP archives used by Chromium-based browsers (like Chrome and Edge) that include digital signatures for integrity validation.

To use the module, include import "crx" in your YARA-X rule. Note that all hashes returned by the module functions are provided in lowercase.

import "crx"

rule AllCrx {
    condition:
        crx.is_crx
}

YARA-X has introduced significant performance optimizations for pattern matching and rule evaluation:

1. Aho-Corasick Optimization: Starting with v1.16.0, YARA-X replaced the aho_corasick crate with daachorse. This uses a compact double-array trie data structure, resulting in a tighter inner loop and better cache efficiency. In benchmarks, this provided a ~2.2x speedup over the previous aho_corasick implementation.

2. Simultaneous Regex Evaluation: Introduced in v1.17.0, the compiler now detects multiple matches operations against the same target (e.g., a variable or structure field) within an or condition. It automatically groups these into a single RegexSet (from the Rust regex crate), allowing the engine to perform a single scan pass over the data instead of sequential passes for each pattern.

Using YARA-X in Python follows a two-step lifecycle:

1. Rule Compilation: Transform YARA rules from text into a Rules object. You can use the simple yara_x.compile(...) function for basic tasks, or the Compiler object for complex scenarios involving namespaces and multiple rule sets.
2. Scanning: Use the Rules object to scan data. You can use the direct Rules.scan(...) method for simplicity, or create a Scanner object for more granular control over the scanning process (e.g., setting timeouts or match limits).

The playground architecture distributes work across the main UI thread and two dedicated Web Workers to ensure responsiveness:

1. Main Thread: Hosts the Lit UI and the Monaco editor. It communicates with the other workers.
2. Language Server Worker: Runs the YARA-X Language Server (WebAssembly). It communicates with the Monaco editor via JSON-RPC over postMessage to provide autocompletion, diagnostics, and navigation.
3. Scan Worker: Runs the @virustotal/yara-x engine (WebAssembly). It performs the actual rule scanning and returns results and console output to the UI via worker messages.

Note on Scope: The playground is intended for testing a single rule against a single sample. For batch scans or large files, use the YARA-X CLI instead.