sigma-cli: a saved query needs its pipeline in the header

The query text is not the whole artifact

sigma convert prints a query in the target language. The words of the query do not include the rule’s UUID, the backend name, or the pipeline files unless you put them there. A saved search with no header is an orphan: it may be correct, and you cannot show which rule it came from.

Two rules can emit similar searches. Without the id in the header, a count of hits cannot be filed against one of them. The count belongs to the text that ran, not automatically to a YAML file you assume.

What the header should carry

Put the rule id, the backend, the pipeline names in order, and the conversion time in comment lines at the top of the saved query. Those lines are part of the artifact you review. If CI stores the query, store the header with it. A later reader should not need the job log to know which pipelines were applied.

If the header and the job log disagree, cite both and do not pick one silently. The disagreement is the fact.

Snippet

# rule: 4c1e0a2b-7d44-4b1a-9c0e-lab000000001
# backend: splunk
# pipelines: splunk_windows, lab_fields
# converted: 2026-11-03T18:00:00Z
index=lab_sysmon process_path="*\\lab-agent.exe"

What to file with a count

File the rule id from the header, the pipelines, the time the query ran, and the hit count with its unit. If the header is missing, file “rule id not on this file” and do not name a rule. Do not reconstruct the id from memory or from a similar search in another folder.

Worked case: six hits and no rule id

A ticket attaches queries.spl and says the lab-agent rule returned 6 events. The file’s first line is the search. There is no comment, no UUID, and no pipeline list. A second rule in the repo searches the same process path with an extra term the file does not have.

The note says the file has no header, so the 6 events are the count for that search text only. They are not attributed to either YAML id. The count stays in the ticket as an unlabeled search. Attribution waits until the header, or the CI log that still has the convert command, is attached.

Snippet

file: queries.spl
header: absent
search text: present
hit count: 6 events
rule id: not on this file
write: unlabeled search, not the lab-agent rule

Diagram

A query file with and without a header

The search can run either way. Only one can be reviewed.

Header present

Names. Rule id, backend, pipelines, conversion time

A hit count. Can be filed against that rule id

Disagreement. Visible if the job log says something else

Header absent

Names. Only the search text

A hit count. Belongs to that text, not to a guessed rule

Disagreement. You cannot see it, because the pipelines are unstated

Check yourself

1. A saved query has no comment header. What can you say about a hit count?

2. Which lines make a converted query reviewable later?

3. The job log’s pipeline list differs from the header. What do you do?