Writing Sigma rules

Sigma is the vendor-neutral YAML format for log detections. Rule anatomy (logsource, detection, condition), value modifiers such as contains, endswith, windash and base64offset, converting rules with pySigma backends and field-mapping pipelines, testing against positive and negative samples, writing honest false-positive notes, and versioning rules like code.

FREEBy ·Lesson·15 min read·Intermediate → Advanced
Sigma rulesdetection engineeringpySigmasigma-clidetection as code

01What Sigma is and how a rule is built

✓What you will learn
  • Read and write the parts of a Sigma rule: logsource, detection, condition
  • Use lists, maps and modifiers to express AND, OR and string matching precisely
  • Convert rules to SPL, KQL and Lucene with pySigma backends and pipelines
  • Test rules against positive and negative samples before they reach the SOC
  • Write false-positive notes and version rules so they survive handover

Sigma is to log detections what YARA is to files and Snort to packets: an open, vendor-neutral format. You write the logic once in YAML against abstract log sources and field names, and a converter produces the query for whichever SIEM you run. The public SigmaHQ repository holds thousands of community rules, so writing Sigma also means you can read, borrow and contribute.

A complete Sigma ruleyaml
title: PowerShell started with an encoded command
id: 3a6b7f1e-5c2d-4e8a-9b0f-1d2c3e4f5a6b
status: test
description: |
  Detects powershell.exe or pwsh.exe launched with an -EncodedCommand style flag.
  Encoded commands hide download cradles and are rare in normal admin work.
references:
  - https://attack.mitre.org/techniques/T1059/001/
author: CyArt detection team
date: 2026-11-02
modified: 2026-11-10
tags:
  - attack.execution
  - attack.t1059.001
  - attack.t1027.010
logsource:
  category: process_creation
  product: windows
detection:
  selection_img:
    - Image|endswith:
        - '\powershell.exe'
        - '\pwsh.exe'
    - OriginalFileName:
        - 'PowerShell.EXE'
        - 'pwsh.dll'
  selection_flag:
    CommandLine|contains|windash:
      - ' -e '
      - ' -ec '
      - ' -enc '
      - ' -encodedcommand '
  filter_sccm:
    ParentImage|endswith: '\CCM\CcmExec.exe'
    CommandLine|contains: '\ccmcache\'
  condition: all of selection_* and not 1 of filter_*
falsepositives:
  - SCCM and some RMM agents pass install scripts encoded (filtered above for SCCM only)
  - Developer tooling that shells out to PowerShell with -EncodedCommand
level: medium
FieldPurposeNotes
title, descriptionWhat it detects and why that mattersWrite for the analyst triaging it at 3 a.m.
idA random UUID that never changesEdits keep the id; only modified changes
statusMaturity: experimental, test, stable (plus deprecated, unsupported)Drives whether the SOC pages on it
logsourcecategory, product, service: which data the rule needsThe converter maps this to an index, table or event ID
detectionNamed search identifiers plus a conditionThe logic
falsepositives, levelKnown benign causes; severity from informational to criticalHonest FP notes save hours of triage
tagsATT&CK tactic and technique IDsLets you build coverage maps from the repository
◎Interview radar

Detection engineering interviews often say "write a Sigma rule for X" on a whiteboard. Get the skeleton right (logsource, named selections, a filter, a condition), explain why you chose the fields, and volunteer the false positives. Knowing that the id is stable and status reflects maturity marks you as someone who has run a rule repository.

02Detection logic: lists, maps and modifiers

The detection block is a set of named search identifiers and one condition. Two YAML shapes carry all the boolean logic: a map (keys and values) means every key must match, so AND; a list means any item may match, so OR. In the rule above, selection_img is a list of two maps: image name OR original file name. selection_flag has one key with a list of values: any of the flags.

