☁️ Azure Microsoft Sentinel ML Behaviour Analytics Rule Terraform Module

Enables Microsoft's machine-learning behaviour model, which learns normal activity in the workspace and alerts on deviations (azurerm_sentinel_alert_rule_machine_learning_behavior_analytics). Targets hashicorp/azurerm ~> 4.0.

• 🧠 Microsoft's behaviour model. It learns normal activity in the workspace and alerts on deviations — anomalous SSH and RDP sign-ins being the canonical cases.
• ℹ️ You supply no logic and no thresholds — the template is the detection, and this resource turns it on.
• 🔴 The model needs a learning period on the workspace's own data. Early silence is not a misconfiguration, and nothing in Terraform reports when the model is ready.
• 🔁 enabled is the only argument that updates in place; the other three are force-new.
• 🧪 The module's surface is as small as the resource's — no invented knobs for a model you cannot configure.
• 🔒 No credential is accepted and none is emitted.

Four arguments, and the only interesting one is the one that is not there.

💡 Why it matters: The mechanics take a minute. The thing worth knowing is operational: a correctly configured behaviour-analytics rule is legitimately quiet for days while the model trains, which is exactly the situation in which someone reaches for a fix that is not needed.

📅 Azure portal retirement - March 31, 2027

Microsoft states that after March 31, 2027, Microsoft Sentinel will no longer be supported in the Azure portal and will be available only in the Microsoft Defender portal, and that customers using Microsoft Sentinel in the Azure portal will be redirected to the Defender portal. Since July 2025 many new customers are onboarded and redirected to the Defender portal automatically.

This does not change what this module manages. azurerm_sentinel_* are ARM resources and Terraform talks to ARM, not to a portal, so these resources continue to exist and stay manageable from code across that date. What moves is the management experience - runbooks, screenshots, analyst training, and any procedure that ends in a human clicking through Sentinel in the Azure portal. Plan that transition on its own schedule; this module emits management_moves_to_the_defender_portal so the date reaches plan output and inventory reports rather than living only in documentation.

Reference: https://learn.microsoft.com/azure/sentinel/overview#microsoft-sentinel-in-the-azure-portal-retirement-timeline

If this module saves you time, please consider supporting its continued development:

• ⭐ Star the repository on GitHub.
• 🤝 Connect on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

