/writing-sigma-rules

name: writing-sigma-rules
description: Author and maintain Sigma detection rules — structure, logsource taxonomy, detection logic with modifiers, false-positive filtering, backend conversion with pySigma, and offline validation with Hayabusa or Chainsaw. Use when translating threat intel into vendor-agnostic detection logic, building a detection-as-code pipeline around Sigma, reviewing or tuning existing Sigma rules, or converting rules across SIEM backends.
verified: 2026-07-27

Writing Sigma Rules

Sigma is the common language for detection logic -- write once, convert to any SIEM. The value is portability and reviewability, but only if the rule is precise: a Sigma rule that matches everything is worse than no rule, because it consumes analyst time and trains the team to ignore alerts. The work is specificity without brittleness.

When to Use

• Translating a TTP, threat intel report, or incident finding into a portable detection rule
• Writing vendor-agnostic detection logic that converts to multiple SIEM backends
• Building or maintaining a detection-as-code pipeline centered on Sigma
• Reviewing or tuning existing Sigma rules for precision and false-positive reduction
• Converting Sigma rules between backends (Splunk, Elastic, Sentinel, CrowdStrike, Chronicle)
• Contributing rules upstream to SigmaHQ or maintaining a private rule repository

When NOT to Use

• **Broader detection engineering including YARA, Suricata, and the full detection lifecycle** -- use `engineering-detections`
• **The signature belongs on files or memory, not log telemetry** -- use `writing-yara-rules`
• **Hypothesis-driven threat hunting, not rule writing** -- use `hunting-threats`
• **Active incident response, not rule development** -- use `responding-to-incidents`

Sigma Rule Structure

Every rule is a YAML document with these fields in order:

**The specification requires only three fields:** `title`, `logsource`, and `detection` (which must contain a `condition`). Everything else is optional *to the spec*. Do not confuse that with the SigmaHQ rule repository, which requires far more — `id`, `status`, `description`, `author`, `date`, `level`, and ATT&CK `tags` — before it will accept a contribution. Write to the stricter SigmaHQ convention by default, because a rule without an `id` or a `level` is unmanageable in a real pipeline, but know which constraint you are meeting when a converter accepts a rule your reviewer rejects.

title: Short Descriptive Name              # REQUIRED by spec, max ~100 chars
id: a1b2c3d4-0000-4000-8000-000000000001  # optional to spec; UUIDv4, never reuse
related:                                    # optional, link to predecessor rules
  - id: <uuid>
    type: derived | obsoletes | merged | renamed | similar
status: experimental                        # optional; see lifecycle below
description: >                              # optional to spec, expected by SigmaHQ
  Detects X behaviour consistent with Y technique.
references:                                 # optional, strongly recommended
  - https://attack.mitre.org/techniques/T1059/001/
author: Your Name                           # optional to spec
date: 2026-07-26                            # optional; ISO 8601 YYYY-MM-DD
modified: 2026-07-26                        # optional; same format, on update
tags:                                       # optional to spec, expected by SigmaHQ
  - attack.execution                        #   tactic (lowercase, dotted)
  - attack.t1059.001                        #   technique (lowercase)
logsource:                                  # REQUIRED by spec
  category: process_creation
  product: windows
detection:                                  # REQUIRED by spec
  selection:
    CommandLine|contains: 'some-indicator'
  condition: selection                      # REQUIRED inside detection
falsepositives:                             # optional to spec
  - Legitimate admin scripts using the same flag
level: medium                               # optional; informational|low|medium|high|critical

**Date format.** The spec mandates ISO 8601 with hyphens — `YYYY-MM-DD`. Older rules and much online material use the legacy `YYYY/MM/DD`; that form is outdated, and some tooling now rejects it.

**Status lifecycle.** The permitted values are `experimental`, `test`, `stable`, `deprecated`, and `unsupported`. In practice: `experimental` = observation only, no alerting. `test` = validated against emulation, ready for limited deployment. `stable` = tuned in production with documented FPs. `deprecated` = replaced, no longer accurate. `unsupported` = not usable as written (e.g. depends on homemade fields). Never promote without the corresponding work.

Logsource Taxonomy

The `logsource` block abstracts the data source. Specify only what is needed.

**Categories:** `process_creation`, `file_event`, `file_access`, `network_connection`, `registry_event`, `dns_query`, `image_load`, `pipe_created`, `process_access`, `driver_load`, `create_remote_thread`.

**Product:** `windows`, `linux`, `macos`.

**Service:** `sysmon`, `security`, `system`, `powershell`, `powershell-classic`, `application`, `taskscheduler`, `windefend`, `firewall-as`.

Use `category` when you care about the event type regardless of collection method. Use `product` + `service` when targeting a specific log channel. Do not combine `category` and `service` unless the backend requires it.

Detection Logic

Selection and filter pattern

Define what to match (`selection`), what to exclude (`filter_*`), combine in `condition`:

detection:
  selection:
    ParentImage|endswith: '\explorer.exe'
    CommandLine|contains|all:
      - 'powershell'
      - '-enc'
  filter_legitimate:
    CommandLine|contains: 'company-deploy-script'
    User|startswith: 'SVC_'
  condition: selection and not filter_legitimate

Condition syntax

condition: selection                           # simple match
condition: