This repository provides a complete end-to-end CI/CD solution for deploying Microsoft Sentinel environments using Azure DevOps pipelines or GitHub Actions. Starting from an empty subscription, the pipeline provisions all required infrastructure via Bicep, deploys Content Hub solutions (the source of truth for out-of-the-box content), deploys custom content (detections, watchlists, playbooks, workbooks, hunting queries, automation rules, summary rules), and deploys Defender XDR custom detection rules - all from a single repo.
It ships with a five-job PR validation gate, a nightly end-to-end smoke test against a dedicated test workspace, daily portal-drift detection that absorbs edits back into the repo as PRs, an auto-derived dependency graph, a workbook round-trip exporter, and thirteen cross-platform GitHub Copilot agents that work on github.com and in every supported IDE so authors can build, edit, tune, and explain content with repo-aware AI assistance.
Sentinel-As-Code is built and maintained on my own time as an open source project. I spend countless hours developing, testing, documenting, and supporting the work that lands in this repository - at no cost to the people and organisations who benefit from it.
If you are an organisation deploying this code into production, or if it has saved your team meaningful engineering time, please consider supporting the project. Your contribution directly funds the next round of features, the test infrastructure, and the time it takes to keep the content current with Microsoft's release cadence.
Recurring Organisation tiers (£125 / £250 / £500 per month), one-off tips at any amount, and annual sponsorships by invoice are all live on sentinel.blog/support. All channels are Stripe-backed, all blog content stays free for everyone, and contributions do not create a support contract - see the support page for the full disclaimer.
The Sentinel as Code Toolkit is a companion VS Code extension for authoring content in this repo, covering schema validation, IntelliSense, field-order formatting, ARM-to-YAML conversion, and Defender XDR authoring helpers. It authors and validates; it does not deploy, so it pairs with (rather than replaces) the pipelines documented here. See Docs/Toolkit/README.md.
.github/ GitHub Actions workflows, composite actions, and Copilot customisations
AGENTS.md Cross-tool agent guidance (Copilot, Claude, Gemini, Cursor)
Blog/ Source posts for sentinel.blog
Content/ All Sentinel content, grouped by type (analytical/hunting/summary rules,
watchlists, playbooks, workbooks, parsers, automation rules, Defender detections)
Infra/ Three subscription-scoped Bicep stacks (production Sentinel, test workspace,
DCR-watchlist automation)
Deploy/ Deployment scripts and sentinel-deployment.config
Tools/ CI and maintenance tooling (dependency manifest, drift, PR validation,
workbook export, community import, Documenter)
Pipelines/ Azure DevOps pipeline definitions
Modules/ In-repo PowerShell modules (Sentinel.Common shared deployer + KQL helpers)
Tests/ Pester test suite
Docs/ All documentation, mirroring the repo layout (start at Docs/README.md)
dependencies.json Auto-derived content dependency graph
For what lives inside each folder and how content is authored, see the
Documentation section below, starting at
Docs/README.md.
- End-to-end deployment: a single pipeline provisions infrastructure via Bicep, then deploys Content Hub solutions, custom Sentinel content (analytical rules, hunting queries, watchlists, playbooks, workbooks, parsers, automation rules, summary rules), and Defender XDR custom detections.
- Smart, incremental deployment: the deploy pipeline runs incrementally by default, using a git diff and a state file to skip unchanged items and auto-retry previously failed ones. See Deploy and Scripts.
- Auto-derived dependency graph:
dependencies.jsonis generated from KQL content discovery, gated in CI, and refreshed by a daily auto-PR. See Dependency Manifest. - Drift detection and absorption: a daily detector compares every deployed rule against its source of truth and absorbs portal edits back into the repo as PRs. See Sentinel Drift Detection.
- Workbook round-trip export: pull user-authored workbooks from a workspace into the repo with placeholders and curated metadata, making portal authoring a first-class repo workflow. See Workbooks.
- PR validation and nightly E2E: a five-job merge gate (Pester, Bicep build, ARM validation, KQL syntax, dependency-manifest drift) runs on every PR, and a nightly smoke test exercises every deploy path against a throwaway test workspace. See PR Validation and Deploy Nightly.
- Customisation protection and dry runs: locally tuned rules are detected and skipped, and
-WhatIfpreviews changes before applying. - Azure Government support: target both commercial and government cloud environments.
- Shared tooling: the
Sentinel.CommonPowerShell module is the single source of truth for the deployer helpers and KQL discovery, and reusable GitHub Actions composites (azure-login-oidc,setup-pwsh-modules) pin every dependency. See Sentinel.Common module. - Repo-aware AI assistance: thirteen cross-platform GitHub Copilot agents plus path-scoped instructions and reusable prompts. See GitHub Copilot.
- Grant permissions. Run
Deploy/setup/Setup-ServicePrincipal.ps1once to grant the service principal every required role (Contributor, ABAC-conditioned User Access Administrator, plus the optional Security Administrator andCustomDetection.ReadWrite.Allgrants) with a Y/N consent prompt. After that the pipeline is autonomous. Full role list: Deploy; bootstrap detail: Scripts. - Wire up CI. On Azure DevOps, create the
sc-sentinel-as-codeservice connection and thesentinel-deploymentvariable group, then point a pipeline atPipelines/Sentinel-Deploy.yml. See ADO OIDC Setup and Deploy. On GitHub, the workflows under.github/workflows/authenticate via OIDC; see PR Validation Setup. - Run it. The deploy checks for existing infrastructure, deploys Bicep if needed, configures Sentinel settings, then deploys Content Hub and custom content in ordered stages followed by Defender XDR detections.
New to the project? The Build and Test Guide walks through requirements, permissions, and a no-local-install path end to end. For the standalone pipelines, the GitHub-to-ADO parity map, and each pipeline's schedule, see Docs/Pipelines/README.md.
The repo ships a complete GitHub Copilot customisation set so authors get repo-aware AI help out of the box, with no VS Code settings or feature toggles required. It comprises thirteen custom agents (five persona-broad, eight engineering specialists), nine path-scoped instruction files that load automatically when you edit a matching file, and six reusable slash-command prompts, plus repo-wide guidance in .github/copilot-instructions.md and cross-tool guidance in AGENTS.md. It works on github.com Chat, the github.com cloud agent, VS Code, Visual Studio, JetBrains, and Copilot CLI without configuration. Full roster and usage: Docs/GitHub/GitHub-Copilot.md.
All documentation lives under Docs/, whose folders mirror this repo's
layout (Deploy/ to Docs/Deploy/, Pipelines/ to Docs/Pipelines/, .github/
to Docs/GitHub/, and so on). Start at Docs/README.md for the
full index. Only Guides/, Releases/, and Toolkit/ are concern-based, with no code
counterpart.
Schemas and conventions for every content type. The Toolkit schemas and templates are the authoring source of truth for these.
| Area | Doc |
|---|---|
| Analytical Rules | Content/Analytical-Rules.md |
| Automation Rules | Content/Automation-Rules.md |
| Community Rules | Content/Community-Rules.md |
| Defender Custom Detections | Content/Defender-Custom-Detections.md |
| Hunting Queries | Content/Hunting-Queries.md |
| Parsers | Content/Parsers.md |
| Playbooks | Content/Playbooks.md |
| Summary Rules | Content/Summary-Rules.md |
| Watchlists | Content/Watchlists.md |
| Workbooks | Content/Workbooks.md |
Auto-generated per-contributor summaries live under Docs/Content/Community/ (for
example Dalonso); do not hand-edit them.
The Sentinel as Code Toolkit companion VS Code extension (a separate repository). It authors and validates; it does not deploy.
| Area | Doc |
|---|---|
| Overview and install | Toolkit/README.md |
| Commands | Toolkit/Commands.md |
| Templates | Toolkit/Templates.md |
| Schemas and Validation | Toolkit/Schemas-and-Validation.md |
| Configuration | Toolkit/Configuration.md |
| ARM to YAML Conversion | Toolkit/ARM-to-YAML-Conversion.md |
| Defender Workflows | Toolkit/Defender-Workflows.md |
| Graph API Migrations | Toolkit/Graph-API-Migrations.md |
| Area | Doc |
|---|---|
| Scripts | Deploy/Scripts.md |
| PR Validation Setup | Deploy/PR-Validation-Setup.md |
| ADO OIDC Setup | Deploy/ADO-OIDC-Setup.md |
| PowerShell Module Requirements | Deploy/PowerShell-Module-Requirements.md |
Start at the index for the GitHub/ADO parity map, then the deep per-pipeline pages: PR-Validation, Deploy, Deploy-Nightly, Drift-Detect, Documenter, Dependency-Update, DCR-Inventory, and Word-Report.
| Area | Doc |
|---|---|
| Bicep | Infra/Bicep.md |
| Sentinel.Common module | Modules/Sentinel-Common-Module.md |
| Area | Doc |
|---|---|
| Dependency Manifest | Tools/Dependency-Manifest.md |
| Sentinel Drift Detection | Tools/Sentinel-Drift-Detection.md |
| DCR Watchlist Sync | Tools/DCR-Watchlist.md |
| SDL Migration Workbook Export | Tools/SDL-Migration-Workbook-Export.md |
Documenter (Docs/Tools/Documenter/): Sentinel Documenter,
Renderer Design,
References,
Data Lake Coverage, and
Word Report.
| Area | Doc |
|---|---|
| Pester Tests | Tests/Pester-Tests.md |
| GitHub Copilot | GitHub/GitHub-Copilot.md |
End-to-end walkthroughs.
| Area | Doc |
|---|---|
| Build and Test Guide | Guides/Sentinel-As-Code-Build-and-Test-Guide.md |
| Area | Doc |
|---|---|
| Versioning | Releases/Versioning.md |
| Changelog | Releases/CHANGELOG.md |
| Layout Restructure 26.06 | Releases/Layout-Restructure-26.06.md |
Contributions are welcome. See the Contributing guide for how to report bugs, suggest enhancements, author content, run the checks, and open a pull request. In short: fork the repository, branch from main, fill in the pull request template, and make sure the template check and the five-job validation gate pass before requesting a merge.
If you've found Sentinel-As-Code useful, subscribe to sentinel.blog for more Sentinel and security content!
The best way to support this project is by subscribing to the blog, submitting issues, suggesting improvements, or contributing code! If you're using this in an organisation, see the donation callout under Overview.
This project is provided as-is, with no warranty and no support of any kind, express or implied. Use at your own risk.
The maintainers make no guarantee that the code is fit for any particular purpose, that it will work in your environment, or that any issue you encounter will be acknowledged or fixed. Bug reports and pull requests are welcome (see Contributing), but there is no SLA, no guaranteed response time, and no obligation to provide assistance.
You are solely responsible for reviewing, testing, and validating any content from this repository before deploying it to production Microsoft Sentinel or Defender XDR environments.
This project is licensed under the Apache License 2.0. See NOTICE for copyright and third-party attribution. Releases from 26.07 onward are Apache-2.0; earlier releases remain available under the MIT License.