Detection-as-Code: Lab Environment and Tooling Setup

This course runs on your own machine and your own GitHub account. The toolchain is open-source, cross-platform (macOS, Linux, Windows with WSL or native), and free. Install everything below before starting Module 1.

Required tools

The tools relate to each other in a clear dependency chain. Git manages the repository. Python runs sigma-cli and pySigma. sigma-cli validates and converts Sigma rules using pySigma backend plugins. GitHub Actions runs the CI workflow in the cloud, using the same sigma-cli and pySigma that you run locally. The code editor is where you write the rules and the YAML configurations.

Install bottom-left to top-right: Git and Python first, then sigma-cli and pySigma on top of Python. GitHub Actions runs the identical toolchain in the cloud, so what passes locally passes in CI.

Install in order: Git first, then Python, then sigma-cli and the pySigma backends. This order matters because sigma-cli depends on Python, and the quick-check commands below verify each tool in the dependency chain. If Python is not installed, sigma-cli will not install. If sigma-cli is not installed, the backend plugins have nowhere to register.

A virtual environment is recommended but not required. If you work with multiple Python projects, python3 -m venv ~/.sigma-env followed by source ~/.sigma-env/bin/activate keeps the course's dependencies isolated. If you only use Python for security tooling, a global install works fine. Module 1 does not assume either approach.

Quick-check commands

Run these after installation to confirm everything is working. If any command fails, fix it before starting Module 1.

# Git
git --version
# expect: git version 2.x.x
# Python
python3 --version
# expect: Python 3.11.x or later
# sigma-cli
sigma version
# expect: version string with installed backends listed
# pySigma backends (example: Sentinel)
sigma list backends
# expect: microsoft365defender listed (or whichever you installed)

If sigma version fails, the most common cause is that the pip install put the binary in a directory that is not on your shell's PATH. On macOS and Linux, check ~/.local/bin. On Windows, check the Scripts directory inside your Python installation. Module 1 includes troubleshooting steps, but getting these four commands to pass before you start is the single most useful preparation you can do.

Setting up your detection repository

Module 2 walks through the full repository setup, but you can create the empty repo now so it is ready. Log into GitHub, create a new private repository (you can make it public later if you choose), and clone it to your local machine. The name is yours to choose; the course uses detection-pipeline as the working example. You will add the folder structure, the CI workflow, and the first Sigma rule in Modules 1 through 3.

# Clone your empty repo
git clone https://github.com/YOUR-USERNAME/detection-pipeline.git
cd detection-pipeline
# Confirm Git identity
git config user.name
git config user.email

If you have not configured Git before, set your name and email with git config --global user.name "Your Name" and git config --global user.email "you@example.com". These values appear in every commit you make, and they should match the name and email on your GitHub account.

Optional: a SIEM for the deployment module

Modules 0 through 6 and Modules 8 through 11 work entirely on your local machine and in GitHub. You do not need a SIEM to write rules, test them, run CI, track coverage, or measure rule health.

Module 7 (Deployment) is the exception. It teaches automated deployment to a live SIEM. The module offers parallel tracks for Sentinel and Splunk so you follow the track for the platform you have.

If you have neither Sentinel nor Splunk, the pipeline still works end to end through CI. The deployment step is deferred, and the module explains what the deployment stage does so you can wire it up when you have a target. Many students complete the course without a live SIEM and wire the deployment later when they have a target environment at work. This is a real constraint the course acknowledges, not a gap.

What you do NOT need

The course deliberately avoids dependencies that cost money, require enterprise licences, or demand a specific operating system. The barrier to starting is a GitHub account, a Python installation, and a code editor. Everything else is taught as you go.

You do not need a Windows test host. The testing module (M5) uses pre-captured Atomic Red Team output committed as fixtures, not a live execution environment. The fixtures travel with the rule in the repository. You run the tests on macOS, Linux, or Windows; the fixtures are JSON files that work on any platform. The test harness reads the fixture, converts the Sigma rule to the target backend query, evaluates the query against the fixture data, and reports pass or fail. The operating system running the test is irrelevant because the evaluation happens against committed JSON, not against live telemetry.

