Why readability matters
When a pipeline decides which security events reach your SIEM, its rules decide what your analysts can see. That is a serious responsibility to hand to a black box. If the logic lives in a compiled binary or a vendor console you cannot inspect, nobody in your organisation can answer the simplest question an auditor will ask: why was this event not indexed?
Our view is that a rule should be a plain text file that states what it matches and what class it assigns. Anyone with access can open it, read it and change it. But readability alone is not enough. A rule you can change but cannot test is the most dangerous kind, because it invites edits nobody can verify.
Order is part of the rule
In a chain of rules, precedence matters as much as content. A rule that runs later overrules one that ran earlier, so the order the pipeline wires files together is itself a decision. We make that order deliberate and visible, and we do not let it depend on how filenames happen to sort. Reading the chain from top to bottom should be reading what actually happens to an event.
One gate deserves special mention. The stage that drops events should only ever see an event that an earlier rule has already moved off the default of keep. That way nothing is dropped by omission: an event has to be named as low value and then named again as noise before it can be discarded.
Cases and near misses
Every rule gets a case: a real log line that should hit it. That proves the rule fires. But the more important artefact is the near miss: a log line that looks similar and must not hit the rule. Near misses exist because a rule that catches too much is the failure nobody notices. A missed detection eventually shows up as a gap; an over-broad drop rule quietly removes evidence for months.
The whole catalogue of cases is run on every change, and each case must reach the rule it claims and no other. A case that lands on a different rule fails the build. This is ordinary software testing applied to something that is too often treated as configuration.
A seven-step process
Each step below exists because changing a classification rule changes what a security team can see, and that has to be provable before it reaches a collector and reversible after.
- Write it: a plain text file stating what it matches and the class it assigns.
- Give it a case and a near miss: one log that must hit it, one that must not.
- Prove it reaches that rule and no other, across the entire catalogue.
- Ask the engine: have the pipeline software itself validate the configuration, because reading a file and asking the engine are not the same act.
- Replay it against last week's raw archive and report every event whose verdict moved, with the volume it adds to or removes from the indexer.
- Push it as a versioned configuration pack, and have the collector prove itself by testing its outputs rather than reporting that a file was written.
- Keep it reversible: the previous pack stays available, every change is in the audit trail, and the raw archive is untouched.
Cross-checking with the people who know
Rules should not be written in isolation. The best practice we know is to go through every event identifier with the security operations team in a shared workbook, so each case carries two verdicts: what the chain produces and what the analysts expect. Where they differ, the divergence is recorded openly and resolved, not smoothed over.
This produces something valuable beyond the pipeline itself: a written, reviewable record of why each class of event is handled the way it is. When the team changes, or an auditor arrives, the reasoning is still there. That record is part of what we hand over, alongside the rules themselves.
What this buys you
The practical outcome is confidence. Analysts can propose a change and see its effect on real traffic before anyone is affected. Engineers can deploy without opening an SSH session. Managers can show an auditor exactly why a category of event goes to the archive rather than the indexer. And if a change turns out to be wrong, it costs a reload, not a reconstruction.