YARA

Security Threat Intelligence Flow Control

Synopsis

Scans an event field with YARA rules. A match annotates the event with the rule's name, tags, and resolved MITRE ATT&CK enrichment.

The engine is built for log payloads — many small buffers scanned at a high rate against tens to low hundreds of rules — rather than for scanning files on disk.

Schema

- yara:
    library: <string[]>
    rules: <string[]>
    rule_files: <string[]>
    rule_dirs: <string[]>
    field: <ident>
    mode: <enum>
    mark_field: <ident>
    namespace: <string>
    mitre_enrich: <boolean>
    include_strings: <boolean>
    description: <text>
    if: <script>
    tag: <string>
    disabled: <boolean>
    ignore_missing: <boolean>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>

Configuration

At least one rule source is required. With none, the processor fails.

Field	Required	Default	Description
library	Y*		Names of YARA rule packs assigned through the Library.
rules	Y*		Rules given inline, as YARA rule text.
rule_files	Y*		Paths to rule files (.yar, .yara).
rule_dirs	Y*		Directories searched recursively for rule files.
field	N		The field to scan. Left unset, _raw is scanned when present, and otherwise the whole event.
mode	N	annotate	annotate marks matches and forwards every event. filter drops every event that matches no rule.
mark_field	N	_yara	Root field the match markers are written under.
namespace	N	default	Namespace the rules are compiled into.
mitre_enrich	N	true	Resolve MITRE ATT&CK tactics and techniques onto each match, from the rule's tags and meta.
include_strings	N	false	Include the matched strings, each with its identifier, offset, and length.
description	N		Explanatory note.
if	N		Condition that must be true for the processor to run.
tag	N		Identifier for this processor instance.
disabled	N	false	When true, the processor is skipped.
ignore_missing	N	false	Continue quietly when the field to scan is absent.
ignore_failure	N	false	Continue pipeline processing if the processor fails.
on_failure	N		See Handling Failures.
on_success	N		See Handling Success.

* = At least one of library, rules, rule_files, or rule_dirs is required. Sources are combined, in that order.

There is no select on this processor. YARA rules refer to one another and use private rules, so removing individual rules from a pack could break the ones that depend on them. Narrow the rule set with library instead.

Loading include...

Details

Annotating and Filtering

In the default annotate mode, every event is forwarded. A matching event gains its markers; a non-matching event passes through untouched.

Setting mode: filter turns the processor into an allowlist: an event that matches no rule is dropped. Use it deliberately — it discards telemetry.

What Is Scanned

The scan target is chosen in this order:

1. The field named by field, if it is set. Its value must be a string or a byte sequence.
2. Otherwise _raw, if the event has it.
3. Otherwise the whole event, serialized.

If field names a field that is absent, or holds a value that is neither a string nor bytes, the processor fails — unless ignore_missing: true, which makes it return quietly instead.

That interaction is worth stating plainly: under ignore_missing: true and mode: filter, an event whose scan target is missing is kept, not dropped. The missing target is settled before the match decision is reached, so filtering never sees the event.

Supported Modules

Only these YARA modules are available: math, hash, string, time, and console.

The modules that inspect binary file formats — pe, elf, dotnet, macho, lnk, dex, crx, magic, cuckoo, and vt — are not supported, because the engine scans log payloads rather than files.

A rule importing an unsupported module fails to compile, and that failure fails the processor on every event. One such rule is enough. This matters when assigning a community rule pack wholesale, since large public collections routinely include pe and elf rules: assign packs whose rules are string- and hash-based, or strip the binary-format rules before assigning.

A rule source that cannot be parsed is treated differently: it is skipped with a warning and the remaining sources still load. A malformed rule therefore costs you that rule, not the processor.

Markers

Field	Description
_yara.matched	true on a matching event.
_yara.rules	One entry per matched rule.
_yara.count	The number of matched rules.

Each entry in _yara.rules carries name, and — when present — tags, mitre, and namespace (only when it is set to something other than default). The matched strings are included only under include_strings.

Examples

Scanning a Field

Scanning a command line with an inline rule...	{ "CommandLine": "rundll32.exe C:\\Users\\Public\\mimikatz.dll,Main" } - yara: field: CommandLine rules: - | rule Mimikatz_Reference { meta: mitre_attack = "T1003" strings: $a = "mimikatz" nocase condition: $a }
The rule matches. Its meta supplies the ATT&CK technique, which is resolved into the enrichment...	{ "CommandLine": "rundll32.exe C:\\Users\\Public\\mimikatz.dll,Main", "_yara": { "matched": true, "count": 1, "rules": [ { "name": "Mimikatz_Reference", "mitre": { "techniques": [{ "id": "T1003", "name": "OS Credential Dumping" }] } } ] } }

Reporting Matched Strings

Asking for the matched strings and their offsets...	- yara: field: CommandLine include_strings: true library: - malware_indicators
Each match reports which string fired, and where in the scanned value...	{ "_yara": { "matched": true, "count": 1, "rules": [ { "name": "Mimikatz_Reference", "strings": [ { "id": "$a", "offset": 29, "length": 8 } ] } ] } }

Forwarding Only Matches

Keeping only the events a rule matched...	- yara: field: CommandLine mode: filter library: - malware_indicators
An event no rule matched is dropped. An event with no CommandLine at all is a different case: it fails the processor rather than being dropped, or — with ignore_missing set — is forwarded untouched...	// dropped