Scanning with yr

YARA-X is a Rust reimplementation of YARA, the pattern-matching tool for malware research. Its command-line interface ships as a single binary named yr. The scan subcommand compiles one or more rule sets and matches them against a target file or directory.

A YARA rule is made up of three sections — meta, strings, and condition. The yr scan command takes the path to your rules (source or compiled) and the path to the data you want to inspect.

Basic usage

The general form of the command is:

yr scan [OPTIONS] <[NAMESPACE:]RULES_PATH>... <TARGET_PATH>

• RULES_PATH — a YARA source file, or a directory of source files. When it is a directory, yr searches it recursively for any *.yar or *.yara files. You may supply more than one rules path, and each can be prefixed with an optional namespace (namespace:path).
• TARGET_PATH — the file or directory to scan.

Scan a single file with a single rule file:

yr scan rules.yar suspicious.bin

Scan with several rule files at once:

yr scan rules.yar more_rules.yar /tmp/sample

note

When the target path is a directory, by default only the files directly within it are scanned; its subdirectories are excluded. To walk into subdirectories, opt in with --recursive.

Recursive directory scanning

When TARGET_PATH is a directory, pass --recursive to scan its subdirectories' contents as well (the files directly inside the directory are already scanned without it). An optional maximum depth limits how deep the traversal goes.

# Scan every file under ./samples
yr scan --recursive rules.yar ./samples

# Limit recursion to 2 directory levels
yr scan --recursive=2 rules.yar ./samples

Flag	Behavior
--recursive	Recurse into subdirectories with no depth limit.
--recursive=<MAX_DEPTH>	Recurse, but stop after MAX_DEPTH levels.

tip

Combine --recursive with --skip-larger <FILE_SIZE> to ignore files above a byte threshold, which keeps large bulk scans fast and predictable.

Performance: threads and timeout

yr scans files in parallel. By default it uses one thread per CPU core; override this with --threads. Use --timeout to abort a scan that runs too long.

Flag	Short	Argument	Default	Purpose
--threads	—	<NUM_THREADS>	number of CPU cores	Number of worker threads to use.
--timeout	—	<SECONDS>	none	Abort scanning after the given number of seconds.

# Use 8 threads and give up after 60 seconds
yr scan --threads 8 --timeout 60 --recursive rules.yar ./samples

Inverse matching with --negate

By default yr prints the rules that match. The --negate (-n) flag inverts this and prints the rules that do not match — useful for finding files that fail an expected rule.

yr scan --negate rules.yar suspicious.bin

Filtering output by tag

YARA rules can carry tags (declared after the rule name, e.g. rule Foo : trojan { ... }). Use --tag <TAG> to print only matching rules that carry a given tag, and --print-tags (-g) to include each matching rule's tags in the output.

# Only report matches from rules tagged "trojan", and show their tags
yr scan --tag trojan --print-tags rules.yar suspicious.bin

info

--tag is a filter (it narrows which matches are reported), while --print-tags / -g controls display (it adds the tag list to each reported match). They are independent and can be combined.

Controlling output

yr writes human-readable text by default. The --output-format flag selects the format, and several flags enrich what is printed per match.

Flag	Short	Description
--output-format <FORMAT>	—	Output format: text (default), json, or ndjson.
--count	-c	Print the number of matching rules per file instead of rule names.
--print-meta	-m	Print the metadata associated with matching rules.
--print-namespace	-e	Print the namespace of matching rules.
--print-strings[=<N>]	—	Print matching patterns (default limit 120 characters).
--print-tags	-g	Print the tags associated with matching rules.

# Emit newline-delimited JSON, one object per match, with metadata and namespaces
yr scan --output-format ndjson --print-meta --print-namespace rules.yar ./samples

Scanning compiled rules

To scan with precompiled rules instead of source, pass --compiled-rules (-C). When this flag is used, exactly one RULES_PATH is expected and it must point to a compiled rule file.

yr scan --compiled-rules rules.yarc suspicious.bin

Worked example

Illustrative example

The values below are illustrative and do not refer to a real sample. They show how the flags combine in practice.

yr scan \
  --recursive=3 \
  --threads 16 \
  --timeout 120 \
  --tag ransomware \
  --print-meta \
  --print-tags \
  --output-format json \
  rules/ ./incoming_uploads

This command:

1. Scans ./incoming_uploads recursively, up to 3 directory levels deep.
2. Compiles every *.yar / *.yara file found under rules/.
3. Uses 16 worker threads and aborts any single scan after 120 seconds.
4. Reports only matches from rules tagged ransomware.
5. Includes each matching rule's metadata and tags.
6. Emits the results as JSON.

Sources

• YARA-X — Commands (CLI reference)
• YARA-X — Documentation home
• YARA-X — Anatomy of a rule
• VirusTotal/yara-x on GitHub