A detection engineering lab built around a repeatable workflow: observe behavior, capture telemetry, write a detection, test it, and tune the result.
The repository brings together a three-host AWS lab, Windows/Sysmon telemetry, a native Wazuh example, an Elastic query collection, and Python tools for validation and reporting.
| Component | What is here |
|---|---|
| AWS lab | Terraform for a Wazuh server, Windows target with Sysmon and a Wazuh agent, and Kali host |
| Detection collection | Ten TOML detections with Elastic/KQL queries and ATT&CK mappings |
| Native Wazuh rule | A Sysmon process-creation rule for PowerShell launched by a BAT file |
| Development tools | Schema and ATT&CK checks, report exports, and explicit Elastic API utilities |
| Metrics | Detection inventory and ATT&CK Navigator mappings |
| Theory | Security operations, detection lifecycle, and reference frameworks |
The TOML queries use Elastic field names and are not directly deployable as Wazuh XML. The AWS setup collects Windows/Sysmon events; Zeek and Elastic Endpoint telemetry used by other examples require their own sensors and ingestion. Detection prerequisites explain each dependency.
Use Python 3.11 or newer. These steps need no AWS account or SIEM credentials.
git clone https://github.com/TerminalsandCoffee/detection-engineering-lab.git
cd detection-engineering-lab
python -m venv .venvActivate the environment with .venv\Scripts\Activate.ps1 in Windows PowerShell or source .venv/bin/activate on macOS/Linux, then run:
python -m pip install -r requirements.txt
python development/validation.py
python -m unittest discover -s tests -v
python development/toml_to_json.py --dry-runTo check mappings against MITRE's published Enterprise ATT&CK data (network access required):
python development/mitre.pyGenerate the inventory and Navigator layer:
python development/toml_to_csv.py
python development/toml_to_navigator.pySee development usage for offline mapping checks, output options, and the optional Elastic upload commands.
Start with PowerShell execution via a BAT file. It has a corresponding Wazuh XML rule, which makes it a useful example for comparing query metadata with a native SIEM implementation.
- Review the telemetry prerequisites and expected behavior.
- Run the local tests against the synthetic event fixtures.
- Follow the setup guide to provision your own lab and confirm Sysmon events reach Wazuh.
- Run the container fixture tests, install the custom XML rule, and check the manager configuration before restarting it.
- Record the alert, a benign comparison, and any tuning decisions.
A valid file, correct ATT&CK mapping, or matching fixture is one piece of evidence. End-to-end coverage also depends on sensor configuration, event delivery, field mappings, rule loading, and the surrounding workload. The repository does not claim that all ten queries have been replayed against a live Elastic deployment.
detections/ TOML collection, native Wazuh rules, decoder examples
development/ Validators, Elastic utilities, report exporters
metrics/ Committed inventory and Navigator outputs
setup/terraform/ Canonical three-host AWS lab
setup/wazuh/tf-deployment/ Historical single-host prototype; see its README
theory/ Detection engineering reference material
tests/ Regression tests and synthetic fixtures
.github/workflows/ Validation workflows and historical integration paths
Rules preserve their original filenames, identifiers, creation dates, and author metadata. Use an existing TOML example as the schema reference:
[metadata]
creation_date = "2026/09/06"
[rule]
author = ["Your name"]
name = "Example PowerShell Process"
description = "Study example; tune and test against your process telemetry."
rule_id = "0ae618f8-a41b-4c72-a818-6c0b78fd386b"
risk_score = 50
severity = "medium"
type = "query"
language = "kuery"
query = 'process.name : "powershell.exe"'
[[rule.threat]]
framework = "MITRE ATT&CK"
[[rule.threat.technique]]
id = "T1059"
name = "Command and Scripting Interpreter"
reference = "https://attack.mitre.org/techniques/T1059/"
[[rule.threat.technique.subtechnique]]
id = "T1059.001"
name = "PowerShell"
reference = "https://attack.mitre.org/techniques/T1059/001/"
[rule.threat.tactic]
id = "TA0002"
name = "Execution"
reference = "https://attack.mitre.org/tactics/TA0002/"Generate a new UUID for a new rule. Choose the actual telemetry source, scope, language, and false-positive handling before deployment.
- Security Operations
- Detection Engineering Workflow
- Frameworks
- Setup and telemetry checks
- Development commands
- Valid TOML, required fields, unique UUIDs, and correctly typed scores and thresholds
- Valid ATT&CK identifiers, names, tactics, and sub-technique relationships
- Documented telemetry, field mappings, and query-language assumptions
- Positive, negative, and edge-case evidence from the intended engine
- A review of benign matches before operational use
Repository checks run without production credentials. Infrastructure provisioning and rule installation are explicit operator steps; pushing a rule does not run Terraform or upload it to a live SIEM. Historical integration filenames remain available for readers arriving from earlier walkthroughs.
For a cloud lab, begin with setup/README.md, inspect the Terraform plan, and verify the instances and telemetry after provisioning. AWS resources incur charges until removed; the setup guide includes teardown and cleanup checks.
Maintained by Rafael Martinez / Terminals & Coffee. The original TOML collection credits Anthony Isherwood in its author metadata; those credits are retained. This repository builds on that learning material with lab infrastructure, tooling, and Wazuh examples.
Earlier articles may show Elastic infrastructure or older deployment defaults. The repository name, existing file paths, and Git history are retained; the setup guide describes the current Wazuh-based environment.