flowchart LR
  law["terraform-azurerm-log-analytics-workspace: Sentinel has no workspace of its own. Everything here lives on a Log Analytics workspace, and its RETENTION decides how far back any detection can look."]
  onboard["terraform-azurerm-sentinel-log-analytics-workspace-onboarding: THE GATE. Nothing else in this family works until it exists, and DESTROYING IT OFFBOARDS SENTINEL from the workspace."]
  wsid["AND WIRE log_analytics_workspace_id FROM THIS MODULE'S workspace_id OUTPUT, not from the workspace module's id. Both carry the same value, but reading it through here makes Terraform ORDER ONBOARDING FIRST. The provider's own examples chain it this way."]
  gotcha["NOTE THE FIELD NAME TRAP: azurerm_log_analytics_workspace exports BOTH id AND an attribute literally named workspace_id. Every module in this family wants the ARM RESOURCE ID, not the GUID. A bare GUID is rejected at plan time."]
  cmk["and customer_managed_key_enabled is PERMANENT FOR THE WORKSPACE: once onboarded with it true, the workspace cannot be onboarded again with it false. It is also force-new, so a plan that looks like an ordinary replacement can leave the workspace offboarded and unable to come back the way you asked."]
  sched["terraform-azurerm-sentinel-alert-rule-scheduled: THE WORKHORSE. Your KQL, on a schedule. query_period must be at least query_frequency or events between runs are never examined."]
  nrt["terraform-azurerm-sentinel-alert-rule-nrt: the same shape MINUS the schedule, evaluated continuously. event_grouping is REQUIRED here, entity mappings cap at 5 combined not 10, and alert_rule_template_version is force-new."]
  nrtq["BUT NRT RESTRICTS THE QUERY: joins, wide unions and long aggregations are the usual casualties, and NOTHING CHECKS THAT AT PLAN TIME. Build it in the analytics-rule wizard first; porting a scheduled rule's query straight in is the common way to get a rule that will not run."]
  ms["terraform-azurerm-sentinel-alert-rule-ms-security-incident: PROMOTES alerts another Microsoft product already raised. Detects nothing itself. product_filter takes LEGACY product names, so Microsoft Defender for Endpoint is REJECTED and Microsoft Defender Advanced Threat Protection is accepted."]
  fusion["terraform-azurerm-sentinel-alert-rule-fusion: Microsoft's MULTI-STAGE attack correlation. Its name argument is DEPRECATED and removed in provider v5.0, so this module neither accepts nor emits it."]
  mlba["terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics: Microsoft's behaviour model. Needs a LEARNING PERIOD, so early silence is not a misconfiguration."]
  ti["terraform-azurerm-sentinel-alert-rule-threat-intelligence: matches logs against threat-intelligence INDICATORS, and supplies none. With no indicator source it is a detection that CANNOT FIRE, and nothing about it looks wrong."]
  tmpl["these three are TEMPLATE-DRIVEN: the alert_rule_template_guid IS the detection, so repointing it is a different detection rather than a retune, and enabled is the only thing that updates in place"]
  anom["terraform-azurerm-sentinel-alert-rule-anomaly-built-in: TOGGLES a rule Microsoft ships. It creates nothing, so REMOVING THIS RESOURCE DISABLES THE RULE rather than releasing it."]
  dup["terraform-azurerm-sentinel-alert-rule-anomaly-duplicate: a TUNED COPY, because a built-in rule's thresholds are read-only. Anything you do not override is INHERITED from the built-in rule."]
  pair["so the usual shape is a PAIR, and it needs a decision the provider will not make: running the original AND a tuned duplicate in Production means the same detection active twice with two sets of thresholds"]
  mode["and BOTH anomaly modules take a REQUIRED mode: Production or FLIGHTING. Flighting runs in evaluation - enabled, configured, and not contributing. Right while tuning, wrong to leave behind."]
  gaps["THE FAMILY'S REAL RISK IS NOT AN OPEN DOOR, IT IS A SILENT DETECTION. enabled false, create_incident_enabled false, suppression_enabled true, mode Flighting, a trigger threshold above zero, a severity_filter missing High - each looks reasonable alone and each leaves a rule that passes a review asking IS IT CONFIGURED and fails one asking DOES IT WORK."]
  emit["which is why every module here emits derived posture flags - is_active, creates_incidents, is_production_mode - and the two query modules gather them into a single detection_gaps output"]

  law -->|"id"| onboard
  cmk -->|"decide before the first apply"| onboard
  onboard -->|"workspace_id"| wsid
  gotcha -->|"read this first"| wsid
  wsid -->|"log_analytics_workspace_id"| sched
  wsid -->|"log_analytics_workspace_id"| nrt
  wsid -->|"log_analytics_workspace_id"| ms
  wsid -->|"log_analytics_workspace_id"| fusion
  wsid -->|"log_analytics_workspace_id"| mlba
  wsid -->|"log_analytics_workspace_id"| ti
  wsid -->|"log_analytics_workspace_id"| anom
  wsid -->|"log_analytics_workspace_id"| dup
  nrtq -->|"unvalidatable"| nrt
  tmpl -->|"shape"| fusion
  tmpl -->|"shape"| mlba
  tmpl -->|"shape"| ti
  anom -->|"settings_definition_id becomes built_in_rule_id"| dup
  pair -->|"disable or flight the original"| dup
  mode -->|"required"| anom
  mode -->|"required"| dup
  gaps -->|"so"| emit
  emit -->|"assert on these"| sched
  emit -->|"assert on these"| nrt

  classDef me fill:#0078D4,stroke:#004578,color:#fff;
  classDef keystone fill:#004578,stroke:#001f3f,color:#fff;
  classDef sib fill:#eef2f7,stroke:#b8c4d0,color:#1b1b1b;
  class onboard keystone;
  class sched,nrt,ms,fusion,mlba,ti,anom,dup me;
  class law,wsid,gotcha,cmk,nrtq,tmpl,pair,mode,gaps,emit sib;

flowchart TB
  what["MACHINE-LEARNING BEHAVIOUR ANALYTICS IS A MICROSOFT-AUTHORED MODEL. It learns normal behaviour in the workspace and alerts on deviations - anomalous SSH and RDP sign-ins being the canonical cases."]
  tmpl["you supply NO LOGIC AND NO THRESHOLDS: the alert_rule_template_guid IS the detection. Four arguments, three of them force-new, and enabled is the only one that updates in place."]
  learn["AND THE MODEL NEEDS A LEARNING PERIOD on the workspace's own data before it produces anything meaningful. EARLY SILENCE IS NOT A MISCONFIGURATION - and nothing in Terraform reports when the model is ready."]
  caveat["so the caveat sits next to is_active, the flag someone would check: a correctly configured rule that is legitimately quiet for days is exactly the case where an operator reaches for a fix that is not needed"]
  small["THE MODULE'S SURFACE IS DELIBERATELY AS SMALL AS THE RESOURCE'S. There is no synthetic input for anything the model does, because none of it is configurable - inventing knobs would misrepresent what the caller controls."]
  silent["and the family risk still applies: enabled false leaves the detection present and SILENT, the state that survives a review asking IS IT CONFIGURED while failing one asking IS IT WORKING. enabled KEEPS the provider's true default because for a detection the closed value is the dangerous one."]
  name["name is an ARM name rather than something an analyst sees - the detection's presentation comes from the template. It is force-new, so renaming replaces the rule and Sentinel treats the new one as unrelated."]
  ws["and like every module in this family, log_analytics_workspace_id wants the workspace's ARM RESOURCE ID and is wired from the ONBOARDING module's workspace_id output, which is what orders onboarding first"]
  this["terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics"]
  keystone["azurerm_sentinel_alert_rule_machine_learning_behavior_analytics.this"]

  what -->|"so"| tmpl
  tmpl -->|"but"| learn
  learn -->|"therefore"| caveat
  caveat -->|"posture"| this
  small -->|"scope"| this
  silent -->|"default"| this
  name -->|"and"| ws
  ws -->|"wiring"| this
  this -->|"enables Microsoft's behaviour model"| keystone

  classDef me fill:#0078D4,stroke:#004578,color:#fff;
  classDef keystone fill:#004578,stroke:#001f3f,color:#fff;
  classDef sib fill:#eef2f7,stroke:#b8c4d0,color:#1b1b1b;
  class this me;
  class keystone keystone;
  class what,tmpl,learn,caveat,small,silent,name,ws sib;

Resource inventory

Schema notes that bite — confirmed against the live provider schema and its documentation:

• enabled is the only argument that updates in place. name, log_analytics_workspace_id and alert_rule_template_guid are all force-new.
• name is an ARM name, not something an analyst sees — the detection's presentation comes from the template.
• The model requires a learning period, which is a service behaviour rather than a schema fact and is reported nowhere in Terraform.
• Force-new: name, log_analytics_workspace_id, alert_rule_template_guid.
• enabled is the only argument that updates in place. Everything else is force-new.
• No tags. Tag the workspace.
• lifecycle is not valid inside a module block, so a caller cannot add ignore_changes or prevent_destroy.

Contributor or Owner at the same scope also work, and are broader than needed.

ℹ️ Sentinel's roles are workspace-scoped, and there is no per-rule permission — so a team that may enable this detection may also disable every other one.

• The Log Analytics workspace already onboarded to Microsoft Sentinel — wire log_analytics_workspace_id from that module's workspace_id output so Terraform orders the two correctly.
• The alert rule template present in the workspace's template gallery, and its GUID. Templates are supplied by Microsoft and by installed content solutions.
• The behaviour-analytics template in the workspace's gallery, and its GUID.
• The data the model learns from already flowing — sign-in data for the SSH and RDP detections. A model with no history has nothing to learn from.
• Patience. Expect a learning period before the rule produces meaningful alerts.

terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics/
├── providers.tf   # required_version + the pinned azurerm provider. No provider block.
├── variables.tf   # log_analytics_workspace_id, name, alert_rule_template_guid,
#                  # enabled, timeouts
├── main.tf        # the keystone, one resource
├── outputs.tf     # id first, then the template facts, then is_active
├── README.md      # this document
├── SCOPE.md       # the cross-module contract
├── LICENSE        # MIT
└── .gitignore

provider "azurerm" {
  features {}
}

module "rule_mlba" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics.git?ref=v1.0.0"

  # ⚠️ From the ONBOARDING module, not the workspace module. See example 1.
  log_analytics_workspace_id = module.sentinel.workspace_id

  name                     = "anomalous-ssh-login"
  alert_rule_template_guid = "737a2ce1-70a3-4968-9e90-3e6aca836abf"
}

ℹ️ The caller configures the provider, its authentication, and the mandatory features {} block. This module declares none of them.

⚠️ Read example 3 before judging whether this rule is working — early silence is expected.

Consumes

Emits

No credential is accepted and none is emitted.

# ✅ This creates the dependency edge.
log_analytics_workspace_id = module.sentinel.workspace_id

# ⚠️ Identical string. No dependency on onboarding.
log_analytics_workspace_id = module.law.id

# ❌ Rejected at plan time.
log_analytics_workspace_id = azurerm_log_analytics_workspace.example.workspace_id

Error: Invalid value for variable

  log_analytics_workspace_id must be a Microsoft.OperationalInsights/workspaces
  ARM Resource ID with nothing appended. Prefer the Sentinel onboarding module's
  `workspace_id` output; a bare GUID is the workspace's customer ID and is not
  accepted.

alert_rule_template_guid = "737a2ce1-70a3-4968-9e90-3e6aca836abf"

Enable the rule  ->  the model trains on the workspace's own history
                 ->  ...for a while...
                 ->  meaningful alerts

output "check" { value = module.rule_mlba.is_active } # true, and still possibly silent

log_analytics_workspace_id = module.sentinel.workspace_id
name                       = "anomalous-ssh-login"
alert_rule_template_guid   = "737a2ce1-70a3-4968-9e90-3e6aca836abf"
enabled                    = true

NOT exposed, because the resource does not have them:
  severity          the template decides
  query             there is no query — it is a model, not KQL
  thresholds        internal to the model
  tactics           the template's classification
  entity mapping    the template's
  frequency         the model's

name = "anomalous-ssh-login"

enabled = true # the default

output "check" { value = module.rule_mlba.is_active } # expect true

Force-new: name  log_analytics_workspace_id  alert_rule_template_guid
Updatable: enabled

locals {
  mlba_rules = {
    ssh = "737a2ce1-70a3-4968-9e90-3e6aca836abf"
    rdp = "fa118b98-de46-4e94-87f9-8e6d5060b60b"
  }
}

module "rule_mlba_all" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics.git?ref=v1.0.0"
  for_each = local.mlba_rules

  log_analytics_workspace_id = module.sentinel.workspace_id
  name                       = "mlba-${each.key}"
  alert_rule_template_guid   = each.value
}

output "active" {
  value = { for k, m in module.rule_mlba_all : k => m.is_active }
}

output "rule_mlba_review" {
  value = {
    active   = module.rule_mlba.is_active            # the assertion
    template = module.rule_mlba.alert_rule_template_guid
    name     = module.rule_mlba.name
  }
}

terraform import 'module.rule_mlba.azurerm_sentinel_alert_rule_machine_learning_behavior_analytics.this' \
  "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sentinel/providers/Microsoft.OperationalInsights/workspaces/law-sentinel-prod/providers/Microsoft.SecurityInsights/alertRules/anomalous-ssh-login"

terraform destroy on THIS module:
  removes the alert rule  ->  the detection stops
                          ->  the TEMPLATE is untouched, and can be re-instantiated
                          ->  nothing else in the workspace is affected

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-sentinel-prod"
  location = "eastus"
}

module "law" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-log-analytics-workspace.git?ref=v1.0.0"

  name                = "law-sentinel-prod"
  resource_group_name = module.rg.name
  location            = module.rg.location
  sku                 = "PerGB2018"
  retention_in_days   = 90
}

# ── The gate ──────────────────────────────────────────────────
module "sentinel" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-sentinel-log-analytics-workspace-onboarding.git?ref=v1.0.0"

  workspace_id = module.law.id
}

# ── Microsoft's behaviour models — several, each training independently ─────
locals {
  mlba_rules = {
    ssh = "737a2ce1-70a3-4968-9e90-3e6aca836abf"
    rdp = "fa118b98-de46-4e94-87f9-8e6d5060b60b"
  }
}

module "rule_mlba" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-sentinel-alert-rule-machine-learning-behavior-analytics.git?ref=v1.0.0"
  for_each = local.mlba_rules

  log_analytics_workspace_id = module.sentinel.workspace_id
  name                       = "mlba-${each.key}"
  alert_rule_template_guid   = each.value

  # enabled left at true. Expect a learning period before anything appears (example 3).
}

# ── A rule we wrote ourselves, for contrast ────────────────────────────
module "rule_impossible_travel" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-sentinel-alert-rule-scheduled.git?ref=v1.0.0"

  name                       = "impossible-travel"
  log_analytics_workspace_id = module.sentinel.workspace_id

  display_name = "Impossible travel sign-in"
  severity     = "High"
  query        = file("${path.module}/queries/impossible_travel.kql")

  query_frequency = "PT15M"
  query_period    = "PT1H"

  tactics  = ["InitialAccess"]
  incident = { create_incident_enabled = true }
}

output "detection_posture" {
  value = {
    # Active, which is necessary and not sufficient — the models train first.
    mlba_active = { for k, m in module.rule_mlba : k => m.is_active }

    # And the rule we own outright.
    scheduled_gaps = module.rule_impossible_travel.detection_gaps
  }
}

There is no tags variable — the provider exposes none on Sentinel alert rules.

variable "alert_rule_template_guid" {
  type = string
  # The template IS the detection: the model, its notion of normal, and its thresholds are all
  # internal to it. Force-new, because repointing it is a different detection.
  validation {
    condition     = can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", var.alert_rule_template_guid))
    error_message = "alert_rule_template_guid must be a GUID, for example 737a2ce1-70a3-4968-9e90-3e6aca836abf."
  }
}

variable "enabled" {
  type    = bool
  default = true
  # The provider's default, kept deliberately: for a detection the closed value is the dangerous
  # one. Note that active is not the same as producing — the model needs a learning period first.
}

🔒 No credential is accepted and none is emitted.

• The learning period is documented next to the flag someone would check. A correctly configured rule that is legitimately quiet for days is precisely the case where an operator reaches for a fix that makes things worse — disabling and re-enabling, or repointing the template. So the caveat lives on enabled and on is_active, not only in a prose section.

• The module's surface is deliberately as small as the resource's. No synthetic inputs for severity, thresholds, tactics or frequency, because none of them is configurable on this resource. Inventing them would misrepresent what the caller controls, and this suite would rather document a four-argument resource honestly than pad it.

• The contrast with the anomaly-built-in module is drawn explicitly. Both wrap a Microsoft-authored detection, but that resource exposes eleven read-only facts — description, frequency, required data connectors, observation settings — and this one exposes none. Knowing which module tells you what saves a search through both.

• enabled keeps the provider's true default, inverting this suite's usual convention. The rule "default to the closed value" assumes the closed value is the safe one; for a detection it is not. The convention is followed by understanding it rather than applying it mechanically — the same reasoning as every other rule module in this family.

• The module's surface is kept as small as the resource's. There is no synthetic input for anything the detection does, because none of it is configurable. Inventing knobs would misrepresent what the caller controls, and this suite would rather be honest about a four-argument resource than pad it.

