Daily Defender News
Aboutmerill.net
Microsoft Defender XDR
Hunting and detection

Custom Detection Rules

4 September 2026New feature+30 / −11 lines

In brief

The documentation adds support for governance actions on supported SaaS identities returned by CloudAppEvents queries. Queries must include AccountObjectId, InstanceId, ApplicationId, AppInstanceId, and other required fields; unsupported actions or services produce no action.

What Defender admins need to know

Administrators can use these actions for SaaS identities, but should verify query columns and service support before enabling them.

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.

Custom detection rules are advanced hunting queries you design and tweak to proactively monitor various events and system states, including suspected breach activity and misconfigured endpoints. You can set them to run at regular intervals, generating alerts and taking response actions whenever there are matches.

This article walks you through creating and configuring a custom detection rule, including preparing the query, setting alert details, specifying automated response actions, and defining the rule scope.

Required permissions for managing custom detections

To manage custom detections, you need roles with permissions for the data these detections target. For example, to manage custom detections on multiple data sources (Microsoft Defender and Microsoft Sentinel, or multiple Defender workloads), you need all the applicable Defender and Sentinel roles. For more information, see the following sections.Microsoft Defender XDR and Microsoft Sentinel.

Required permissions in Microsoft Defender XDR

To manage custom detections on Microsoft Defender data, you need to be assigned one of these roles:

Required permissions in Microsoft Sentinel

To manage custom detections on Microsoft Sentinel data, you need to be assigned the Microsoft Sentinel Contributor role or higher. Users with this Azure role can manage Microsoft Sentinel SIEM workspace data, including alerts and detections. You can assign this role on a specific primary workspace, Azure resource group, or an entire subscription.

To create a custom detection rule by using Defender data, we recommend that the query returns the following columns:

  1. Timestamp or TimeGenerated - This column sets the timestamp for generated alerts. If these columns aren't projected from the KQL, the first and last event time for the generated alert is set according to the lookback window of the detection.
  2. For Microsoft Defender for Endpoint tables, include DeviceId orand DeviceNameReportId columns to ensure that:
    • Alerts are tagged with the correct device group scope scope.
    • Process tree view is built successfully.
  3. For all other Defender tables, project Timestamp and ReportId from the same event to ensure Defender identifies the original event that triggered the alert so that:
    • Alerts are tagged with the correct entity scope (only relevant for organizations that use Defender XDR scopes)

      Avoid filtering custom detections by using the Timestamp or TimeGenerated column. The service prefilters data for custom detections based on the detection lookback. Filter the results by Timestamp or TimeGenerated columns only if you want to add additional filtering to ensure a specific sunset of the lookback window is evaluated.

The following sample query shows how to return the recommended columns in a more complex query. It counts the number of unique devices (DeviceId) with antivirus detections and uses this count to findfinds only the devices with more than five detections. To return the latest Timestamp and the corresponding ReportId, it uses the summarize operator with the arg_max function. This query references a single table and uses only supported operators, which also makes it compatible with Continuous (NRT) frequency.

DeviceEvents

|Microsoft Defender XDR| Microsoft Sentinel|
|----------------------|-------------------|
|<ul><li>`AlertEvidence`<li>`CloudAppEvents`<li>`DeviceEvents`<li>`DeviceFileCertificateInfo`<li>`DeviceFileEvents`<li>`DeviceImageLoadEvents`<li>`DeviceLogonEvents`<li>`DeviceNetworkEvents`<li>`DeviceNetworkInfo`<li>`DeviceInfo`<li>`DeviceProcessEvents`<li>`DeviceRegistryEvents`<li>`EmailAttachmentInfo`<li>`EmailEvents` (except `LatestDeliveryLocation` and `LatestDeliveryAction` columns)<li>`EmailPostDeliveryEvents`<li>`EmailUrlInfo`<li>`IdentityDirectoryEvents`<li>`IdentityLogonEvents`<li>`IdentityQueryEvents`<li>`UrlClickEvents`</ul>| <ul><li>`ABAPAuditLog_CL`ABAPAuditLog_C`<li>`ABAPChangeDocsLog_CL`<li>`AuditLogs`<li>`AWSCloudTrail`<li>`AWSGuardDuty`<li>`AzureActivity`<li>`CommonSecurityLog`<li>`GCPAuditLogs`<li>`MicrosoftGraphActivityLogs`<li>`OfficeActivity`<li>`Okta_CL`<li>`OktaV2_CL`<li>`ProofpointPOD`<li>`ProofPointTAPClicksPermitted_CL`<li>`ProofPointTAPMessagesDelivered_CL`<li>`SecurityAlert`<li>`SecurityEvent`<li>`SigninLogs`</ul> 

Apply these actions to devices in the DeviceId column of the query results:

Actions on files

  • For Microsoft Entra identities, AccountObjectId parameter is needed for all actions.

  • Custom detection rules can apply governance actions to supported SaaS identities returned by queries that use the CloudAppEvents table. This capability is in preview.

  • To apply SaaS actions, the query results must include AccountObjectId, InstanceId, ApplicationId, and AppInstanceId, along with other required columns such as Timestamp. You can use joins as long as the required columns are present in the query results.

For more information on user actions, see Remediation actions in Microsoft Defender for Identity

The following table lists the supported governance actions for SaaS identities:

SaaS service Supported governance actions
Box Disable user
Google Workspace Disable user, Force password reset
Salesforce Disable user

For more information on user actions, see Remediation actions in Microsoft Defender for Identity and Remediation actions in Microsoft Defender for Cloud Apps.

Actions on emails