Getting Started
Sigma is an open format for writing detection rules in YAML. A single rule converts into a query for whichever SIEM you run, whether that is Splunk, Elasticsearch, Microsoft Sentinel, Grafana Loki, or one of many others. Your detections become portable, vendor-neutral, and easy to share across teams and tooling.
This guide takes you from installing the converter to writing a rule and turning it into effective, workable SIEM queries. It assumes no prior Sigma experience and doubles as a reference once you are comfortable.
Try it as you read
The converters throughout this guide run entirely in your browser. Edit the YAML, choose a target SIEM, and the query updates as you type. Install the CLI when you want to run conversions locally.
Installation
The Sigma ecosystem offers several tools for your use. This documentation will mainly focus on the primary Sigma converter, called sigma-cli, which converts all Sigma rules into usable SIEM queries for your security environment(s).
Requirements
To use sigma-cli (the Sigma Rule Converter) & the underlying library, you must have Python >= 3.9 installed.
Using uvx
The easiest way to run sigma-cli without a permanent installation is with uvx, a tool runner from the uv project. It downloads and runs sigma-cli in a temporary environment with no setup required.
uvx --from sigma-cli sigmaTIP
uvx is provided by uv. If you don't have it yet, install it with pip install uv or visit the uv installation docs.
Using pip
Alternatively, you can install sigma-cli permanently through the Python 3 package manager pip.
pip3 install sigma-cliTIP
Be sure that you've added Python's binary location (usually ~/.local/bin) to your PATH, so you can run sigma-cli straight from your CLI. Visit Python's website for Windows and more info.
or from Source
If you don't want to use pip, or if you instead want to download and install sigma-cli from source, first install Poetry on your system, then clone and install the required dependencies using Poetry.
git clone https://github.com/SigmaHQ/sigma-cli.git
cd sigma-cli
poetry install && poetry shell
sigma versionInstall your SIEM plugin pip only
Once you've installed sigma-cli, you will need to install your backend plugin through sigma-cli.
Newly introduced, the sigma-cli tool now offers a selection of installable backends – through a plugin system, each designed to target a specific SIEM commonly used by users. To see which backend plugins are available, run the sigma plugin list command from the command line.
sigma plugin list+----------------------+----------+---------+--------------------------------------------------------------+-------------+
| Identifier | Type | State | Description | Compatible? |
+----------------------+----------+---------+--------------------------------------------------------------+-------------+
| splunk | backend | stable | Splunk backend for conversion into SPL ... | yes |
...
+----------------------+----------+---------+--------------------------------------------------------------+-------------+To install a backend plugin, use the sigma plugin install command, followed by the backend identifier.
sigma plugin install splunkInstall the backend for whichever SIEM you target — for example splunk, elasticsearch, loki, or microsoft365defender. The rest is identical regardless of platform.
If you're using uvx, you don't install the plugin separately. Take the plugin's package name (for Splunk, pysigma-backend-splunk) and add it to the uvx oneliner with --with, as shown in the conversion examples below.
Pick your platform
The examples below use Splunk as a concrete walkthrough, but Sigma converts to dozens of SIEMs. Swap splunk for your own target (and its backend package) and every command works the same way. Browse the full list on the Backends page.
Converting Sigma Rules
Basic Example
Once you have installed the sigma-cli tool and the associated SIEM backend plugin, create a directory that will contain your Sigma rules and function as your "detection-as-code" repository. Consolidating your rules in one place is considered best practice and simplifies the deployment process.
Next, to create a Sigma rule that will detect when someone tries to disable Windows Defender's Threat Protection, create a YAML file called windows_defender_threat_detection_disabled.yml and fill it with the example Sigma detection shown below.
# Create a test repository to store your detections-as-code
mkdir sigma_test_repo && cd sigma_test_repo
mkdir ./rules
# Create a new Sigma rule
vim ./rules/windows_defender_threat_detection_disabled.ymlA Sigma rule is comprised of three sections: a title, the log source it applies to, and the detection logic that fires on a match.
Convert it live
Click Live Edit below, then choose a target from the dropdown to see this rule rendered as Splunk, ES|QL, Loki, KQL, and more.
title: Windows Defender Threat Detection Disabled
logsource:
# Windows Defender
product: windows
service: windefend
detection:
selection:
# The detection itself
EventID:
- 5001
- 5010
- 5012
- 5101
condition: selectionEventID IN (5001, 5010, 5012, 5101)In-browser vs. CLI output
The live query above is the bare-rule conversion (no pipeline). The sigma convert command further below adds a target-specific pipeline (here Splunk's built-in splunk_windows), which maps the rule onto the Defender source= and EventCode fields — hence the slightly different output. Each SIEM ships its own pipelines, so the same rule lands correctly on every platform.
Quickly running through this rule, we can describe it as detecting when the field EventID matches the following cases:
- A user has disabled Windows Defender's Real-time protection or
EventID: 5001 - A user has disabled Windows Defender's Anti-Spyware protection or
EventID: 5010 - A user has disabled Windows Defender's Anti-Virus protection or
EventID: 5012 - Windows Defender's Antimalware platform has expired
EventID: 5101
After saving the file and closing vim (or your preferred editor), you can use the sigma convert command to convert this Sigma rule into a Splunk query. It's important to set the correct parameters to ensure a valid query is produced for the SIEM being used in your environment.
- Set the Target SIEM
--target splunk
Use this option to instruct Sigma to convert the Sigma files under the./rules/directory to Splunk SPL.
See the full list of supported backends here -> - Set the SIEM Pipeline
--pipeline splunk_windows
Use this option to instruct Sigma to use thesplunk_windowsdefault field- and source-mapping pipeline.
Learn more about Sigma pipelines here ->
uvx --from sigma-cli --with pysigma-backend-splunk sigma convert \
--target splunk \
--pipeline splunk_windows \
./rulessigma convert \
--target splunk \
--pipeline splunk_windows \
./rulessource="WinEventLog:Microsoft-Windows-Windows Defender/Operational" \
EventCode IN (5001, 5010, 5012, 5101)Once events are populated under the WinEventLog:Microsoft-Windows-Windows Defender/Operational source within your SIEM – this example being Splunk, you can easily use this query to set up a detection and alert when someone disables Windows Defender within your monitored environment.
Congratulations, you're now ready to start detecting security threats using Sigma! 🎉
You don't have to start from scratch, either. The community maintains thousands of ready-to-use detections for Windows, Microsoft 365, Okta, AWS, and many more in the SigmaHQ/sigma repository.
Adding Contextual Information
While the previous example demonstrated a simple detection, in practice, Sigma rules contain additional metadata to provide context for the detection. This metadata may include severity (called "level" within Sigma), references, false-positives, tags (such as MITRE Attack mapping), and a rationale for the detection.
To better illustrate this point, let's take a look at a more complex Sigma rule, taken from the SigmaHQ/sigma repository written by Austin Songer.
This one targets Okta rather than Windows. The format does not change between platforms, and neither does the way you convert it.
# rules/identity/okta/okta_user_account_locked_out.yml
title: Okta User Account Locked Out
id: 14701da0-4b0f-4ee6-9c95-2ffb4e73bb9a
status: test
description: Detects when an user account is locked out.
references:
- https://developer.okta.com/docs/reference/api/system-log/
- https://developer.okta.com/docs/reference/api/event-types/
author: Austin Songer @austinsonger
date: 2021-09-12
modified: 2026-04-27
tags:
- attack.impact
- attack.t1531
logsource:
product: okta
service: okta
detection:
selection:
displayMessage: Max sign in attempts exceeded
condition: selection
falsepositives:
- Unknown
level: mediumdisplaymessage="Max sign in attempts exceeded"It's worth noting that Sigma rules often contain fantastic metadata about a detection, which is highly useful when investigating a security incident.
Learn more about Rules
To learn more about the fields above and how they are used in Sigma,
visit the Rules section of the documentation.
Converting this rule with the Splunk backend and its pipelines produces the query below. Point --target and --pipeline at a different SIEM and the same rule yields a query for that platform instead.
uvx --from sigma-cli --with pysigma-backend-splunk sigma convert \
--target splunk \
--pipeline splunk_windows \
./rules/cloud/okta/okta_user_account_locked_out.ymlsigma convert \
--target splunk \
--pipeline splunk_windows \
./rules/cloud/okta/okta_user_account_locked_out.ymldisplaymessage="Max sign in attempts exceeded"Outputting to Different Formats
Notice that adding the metadata to this Sigma rule hasn't changed the output of this query – using the default output format. Sigma supports outputting to multiple formats, unique to each backend.
We can see this metadata being used if we change the output format to savedsearches.
# Convert to Splunk savedsearches format
uvx --from sigma-cli --with pysigma-backend-splunk sigma convert \
--format savedsearches \
--target splunk \
--pipeline splunk_windows \
./rules/cloud/okta/okta_user_account_locked_out.yml# Convert to Splunk savedsearches format
sigma convert \
--format savedsearches \
--target splunk \
--pipeline splunk_windows \
./rules/cloud/okta/okta_user_account_locked_out.yml[default]
dispatch.earliest_time = -30d
dispatch.latest_time = now
[Okta User Account Locked Out]
description = Detects when an user account is locked out.
search = displaymessage="Max sign in attempts exceeded"Custom Field & Source Mapping
Although many logsources in enterprise IT environments are similar, it is essential to recognize that each SIEM is uniquely configured, particularly in its usage of field names, data types, and log formats.
To address these variances, sigma-cli provides end-users with the ability to perform field-mapping when converting rules. This function ensures any fields found in Sigma rules correctly map to users' fields found within their SIEM.
To best illustrate the adaptability of the Sigma format, we will onboard a custom logsource (in this example, an internal production service called puppy_app_production) and its corresponding detection rule, into our detections-as-code repository.
The pipeline below is written for Splunk, since field names and index conventions are specific to each platform. A different SIEM would use its own pipeline while reusing the exact same rule.
# Inside of sigma_test_repo, create a pipelines directory
mkdir ./pipelines
# Create a new Sigma pipeline file
vim ./pipelines/puppy_app_production_config.yml# ./pipelines/puppy_app_production_config.yml
name: Puppy Application – Splunk Log Source Configuration
priority: 100
transformations:
- id: prefix_source_and_index_for_puppy_logs
type: add_condition
conditions:
index: "puppy_prod"
source: "PuppyApp/App"
rule_conditions:
- type: logsource
product: puppy
service: app
- id: map_fields_for_puppies
type: field_name_mapping
mapping:
status: "puppy.status"
dog_name: "puppy.name"
dog_breed: "puppy.breed"
rule_conditions:
- type: logsource
product: puppy
service: app# ./rules/sad_puppy.yml
title: Sad Puppy in Dog Supply Line
id: 469b8469-508d-42d0-98a1-0c7e937ca7a3
status: experimental
description: >
Detects whenever a sad puppy is logged to the Dog Supply Line (DSL) log stream output.
See wiki on how to triage with treats and/or walks.
references:
- https://wiki.example.com/DOG/Sad+Puppy+Playbook+(2023)
author: Toto <toto@example.com>
date: 2023-04-06
logsource:
product: puppy
service: app
detection:
selection:
status: "sad"
condition: selection
fields:
- dog_name
- dog_breed
- status
falsepositives:
- sometimes sad dogs are reported as guilting owners for walks, treats etc.
level: highindex="puppy_prod" source="PuppyApp/App" puppy.status="sad" | table puppy.name,puppy.breed,puppy.statusIn the above configuration example, any rules that have a match on the following:product: puppy and service: app, Sigma will apply
index='puppy_prod' source='PuppyApp/App' ...to the resultant SIEM query output, and map each field across, for example status to puppy.status, dog_name to puppy.name etc.
We can combine this configuration example with the custom sad_puppy.yml detection rule, that will detect whenever our log source detects a sad puppy in our SIEM.
uvx --from sigma-cli --with pysigma-backend-splunk sigma convert \
-t splunk \
-p ./pipelines/puppy_app_production_config.yml \
./rules/sad_puppy.ymlsigma convert \
-t splunk \
-p ./pipelines/puppy_app_production_config.yml \
./rules/sad_puppy.ymlindex="puppy_prod" source="PuppyApp/App" puppy.status="sad"
| table puppy.name,puppy.breed,puppy.statusMost supported SIEMs ship with their fields and log sources already mapped, so you rarely write a pipeline from scratch. Pipelines handle the mapping; log sources describe what your rules match against.
What's Next?
You now have the essentials: writing a rule, converting it for any SIEM, and tailoring the output with pipelines. The pages below go deeper on each part of Sigma.