ModifierMeaningExample
contains, startswith, endswithSubstring, prefix, suffix match (case-insensitive by default)Image|endswith: '\rundll32.exe'
allEvery value in the list must match, turning the list into ANDCommandLine|contains|all: ['-nop', 'hidden']
windashAlso try /, en dash, em dash and horizontal bar in place of -Catches powershell /enc and Unicode dash tricks
reRegular expression (keep it simple; backends differ)CommandLine|re: '\s-[eE][nN]?[cC]?\s'
base64offsetMatch a string inside base64 at any of the three alignmentsCommandLine|base64offset|contains: 'IEX'
cidrIP address within a network rangeDestinationIp|cidr: '10.0.0.0/8'
exists, gt, ltField presence and numeric comparison (Sigma 2.0)ParentImage|exists: false
Process access to LSASS (Sysmon event 10), with filtersyaml
detection:
  # map = AND: both keys must match
  selection_lsass:
    TargetImage|endswith: '\lsass.exe'
    GrantedAccess:            # list = OR
      - '0x1010'
      - '0x1410'
      - '0x1fffff'
  # list of maps = OR of ANDs
  filter_known:
    - SourceImage|endswith: '\MsMpEng.exe'
    - SourceImage|startswith: 'C:\Program Files\CrowdStrike\'
  condition: selection_lsass and not filter_known

The condition combines identifiers with and, or, not and parentheses, plus the shorthands 1 of selection_*, all of selection_* and all of them. Name identifiers by role, selection_* and filter_*, so conditions read like sentences and a reviewer can see at a glance what is excluded.

!Three logic bugs that ship

`contains` with a list is OR: CommandLine|contains: ['-nop', 'hidden'] matches either; add |all if you meant both. Filters too broad: filter: ParentImage|endswith: '\CcmExec.exe' alone excludes anything an attacker runs through a compromised SCCM. Escaping: in Sigma a backslash is literal, but * and ? are wildcards and must be escaped as \* when you mean the character.

03Field mapping and conversion backends

A Sigma rule says category: process_creation and Image. Your SIEM might call that Sysmon event 1 with Image, Windows 4688 with NewProcessName, the Defender DeviceProcessEvents table with FolderPath, or ECS process.executable. pySigma (the Python library behind the sigma CLI) splits conversion into two parts: processing pipelines that rename fields and add log source conditions, and backends that write the target query language.

Converting with sigma-clibash
# one-time: install the CLI and the backends you need
pip install sigma-cli
sigma plugin install splunk
sigma plugin install kusto

# lint the rule against the Sigma specification first
sigma check rules/windows/proc_creation_win_powershell_encoded.yml

# Splunk, Windows TA field names
sigma convert -t splunk -p splunk_windows rules/windows/proc_creation_win_powershell_encoded.yml

# Defender XDR advanced hunting (KQL); the pipeline maps fields to DeviceProcessEvents
sigma convert -t kusto -p microsoft_xdr rules/windows/proc_creation_win_powershell_encoded.yml
Same rule, two dialects: note the field renames and windash expansiontext
# Splunk output (abridged, reformatted)
(Image IN ("*\\powershell.exe", "*\\pwsh.exe") OR OriginalFileName IN ("PowerShell.EXE", "pwsh.dll"))
  CommandLine IN ("* -e *", "* /e *", "* -ec *", "* /ec *", "* -enc *", "* /enc *", ...)
  NOT (ParentImage="*\\CCM\\CcmExec.exe" CommandLine="*\\ccmcache\\*")

