Sigma

Security Threat Intelligence Flow Control

Synopsis

Evaluates Sigma detection rules against each event. A match annotates the event with the rule's name, level, tags, and resolved MITRE ATT&CK enrichment.

Sigma rules are written against Sigma's own field taxonomy, which is largely Windows and Sysmon. The processor resolves that taxonomy to the real field paths of the schema your events are in, so community rules run against normalized data without being rewritten.

Schema

- sigma:
    library: <string[]>
    rules: <string[]>
    rule_files: <string[]>
    rule_dirs: <string[]>
    select: <object>
    source_format: <enum>
    mode: <enum>
    mark_field: <ident>
    min_level: <enum>
    mitre_enrich: <boolean>
    case_sensitive: <boolean>
    strict_fields: <boolean>
    category_field: <ident>
    auto_category: <boolean>
    description: <text>
    if: <script>
    tag: <string>
    disabled: <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 Sigma rule packs assigned through the Library.
`rules`	Y*		Rules given inline, as rule YAML.
`rule_files`	Y*		Paths to rule files (`.yml`, `.yaml`).
`rule_dirs`	Y*		Directories searched recursively for rule files.
`select`	N	all rules	Narrows which of the loaded rules are registered. See below.
`source_format`	N	auto-detected	The schema the events are in: `ecs`, `cim`, `asim`, `csl`, `cef`, `leef`, `ocsf`, `udm`, `gelf`, or `native`. Left unset, the format is detected per event.
`mode`	N	`annotate`	`annotate` marks matches and forwards every event. `filter` drops every event that matches no rule.
`mark_field`	N	`_sigma`	Root field the match markers are written under.
`min_level`	N		Ignore rules below this level: `informational`, `low`, `medium`, `high`, or `critical`. A rule that declares no level is never filtered out.
`mitre_enrich`	N	`true`	Resolve MITRE ATT&CK tactics and techniques onto each match.
`case_sensitive`	N	`false`	Match rule values case-sensitively.
`strict_fields`	N	`false`	Refuse to compile a rule that references a field the schema does not map.
`category_field`	N	`_vmetric.category`	The event field holding the logsource category, used to route rules.
`auto_category`	N	`true`	Derive the category from the event when `category_field` is absent.
`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_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.

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.

Select

All criteria are combined with AND; the values within one criterion are combined with OR. Matching is case-insensitive.

Field	Description
`categories`	Rules by logsource category, such as `process_creation`.
`products`	Rules by logsource product, such as `windows`.
`services`	Rules by logsource service, such as `sysmon`.
`levels`	`informational`, `low`, `medium`, `high`, or `critical`.
`statuses`	Rule status, such as `stable` or `experimental`.
`ids`	Rule id, matched exactly.
`name_prefix`, `name_contains`, `name_regex`	Rule title matching.
`desc_contains`	Rule description matching.
`tags`	Rule tags.

A select that matches no rules is an error, raised when the first event reaches the processor.

Details

warning

This processor runs on the Director only. An Agent skips it as if it were disabled and passes its records on unchanged; the Director logs a warning when it sends that Agent its configuration. Put it in a pipeline the Director runs, such as a route pipeline or a target postprocessing pipeline.

Upgrading Agents and Directors

Agents ran this processor before the release that made it Director-only. Since that release an upgraded Director sends Agents no Sigma rule packs, so during an upgrade, in either order:

An upgraded Agent skips the processor, so a pipeline that used it to tag or drop records on the Agent stops doing so, without an error.
An Agent still on an older version, served by an upgraded Director, fails the records of a step whose library names an exact Library entry until that Agent is upgraded too. A library list of globs matches nothing instead.

Move any sigma step out of an Agent's pipeline into a pipeline the Director runs before upgrading either.

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.

Field Resolution

Sigma rules name fields in Sigma's taxonomy. Those names are resolved to the concrete field paths of the schema named by source_format, once, when the rules are compiled — not per event.

A rule referencing a field the schema has no mapping for is compiled on a best-effort basis. Setting strict_fields: true makes that rule fail to compile instead, and a rule that fails to compile is dropped from the set — it will never match anything. The rest of the rules are unaffected.

Levels

min_level ignores rules below the level given. A rule that declares no level is never filtered out by it — an unleveled rule always remains in the set.

Rule Routing

When the compiled rule set is large, the processor uses the event's logsource category to skip rules that cannot apply to it. category_field names where the category lives, and auto_category derives one from the event when that field is absent.

Routing skips a rule only when the event's logsource is provably incompatible with it, so it never changes which rules match — it only avoids evaluating ones that could not have fired. For a small rule set the derivation costs more than it saves, so routing is skipped entirely and every rule is evaluated. Either way the result is the same.

Markers

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

Each entry in _sigma.rules carries name, and — when the rule defines them — id, level, tags, and mitre. Note the key is level, Sigma's own term, not severity.

Examples

Annotating a Match

Running an assigned Sigma pack against events already normalized to ECS...

{
  "process": { "name": "powershell.exe", "command_line": "powershell -enc SQBFAFgA" }
}

- sigma:
    library:
      - "*"
    source_format: ecs

The rule's Sigma field names were resolved to their ECS paths at compile time, so it matches. The event is annotated and forwarded unchanged...

{
  "process": { "name": "powershell.exe", "command_line": "powershell -enc SQBFAFgA" },
  "_sigma": {
    "matched": true,
    "count": 1,
    "rules": [
      {
        "name": "Encoded PowerShell Command Line",
        "level": "high",
        "tags": ["attack.execution", "attack.t1059.001"]
      }
    ]
  }
}

Narrowing a Large Pack

Registering only the stable process-creation rules from every assigned pack...	`- sigma: library: - "*" select: categories: - process_creation statuses: - stable min_level: high`
Only rules meeting every criterion are registered. A registered rule below `high` is then ignored at match time, though one declaring no level at all still applies...	`{ "_sigma": { "matched": true, "count": 1, "rules": [ { "name": "Suspicious Process Creation", "level": "high" } ] } }`

Forwarding Only Matches

Keeping only events that some rule matched...	`- sigma: library: - "*" mode: filter`
An event no rule matched is dropped rather than forwarded unannotated...	`// dropped`

Synopsis​

Schema​

Configuration​

Rule Packs​

Select​

Details​

Upgrading Agents and Directors​

Annotating and Filtering​

Field Resolution​

Levels​

Rule Routing​

Markers​

Examples​

Annotating a Match​

Narrowing a Large Pack​

Forwarding Only Matches​