You do not need an Atomic Red Team installation. The output from Atomic tests is captured and committed as JSON fixtures. You learn what Atomic produces, how to read the output, and how to construct fixtures from it, without running Atomic on a host. If you do have a Windows test host and want to generate your own fixtures from live Atomic executions, Module 5 shows you how, but it is optional. The constructed-fixture approach works for students who do not have a lab host, and the captured-fixture approach works for students who do. Both produce the same test contract: a JSON file that the harness evaluates against the converted query.

You do not need a paid GitHub plan. The free tier provides unlimited public and private repositories and 2,000 CI minutes per month. The detection CI workflow uses a fraction of that budget. A typical CI run for a single-rule PR completes in under two minutes. Even a heavy development session where you open and re-push a dozen PRs in an afternoon uses fewer than 30 minutes of CI time. At that rate, you would need to run more than 60 active development sessions in a single month to exhaust the free allocation.

You do not need Docker, Kubernetes, Terraform, or any infrastructure-as-code tooling. The pipeline runs in GitHub Actions. The deployment stage pushes to a SIEM API. The complexity is in the detection engineering, not in the infrastructure. Some organizations add containerised runners or Terraform-managed SIEM resources as the pipeline matures, but those are extensions, not prerequisites. This course builds the pipeline with the simplest tools that work so you understand every layer before adding abstraction.

You do not need prior experience with YAML, Git, CI/CD, or Sigma. Each is taught at first use in the module where it matters. An experienced reader skips past the explanations they already know; an inexperienced reader follows them step by step. The course is designed so that both readers finish with the same pipeline.

Platform-specific notes

macOS. Git ships with the Xcode Command Line Tools (xcode-select --install). Python 3 is available through Homebrew (brew install python3) or from python.org. Both sigma-cli and pySigma install with pip. If you use an M-series Mac, everything runs natively on Apple Silicon; no Rosetta translation is needed. VS Code, the recommended editor, also runs natively on Apple Silicon and includes a built-in terminal where you can run sigma-cli commands without switching windows.

Linux. Git and Python 3 are available through your distribution's package manager. On Ubuntu and Debian: sudo apt install git python3 python3-pip. On Fedora: sudo dnf install git python3 python3-pip. sigma-cli and pySigma install with pip after that. If your distribution ships Python 3.10 or earlier (check with python3 --version), you will need to install a newer version through pyenv or a deadsnakes PPA. sigma-cli requires 3.11 or later, and the pySigma backend plugins share that requirement.

Windows. The recommended path is Windows Subsystem for Linux (WSL). Install WSL, then follow the Linux instructions inside the WSL environment. WSL gives you a full Linux terminal with native Python and pip support, and the file system is accessible from your Windows editor. If you prefer native Windows, install Git from git-scm.com and Python from python.org, then use PowerShell or the Git Bash terminal for sigma-cli commands. The course examples use Unix-style shell syntax (/, ~, source); on native Windows you may need to translate path separators and activation commands for your environment. Git Bash handles most of this translation automatically.

Common installation issues

The most frequent problem is pip installing sigma-cli into a directory that is not on the shell's PATH. If sigma version returns "command not found" after a successful pip install, check whether ~/.local/bin (macOS/Linux) or the Python Scripts directory (Windows) is in your PATH. The fix on macOS and Linux is usually adding export PATH="$HOME/.local/bin:$PATH" to your shell profile (.bashrc, .zshrc, or .bash_profile). On Windows, the fix is adding the Scripts directory to the system PATH through the Environment Variables settings.

The second most common issue is Python version conflicts: sigma-cli requires 3.11 or later, and some systems ship with an older Python. python3 --version confirms what you have. On macOS, the system Python is often 3.9 from an older Xcode installation; Homebrew installs a current version alongside it without conflicting. On Ubuntu 22.04 LTS, the default Python is 3.10, which is one minor version too old; the deadsnakes PPA provides 3.11 and 3.12.

A third issue specific to Windows without WSL is pip's --user flag behaving differently depending on whether you run from PowerShell, Command Prompt, or Git Bash. If sigma-cli installs successfully but the command is not found in one terminal while it works in another, the PATH configuration differs between the two shells.

If you hit a problem that the quick-check commands do not diagnose, Module 1 includes a detailed troubleshooting section. For now, getting the four commands to pass is sufficient.

Section 0.5 maps the course structure: which modules cover which pipeline stages, how the phases build on each other, and how to pace your study.