Skip to main content

Write and test your first Sigma detection rules

Learn the required fields, write a small rule, validate it with sigma-cli, convert it for your SIEM, and finish with the 10-control checklist that closes this series.

Updated 11 min readMarkdown
Write and test your first Sigma detection rules

A beginner’s path from a YAML file to a tested rule in your SIEM, plus the checklist that closes this ten-post series. 18 November 2026, Asia/Dhaka. By the Rokkhe research team.

A detection that lives in one vendor’s query language is hard to review, hard to share, and hard to take with you. Sigma is a YAML format for describing a detection once, then converting it for the SIEM you actually run. You still have to test it. A rule that has never seen a log line is a hope, not a control.

This post writes a first rule, tests it, and talks about conversion and false positives. It also ends with the Rokkhe hardening checklist, 10 controls, which ties the series together. It does not claim a detection rate, and it does not drop a pack of offensive payloads.

This is post 10 of 10, the last in the Rokkhe hardening series. Post 9 built a small LLM security-review harness, and the series starts at post 1 with pinning your GitHub Actions. Detection is the other half of hardening: once the controls are in place, you want to know when something walks around them.

TL;DR

  • A Sigma rule must have a title, a logsource, and a detection section with a condition, as the official specification requires.
  • Start with a boring, testable behaviour (for example, execution of whoami.exe), not with a sprawling threat hunt.
  • Test against sample logs you are allowed to use before you ship the rule to production.
  • Convert with official or well-known Sigma tooling for your SIEM; then tune false positives and name an owner.
  • Use the ten-control checklist at the end of this post as the series home page.

What a Sigma rule is, and what it is not

SigmaHQ describes a rule as a YAML file that contains what you need to detect odd or malicious behaviour in logs, usually in a SIEM. The Sigma rules specification (version 2.1.0, released 2 August 2025, the current version when we checked on 18 November 2026) says the required pieces are title, logsource, and detection. Everything else (id, author, references, falsepositives, level, tags) is metadata you should still fill in, because that is how the next person tunes the rule at 3 a.m.

A Sigma rule is not:

  • A guarantee that the SIEM is collecting the right logs. If Windows Security or your Linux auth log never arrives, the rule cannot fire.
  • A substitute for the vendor query. Conversion gets you a starting query; you still have to run it.
  • An exploit. If a rule needs a payload to be demonstrated, use a lab and a known-benign trigger (running whoami, failing a login with a test account), not an attack on a production host.

The required fields: title, logsource, detection

The specification’s file conventions are practical and worth following: UTF-8, LF line endings, four-space indents, lowercase keys, and single quotes around strings unless the string itself contains a quote.

  • title: a short, precise name. “Whoami Execution” is better than “Suspicious Activity.”
  • logsource: where the data comes from. Typical keys are product (for example windows or linux), category (for example process_creation), and sometimes service. Converters use this to pick the right field names.
  • detection: one or more search identifiers (maps of field to value) and a condition that combines them (selection, selection and not filter, and so on).

A small rule, adapted from the whoami example in the specification (which matches the full C:\Windows\System32\whoami.exe path), looks like this. We match on the file name with the endswith modifier so a copy under another directory still matches:

title: Whoami Execution
id: 6f1b2f7e-3d57-4f0a-9d54-1d2f3a9c7a10
status: experimental
description: Detects execution of whoami.exe
references:
    - https://sigmahq.io/docs/basics/rules.html
    - https://github.com/SigmaHQ/sigma-specification/blob/main/specification/sigma-rules-specification.md
author: Your Name
date: 2026-11-18
logsource:
    category: process_creation
    product: windows
detection:
    selection:
        Image|endswith: '\whoami.exe'
    condition: selection
falsepositives:
    - Administrators troubleshooting permissions
level: low

That rule is deliberately small. It will fire when the process-creation log says an image ending in \whoami.exe was started. It will also fire when a help-desk technician runs whoami honestly, which is why falsepositives and level are there.

Write a small, testable rule

Pick a behaviour you can generate in a lab:

  • A Windows process you can start yourself (whoami.exe).
  • A failed SSH login on a Linux host you own, if your SIEM already has auth logs.
  • A web-server 401 on a path you own, if you are writing a web detection.

Here is a second example, for SSH failures on Linux, still written as Sigma, not as a vendor query. It matches a single failure; counting repeats belongs in the SIEM or in a Sigma correlation rule:

title: SSH Authentication Failure
id: 0b7c4d2a-5c1e-4a8b-8f3d-7a9e6d5c4b31
status: experimental
description: Detects a failed SSH password or publickey attempt in auth logs
author: Your Name
date: 2026-11-18
logsource:
    product: linux
    service: auth
detection:
    selection:
        Message|contains:
            - 'Failed password'
            - 'Failed publickey'
    condition: selection
falsepositives:
    - Users mistyping a password
    - Automated inventory or backup jobs with a stale key
level: medium

The Message field name in the second example must match the taxonomy your pipeline uses, or a converter must map them. If your log shipper already parses sshd lines into different fields, adjust selection to those fields. Do not invent a field that your logs do not contain; open one sample event and copy the keys.

Both examples carry an id, a random UUID v4 per the specification; generate a new one for every rule you write. Add references to the advisory or the internal ticket that justified the rule. If the rule is meant to watch for a KEV item you actually run, link that CVE and the triage ticket (see post 4 for the weekly triage routine).

Validate and test before you ship

Do not merge a rule whose only test is “it looks right.” The current official command line tool is sigma-cli, which is built on the pySigma library. Install it in a virtual environment, together with the backend plugins for the SIEM you use:

