Daily Defender News
Aboutmerill.net
Microsoft Sentinel
Hunting and detection

Sentinel Hunting Rules Creation

4 September 2026Feature update+75 / −10 lines

In brief

The documentation adds sample hunting queries and a template, updates validation guidance, supports ATT&CK Framework v16, and limits queries to five tactics. Names may be up to 100 characters, must use ASCII, and analytic-rule-only fields can cause review failure.

What Defender admins need to know

Use the updated examples and validation rules when creating or reviewing hunting queries to avoid failed reviews and ensure current ATT&CK mappings.

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 hunting queries

You create hunting queries in YAML format. You can use thisUse these hunting queryqueries in the Azure-Sentinel repository as a referencereferences to create your own queries: own:

In this section, we provide a detailed walkthrough of hunting query attributes.

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

Sample hunting query template

The following is a sample hunting query template. Use it as a reference to create your own hunting queries. 

id: aaaaaaaa-0000-1111-2222-bbbbbbbbbbb
name: Admin privilege granted to user or group
description: |
  Identifies successful grants of administrator permissions to users or groups.
  Adversaries often assign administrator permissions to maintain access or elevate privileges.
description-detailed: |
  This query searches for successful grant of administrator permissions to user or groups.
  Please verify that the behavior is known and filter out anything that is expected.
  Reference: https://developer.okta.com/docs/reference/api/event-types/
status: Available
requiredDataConnectors:
  - connectorId: ContosoMyProduct
    dataTypes:
      - ContosoMyProduct_CL
tactics:
  - Persistence
relevantTechniques:
  - T1098
query: |
  ContosoMyProduct_CL
  | where EventType == "privilege.grant"
  | where Outcome == "SUCCESS"
  | summarize StartTime = min(TimeGenerated), EndTime = max(TimeGenerated),
      count() by ActorDisplayName, TargetDisplayName, PrivilegeGranted
entityMappings:
  - entityType: Account
    fieldMappings:
      - identifier: FullName
        columnName: ActorDisplayName
customDetails:
  PrivilegeGranted: PrivilegeGranted
  TargetUser: TargetDisplayName
version: 1.0.0

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.

  • Uses sentence-case capitalization.
  • Doesn't end in a period.
  • HasRecommended length of up to 50 characters, and a maximum length of 50 characters (whenever possible).100 characters.

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.

Detailed description

The description-detailed attribute is optional and has no length limit. Use it when 255 characters isn't enough to document data sources, filters, or reference links.

Status

The status attribute indicates the production readiness of the query. Use Available for production-ready queries.

Required data connectors

The requiredDataConnectors attribute represents the list of data connectors that the query 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 tacticsMITRE 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 can't include spaces. For example: InitialAccess or LateralMovement.
  • A maximum of five tactics can be defined per query.

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 query.

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.

Don't include a hardcoded time filter in a hunting query. The Hunting blade injects the analyst's selected time range at runtime. When you surface time bounds in the results, use the StartTime and EndTime column names, not StartTimeUtc or EndTimeUtc.

This field is mandatory.

Entity mappings

The entityMappings attribute is integral when you configure scheduled hunting queries. 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. See allowed values in the Entity type column in the Entity mapping table.

This field is mandatory.For hunting queries, entity mappings are recommended but not required.

Field mappings

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.template, and key names must be 20 characters or fewer. Custom details are recommended because they surface key columns in the results pane for faster triage.

    customDetails: