> For the complete documentation index, see [llms.txt](https://0xzoro.gitbook.io/0xzoro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://0xzoro.gitbook.io/0xzoro/soc-operations/detection-engineering/00-course-reference.md). # 00 course reference *The map of the whole course, the real technology stack, and — most importantly — the actual detection-as-code architecture every module builds toward. Read this once before Part 1, and return to it whenever a later module feels like an isolated task; almost everything in this course is one moving part of the single pipeline described here.* > **Course:** [Detection Engineering for Beginners](https://tcm-sec.com/academy/detection-engineering-for-beginners/) — TCM Security\ > **Instructor:** Anthony Isherwood — Lead Detection Engineer (OSCP, GREM); background in IR, SIEM engineering, and SOC coaching.\ > **Reference implementation:** the instructor's public repo, [isherwood-sec/detection-engineering](https://github.com/isherwood-sec/detection-engineering) (course fork: [Roka-5/tcm\_detection-engineering\_course](https://github.com/Roka-5/tcm_detection-engineering_course)). Every TOML schema, Python script, and workflow referenced in these notes is taken from that repo directly. *** ## What this course actually is Most "detection" training teaches you to click around a SIEM and save queries. This course teaches something narrower and more durable: **how to run detections as version-controlled code**, with the same discipline software engineers apply to source — validated on commit, deployed by automation, and measured continuously. The mental model to hold from the very first module: you are not building 10 clever queries. You are building **one pipeline** that happens to carry 10 detections today and could carry 500 tomorrow without changing shape. {% hint style="info" %} **Think of it as** a factory, not a workshop. A workshop hand-crafts one item at a time; a factory builds the *line* that produces items repeatably. The queries are the cargo; the pipeline is the skill. If you ever lose the thread of why a module matters, ask which part of the line it's building. {% endhint %} ``` Attack (lab) → Telemetry (Elastic) → Detection authored as TOML → Git commit │ ┌─────────────────────────────────────────────────┘ ▼ GitHub Actions ├── validate TOML schema + MITRE mapping (fail the commit if broken) ├── sync valid rules into Elastic (deploy automatically) └── regenerate metrics (CSV / MD / Navigator) weekly │ ▼ Detection program you can measure and prove ``` This is the spine. The rest of this document walks each part of it. *** ## The technology stack — and *why* each piece The course deliberately uses free/trial tooling that mirrors a real detection engineering shop. Each tool earns its place by covering one link in the pipeline above. | Tool | Role in the pipeline | Why this one | | ------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **VirtualBox** | Hosts the lab (Windows 11 victim, ParrotOS attacker, Ubuntu for Elastic) | Free, snapshot-capable — snapshots let you re-run an attack from a clean state, which is what makes tests *repeatable* | | **Elastic** (Elasticsearch + Kibana) | The SIEM: stores telemetry, runs the detection queries, raises alerts | Free trial; its detection rules are expressible as data (TOML → API), which is what makes detection-as-code possible at all | | **Sysmon** | Rich Windows endpoint telemetry (process creation, command lines, file writes) | Default Windows logs don't show command lines or parent processes; Sysmon does — and command lines are where most of these detections live | | **Zeek** | Network telemetry (FTP, HTTP, connection metadata) | Endpoint logs can't see exfil-over-the-wire; Zeek gives the network-side detections (FTP exfil, web scanning) | | **Atomic Red Team** | Repeatable, per-ATT\&CK-technique attack procedures | Turns "I ran something once" into a defined test with an ID — the backbone of *Validation & Testing* | | **Python** | Glue: validates TOML, maps MITRE, pushes rules to the Elastic API, generates metrics | Detection-as-code needs code; Python is the automation layer between the files and the SIEM | | **TOML** | The on-disk format for each detection | Human-readable, diff-friendly in git, trivially parsed by Python (`tomllib`) — a rule becomes a reviewable text file | | **GitHub + Actions** | Source of truth + CI/CD engine | Git gives history and review; Actions runs validation/sync/metrics automatically on every push | | **MITRE ATT\&CK** | The coverage framework every detection maps to | Gives a shared vocabulary and a way to answer "what can't we detect yet" | The through-line: **every tool exists to serve one stage of `attack → telemetry → rule → validate → deploy → measure`.** If you ever lose track of why you're configuring something, locate it on that line. *** ## Course map (real curriculum → these notes) The course's own module order, mapped to the five note files. Your folder layout collapses Intro + Theory + Lab Setup into Part 1, which matches how the notes are organised. | Course module | Key lessons | Notes file | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | **Introduction** | Welcome / orientation | Part 1 | | **Theory** | Security Operations · Role Variety · SIEM · **The Detection Engineering Workflow** · **What Makes a Good Detection** · Technology Stack · **MITRE ATT\&CK** · Navigating the ATT\&CK Matrix | Part 1 | | **Lab Setup** | VirtualBox import (ParrotOS / Win11 / Ubuntu) · VM snapshots · disabling Defender · installing Zeek | Part 1 | | **Elastic Setup** | Elastic overview · trial signup · Elastic Agent install · confirming Zeek/Sysmon logging · improving PowerShell visibility | Part 2 | | **Attack Scenarios 1–3** | Three progressively harder attacks; author a detection for each | Part 3 | | **Atomic Red Team** | Install · running atomics · writing your own | Part 3 | | **TOML** | Validation · Elastic rule templates · MITRE objects · managing many rule files | Part 4 | | **Elastic API** | API keys · pushing/updating rules programmatically · custom detection workflow | Part 5 | | **GitHub** | Actions · uploading detections · TOML validation in CI · Elastic sync | Part 5 | | **Metrics** | TOML → CSV/MD/JSON · Actions integration · status badges | Part 5 | | **Conclusion** | Wrap-up | Part 5 | *** ## The real detection-document schema This is the single most important correction to make early, because it defines *"what a detection is"* for the rest of the course. A detection here is not a paragraph of documentation — it's a **TOML file with a schema that `validation.py` enforces on every commit.** If a required field is missing, CI fails and the rule never reaches Elastic. A complete rule looks like this (real example, `msfvenom_powershell_payload.toml`): ```toml [metadata] creation_date = "2023/10/11" [rule] author = ["Anthony Isherwood"] description = "This alert triggers via sysmon data on a string of text that occurs out of the box with msfvenom." from = "now-6m" name = "Potential MSF PowerShell Payload Observed" risk_score = 50 severity = "high" type = "query" rule_id = "00000000-0000-0000-0000-000000000005" query = ''' process.command_line: "\"cmd.exe\"" and message : "*powershell -w hidden -nop -c $a='*" ''' [[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/" ``` ### Required fields, by rule type Straight from `validation.py` — these are the fields CI refuses to let you skip: | Rule `type` | Required fields | | ----------- | --------------------------------------------------------------------------- | | `query` | `description`, `name`, `rule_id`, `risk_score`, `severity`, `type`, `query` | | `eql` | above **+** `language` | | `threshold` | above **+** `threshold` | Plus `metadata.creation_date` (checked separately), and for the Elastic *sync* step, `author` and `threat` become required too (`update_alert.py`). ### What this tells you about the course's mindset * **"A good detection" is defined by a schema, not by prose.** The theory lesson *"What Makes a Good Detection"* becomes concrete here: it's a rule that (a) fires on real telemetry you've validated, (b) carries a risk score and severity, and (c) is mapped to MITRE. That's the bar. * **The lavish documentation template in earlier drafts of these notes (investigation guidance, tuning history, FP catalogue) is *****beyond***** this course.** It's good practice in a mature enterprise program, and worth keeping as an aspiration — but it is explicitly not what this course enforces. Where these notes show that richer template, it's now labelled as an enterprise extension, not the course standard. * **`rule_id` is a stable UUID.** It's how the sync script knows whether to *create* or *update* a rule in Elastic. This is the detail that makes the git repo the source of truth: change the TOML, and the same rule updates in place rather than duplicating. *** ## The detection library (the real 10) These are the actual detections in the repo — the concrete output of the three attack scenarios. Studying them is the fastest way to internalise the course's detection *style*: short KQL-style queries against specific Elastic datasets, each mapped to one or two ATT\&CK techniques. Note how many live entirely in `process.command_line` — command-line visibility (via Sysmon) is where the endpoint detections are won. | Detection (file) | What it catches | Telemetry / dataset | Severity | ATT\&CK | | -------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------- | -------- | -------------- | | `msfvenom_powershell_payload` | msfvenom's default PowerShell stager string | Sysmon `message`, `process.command_line` | high | T1059.001 | | `powershell_invokewebrequest_downloading_bat` | PowerShell pulling a `.bat` via Invoke-WebRequest | Sysmon `process.command_line` | medium | T1059.001 | | `powershell_exec_via_bat` | PowerShell launched from a `.bat` file | Sysmon process data | medium | T1059.001 | | `data_archive_for_exfil` | `.zip` created under `Windows\Temp` by PowerShell | `endpoint.events.file` | medium | T1074.001 | | `suspicious_file_written_to_tmp` | Specific files / extensions dropped in `Windows\Temp` | `endpoint.events.file` | high | T1082, T1217 | | `suspicious_file_added_to_registry` | Persistence via a registry run key | Sysmon registry data | — | Persistence | | `data_exfil_over_ftp` | `.zip` sent via FTP `STOR` | `zeek.ftp` | high | T1020 | | `data_archive_for_exfil` / `excessive_web_traffic` | Bulk/abnormal outbound web volume | Zeek HTTP | — | Exfiltration | | `bat_files_observed_in_http_on_unusual_port` | `.bat` served over HTTP on a non-standard port | Zeek HTTP | — | Delivery | | `web_scanner_activity_nmap_nikto` | Scanner signatures (nmap / nikto) | Zeek HTTP | — | Reconnaissance | Two things to notice about the *engineering* style, not the individual rules: 1. **The queries are deliberately specific — sometimes brittle on purpose.** `msfvenom` triggers on a literal default string. That's a fragile IOC-style detection an attacker could trivially change — and the course uses it *knowingly*, as a teaching contrast. Your job as you learn is to notice which of these would survive an attacker who changed one flag, and which wouldn't. (This is exactly the *Evasion & Bypass* lens from the notes standard.) 2. **Endpoint vs. network split is deliberate.** Sysmon/`endpoint.events.file` catch host-side execution and staging; Zeek catches the exfil and recon that never touches a monitored endpoint. Neither alone is sufficient — which is the *Detection* section's "log source coverage" point made concrete. *** ## The automation layer (Part 5, previewed) The `development/` Python scripts and `.github/workflows/` are the engine. You don't need to understand them in Part 1, but knowing they exist reframes everything before them: | Script | Job | Triggered by | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------- | | `validation.py` | Enforce the TOML schema; fail the build on missing fields | Every push (CI) | | `mitre.py` | Validate every ATT\&CK ID against MITRE's live CTI data; catch typos/deprecated techniques | Every push (CI) | | `update_alert.py` | Push changed rules into Elastic via the Detection Engine API (create or update by `rule_id`) | Push to `main` | | `toml_to_csv.py` / `toml_to_report.py` / `toml_to_navigator.py` | Generate metrics: a CSV, a latest-detections markdown, and an ATT\&CK Navigator layer | Weekly cron | The three workflows: * **`toml_mitre_validation.yml`** — runs `validation.py` + `mitre.py` on every push. This is the quality gate: a malformed or mis-mapped detection *cannot* merge. * **`elastic_sync.yml`** — on merge to `main`, diffs changed files and pushes them to Elastic. This is deployment-by-git-push. * **`metrics.yml`** — weekly, regenerates the metrics artifacts and commits them back, driving the repo's status badges. The payoff this whole architecture delivers, and the sentence to carry through the course: **you edit a text file and open a pull request; a robot validates it, deploys it to your SIEM, and updates your coverage metrics.** That loop — not any single query — is the thing the course is actually teaching. *** ## How to read the rest of these notes * **Part 1** covers the theory and the lifecycle mindset, plus lab setup. It's the "why." * **Parts 2–3** are hands-on: get telemetry flowing, run the attacks, write the detections. This is where the detection *style* above gets built. * **Parts 4–5** are the automation spine: TOML discipline, the Elastic API, and the GitHub Actions that turn a folder of files into a living detection program. Whenever a module feels like busywork (why am I learning TOML? why a Python script?), come back to the pipeline diagram at the top. Every task is one link in `attack → telemetry → rule → validate → deploy → measure`.