Keyword & operator reference

YARA-X is a Rust reimplementation of YARA, the pattern-matching engine used to identify and classify files (notably malware). Rules are written in the same declarative language as classic YARA, and the command-line tool is yr. This page is a quick reference for the building blocks of a rule: the rule sections, the modifiers you can attach to patterns, and the keywords and operators you use inside a condition.

note

The terms string and pattern are used interchangeably in YARA. The section is still introduced with the strings: keyword, but a pattern can be plain text, a hex sequence, or a regular expression.

A minimal rule has the following shape:

rule example_rule {
    meta:
        author = "analyst"
        description = "Illustrative example only"
    strings:
        $a = "suspicious string"
        $b = { 6A 40 68 00 30 00 00 }
        $c = /md5: [0-9a-f]{32}/
    condition:
        $a and ($b or $c)
}

info

The rule above is an illustrative example and does not detect any real-world threat.

Rule sections and modifiers

A rule begins with the rule keyword followed by an identifier. The condition section is always required; the metadata and pattern sections are optional.

Keyword	Where it appears	Purpose
rule	Start of every rule	Declares a rule, followed by its identifier.
meta:	Section header (optional)	Holds key = value pairs (string, integer, or boolean) for context.
strings:	Section header (optional)	Defines the text, hex, or regex patterns to search for.
condition:	Section header (required)	Boolean expression that determines when the rule matches.
global	Modifier before rule	Applies the rule's restriction universally; evaluated before others.
private	Modifier before rule	Rule is not reported when it matches; used as a building block.

Tags can be added after the rule identifier with a colon, for example rule example : trojan downloader { ... }. The global and private modifiers can be combined on a single rule.

tip

Use private rules to factor out reusable logic. A private rule that matches still does not appear in the output, but other rules can reference it in their conditions.

String (pattern) modifiers

Modifiers are placed after a text or regex pattern definition to change how it is matched. Text patterns are ASCII-encoded and case-sensitive by default.

Modifier	Example syntax	Description
nocase	$a = "foobar" nocase	Case-insensitive matching.
wide	$a = "foobar" wide	Matches two-byte-per-character (null-interleaved) encoding.
ascii	$a = "foobar" ascii wide	Explicitly matches ASCII encoding; the default, usually paired with wide.
fullword	$a = "domain" fullword	Matches only when delimited by non-alphanumeric characters.
xor	$a = "text" xor	Matches single-byte XOR variants; range form: xor(0x01-0xff).
base64	$a = "text" base64	Matches the three base64 encodings of the pattern; custom alphabet: base64("...").
base64wide	$a = "text" base64wide	Like base64, but the base64 result is then matched in wide form.

Constraints to keep in mind:

• base64 and base64wide require a pattern of at least 3 bytes.
• nocase, xor, and fullword cannot be combined with base64 or base64wide.
• nocase cannot be combined with xor.
• A custom base64 alphabet must be exactly 64 characters.

note

This is a behavioral difference from classic YARA: YARA 4.x allowed base64 on patterns shorter than 3 characters, whereas YARA-X rejects them. YARA-X also avoids the base64 false positives that YARA could produce.

Condition keywords and operators

The condition is a boolean expression. The tables below group the keywords and operators available inside it.

Pattern references and counts

Syntax	Meaning
$a	True if pattern $a is found at least once.
#a	Number of occurrences of $a.
@a[i]	Offset of the i-th occurrence of $a (1-based); @a is @a[1].
!a[i]	Length of the i-th match of $a (1-based); !a is !a[1].
$a at <off>	True if $a is found at the given offset.
$a in (s..e)	True if $a is found within the offset range s..e.

Quantifiers (the of operator)

Syntax	Meaning
all of them	Every pattern in the rule matches.
any of them	At least one pattern matches.
none of them	No pattern matches.
N of ($a, $b, $c)	At least N patterns from the set match.
all of ($a*)	All patterns matching the $a* wildcard match.
any of ($a*, $b)	Any pattern from the wildcard or explicit list matches.
all of ($a*) in (s..e)	Quantifier restricted to an offset range.

Loops: for

for <quantifier> of <pattern_set> : ( <boolean_expression> )
for <quantifier> <var> in <range> : ( <boolean_expression> )

for requires that at least the quantified number of items (patterns, or values from the range) satisfy the inner boolean expression.

with bindings

YARA-X adds a with statement that binds local identifiers for use inside a scoped condition:

with <id> = <expr> : ( <condition> )

File data

Keyword	Meaning
filesize	Size of the scanned file in bytes; accepts KB / MB postfixes.

Boolean, comparison, arithmetic, and bitwise operators

Category	Operators
Boolean	and, or, not
Comparison	==, !=, <, <=, >, >=
Arithmetic	+, -, *, /, %
Bitwise	&, `

String operators

These operate on string expressions (for example, values returned by modules).

Operator	Meaning
contains	Substring is present (case-sensitive).
icontains	Substring is present (case-insensitive).
startswith	String starts with the prefix (case-sensitive).
istartswith	String starts with the prefix (case-insensitive).
endswith	String ends with the suffix (case-sensitive).
iendswith	String ends with the suffix (case-insensitive).
iequals	Strings are equal (case-insensitive).
matches	String matches a regular expression.

defined is a unary operator (not specific to strings) that is true when its operand evaluates to a defined value; it is commonly used to guard values returned by modules.

Command-line quick reference

Rules are run with the yr command. The main subcommands are:

yr scan rules.yar sample.bin   # Scan a file or directory with rules
yr compile rules.yar           # Compile rules to binary form
yr fmt rules.yar               # Format YARA source files
yr dump sample.bin             # Show data produced by YARA modules for a file
yr deps rules.yar              # Show rule dependencies
yr fix encoding rules.yar      # Fix the source encoding of rule files
yr completion zsh              # Output shell completion code

tip

Run yr help <subcommand> to see the full set of flags for any command.

Sources

• YARA-X documentation home
• Anatomy of a rule
• Global and private rules
• Text patterns (string modifiers)
• Rule conditions
• Differences with YARA
• Using the CLI: commands
• VirusTotal/yara-x on GitHub