// KQL output (abridged)
DeviceProcessEvents
| where (FolderPath endswith @"\powershell.exe" or FolderPath endswith @"\pwsh.exe"
         or ProcessVersionInfoOriginalFileName in~ ("PowerShell.EXE", "pwsh.dll"))
    and (ProcessCommandLine contains " -e " or ProcessCommandLine contains " /e " ...)
    and not (InitiatingProcessFolderPath endswith @"\CCM\CcmExec.exe"
             and ProcessCommandLine contains @"\ccmcache\")
  • Unmapped fields fail loudly or, worse, pass through unchanged: a rule using OriginalFileName converted for a 4688-only estate references a field that does not exist there and silently never matches. Read the converted query, do not just deploy it.
  • Log source gaps are a mapping problem too. category: process_access needs Sysmon event 10 or EDR telemetry; 4688 has nothing equivalent. Track which rules your telemetry can actually feed.
  • Write your own pipeline (a small YAML file passed with -p) for in-house field names and index names rather than editing converted queries by hand, so every rule converts the same way.
iSigma is not the whole detection

Conversion gives you the search. Scheduling, thresholds, suppression, grouping into cases and response actions live in the SIEM or SOAR. Many teams keep that deployment metadata beside the rule in the same repository (a custom field or a sidecar file) so the rule and how it runs are reviewed together.

04Testing against samples

A rule is code, so it gets tests. Every rule needs at least one positive sample (events it must match) and one negative sample (look-alike benign events it must not match). Without them, the next person who "tunes" the filter has no way to know they broke it.

▭On the whiteboard · Test plan for the encoded PowerShell rule4 points
01
positive
Atomic Red Team T1059.001 test that runs powershell -EncodedCommand; record the Sysmon event 1 and the 4688
02
evasion variants
/enc, -EC, -eNcOdEdCoMmAnD, pwsh.exe, renamed powershell.exe (caught by OriginalFileName)
03
negative
SCCM ccmcache install script; a developer running powershell -File build.ps1; powershell -ExecutionPolicy Bypass (contains -e only as a prefix)
04
regression
Every past true positive from the case system, replayed from stored raw events
Chainsaw over EVTX samples as a CI testbash
# Run Sigma directly over EVTX samples, no SIEM needed
chainsaw hunt samples/positive/ -s rules/windows/proc_creation_win_powershell_encoded.yml \
  --mapping mappings/sigma-event-logs-all.yml --json > out/positive.json
chainsaw hunt samples/negative/ -s rules/windows/proc_creation_win_powershell_encoded.yml \
  --mapping mappings/sigma-event-logs-all.yml --json > out/negative.json

# CI gate: positives must hit, negatives must not
test "$(jq length out/positive.json)" -ge 1 || { echo "FAIL: missed positive sample"; exit 1; }
test "$(jq length out/negative.json)" -eq 0 || { echo "FAIL: matched negative sample"; exit 1; }
echo "PASS"

Then test in the real SIEM. Convert the rule, run it over the last 30 days, and count the hits: a rule that would have fired 4,000 times last month is not ready, whatever the samples said. Tools like Zircolite (Sigma over EVTX in SQLite) and Hayabusa do the same job as Chainsaw; pick one and wire it into CI.

Test yourself

Your rule uses `CommandLine|contains: [' -enc ', ' -nop ']` and you intended to alert only when both appear. What happens?

05False-positive notes and versioning

Rules outlive their authors. The falsepositives list and the version history are how the next analyst knows whether an alert is the known SCCM pattern or something new.

PracticeDoAvoid
False-positive notesName the product, process or team: "SCCM ccmcache install scripts""Legitimate administrative activity" with nothing else
Status lifecycleexperimental (new) to test (tuned on real data) to stable (low FP, has runbook)Paging the SOC on an experimental rule
IdentityKeep id forever; bump modified on each changeNew UUIDs for edits: you lose alert history and metrics
Replacing a ruleSet status: deprecated and link the new one with related (types: derived, obsolete, merged, renamed, similar)Deleting the file so nobody knows what happened
Change controlGit, pull requests, CI running sigma check and the sample tests, a reviewer from the SOCEditing the converted query live in the SIEM console
Lifecycle metadata that tells the next analyst what changedyaml
title: PowerShell started with an encoded command
id: 3a6b7f1e-5c2d-4e8a-9b0f-1d2c3e4f5a6b
related:
  - id: 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d
    type: obsolete        # the older, broader rule this one replaces
status: stable
modified: 2026-11-10
falsepositives:
  - SCCM client running install scripts from C:\Windows\ccmcache (filtered)
  - Datto RMM agent scripts on build servers (BLD-*); not filtered, triage by parent AgentProcess.exe
“How to say it in the room

"I treat Sigma rules as code: a stable id, a status that reflects how tuned it is, positive and negative samples in CI, and false-positive notes specific enough that an L1 can close the known pattern in a minute. Conversion goes through a pipeline we own, so field names are fixed in one place."

Q1Sigma or native SIEM queries?+

Sigma for portability, community sharing and review in Git; native queries when you need features Sigma cannot express, such as multi-event correlation over time windows. Sigma correlation rules (event_count, value_count, temporal) narrow that gap but backend support varies.

Q2How do you choose the level?+

By what the analyst should do: critical and high page or need same-shift triage and should be precise; medium goes to the queue; low and informational feed hunting dashboards and risk scoring, not pages.

Q3What makes a filter safe?+

It is narrow (several fields, including a path or signer, not just a process name), owned, documented in falsepositives, and covered by a test proving the true positive still fires.

Finished this one?
Tick it and it shows as done on the roadmap and the course.