python3 -m venv sigma-venv && . sigma-venv/bin/activate
pip install sigma-cli pysigma-backend-splunk pysigma-backend-elasticsearch pysigma-pipeline-windows
sigma version

Save the rules with descriptive file names (for example proc_creation_win_whoami_execution.yml and linux_auth_ssh_authentication_failure.yml) in a rules/ folder, then validate them:

sigma check rules/

sigma check reports YAML and condition errors and best-practice issues. When we ran it on the two rules above with sigma-cli 3.1.0, it found no issues; a too-short file name such as ssh.yml is flagged, which is why the names matter. Validation proves the rule is well formed. It does not prove the rule detects anything, so also do this:

  1. Keep a positive sample (a log event that must match) and a negative sample (a similar event that must not).
  2. Convert the rule (next section) and run the query in your SIEM, or a lab copy of it, against both samples.
  3. Check that the positive sample fires and the negative sample stays quiet. Keep both samples in git next to the rule.

If you cannot produce a positive sample without attacking a system, pick a different first rule. whoami and a failed login with a test account are enough to learn the loop.

Convert it for the SIEM you actually use

Sigma exists because detection engineers got tired of rewriting the same idea in several query languages. After the YAML validates, convert it with the backend and the processing pipeline that match your field names. List what is installed with sigma list targets and sigma list pipelines. For the Windows rule:

sigma convert -t splunk -p splunk_windows rules/proc_creation_win_whoami_execution.yml
sigma convert -t lucene -p ecs_windows rules/proc_creation_win_whoami_execution.yml

With the plugin versions we installed, that produced Image="*\\whoami.exe" for Splunk and process.executable.caseless:*\\whoami.exe for Elasticsearch (Lucene). Your output may differ with plugin versions and pipelines. The SSH rule uses a generic Message field and has no pipeline for it, so you either supply a pipeline that maps your fields or, for a quick look only, pass --without-pipeline:

sigma convert -t splunk --without-pipeline rules/linux_auth_ssh_authentication_failure.yml

That gave Message IN ("*Failed password*", "*Failed publickey*") in our run. Treat it as a starting query, not a finished one.

Then, in the SIEM:

  • Confirm the index or table the rule queries is the one that actually receives those logs.
  • Set a lookback that will not empty your licence on the first afternoon.
  • Save the query next to a link back to the YAML in git, so the YAML remains the source of truth.

If the converted query uses different field names than your ingestion pipeline, fix the pipeline mapping or add a Sigma pipeline. Do not quietly edit only the vendor query, or the next conversion will wipe your fix.

Tune false positives and document the owner

Every useful rule has a false-positive note. Fill it in with real causes after a week, not with “unknown.” Add exclusions narrowly (a named admin group, a named host), and record why.

Give the rule an owner, a review date, and a severity that matches what you will actually do when it fires. A critical rule that everyone ignores is the same failure as logging without alerting, which the OWASP Top 10 lists as a risk in its own right. If a KEV-class vulnerability is the reason the rule exists, say so in the ticket and in references.

When the rule fires in production the first time, treat it as a test of the process: who was paged, what evidence they had, and whether the runbook told them to collect artefacts before a reboot.

The series checklist, and what to do next

This is the end of the series, so here is one page that links all ten posts, with a pass/fail check for each. Copy it into your own tracker as the “Rokkhe hardening checklist, 10 controls”:

  1. GitHub Actions. Every uses: line is pinned to a full SHA; default GITHUB_TOKEN is read-only. Post 1.
  2. OWASP Top 10 2025. A two-user access-control pass and the rest of the week’s checks have been run on the app you ship. Post 2.
  3. Secrets. History and working tree have been scanned; known leaks rotated; push protection is on. Post 3.
  4. CVE triage. A weekly KEV + EPSS + CVSS pass is on the calendar. Post 4.
  5. S3 and IAM. Account-level Block Public Access is on; at least one role is least-privilege; Access Analyzer has been reviewed. Post 5.
  6. API Top 10 2023. Alice cannot read Bob’s objects; admin functions are closed; inventory exists. Post 6.
  7. Kubernetes. The workload namespace enforces Restricted Pod Security; a NetworkPolicy exists; the image is pinned. Post 7.
  8. LLM app. Tools are allowlisted in code; output is treated as untrusted; a staging test set has been run. Post 8.
  9. Review harness. Scout / hunt / disprove exists for at least one repo, with a findings schema and a human in the loop. Post 9.
  10. Sigma. At least one tested rule is in the SIEM, with an owner and a false-positive note. This post.

Each row needs an owner, a date, and a one-line “how I verified it.” The checklist is free. It is not a product trial.

FAQ

Do we need Sigma if we only have one SIEM? It still helps. The YAML is reviewable in git, and you are not stuck if the SIEM changes.

Can we start from the public SigmaHQ rule packs? Yes, those packs exist in the official project, with their own licences and quality process. Read a rule before you enable it, and test it against your logs. Starting with one rule you understand is still the right first step.

Why is the whoami example so simple? Because you can generate a true positive without harming a system. Once the loop works, write the rule you actually need.

Where does the checklist live? Right here, in the section above. Copy the ten items into your own tracker or wiki and add an owner and a date to each.

Sources

This is the last of the ten how-to posts. Start from the top with post 1, or revisit post 9 if you want to see how AI-assisted review fits next to detection.

Rokkhe is an AI pentesting and security-operations workspace. Learn more at rokkhe.com.

No comments yet. Be the first to comment.