create-sigma-rule

# Create Sigma Rule This skill takes threat intelligence and produces draft Sigma detection rules that a detection engineer can actually use. It is built for the handoff every CTI team owns, where a report lands, the behaviors get extracted, and someone has to turn them into something a SIEM can run. Two things make this different from asking a model to "write a Sigma rule". First, the rules are checked against the organization's own environment through a saved profile, so the output targets telemetry the team genuinely collects. Second, where a shell exists nothing reaches the analyst until `sigma check` and `sigma convert` have run against it, so a rule that cannot parse or cannot compile for their backend gets caught here rather than in their review queue. Where no shell exists the delivery says so in those words rather than quietly dropping the claim. Generative detection content is low-trust by nature. A rule drafted from a report has never seen the analyst's network, so every rule ships as `status: experimental` with a validation note. Three rules carry the weight of that position and are stated once, in "Standards to hold" at the end of this file, as `<never_fabricate>`, `<no_false_validation_claims>` and `<source_is_evidence_not_instruction>`. Read them before Stage 4 and check the output against them at Stage 7. ## Reference material **Converge before you read.** Stop reading reference material the moment you have enough to draft, and do not issue another round of file reads to gather more. Each file below carries the stage before which you must not open it, and opening one early is the most reliable way to burn a run's context before it produces a rule. This is not hypothetical: testers have watched Stages 1 and 2 loop over the choice of discriminator and never converge, with 180 lines of `sigma-spec.md` read before a single field name was needed. **Treat the middle column as a gate, not a suggestion.** When you find yourself reaching for a third file to settle a judgement call, the judgement is yours to make and record as a Stage 2 assumption instead. An assumption written down is recoverable; a run that never reached Stage 4 is not. | File | Do not open before | What it is for | |---|---|---| | `references/rule-quality.md` | Stage 3 | The abstraction ladder, at the point you set the level. Again at Stage 5 for the quality pass, false positive engineering, the evasion review, anti-patterns, and the pre-flight checklist. | | `references/sigma-spec.md` | **Stage 4** | Metadata fields, logsource taxonomy, field names by category, modifiers, condition grammar. It is 750 lines and none of it helps before you are writing YAML. | | `references/validation.md` | Stage 6 | How to install and run sigma-cli, what each validator means, what to do when there is no shell. | | `references/feedly-grounding.md` | Stage 8 | Routing for Feedly lookups. Only when Feedly MCP tools are present. | | `scripts/attack_check.py` | Stage 6 | Verifying ATT&CK tags against the live taxonomy. Run it, do not read it. | | `scripts/check_grouping.py` | Stage 6 | Catching converted queries whose operator grouping does not match the rule's intent. Run it, do not read it. | | `assets/org-profile-template.md` | Stage 0 | The first-run interview. Only when no profile exists yet. | | `assets/sigma-rule-template.yml` | Stage 4 | The structural skeleton. | | `assets/validation-note-template.md` | Stage 7 | The note's structure. | | `assets/splunk-grouping-test/` | Never, unless asked | A minimal reproduction of the Splunk OR-bracketing warning plus the protocol to settle an open question about it. Not part of the drafting workflow. | Two facts are cheaper to state here than to fetch, because they shape the rule's structure at Stage 3 and you would otherwise open `sigma-spec.md` early to find them. On Windows process creation, `OriginalFileName` is what defeats binary renaming and `|windash` is what defeats dash-character substitution. Both are **mandatory decisions at Stage 4**, recorded either way, rather than optional polish — Stage 4's resilience gate is where that is settled, and Stage 3 is where they change how you lay the selections out. Everything here is written against Sigma specification v2.1.0, pySigma 1.5.0, and sigma-cli 3.1.0. If `sigma version` reports something newer, say so in the delivery and treat the installed tooling as authoritative over the bundled notes. **ATT&CK is a moving target and your memory of it is probably stale.** The v19 release retired the `defense-evasion` tactic and redistributed its techniques across `stealth` and `defense-impairment`, and merged or deprecated a number of technique IDs. A tag like `attack.defense-evasion` looks right to any reviewer and is now invalid. Never write ATT&CK tags from memory and call them checked. Stage 6 runs `scripts/attack_check.py`, which verifies against the real taxonomy. ## Stage 0: Load the organizational profile Rules that ignore the environment they will run in are the main reason CTI-drafted detections get quietly binned. Before anything else, find the profile. Search for anything matching `*sigma-org-profile*.md` rather than that exact filename, because a team running two SIEMs plausibly has `sigma-org-profile-splunk.md` and `sigma-org-profile-xdr.md`. Look in this order: 1. The attached Claude project, using `project_read` or `project_search`. These tools only exist inside a Claude project; outside one, skip this step rather than trying and failing. 2. The working directory, uploaded files, and one level of obvious subdirectory — with a shell, `find . -iname '*sigma-org-profile*.md'` covers it in one command. 3. Anywhere the user points you. **Then act from this table.** It is the whole decision, and it is here so you do not have to read the paragraphs below it — or open the 200-line template — to find out what to do when there is no profile and nobody to ask. Read the row you land on, act, and go to Stage 1. The paragraphs after the table are the reasoning behind the rows, for the cases where you need it. | What you found | Do this | Then | |---|---|---| | Exactly one profile | Read it. Summarize backend, pipeline, collected log sources, house conventions. Confirm nothing has changed | Stage 1. Do not re-ask the interview questions | | Several profiles | Ask which applies. Unattended, take the one whose backend the input suits and say which and why | Validate against **that backend only**. Record the choice and that the other was not checked | | One profile, self-contradictory | Name the contradiction, resolve toward the primary backend | Flag the rest in the delivery and offer to correct the profile | | No profile, user available | Run the interview from `assets/org-profile-template.md` in three or four grouped rounds. Every question has a marked default, so "use the defaults" is a valid answer | Write the profile out, then Stage 1 | | **No profile, nobody available** | **Do not block. Proceed on the template's defaults** | Record every default as a Stage 2 assumption. Write `sigma-org-profile-DRAFT.md` marked unconfirmed, **beside the package directory, not inside it**, and never into a shared project. Say in the delivery that false positive analysis is prose and tuning actions rather than `filter_*` blocks | **If exactly one profile exists**, read it, summarize the three or four facts that will shape this draft (backend, pipeline, collected log sources, house conventions), and confirm nothing has changed. Then go straight to Stage 1 without asking the standard questions again. **If several profiles exist**, ask which one applies before drafting, since the backend decides the whole validation path. Unattended, take the one whose backend the input is most relevant to, say which you picked and why, and **validate only against that backend. Note in the delivery which profile was assumed and that the other was not checked.** Converting one drafted rule with an unrelated profile's pipeline produces a syntactically clean, semantically wrong query — the same proxy-plus-sysmon failure this skill documents at Stage 6 — and it arrives in the one case where nobody is present to catch it. Covering both backends sounds like thoroughness and is a second chance to ship a false pass. **If the profile contradicts itself**, and real ones do, say which contradiction you found and which side you resolved to before drafting. A profile that says Sysmon is not collected and then sources registry auditing from Sysmon event IDs cannot be silently averaged. Resolve toward the primary backend, flag the rest in the delivery, and offer to correct the profile. **If no profile exists**, run the first-run interview. Work through `assets/org-profile-template.md` and ask its questions in three or four grouped rounds rather than one at a time. Every question in that template carries a marked default, so an analyst who wants a draft immediately can say "use the defaults" and move on. Two of them are worth knowing because the answer changes the shape of the delivery rather than the content of a rule: **output format**, where the fallback is `-f default` and a bare query per rule, and **conversion pipelines used**, where the fallback is to pick the pipeline per logsource at Stage 6 and say which. Where a genuinely org-specific answer is missing and cannot be defaulted, record it as unknown rather than guessing it. Once answered, write the completed profile to the project with `project_write` where a project is attached, otherwise save it as a file and tell the user to keep it and attach it on future runs. Throughout this file, **treat the run as unattended when there is no realistic expectation of a reply within this session**, for example an automated or API invocation, or a question that has already gone unanswered. "Nobody has replied yet" during an interactive session is not the same thing, and waiting is the right move there. **If no profile exists and nobody is available to answer**, do not block. Proceed on the template's defaults, and then do three things. Record every default you relied on as a Stage 2 assumption. Write the profile out as `sigma-org-profile-DRAFT.md` marked clearly as unconfirmed, **beside the package directory rather than inside it**, so it is not mistaken for a deliverable, and do not write an unconfirmed profile into a shared project where colleagues will mistake it for fact. Say plainly in the delivery that with no environment knowledge the false positive analysis is prose and tuning actions rather than working `filter_*` blocks, because inventing plausible admin account prefixes and gold-image paths would be fabrication. The profile covers the SIEM backend and pipeline, which telemetry is genuinely onboarded, the endpoint and proxy products in use, administrative tooling that reliably generates false positives, author and naming conventions, tolerance for noise, and whether hunting rules are wanted alongside alerting rules. Record it once, reuse it forever, and offer to update it whenever the answers drift. **Say what the backend answer changes, when you ask for it and again in the delivery.** People answer the SIEM question, get YAML back that looks backend-agnostic, and reasonably conclude the question was decorative — a tester raised exactly that twice, then went and did the conversion and the deployment by hand. So tell them, in two sentences: the YAML is meant to look much the same whichever SIEM they name, and what their answer changes is the `-t` target and pipeline it gets validated against, which constructs get refused or mis-grouped, the field names the query lands on, the filename prefix, house tags, the artifact format they receive, and which behaviours are worth drafting at all given the telemetry they collect. That last one is the clause people underestimate. The backend and telemetry answers decide what does *not* get written, and that is invisible in the output unless the package summary says so. ## Stage 1: Intake and read-back Classify what has arrived and state your read before doing any work. - **Input type.** One of four, and they need different reading: | Type | What it gives you | What is missing | |---|---|---| | A raw log or telemetry sample | Real field names and value formats from the environment. The most valuable input there is | The adversarial framing, and usually the wider chain | | Report prose with embedded artifacts | Command lines, paths, the intrusion narrative | The telemetry's own field names | | A behavior description | The behavior, stated plainly | Everything concrete | | **Vendor or tool documentation** | The tool's complete, authoritative parameter set and its documented defaults | **The adversarial behavior, and which parameters matter** | - **Documented-tool inputs invert the usual work.** This skill's default reading — outcome language on top, observable underneath — assumes the source is describing an intrusion. Vendor documentation for a legitimate tool describes no intrusion at all. Microsoft's page for `Get-AppLockerPolicy` documents a supported administrative cmdlet, and nothing on it is malicious. So when the input is documentation, name two things explicitly before going further, because neither is stated in the source and a run that skips them drafts a rule on the tool's name alone: 1. **The misuse is the adversarial behavior.** Take it from the user's framing of why they are asking — "adversaries are using PowerShell to enumerate AppLocker policies" is the behavior; the documentation is only the parameter reference for it. Where the user gave no framing, ask for it at Stage 2 rather than inventing an adversarial use for a documented tool. 2. **The documented parameters are the detection anchors.** A cmdlet, API or CLI tool's documented flags are its most durable discriminators, because they are attacker-chosen, they survive as an argument pattern through renaming and recompilation, and the vendor has already enumerated all of them for you. `-Effective`, `-Ldap` and `-Local` are not trivia in the reference table; they are the rule's discriminator, and a rule matching only the cmdlet name has thrown away the strongest signal the input contained. Read the parameter list as the detection surface it is. State both in the read-back. A documented-tool draft that never names the misuse it is detecting, or that anchors only on the tool's name, has failed this stage regardless of what the YAML looks like. - **Default State Analysis — required, every input type.** State what the tool or behavior does when **no arguments are supplied**, and whether that default is in scope. This is a one-line answer and skipping it is how a rule ends up blind to the most common invocation of the behavior it was written for. `Get-AppLockerPolicy` is the worked example: run with no parameters it returns the **local** policy, so the bare `Get-AppLockerPolicy` with no flags is a real enumeration event. A rule requiring one of `-Effective`, `-Ldap` or `-Local` misses it entirely — and that gap is present in the community rule for this cmdlet, which is otherwise more resilient than most. The same shape recurs everywhere: `whoami` with no flags, `net user` with no arguments, `reg query` on a bare key. Write the answer as one of three, and carry it into the note: - **Default is in scope** → the flags cannot be required by the condition. Take one of the two constructions below; do not simply leave the flag selection defined and unreferenced. - **Default is out of scope** → say why, and requiring the flags is then legitimate narrowing with `condition: all of selection_*`. - **No meaningful default** → the tool refuses to run without arguments. Say so and move on. **The two legal constructions when the default is in scope**, both verified against sigma-cli 3.1.0: | Construction | Shape | When | |---|---|---| | **Drop the flags from the rule** | `condition: selection_anchor and selection_invariant`, with the documented flags recorded in the note as an escalation and triage aid rather than as YAML | One rule is wanted, and the bare invocation matters as much as the flagged one | | **Sibling pair** | A hunting rule at `level: informational` with no flags required, plus a narrower rule requiring them at a higher level, linked with `related:` and `type: similar` | Both the broad hunt and a tunable higher-severity alert are wanted. Counts as one entry against the Stage 3 cap of three, being one detection | **What is not legal: defining `selection_discriminator` and leaving the condition not referencing it.** It reads as a deliberate "available but not required" and it is a `DanglingDetectionIssue` at HIGH severity — *"Rule defines detection that is not referenced from condition"* — so `sigma check` reports `Check failure` and the rule fails this skill's own Stage 6 gate. Verified: the same rule passes with 0 issues both with the flag selection deleted and with `condition: all of selection_*`. Every selection you define, the condition references. This interacts directly with the Stage 4 ledger: "the operator would use a flag" is an `INFERRED` narrowing, and `INFERRED` conditions may not narrow the rule. - **Observable behaviors.** Threat reports are written in the language of outcomes, and detections need the language of telemetry. "Established persistence" is a conclusion, and the observable underneath it is a Run key value set, a scheduled task created, a service installed, or a WMI subscription registered. Work down to what would have been written to a log. - **Atomicity.** A single paragraph routinely bundles initial access, execution, and persistence. That is three rules. - **Telemetry reality check.** Cross-reference each candidate log source against the profile. If the behavior lands in telemetry the team does not collect, say so now. **When a source URL cannot be retrieved, stop and say so.** Bot protection, an auth wall, a paywall and a dead link are four different problems with four different fixes, so name which one you hit rather than reporting a generic failure. Then name exactly what would unblock it: the report text pasted in, a sandbox report, a raw telemetry export, or the sample's own analysis page. **Never draft from your own recollection of the campaign or malware family.** A fetch failure is a missing-input condition, not a licence to fill in from memory — that is `<never_fabricate>` applied to the input rather than to a field name, and it produces the same result, which is a confident rule about a campaign that may not work the way you remember. If the analyst supplies data from a different source than the one originally cited, `references` records what was actually used, not what was originally asked about. State the read-back in a few sentences before asking anything: what came in, which behaviors you extracted, which logsources they map to, the default-state answer, and what you cannot infer. Where the input was documentation, the read-back also names the misuse being detected and the parameters you are treating as anchors. Give the analyst the chance to correct you before you have written a line of YAML. Running unattended, put the read-back at the top of the package summary instead, so a returning analyst can see what you understood the report to say before they read a single rule. ## Stage 2: Fill the gaps Ask only what the profile and the input cannot answer, and cap it at three questions. In practice this is usually the source URL for the `references` field, an ambiguity about which variant of a behavior to target, or whether a specific internal tool would collide with the detection. **Three is a ceiling, not a target, and it is also not permission to ask none.** Runs that work the stages one at a time reliably ask their questions; runs that go end to end in a single pass reliably skip them, which is a property of the run's momentum rather than of the input having become clearer. So make this an explicit checkpoint even mid-flow: name the ambiguities you found, and either ask them or state why each one is safe to default. Where the input is tool documentation with no adversarial framing supplied, that framing is a question you must ask rather than default, because inventing an adversarial use for a documented administrative tool is fabrication about the threat rather than about a field name. Where a question goes unanswered, proceed on a documented assumption rather than blocking, and record every assumption in the validation note so testing can confirm or correct it. ## Stage 3: Scope and set the abstraction level Decide how many rules the input needs and, for each, how far up the abstraction ladder to stand. This is the most consequential decision in the whole skill, and `references/rule-quality.md` covers it properly. - **One behavior per rule.** A compound rule cannot be tuned, because suppressing the noisy half suppresses the useful half, and its false positives cannot be attributed. - **Pick the abstraction deliberately.** Hashes, single IPs, and exact domains belong in indicator matching rather than in a Sigma rule, because they will be dead within weeks. Argument patterns and parent-child relationships survive recompilation and renaming, and they are specific enough to tune. Record the choice with an `stp.N` tag. - **Lay the rule out in three layers, one selection each.** Decide the layers here, before any YAML, because the abstraction level and the layout are the same decision seen from two sides: | Layer | What it holds | Example | |---|---|---| | **Anchor** | The binary or process the behavior cannot happen without | `Image\|endswith: '\powershell.exe'`, plus its `OriginalFileName` | | **Invariant** | The cmdlet, API or syntax the technique cannot function without | `CommandLine\|contains: 'Get-AppLockerPolicy'` | | **Discriminator** | The attacker-controlled arguments that make it worth alerting on | the documented flags, with `\|windash` where the target is not Splunk | Three named selections beat one merged block for a reason that shows up in month two rather than on the page: **the analyst can suppress one layer without losing the others.** A single fused selection forces a choice between the whole cmdlet and nothing, so the noisy flag takes the useful invariant down with it. Keep them separate even when the condition is `all of selection_*`, so that tuning has something to grip. **Separate selections, all of them referenced by the condition.** Layering is not a way to park a selection the rule does not use: an unreferenced identifier is a `DanglingDetectionIssue` at HIGH severity and fails `sigma check`. Where a layer is genuinely absent — no discriminator exists, or the default state puts the bare invocation in scope — the layer comes *out* of the YAML and into the note, or becomes a sibling rule. Stage 1's default-state table has the two legal shapes, and Stage 4 has the hunting-query fallback for a rule with no discriminator at all. - **Prefer generic logsources.** `category: process_creation` with `product: windows` converts against Sysmon, native 4688 auditing, Defender XDR, and CrowdStrike. `service: sysmon` with `EventID: 1` binds the rule to one sensor. - **Flag aggregate-only behaviors.** If a single event is not suspicious on its own, for example ten failed logons or a spray of DNS queries, say that a Sigma correlation rule is the right shape and offer to draft the base rule plus the correlation. Do not silently write a single-event rule that will either miss the behavior or flood the queue. A correlation and its base rules count as one entry against the cap below, not two or three, since they are one detection. - **Cap the set at three.** Fully draft the three most load-bearing behaviors and list the rest under "Further rule candidates" with one line of rationale each, so the analyst can prioritize follow-ups rather than receiving twelve half-considered rules. "Most load-bearing" needs a method, otherwise two analysts pick different threes from the same report. Rank the candidate behaviors on four things, in this order: 1. **Telemetry.** Behaviors landing in log sources the profile marks as collected beat behaviors that need telemetry the team does not have. A rule nobody can run scores zero regardless of how elegant it is. **Where this gate excludes a behaviour the source rates as its most significant, say so explicitly in the package summary and draft it anyway as a marked extra. It sits outside the cap of three, not inside it** — the cap governs how many deployable rules you draft, and an undeployable rule shipped as evidence of a telemetry gap is a different artifact. Label it in the filename or the title, keep it in its own converted-query file, and say in the note that it cannot run on this estate today and what would have to be collected for it to.** The template's defaults assume Sysmon process creation, the Windows Security channel, DNS and proxy, and nothing else — enough to push a `registry_set` behaviour out of the drafted three even when the report holds it at DEFINITE confidence and calls it the campaign's most distinctive artifact. Demoting it is the right call; letting it disappear quietly is not, because a CTI team that reads a report's headline finding and then does not see a rule for it loses confidence fast. 2. **Durability.** Higher on the abstraction ladder beats lower. A rule on the invariant behavior survives the actor's next build, and one on this campaign's filenames does not. 3. **Chain position and blast radius.** Behaviors that sit at a chokepoint the actor cannot skip beat optional ones, and behaviors touching the systems the profile names as crown jewels beat behaviors on general workstations. 4. **Standing intelligence requirements.** Where the profile lists current requirements, behaviors relevant to them go first, because that is what the team is actually funded to detect. **Telemetry is a gate, not a score.** A behaviour landing in telemetry the profile says is absent cannot occupy one of the three, however well it scores on everything else — a rule nobody can run is not a rule. Screen on telemetry first, then **score the survivors 0 to 3 on the remaining three criteria and sum. Highest sum wins. Ties break toward the earlier criterion, so Durability beats Chain position beats Standing requirements.** Scoring telemetry alongside the others lets a zero-telemetry behaviour win a slot on the strength of durability and chain position, which is how a package ends up with a rule the team cannot deploy sitting where a runnable one should be. Gate first, then score. Without a stated tie-break the criteria are a preference order rather than a method, and two runs over the same report can pick different threes, which is the exact problem this ranking exists to solve. State the ranking and the scores in one or two lines so the analyst can disagree with it. ## Stage 4: Draft, metadata first ### Stage 4a: the evidence ledger, before any YAML No validator finds this failure. A rule drafted from a report on Winlogon `Shell` persistence shipped this: ```yaml selection_discriminator: # Legitimate value is exactly "explorer.exe". Anything else, including # "explorer.exe,<payload>", is the malicious pattern. Details|contains: '.exe' ``` The report said the malware modifies `HKCU\...\Winlogon\Shell`. It never said the modified value contains `.exe`, nor that the malicious format is `explorer.exe,<payload>`. That came from general Windows knowledge and was presented as though it came from the source — and it is wrong in the direction that costs coverage: if the hypothesis is "Shell was changed from `explorer.exe`", requiring `.exe` misses `.dll` values, extensionless values, and `cmd /c C:\malicious\payload`. An unsourced assumption narrowed the rule past the behaviour it was written for, and the confident comment beside it made that look deliberate. So before writing any YAML, label every non-trivial condition. Three labels, and only three: | Label | Means | What it must carry | |---|---|---| | `SOURCED` | A quote or close paraphrase from the input | The locator — page, section, the command line, the log field | | `GENERIC` | A documented platform default or a tool's documented invariant syntax, e.g. that the default value of Winlogon `Shell` is `explorer.exe` | A citation, not an assertion. Name the documentation, the field's own semantics, or the entry in `sigma-spec.md`. "Windows default, documented behaviour" qualifies; "commonly known" does not | | `INFERRED` | Your own inference from the source | Nothing — see the constraint below | **An `INFERRED` condition may not narrow the rule.** It either goes in as a broadening alternative, or it comes out and becomes a tuning question in the validation note. That single constraint is what would have caught `Details|contains: '.exe'`: the inference was reasonable, and reasonable inferences that tighten a match are exactly how a rule ends up detecting nothing while looking careful. **And `GENERIC` is not the escape hatch from that.** The label only earns its exemption if the citation is real — if you cannot name what documents it, the condition is `INFERRED` wearing a better coat, and it gets the `INFERRED` treatment. The test is whether someone could look it up and disagree with you. `schtasks.exe` requiring `/create` to register a task is checkable and