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. This does not mean "keep filtering and ignore errors" — see the warning below.
`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.

warning

ignore_failure: true silently turns this processor off. The drop is signalled to the pipeline as an error value, and the ignore_failure check runs before that value is inspected — so a matched event is kept instead of dropped, no error is logged, and the pipeline reports success. The processor appears to run normally while filtering nothing.

Use it only if you genuinely want a pass-through. To tolerate real errors without losing the filtering, leave ignore_failure unset and handle the failure with on_failure instead.

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.

Rule Packs

Rules are supplied as packs assigned through the platform Library, one file per pack:

Rule type	Library path
Sigma	`library/sigma/<name>.yml`
Sentinel	`library/sentinel/<name>.yml`
YARA	`library/yara/<name>.yar`

A pack's name is its filename without the extension, and that name is what library refers to.

Globs are accepted, so "*" selects every assigned pack of that type and "win_*" selects those whose names begin with win_. A glob that matches nothing contributes no rules and raises no error. A name given exactly, however, must be assigned — if it is not, the processor fails with an error naming it.

The Sentinel and Smart Engine processors read the same Sentinel rule packs, so a pack assigned once can be used by both.

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:

The field named by field, if it is set. Its value must be a string or a byte sequence.
Otherwise _raw, if the event has it.
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`

Synopsis​

Schema​

Configuration​

Rule Packs​

Details​

Annotating and Filtering​

What Is Scanned​

Supported Modules​

Markers​

Examples​

Scanning a Field​

Reporting Matched Strings​

Forwarding Only Matches​