Sigma Rules Guide: Writing, Converting and Managing Portable Detections

Detection logic written in one SIEM's query language is locked to that SIEM, hard to review and easy to lose when the platform changes. Sigma is an open, YAML based rule format that describes a log detection once and converts it to the query language of many backends. This guide explains the rule format field by field, shows a small example rule in the documented style, covers the SigmaHQ rule repository and its licence, and walks through conversion with pySigma and sigma-cli, testing, tuning and safe rollout. It is for detection engineers and SOC analysts. The detection lifecycle, detection as code and alert metrics are covered in the Detection Engineering Guide; this page stays on Sigma itself.

Key takeaways

• Three sections are mandatory. The Sigma documentation marks only title, logsource and detection (with its condition) as required; everything else is metadata, but good metadata is what makes a rule maintainable.
• The specification is at version 2.1.0. The Sigma Rules Specification in the SigmaHQ sigma-specification repository states version 2.1.0, dated 2 August 2025, with separate specifications for correlation rules and filters.
• Conversion is only as good as the pipeline. pySigma backends turn rules into queries, but processing pipelines map Sigma field names and log sources to your schema, and a wrong mapping produces a query that silently never matches.
• Community rules carry a licence. The SigmaHQ repository content is released under the Detection Rule License (DRL) 1.1, which allows commercial use but requires author attribution, including where rule matches are shown.
• Keep local changes out of upstream rules. Use Sigma filters for environment specific exclusions so that pulling a new SigmaHQ release does not overwrite your tuning.

What the tool does

Sigma does for log events what YARA does for files and Suricata or Snort rules do for network traffic: it gives defenders a shared, vendor neutral way to write and exchange detections. A rule describes which log source to search and which field values indicate suspicious activity. A converter then produces the native query for a target such as Splunk SPL or Elastic ES|QL. For file and memory pattern matching, see the YARA Rules Guide.

Anatomy of a rule

Detection logic in brief

• Lists and maps: values in a list are joined with OR; keys in a map are joined with AND. A plain keywords list searches raw text with OR.
• Modifiers: appended with a pipe, for example CommandLine|contains. Documented modifiers include contains, startswith, endswith, all, re (with i, m, s), base64, base64offset, utf16le and wide (before base64), windash (matches -, / and dash variants in command line flags), cidr, exists, fieldref, cased, expand and the numeric gt, gte, lt, lte.
• Conditions: and, or, not, brackets, and patterns such as 1 of selection_* or all of filter_*. The docs recommend brackets to remove ambiguity, and discourage 1 of them and all of them in rules shared with SigmaHQ.

A short example rule

The rule below is a benign illustration in the documented style. It flags execution of the Windows whoami utility, a common discovery step (ATT&CK T1033 System Owner/User Discovery), and excludes a named inventory agent through a filter group. The parent process path is a placeholder for your own tooling.

title: Whoami Utility Execution
id: 2a813ad9-47d3-4662-9e6c-8007d7b11a93
status: experimental
description: Identifies execution of whoami.exe, which attackers use to confirm the
  account and privileges they hold after initial access. Low fidelity on its own,
  useful for correlation and hunting.
references:
  - https://attack.mitre.org/techniques/T1033/
author: Example Detection Team
date: 2026-10-25
tags:
  - attack.discovery
  - attack.t1033
logsource:
  category: process_creation
  product: windows
detection:
  selection_img:
    - Image|endswith: '\whoami.exe'
    - OriginalFileName: 'whoami.exe'
  filter_inventory:
    ParentImage|endswith: '\InventoryAgent.exe'
  condition: selection_img and not filter_inventory
falsepositives:
  - Administrators and support staff checking their own context
  - Login scripts and management agents
level: low

Matching Image or OriginalFileName catches a renamed binary.

Specification and rule types

• Rules specification: version 2.1.0, with appendices for modifiers, tags and taxonomy, and JSON schemas for rules, correlations and filters.
• Correlation rules: combine base rules by name or id using types event_count, value_count, temporal, temporal_ordered and value aggregations (value_sum, value_avg, value_median, value_percentile), with group-by, timespan and a condition such as gte: 10. Timespan units are case sensitive (m minutes, M months).
• Filters: separate files with a filter block listing target rules (or rules: any), selections and a condition such as not selection. At conversion the filter is appended to each target rule's condition. A filter applies only where its logsource matches the rule's.

Defender use cases

The SigmaHQ repository states it offers more than 3,000 detection rules, organised into rules (generic, threat agnostic), rules-threat-hunting, rules-emerging-threats, rules-compliance, rules-placeholder (meaning resolved at conversion, used with the expand modifier), rules-dfir and deprecated. Release packages are published on the repository's releases page.

Where identity fits

Many of the most useful Sigma rules concern credentials: access to LSASS memory (T1003.001), suspicious PowerShell (T1059.001) launched by service accounts, and sign-in anomalies in identity provider logs (the logsource docs give okta as a product example). Service accounts and automation identities generate a large share of false positives, so exclusions for them must be narrow, owned and reviewed, never a blanket filter on an account name. See the MITRE ATT&CK T1078 Valid Accounts Guide.

Deployment and safe use

