Daily Defender News
Aboutmerill.net
Microsoft Sentinel
Cloud and workloads

Sentinel Analytic Rules Creation

4 September 2026Doc update+84 / −12 lines

In brief

The article now includes multiple YAML examples, a complete sample rule, NRT field guidance, title constraints, status values, and ATT&CK v16 tactic requirements, including a five-tactic limit and valid values.

What Defender admins need to know

Administrators creating or reviewing analytics rules should use the updated examples and follow the documented naming, character, status, tactic, and NRT field requirements.

Summaries are generated from the documentation change itself.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

Create and publish analytics rules

You create analytics rules in YAML format. You can use this exampleUse these examples of an analytics rulerules as a referencereferences to create your own queries: own:

The following sections provide a detailed walkthrough of various attributes of an analytics rule.

Sample analytics rule

The following is a sample analytics rule in YAML format.

id: aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
name: Anomalous login from unknown IP
description: |
  Identifies login attempts from IP addresses not seen in the past 14 days.
severity: Medium
requiredDataConnectors:
  - connectorId: ContosoMyProduct
    dataTypes:
      - ContosoMyProduct_CL
queryFrequency: 1h
queryPeriod: 14d
triggerOperator: gt
triggerThreshold: 0
tactics:
  - InitialAccess
relevantTechniques:
  - T1078
status: Available
query: |
  ContosoMyProduct_CL
  | where TimeGenerated > ago(1h)
  | where EventType == "Login"
  | summarize count() by SrcIpAddr, UserName
  | extend Name = tostring(split(UserName, '@', 0)[0])
  | extend UPNSuffix = tostring(split(UserName, '@', 1)[0])
entityMappings:
  - entityType: Account
    fieldMappings:
      - identifier: Name
        columnName: Name
      - identifier: UPNSuffix
        columnName: UPNSuffix
  - entityType: IP
    fieldMappings:
      - identifier: Address
        columnName: SrcIpAddr
version: 1.0.0
kind: Scheduled

ID

The id attribute consists of a standard globally unique identifier (GUID). Generate it by using any development tool, an online generator, or the new PowerShell New-GUID cmdlet. It must be unique among other GUIDs.

The kind attribute represents the type of rule.

There are two accepted values: scheduled and NRT (near-real time). The scheduled value requires that you define other properties, including queryFrequency, queryPeriod, triggerThreshold, and triggerOperator. For NRT rules, omit queryFrequency, queryPeriod, triggerOperator, and triggerThreshold.

This field is mandatory.

  • Uses sentence-case capitalization.
  • Doesn't end in a period.
  • Has a maximumrecommended length of less than 50 characters (whenever possible)characters, and a hard maximum of 100 characters.
  • Avoids the words "Suspicious" and "Suspect". Use "Unexpected", "Anomalous", or "Rare" instead.

This field is mandatory.

  • Is five sentences or less.
  • Doesn't describe the data source (connector or data type).
  • Doesn't provide a technical explanation for the query language.
  • Uses ASCII characters only. Em dashes, smart quotes, and other non-ASCII characters fail validation.

This field is mandatory.

Status

The status attribute indicates the production readiness of the rule:

  • Available: Production-ready rules.
  • InPreview: Beta rules.
  • Deprecated: Rules being phased out.

Required data connectors

The requiredDataConnectors attribute represents the list of data connectors that the rule needs to function correctly, including the data sources against which the rule queries. If there's no current data connector mapping, you must use an open brace: requiredDataConnectors: [].

Tactics

The tactics attribute defines the MITRE ATT&CK tactics that the detection relates to. When you define the tactics, it helps users understand the context of the detection and how it fits into the overall threat landscape. For this attribute:

  • ATT&CK Framework v13v16 is supported.
  • Names use PascalCase and can't include spaces. For example: InitialAccess or LateralMovement.
  • A maximum of five tactics can be defined per rule.
  • Valid values are: Reconnaissance, ResourceDevelopment, InitialAccess, Execution, Persistence, PrivilegeEscalation, DefenseEvasion, CredentialAccess, Discovery, LateralMovement, Collection, CommandAndControl, Exfiltration, and Impact.

This field is mandatory.

Relevant techniques

The relevantTechniques attribute defines the MITRE ATT&CK techniquesMITRE ATT&CK techniques that the detection relates to. When you define the techniques, it helps users understand the context of the detection and how it fits into the overall threat landscape. For this attribute:

  • ATT&CK Framework v13v16 is supported.
  • Attribute matchesEach technique must belong to at least one of the listed MITREtactics tactics..
  • Names can't include spaces. For example: T1078 or T1078.001.
  • A maximum of 10 techniques can be defined per rule.

This field is mandatory.

Additionally, include as many fields as possible to help the user understand the context of the alert. We recommend that you include at least one of the primary entities: Host, Account, or IP.

Column names in your custom table must use camelCase (for example, SrcIpAddr or UserName).

This field is mandatory.

Event grouping settings

The entityMappings attribute is integral when you configure scheduled analytics rules. It enriches the query's output (alerts and incidents) with essential information that serves as the building blocks of any investigative processes and remedial actions that follow.

The entityType represents the standard list of entities recognized by Microsoft Sentinel. Supported types include Account, Host, IP, URL, File, Process, DNS, AzureResource, FileHash, RegistryKey, RegistryValue, SecurityGroup, Mailbox, and MailMessage. See allowed values in the Entity type column in the Entity mapping table.

This field is mandatory.

Custom details

The customDetails attribute integrates event data into alerts, making it visible in security incidents for faster triaging, investigation, and response. Custom details are key/value pairs of property and column names. For more information, see Surface custom event details in alerts in Microsoft Sentinel. Up to 20 custom details (that is, key/value pairs) can be defined per template. Key names must be 20 characters or fewer. 

    customDetails:
        alertSeverityColumnName: dynamicSeverity

Incident configuration

The incidentConfiguration attribute controls incident creation and the grouping of alerts into incidents. Use it to define how alerts that this rule generates are aggregated into incidents.

Version

When a customer creates a new hunting query from the template, the template version is saved. If a new template version is published, customers are notified in the UX. Versions follow the format a, b, and c, in which a is the major version, b is the minor version, and c is the patch. The version field is the last line of the template.