• alert_rule_template_guid is force-new, and that is documented as semantically correct rather than as a limitation. The template is the detection, so repointing it is a different detection — a replacement is the accurate representation, not an inconvenience.

• Where a value set belongs to the service, it is left unvalidated and the reason is stated. There is little to leave unvalidated here: the GUID is shape-checked and name is checked for emptiness. Naming rules for Sentinel alert rules are a service concern, so nothing stricter is asserted.

• Before enabling: confirm the data the model learns from is already flowing.
• After enabling: record the date, and give the model time before concluding anything.
• Before disabling and re-enabling a quiet rule: that resets nothing useful and may restart learning.
• Before looking for what this detection covers: the template gallery, not Terraform.

terraform init -backend=false
terraform validate
terraform fmt -check

• Pin the source to a tag — ?ref=v1.0.0 — never a branch.
• Plan-only from here. A human applies from CI.
• ✅ enabled updates in place. Turning a detection on or off is an ordinary apply.
• ⚠️ Everything else is force-new, and replacing a rule resets its alert history in Sentinel.
• ℹ️ Assert is_active in CI. It is a single boolean and the only thing here that can be wrong in a way that matters.
• ⏳ Expect a learning period before this rule produces anything. Do not treat early silence as a fault.
• ℹ️ A destroy removes the detection. Nothing else in the workspace is affected.

terraform validate and terraform fmt -check are the offline gate. They confirm:

• log_analytics_workspace_id is a Microsoft.OperationalInsights/workspaces ARM Resource ID — a bare GUID is rejected;
• alert_rule_template_guid is a GUID;
• name is non-empty;
• no output is sensitive, because nothing sensitive is accepted;
• the module declares no provider block.

💡 These were proved by evaluating the conditions in terraform console inside the module — which does fire root-module variable validations, unlike terraform validate on a calling configuration. A bare GUID in the workspace field and a non-GUID template value both fail.

What only plan and apply exercise:

• whether the workspace exists and is onboarded to Sentinel;
• whether the template GUID names a template of the right kind, and whether it exists in this workspace;
• whether the identity holds Microsoft Sentinel Contributor.

What no Terraform command checks at any stage:

• 🔴 whether the model has finished learning — there is no attribute, output or plan line for it;
• whether the workspace has enough history for the model to learn from;
• what the detection actually looks for, or what data it needs — this resource exposes neither.

Outputs:

alert_rule_template_guid   = "737a2ce1-70a3-4968-9e90-3e6aca836abf"
enabled                    = true
id                         = "/subscriptions/00000000-.../providers/Microsoft.SecurityInsights/alertRules/anomalous-ssh-login"
is_active                  = true
log_analytics_workspace_id = "/subscriptions/00000000-.../workspaces/law-sentinel-prod"
name                       = "anomalous-ssh-login"

✅ is_active = true — the rule fires. Whether the model has finished learning is not visible here, and cannot be (example 3).

ℹ️ Six lines is the whole surface. Compare the anomaly-built-in module, which emits eleven read-only facts about its detection; this resource exposes none (example 4).

⚠️ There is no display_name. What an analyst sees comes from the template (example 5).

• azurerm_sentinel_alert_rule_machine_learning_behavior_analytics — provider documentation.
• Advanced multistage attack detection and ML analytics — the built-in ML detections this module enables.
• Anomalous RDP and SSH login detection — including the learning period of example 3.
• Create custom analytics rules — how rule templates are instantiated in the service.
• Microsoft Sentinel roles and permissions — the RBAC table above.
• Sibling modules: terraform-azurerm-sentinel-log-analytics-workspace-onboarding, ...-alert-rule-scheduled, ...-alert-rule-nrt, ...-alert-rule-ms-security-incident, ...-alert-rule-fusion, ...-alert-rule-machine-learning-behavior-analytics, ...-alert-rule-threat-intelligence, ...-alert-rule-anomaly-built-in, ...-alert-rule-anomaly-duplicate.
• This module's SCOPE.md.

💙 "Infrastructure as Code should be standardized, consistent, and secure."