Converting with pySigma and sigma-cli

pySigma is the Python library that parses and converts rules; its README describes it as the replacement for the legacy sigmac toolchain, and sigma-cli is the official command line front end. Both are licensed LGPL-2.1. Backends (for example pySigma-backend-splunk) and processing pipelines (for example pySigma-pipeline-sysmon) live in separate projects so the core stays vendor agnostic.

Pipelines can be stacked with repeated -p options: a vendor pipeline for the data model, then your own YAML pipeline for index names and site specific fields.

Phased rollout

1. Inventory log sources first. List which Sigma logsources you actually collect (for example process_creation needs Sysmon Event ID 1, Windows Security 4688 with command line auditing, or EDR telemetry). A rule for a source you do not collect is dead weight.
2. Build and test the pipeline. Map field names and log sources to your schema, then convert a handful of rules and run them against recorded events you know should match.
3. Validate in CI. Run pySigma validators on every change: ATTACKTagValidator (valid ATT&CK tags), IdentifierUniquenessValidator (no duplicate UUIDs), AllOfThemConditionValidator and dangling detection checks. Configure with validators: [all], -name to disable one, and per rule exclusions.
4. Pilot a reviewed subset. Start with stable and test rules at high and critical level for sources you collect; deploy as non alerting searches and record volumes.
5. Tune with filters, then promote. Write exclusions as Sigma filter files in your repository, each with an owner and reason, and promote rules to alerting once volume and precision are acceptable.
6. Roll back by version. Because the deployed queries are generated, rollback is reverting the rule, pipeline or filter commit and reconverting. Keep the pySigma, backend and pipeline versions pinned so a tool upgrade does not silently change output.

Safe use and licensing

• DRL 1.1 obligations: the licence (SPDX DRL-1.1, based on MIT) permits modification, private and commercial use, but requires crediting the rule author when rules are reproduced and in output that shows matches, for example a column in the alert view. Keep the author field through conversion. Check redistribution in products with your Open Source Licence Compliance Guide process.
• Review before deploy: treat imported rules like code. Read the detection, check the status, and never bulk enable a whole release.
• Protect the deploy path: the credential that pushes converted rules into the SIEM can also disable detections, so scope it to rule management and log its use.
• Online converters: web converters such as sigconverter.io exist; do not paste rules containing internal hostnames, account names or unreleased intelligence into services you do not control. Run sigma-cli locally instead.

Detection and hardening value

Sigma adds value when rules are tested and measured, not when the rule count grows. Track these alongside the Detection Engineering Guide metrics:

• Conversion success rate: share of rules in scope that convert without error for each backend; failures usually point to unsupported modifiers or missing pipeline mappings.
• Collected source coverage: percentage of deployed rules whose logsource is actually present in the SIEM in the last 7 days.
• Rules with a passing test event: share of production rules with at least one recorded true positive event that still matches after conversion.
• Upstream drift: number of SigmaHQ rules you run that were modified or deprecated upstream since your last sync and are not yet reviewed.
• Filter age: number of filters past their review date or without an owner.

Framework mapping

Common failure patterns

• Converting without a pipeline: the query uses Sigma's generic field names, matches nothing, and the team believes it has coverage.
• Editing upstream rules in place: local exclusions vanish at the next SigmaHQ sync. Use filter files instead.
• Using falsepositives as an exclusion: converters ignore it, so the noise continues.
• Misspelt correlation keys: the docs warn that group_by instead of group-by is silently ignored, which changes what the rule counts.
• Bulk enabling a release: hundreds of experimental and hunting rules flood the queue and analysts start ignoring Sigma alerts altogether.
• Losing attribution: stripping author in conversion breaches DRL 1.1 terms for community rules.

Alternatives

Small teams get most value by converting a curated SigmaHQ subset with one pipeline and a short filter set. Large teams should keep all custom content in Sigma where possible, pin tool versions, run validators in CI and keep native queries only for logic Sigma cannot express.

Practitioner checklist

• List the Sigma logsources you collect and drop rules for sources you do not.
• Build, version and test a processing pipeline per backend before converting at scale.
• Pin pySigma, sigma-cli, backend and pipeline versions and record them with each deployment.
• Give every custom rule a UUID v4 id, status, level, ATT&CK tags and a description of why it exists.
• Run pySigma validators in CI on every pull request.
• Keep local exclusions as Sigma filter files with an owner, reason and review date.
• Store at least one matching test event per production rule and check it after every conversion.
• Review upstream changes and deprecations at each SigmaHQ sync.
• Preserve author attribution for DRL 1.1 rules in alert output.
• Convert locally rather than in hosted converters when rules contain internal detail.

Standards and references

• SigmaHQ: Sigma Rules Specification
• SigmaHQ: Rules documentation
• SigmaHQ: Modifiers
• SigmaHQ: Correlation rules
• SigmaHQ: Sigma rule repository
• SigmaHQ: pySigma
• SigmaHQ: Detection Rule License 1.1
• MITRE ATT&CK: System Owner/User Discovery

Related NHI Mgmt Group resources: Detection Engineering Guide · YARA Rules Guide · SIEM Guide · Pyramid of Pain Guide · CyberChef for Analysts Guide