Why Detection-as-Code — From Ad-Hoc to Engineering Discipline

The detection engineering discipline is young enough that many organizations still manage rules the way developers managed code in the 1990s: stored locally, deployed manually, changed without review, and lost when the engineer leaves. Detection-as-code applies the lessons software engineering learned over 30 years to the problem of managing detection rules.

The Problems with Ad-Hoc Rule Management

Problem 1: No history

Scenario: A rule that was suppressing a known FP starts generating alerts again.
"Why did this change?" → nobody knows
"Who added the FP exclusion?" → no record
"What did the rule look like before?" → you'd have to find a backup SIEM snapshot

With DaC: git log --follow rules/lsass-dump.yml
→ Shows every change, who made it, when, and the PR description explaining why

Problem 2: No rollback

Scenario: A rule update caused 10,000 alerts to fire in 30 minutes (logic error)
"How do we revert to the working version?" → manual: find the old rule somewhere, paste it back
→ Takes 30–60 minutes of scrambling

With DaC: git revert <commit-hash>
→ PR auto-reverts the change, CI validates the revert, pipeline deploys old version
→ 5–10 minutes

Problem 3: No review

Scenario: An engineer adds an exclusion for a path that was recently used by a threat actor
(the engineer doesn't know about the threat intel yet)
"Would a second set of eyes have caught this?" → unknown — no review process
→ The rule now has a live blind spot with no documentation

With DaC: PR requires approval from a second engineer with threat intel context
→ Reviewer catches the conflict and blocks the merge

Problem 4: Lost context

Scenario: Original rule author leaves the company
"Why does this exclusion exist?" → nobody knows
"Is this exclusion still valid?" → nobody knows
"Can we remove it?" → nobody knows

With DaC: PR description + ADS document + commit messages tell the complete story
→ Any engineer can reconstruct the reasoning from the repository history

The Detection-as-Code Workflow

Author writes/modifies rule
         │
         ▼
    git commit + push branch
         │
         ▼
    Open Pull Request
         │
         ├─ Automated CI runs:
         │   ├─ sigma check (YAML syntax valid)
         │   ├─ sigma convert (conversion succeeds)
         │   ├─ Unit test (query produces correct output)
         │   └─ Regression test (known-FP samples don't fire)
         │
         ├─ Peer review (required before merge)
         │   ├─ Rule logic correct?
         │   ├─ Exclusions appropriate?
         │   ├─ ADS document updated?
         │   └─ TP test included?
         │
         ▼
    Merge to main
         │
         ▼
    CI/CD deploys to dev → staging → prod
         │
         ▼
    Production SIEM updated

This workflow guarantees: every production rule was reviewed, every production rule passed automated tests, every production change has an audit trail.

Detection-as-Code vs Software Engineering

Detection-as-code borrows directly from software engineering practices:

Software Engineering	Detection Engineering
`git commit` / PR	Rule change PR
Unit test	Rule logic test against sample events
Integration test	Rule test against real SIEM with TP sample data
Linting (`eslint`, `black`)	`sigma check`
CI/CD pipeline	Convert → test → deploy pipeline
Feature flags	Rule status (experimental → test → stable)
SLO / error budget	Precision target / alert volume budget
Code review	Detection rule peer review

The key difference: in software, a bad deploy breaks a feature. In detection engineering, a bad deploy either floods the SOC with noise (breaking analyst capacity) or suppresses alerts (creating blind spots). Both failures are operationally serious.

The Policy Foundation

Detection-as-code requires policy backing to be effective:

No direct SIEM changes: all changes via the repository PR process
All rules in version control: no “shadow” rules maintained outside the repo
CI must pass before merge: no bypassing the automated tests
At least one peer reviewer: PR requires approval before deployment
ADS document required: every new rule must have an accompanying ADS doc in the same PR

Without policy enforcement, individual engineers bypass the process “just this once” during incidents, accumulating exceptions that erode the practice.

Elastic detection-rules— GitHub panther-analysis— GitHub

Retrieval Practice

Your detection program currently has 300 rules managed directly in the Splunk UI. You want to migrate to detection-as-code. What are the three most important things to do in the first two weeks, before automating the CI/CD pipeline?

Reveal answer

(1) Export all rules to Sigma YAML (or at least native SIEM format) and commit them to a git repository. This gives you version control history going forward and a recoverable baseline even before CI is built. (2) Establish the 'no direct SIEM changes' policy and communicate it to all engineers. Without this cultural change, the migration fails — engineers will continue editing in the SIEM UI because it's faster. (3) Document the current state: for each rule, record its current status (what it was testing, known FP sources, last modified). Even a basic CSV is better than nothing — this context becomes the foundation for ADS documents. CI/CD automation comes in week 3+, after the repository structure is established and the team is accustomed to using git for rule changes.

Retrieval Practice

A junior detection engineer pushes a rule directly to the production SIEM during an incident because 'the PR process was too slow.' The rule had a logic error and generated 5,000 alerts in 2 hours. How should the team respond, and what process change should come out of the post-incident review?

Reveal answer

Immediate response: revert the rule using the detection-as-code process (even if the deploy was done manually, the revert should go through the pipeline to establish the pattern). Restore the previous version. Triage the 5,000 alerts to determine if any were TPs that need investigation. Post-incident process change: establish a 'fast-track PR' process for incidents — a second engineer can approve a PR in 5 minutes during an incident without full review. The 5-minute review catches logic errors; a 0-minute review (direct deploy) does not. The process should never require choosing between speed and safety — make the safe path fast enough to use in incidents. Also: add a CI check that detects direct SIEM deploys and alerts the team when a rule in production doesn't match any commit in the repository.