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.
01What Sigma is and how a rule is built
- 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.
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| Field | Purpose | Notes |
|---|---|---|
title, description | What it detects and why that matters | Write for the analyst triaging it at 3 a.m. |
id | A random UUID that never changes | Edits keep the id; only modified changes |
status | Maturity: experimental, test, stable (plus deprecated, unsupported) | Drives whether the SOC pages on it |
logsource | category, product, service: which data the rule needs | The converter maps this to an index, table or event ID |
detection | Named search identifiers plus a condition | The logic |
falsepositives, level | Known benign causes; severity from informational to critical | Honest FP notes save hours of triage |
tags | ATT&CK tactic and technique IDs | Lets you build coverage maps from the repository |
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.
| Modifier | Meaning | Example |
|---|---|---|
contains, startswith, endswith | Substring, prefix, suffix match (case-insensitive by default) | Image|endswith: '\rundll32.exe' |
all | Every value in the list must match, turning the list into AND | CommandLine|contains|all: ['-nop', 'hidden'] |
windash | Also try /, en dash, em dash and horizontal bar in place of - | Catches powershell /enc and Unicode dash tricks |
re | Regular expression (keep it simple; backends differ) | CommandLine|re: '\s-[eE][nN]?[cC]?\s' |
base64offset | Match a string inside base64 at any of the three alignments | CommandLine|base64offset|contains: 'IEX' |
cidr | IP address within a network range | DestinationIp|cidr: '10.0.0.0/8' |
exists, gt, lt | Field presence and numeric comparison (Sigma 2.0) | ParentImage|exists: false |
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_knownThe 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.
`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.
# 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# 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
OriginalFileNameconverted 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_accessneeds 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.
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.
# 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.
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.
| Practice | Do | Avoid |
|---|---|---|
| False-positive notes | Name the product, process or team: "SCCM ccmcache install scripts" | "Legitimate administrative activity" with nothing else |
| Status lifecycle | experimental (new) to test (tuned on real data) to stable (low FP, has runbook) | Paging the SOC on an experimental rule |
| Identity | Keep id forever; bump modified on each change | New UUIDs for edits: you lose alert history and metrics |
| Replacing a rule | Set status: deprecated and link the new one with related (types: derived, obsolete, merged, renamed, similar) | Deleting the file so nobody knows what happened |
| Change control | Git, pull requests, CI running sigma check and the sample tests, a reviewer from the SOC | Editing the converted query live in the SIEM console |
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"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.