Cyber Security Academy · Lesson

Detection-as-Code Principles

Treating detections like software.

Detection-as-Code Principles is a free Cyber Security Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Cyber Security Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Detection-as-Code

Detection-as-Code (DaC) applies software engineering discipline to security detections. Instead of analysts hand-editing rules inside a SIEM console, detections live as text files in version control and ship through a pipeline.

The benefits are concrete:

Reviewable changes via pull requests
Reproducible deployments across environments
Testable logic before it reaches production
Auditable history of who changed what and why

A detection becomes an artifact you can diff, roll back, and reason about like any other code.

Detections as Versioned Files

Each detection is stored as a standalone file, typically YAML or a vendor query language, committed to a Git repository. The repository layout mirrors how you organize your coverage.

A common structure separates rules by platform and tactic:

detections/
  windows/
    credential_access/
      lsass_memory_dump.yml
    execution/
      suspicious_powershell.yml
  cloud/
    aws/
      root_account_usage.yml
tests/
  windows/
    lsass_memory_dump_test.yml

Pull Request Review

Every new or modified detection flows through a pull request. A second engineer reviews the logic, false-positive risk, and ATT&CK mapping before it merges.

Reviewers ask:

Does the logic match the described threat?
What legitimate activity could trigger this?
Is the severity and ATT&CK reference correct?
Are there tests covering true and false positives?

This catches mistakes that a lone analyst editing the SIEM at 2 a.m. would miss.

CI Validation

A continuous integration pipeline runs automatically on each push. It enforces quality gates before a rule can merge.

Typical CI stages for a Sigma-based repo:

# .github/workflows/validate.yml (excerpt)
steps:
  - name: Lint Sigma syntax
    run: sigma check ./detections
  - name: Validate against schema
    run: sigma check --validators all ./detections
  - name: Run unit tests
    run: pytest tests/

Automated Deployment

Once merged, a deployment job converts the portable rules into the target query language and pushes them to the SIEM or EDR via API.

For Sigma you typically run a converter such as sigma convert with a backend that matches your platform (Splunk, Elastic, Microsoft Sentinel). The pipeline then uploads the generated saved searches or analytic rules.

No human pastes queries into a console. The deployed state always matches what is in main.

sigma convert -t splunk -p splunk_windows \
  detections/windows/execution/suspicious_powershell.yml

Testing Detections

A detection without tests is a guess. DaC pairs each rule with test data: log samples that should fire it (true positives) and benign samples that should not (false positives).

Tests run in CI, so a change that breaks coverage or reintroduces noise fails the build before merge. This is the single biggest source of confidence when refactoring rules at scale.

test:
  - log: { Image: 'C:\\Windows\\System32\\rundll32.exe', CommandLine: 'rundll32 javascript:...' }
    expected: match
  - log: { Image: 'C:\\Windows\\System32\\rundll32.exe', CommandLine: 'rundll32 shell32.dll,Control_RunDLL' }
    expected: no_match

Rule Metadata and Lifecycle

Treat metadata as first-class. Each detection records its status as it matures through the lifecycle:

experimental — newly written, monitored closely
test — running but not yet trusted for alerting
stable — proven, low false-positive rate
deprecated — superseded or retired

Tracking status in the file lets you promote, demote, and retire rules deliberately rather than letting stale logic linger in production.

Portability Across Backends

A core DaC win is writing detection logic once in a vendor-neutral format, then compiling it to many backends. Sigma is the de facto standard for log-based detections.

The same rule file can target Splunk SPL, Elastic Lucene/EQL, Microsoft Sentinel KQL, and others through pipeline-specific field mappings. You avoid rewriting the same idea five times and you avoid lock-in.

sigma convert -t elasticsearch rule.yml
sigma convert -t microsoft365defender rule.yml
sigma convert -t splunk rule.yml

Field Mapping Pipelines

Different log sources name the same data differently. A Sysmon process-creation event uses Image; a Windows Security log may use NewProcessName. Processing pipelines bridge that gap.

Pipelines transform generic Sigma field names into the exact fields your data uses, so one logical rule maps cleanly onto whatever schema your SIEM ingests. Maintaining pipelines centrally means a schema change is fixed once, not per rule.

sigma convert -t splunk -p sysmon rule.yml

Environments and Promotion

Like application code, detections move through environments before reaching production. A typical flow is dev to staging to prod.

Dev — author and run unit tests in CI
Staging — deploy against a copy of real telemetry in audit mode
Prod — promote once false-positive rate is acceptable

Promotion is a deliberate, reviewed step tied to the rule's lifecycle status, not an accident of merging. This staged rollout mirrors the alert-then-block discipline used with inline detections.

Coverage and Metrics

Because detections are code, you can measure coverage programmatically. Tie each rule to MITRE ATT&CK techniques and generate a heatmap of what you do and do not cover.

Useful metrics to track over time:

Techniques covered vs. total in your threat model
False-positive rate per rule
Mean time from rule idea to production
Number of rules in each lifecycle status

These numbers turn detection engineering from anecdote into a managed program.

Quick Check

Test your understanding of Detection-as-Code fundamentals.

Recap

Detection-as-Code brings software engineering rigor to detections:

Rules live as versioned files in Git
Changes go through pull request review
CI lints, validates, and runs tests automatically
Merged rules deploy via pipeline, keeping prod in sync with main
Tests guard against false positives and regressions
Portability (Sigma + pipelines) lets one rule target many backends
Metadata, lifecycle, and metrics make detection a managed program

Next, you will write the portable rules themselves with Sigma.

Frequently asked questions

Is the “Detection-as-Code Principles” lesson free?

Yes — the full text of “Detection-as-Code Principles” is free to read here on the web, and the Cyber Security Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Cyber Security Academy course, upgrade to CoddyKit PRO.

What will I learn in “Detection-as-Code Principles”?

Treating detections like software. You practise Cyber Security Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Cyber Security Academy?

No prior experience is required. Cyber Security Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Detection-as-Code Principles” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Cyber Security Academy lesson?

Yes. Every Cyber Security Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Cyber Security Academy