Create and manage custom detection rules in Microsoft 365 Defender (2023)

  • Article
  • 10 minutes to read


Want to experience Microsoft 365 Defender? Learn more about how you can evaluate and pilot Microsoft 365 Defender.

Applies to:

  • Microsoft 365 Defender

Custom detection rules are rules you can design and tweak using advanced hunting queries. These rules let you 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.

Required permissions for managing custom detections

To manage custom detections, you need to be assigned one of these roles:

  • Security administrator—Users with this Azure Active Directory role can manage security settings in the Microsoft 365 Defender portal and other portals and services.

  • Security operator—Users with this Azure Active Directory role can manage alerts and have global read-only access to security-related features, including all information in the Microsoft 365 Defender portal. This role is sufficient for managing custom detections only if role-based access control (RBAC) is turned off in Microsoft Defender for Endpoint. If you have RBAC configured, you also need the manage security settings permission for Defender for Endpoint.

You can also manage custom detections that apply to data from specific Microsoft 365 Defender solutions if you have permissions for them. If you only have manage permissions for Microsoft 365 Defender for Office, for instance, you can create custom detections using Email tables but not Identity tables.

To manage required permissions, a global administrator can:

  • Assign the security administrator or security operator role in Microsoft 365 admin center under Roles > Security admin.
  • Check RBAC settings for Microsoft Defender for Endpoint in Microsoft 365 Defender under Settings > Permissions > Roles. Select the corresponding role to assign the manage security settings permission.


To manage custom detections, security operators will need the manage security settings permission in Microsoft Defender for Endpoint if RBAC is turned on.

Create a custom detection rule

1. Prepare the query.

In the Microsoft 365 Defender portal, go to Advanced hunting and select an existing query or create a new query. When using a new query, run the query to identify errors and understand possible results.

(Video) Creating Custom Detection Rules | Microsoft 365 Defender


To prevent the service from returning too many alerts, each rule is limited to generating only 100 alerts whenever it runs. Before creating a rule, tweak your query to avoid alerting for normal, day-to-day activity.

Required columns in the query results

To create a custom detection rule, the query must return the following columns:

  • Timestamp—used to set the timestamp for generated alerts
  • ReportId—enables lookups for the original records
  • One of the following columns that identify specific devices, users, or mailboxes:
    • DeviceId
    • DeviceName
    • RemoteDeviceName
    • RecipientEmailAddress
    • SenderFromAddress (envelope sender or Return-Path address)
    • SenderMailFromAddress (sender address displayed by email client)
    • RecipientObjectId
    • AccountObjectId
    • AccountSid
    • AccountUpn
    • InitiatingProcessAccountSid
    • InitiatingProcessAccountUpn
    • InitiatingProcessAccountObjectId


Support for additional entities will be added as new tables are added to the advanced hunting schema.

Simple queries, such as those that don't use the project or summarize operator to customize or aggregate results, typically return these common columns.

There are various ways to ensure more complex queries return these columns. For example, if you prefer to aggregate and count by entity under a column such as DeviceId, you can still return Timestamp and ReportId by getting it from the most recent event involving each unique DeviceId.


Avoid filtering custom detections using the Timestamp column. The data used for custom detections is pre-filtered based on the detection frequency.

The sample query below counts the number of unique devices (DeviceId) with antivirus detections and uses this count to find 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.

DeviceEvents| where ingestion_time() > ago(1d)| where ActionType == "AntivirusDetection"| summarize (Timestamp, ReportId)=arg_max(Timestamp, ReportId), count() by DeviceId| where count_ > 5


For better query performance, set a time filter that matches your intended run frequency for the rule. Since the least frequent run is every 24 hours, filtering for the past day will cover all new data.

(Video) MDE Tutorial -23 -How to Create Detection Rule in Microsoft Defender for Endpoints

2. Create new rule and provide alert details.

With the query in the query editor, select Create detection rule and specify the following alert details:

  • Detection name—name of the detection rule; should be unique
  • Frequency—interval for running the query and taking action. See additional guidance below
  • Alert title—title displayed with alerts triggered by the rule; should be unique
  • Severity—potential risk of the component or activity identified by the rule
  • Category—threat component or activity identified by the rule
  • MITRE ATT&CK techniques—one or more attack techniques identified by the rule as documented in the MITRE ATT&CK framework. This section is hidden for certain alert categories, including malware, ransomware, suspicious activity, and unwanted software
  • Description—more information about the component or activity identified by the rule
  • Recommended actions—additional actions that responders might take in response to an alert

Rule frequency

When you save a new rule, it runs and checks for matches from the past 30 days of data. The rule then runs again at fixed intervals, applying a lookback duration based on the frequency you choose:

  • Every 24 hours—runs every 24 hours, checking data from the past 30 days
  • Every 12 hours—runs every 12 hours, checking data from the past 48 hours
  • Every 3 hours—runs every 3 hours, checking data from the past 12 hours
  • Every hour—runs hourly, checking data from the past 4 hours

When you edit a rule, it will run with the applied changes in the next run time scheduled according to the frequency you set. The rule frequency is based on the event timestamp and not the ingestion time.


Match the time filters in your query with the lookback duration. Results outside of the lookback duration are ignored.

Select the frequency that matches how closely you want to monitor detections. Consider your organization's capacity to respond to the alerts.

3. Choose the impacted entities.

Identify the columns in your query results where you expect to find the main affected or impacted entity. For example, a query might return sender (SenderFromAddress or SenderMailFromAddress) and recipient (RecipientEmailAddress) addresses. Identifying which of these columns represent the main impacted entity helps the service aggregate relevant alerts, correlate incidents, and target response actions.

You can select only one column for each entity type (mailbox, user, or device). Columns that are not returned by your query can't be selected.

4. Specify actions.

Your custom detection rule can automatically take actions on devices, files, users, or emails that are returned by the query.

Actions on devices

These actions are applied to devices in the DeviceId column of the query results:

  • Isolate device—uses Microsoft Defender for Endpoint to apply full network isolation, preventing the device from connecting to any application or service. Learn more about Microsoft Defender for Endpoint machine isolation
  • Collect investigation package—collects device information in a ZIP file. Learn more about the Microsoft Defender for Endpoint investigation package
  • Run antivirus scan—performs a full Microsoft Defender Antivirus scan on the device
  • Initiate investigation—initiates an automated investigation on the device
  • Restrict app execution—sets restrictions on device to allow only files that are signed with a Microsoft-issued certificate to run. Learn more about app restrictions with Microsoft Defender for Endpoint

Actions on files

  • When selected, the Allow/Block action can be applied to the file. Blocking files are only allowed if you have Remediate permissions for files and if the query results have identified a file ID, such as a SHA1. Once a file is blocked, other instances of the same file in all devices are also blocked. You can control which device group the blocking is applied to, but not specific devices.

  • When selected, the Quarantine file action can be applied to files in the SHA1, InitiatingProcessSHA1, SHA256, or InitiatingProcessSHA256 column of the query results. This action deletes the file from its current location and places a copy in quarantine.

Actions on users

  • When selected, the Mark user as compromised action is taken on users in the AccountObjectId, InitiatingProcessAccountObjectId, or RecipientObjectId column of the query results. This action sets the users risk level to "high" in Azure Active Directory, triggering corresponding identity protection policies.

  • Select Disable user to temporarily prevent a user from logging in.


  • Select Force password reset to prompt the user to change their password on the next sign in session.

Both the Disable user and Force password reset options require the user SID, which are in the columns AccountSid, InitiatingProcessAccountSid, RequestAccountSid, and OnPremSid.

For more details on user actions, read Remediation actions in Microsoft Defender for Identity.

Actions on emails

  • If the custom detection yields email messages, you can select Move to mailbox folder to move the email to a selected folder (any of Junk, Inbox, or Deleted items folders).

  • Alternatively, you can select Delete email and then choose to either move the emails to Deleted Items (Soft delete) or delete the selected emails permanently (Hard delete).

The columns NetworkMessageId and RecipientEmailAddress must be present to apply actions to email messages.

5. Set the rule scope.

Set the scope to specify which devices are covered by the rule. The scope influences rules that check devices and doesn't affect rules that check only mailboxes and user accounts or identities.

When setting the scope, you can select:

  • All devices
  • Specific device groups

Only data from devices in scope will be queried. Also, actions will be taken only on those devices.

6. Review and turn on the rule.

After reviewing the rule, select Create to save it. The custom detection rule immediately runs. It runs again based on configured frequency to check for matches, generate alerts, and take response actions.


Custom detections should be regularly reviewed for efficiency and effectiveness. To make sure you are creating detections that trigger true alerts, take time to review your existing custom detections by following the steps in Manage existing custom detection rules.

You maintain control over the broadness or specificity of your custom detections so any false alerts generated by custom detections might indicate a need to modify certain parameters of the rules.

Manage existing custom detection rules

You can view the list of existing custom detection rules, check their previous runs, and review the alerts they have triggered. You can also run a rule on demand and modify it.

(Video) Creating custom threat detection policies in Microsoft Cloud App Security


Alerts raised by custom detections are available over alerts and incident APIs. For more information, see Supported Microsoft 365 Defender APIs.

View existing rules

To view all existing custom detection rules, navigate to Hunting > Custom detection rules. The page lists all the rules with the following run information:

  • Last run—when a rule was last run to check for query matches and generate alerts
  • Last run status—whether a rule ran successfully
  • Next run—the next scheduled run
  • Status—whether a rule has been turned on or off

View rule details, modify rule, and run rule

To view comprehensive information about a custom detection rule, go to Hunting > Custom detection rules and then select the name of rule. You can then view general information about the rule, including information its run status and scope. The page also provides the list of triggered alerts and actions.

Custom detection rule details

You can also take the following actions on the rule from this page:

  • Run—run the rule immediately. This also resets the interval for the next run.
  • Edit—modify the rule without changing the query
  • Modify query—edit the query in advanced hunting
  • Turn on / Turn off—enable the rule or stop it from running
  • Delete—turn off the rule and remove it

View and manage triggered alerts

In the rule details screen (Hunting > Custom detections > [Rule name]), go to Triggered alerts, which lists the alerts generated by matches to the rule. Select an alert to view detailed information about it and take the following actions:

  • Manage the alert by setting its status and classification (true or false alert)
  • Link the alert to an incident
  • Run the query that triggered the alert on advanced hunting

Review actions

In the rule details screen (Hunting > Custom detections > [Rule name]), go to Triggered actions, which lists the actions taken based on matches to the rule.


To quickly view information and take action on an item in a table, use the selection column [✓] at the left of the table.


Some columns in this article might not be available in Microsoft Defender for Endpoint. Turn on Microsoft 365 Defender to hunt for threats using more data sources. You can move your advanced hunting workflows from Microsoft Defender for Endpoint to Microsoft 365 Defender by following the steps in Migrate advanced hunting queries from Microsoft Defender for Endpoint.

See also

  • Custom detections overview
  • Advanced hunting overview
  • Learn the advanced hunting query language
  • Migrate advanced hunting queries from Microsoft Defender for Endpoint


Which type of alert can you manage from the Microsoft 365 Defender? ›

This article describes security alerts in Microsoft 365 Defender. However, you can use activity alerts to send email notifications to yourself or other admins when users perform specific activities in Microsoft 365. For more information, see Create activity alerts - Microsoft Purview | Microsoft Docs.

What is the maximum number of alerts that will be generated by the rule? ›

Currently the number of alerts a rule can generate is capped at 150.

What two ways can you use to manage access to Microsoft 365 Defender functionality and data? ›

There are two ways to manage access to Microsoft 365 Defender:
  • Global Azure Active Directory (AD) roles.
  • Custom role access.
Feb 7, 2023

How do I run a custom scan with Windows Defender? ›

Scan an item with Windows Security
  1. To scan specific files or folders, right-click the ones you want then select Scan with Microsoft Defender. ...
  2. To turn on Microsoft Defender Antivirus in Windows Security, go to Start > Settings > Update & Security > Windows Security > Virus & threat protection.

What is the difference between alerting rules and recording rules? ›

Recording rules are for pre-calculating frequently used or computationally expensive queries. The results of those rules are saved into their own time series. Alerting rules on the other hand enable you to specify the conditions that an alert should be fired to an external service like Slack.

How many notifications per day is too many? ›

The number of push notifications you should send depends on your industry. That said, the best thing to do is send your customers 2 notifications a day at most. And no more than 5 a week. An average of 1 notification a day works even better.

What are the three types of alerts? ›

There are three major alert systems: Wireless Emergency Alerts, Emergency Alert System and Opt-In Alert Systems. Each system has different ways of communicating with people, but all of the emergency alert systems provide a way to let people know when there is something wrong.

What are two capabilities of Microsoft Defender for endpoint each correct answer? ›

  • Eliminate the blind spots in your environment.
  • Discover vulnerabilities and misconfigurations in real time.
  • Quickly go from alert to remediation at scale with automation.
  • Block sophisticated threats and malware.
  • Detect and respond to advanced attacks with deep threat monitoring and analysis.

What are the four categories of reporting found in the Microsoft 365 Defender portal? ›

Email & collaboration RBAC in the Microsoft 365 Defender portal: Membership in any of the following role groups: Organization Management. Security Administrator. Security Reader.

What should you use in the Microsoft 365 Defender portal to view security? ›

You can access Threat analytics either from the upper left navigation bar in Microsoft 365 Defender, or from a dedicated dashboard card that shows the top threats for your organization. Learn more about how to track and respond to emerging threats with threat analytics.

What is the difference between an alert and incident in Microsoft 365 defender? ›

An incident in Microsoft 365 Defender is a collection of correlated alerts and associated data that make up the story of an attack. Microsoft 365 services and apps create alerts when they detect a suspicious or malicious event or activity. Individual alerts provide valuable clues about a completed or ongoing attack.

How do I manage alerts in defender? ›

You can manage alerts by selecting an alert in the Alerts queue, or the Alerts tab of the Device page for an individual device. Selecting an alert in either of those places brings up the Alert management pane. Watch this video to learn how to use the new Microsoft Defender for Endpoint alert page.

What is the difference between Windows security and Microsoft Defender? ›

Windows Security is built-in to Windows and includes an antivirus program called Microsoft Defender Antivirus. (In early versions of Windows 10, Windows Security is called Windows Defender Security Center).

Is Windows Defender scan enough? ›

Microsoft Defender is a good enough option for basic antivirus protection. It has a very strong firewall and a good number of features for the program and device security.

Is Windows Defender Quick scan enough? ›

In most cases, a quick scan is sufficient and is the recommended option for scheduled scans. A full scan starts by running a quick scan and then continues with a sequential file scan of all mounted fixed disks and removable/network drives (if the full scan is configured to do so).

Does Windows Defender automatically scan files? ›

Microsoft Defender Antivirus regularly scans your device to help keep it safe. We try to do this while you're not using your device so it doesn't interfere with your work.

What is the disadvantage of Microsoft Defender for Identity? ›

Microsoft Defender for Identity Cons

There is no option to remedy an issue directly from the console. If we see an alert, we can't fix it from the console. Instead, we must depend on other Microsoft products, such as MDE. That is a significant drawback.

What is the difference between Defender for identity and identity protection? ›

Defender for Identity also supports integration into the broader Microsoft XDR environment, including Microsoft 365 Defender and Cloud App Security. Azure Active Directory Identity Protection, on the other hand, lives solely in the Azure cloud and combats threats against Azure Active Directory instances.

How often should Windows Defender scan? ›

You can usually customise the schedule, although scanning your entire PC every day is probably overkill, while leaving more than a week between scans is not safe. Antivirus programs often offer two types of scan: a 'quick' scan and a 'deep' or 'full' scan. Set your software to do a full scan once a week.

What is an alert rule? ›

An alert rule monitors your telemetry and captures a signal that indicates something is happening on the specified resource.

What is notification rule? ›

A notification rule is where you configure which events you want users to receive notifications about and specify the targets that receive those notifications. You can send notifications directly to users through Amazon SNS, or through AWS Chatbot clients configured for Slack channels.

What are recording rules? ›

Recording rules allow you to precompute frequently needed or computationally expensive expressions and save their results as a new set of time series. Querying the precomputed result is often much faster than running the original expression every time it is needed.

Why you should turn off all notifications? ›

Notifications are one of the worst parts of smartphones. Simply turning them off allows you to reduce your phone addiction while still having access to all the apps you use. Without notifications, you are in control of when you pick up your phone, rather than your phone shouting for your attention.

Do notifications drain data? ›

Apps refresh in the background to regularly check for notifications. This means, when you get an email, message or Tweet, it's delivered right to your device, whether you're on Wi-Fi or mobile data. So yes, if you're not on Wi-Fi, it will use mobile data.

Do notifications waste data? ›

Apps that use push notifications (such as instant messaging or social media apps) will use cellular data. To turn off push notifications, go to Settings > Notifications. To view the cellular data usage for your apps, tap Settings > Cellular.

What are the two valid types of alerts? ›

There are two alert types, scheduled and real-time. Alert type definitions are based on alert search timing.

What is the difference between alerts and notifications? ›

Alerts are enabled by the user and are triggered by driving events like speeding, harsh braking, and entering/exiting a geofence. Notifications are set up by the user and are triggered by specified alerts to send an email, SMS text, or a push notification via the mobile app.

What are the types of alerts? ›

Let's take a closer look at the different alert colors and what they mean:
  • Amber (AMBER) Alert. The Amber Alert program is the best-known missing persons program in the United States. ...
  • Silver Alert. ...
  • Blue Alert. ...
  • Endangered Missing Persons Alert. ...
  • Camo Alert. ...
  • Clear (CLEAR) Alert.
Jul 13, 2021

How do I create a Windows Defender exception? ›

Go to Start > Settings > Update & Security > Windows Security > Virus & threat protection. Under Virus & threat protection settings, select Manage settings, and then under Exclusions, select Add or remove exclusions. Select Add an exclusion, and then select from files, folders, file types, or process.

How do I add exclusions to endpoint in Microsoft Defender? ›

In the Group Policy Management Editor go to Computer configuration, and select Administrative templates. Expand the tree to Windows components > Microsoft Defender Antivirus > Exclusions. Open the Path Exclusions setting for editing, and add your exclusions. Set the option to Enabled.

Where do I put Microsoft Defender for identity sensor? ›

Add and download a sensor
  • In Microsoft 365 Defender, go to Settings and then Identities.
  • Select the Sensors page, which displays all of your Defender for Identity sensors.
  • Select Add sensor.
  • A pane will open, providing you with a button to download the sensor installer and a generated access key.
Feb 5, 2023

How do I make Windows Defender ask before action? ›

There is no setting in Windows Defender that gives the option to prompt the user to select from a list of possible options when a virus or other malware is detected. You can review the scan logs and you can whitelist files and directories, but these are done manually, and likely after an unwanted detection occurs.

How do I automate Windows Defender? ›

As a global administrator or security administrator, go to the Microsoft 365 Defender portal ( and sign in.
  1. In the navigation pane, choose Settings.
  2. Select Endpoints, then select Advanced features.
  3. Turn on both Automated Investigation and Automatically resolve alerts.
Feb 7, 2023

How do I allow apps to bypass Windows Defender? ›

To allow an item that Microsoft Defender has blocked, use these steps:
  1. Open Windows Security.
  2. Click on Virus & threat protection.
  3. Under the “Current threats” section, click the Protection history option.
  4. Select the file or application you want to allow.
Feb 1, 2023

Should there be exclusions in Windows Defender? ›

Recommendations for defining exclusions

Defining exclusions lowers the protection offered by Microsoft Defender Antivirus. You should always evaluate the risks that are associated with implementing exclusions, and you should only exclude files that you are confident are not malicious.

How do you verify if an endpoint client has automatically excluded an application or directory? ›

  1. Open the SEP client UI.
  2. Click Help > Troubleshooting.
  3. Click Debug Logs at the left side.
  4. Under Symantec Endpoint Protection Debug log setting: click Edit Debug Log Settings.
  5. In the Symantec Endpoint Protection Debug Log Settings dialog enter: ALL.
  6. Click OK, then close Troubleshooting and the SEP client UI.
Dec 21, 2022

How do I whitelist in Microsoft 365 defender? ›

In the Microsoft 365 Defender portal at, go to Policies & rules > Threat Policies > Rules section > Tenant Allow/Block Lists. Or, to go directly to the Tenant Allow/Block List page, use Add.

How do I know if my Defender is scanning? ›

In your System tray click on the ^ to expand the running programs. If you see the shield your Windows Defender is running and active.

How to integrate Defender for Identity with Microsoft Defender for Endpoint? ›

Enable Defender for Identity

In Defender for Cloud Apps, under the settings cog, select Settings. Under Threat Protection, select Microsoft Defender for Identity. Select Enable Microsoft Defender for Identity data integration and then select Save.

Does Windows Defender scan mapped? ›

On any OS, only the network drives that are mapped at system level, are scanned. User-level mapped network drives aren't scanned.

Can Windows Defender be wrong? ›

False positives/negatives can occur with any threat protection solution, including Defender for Endpoint.

Does Windows Defender automatically remove threats? ›

The Windows Defender Offline scan will automatically detect and remove or quarantine malware.

Can Windows Defender detect all viruses? ›

As part of the Windows Security suite, it will search for any files or programs on your computer that can cause harm to it. Defender looks for software threats like viruses and other malware across email, apps, the cloud, and the web.


1. Learn How to Configure Defender for Office 365 for Maximum Security
(Jonathan Edwards)
2. MDE Tutorial -21 - How to Manage Incidents and Alerts in Microsoft Defender for Endpoints
(Harvansh Singh)
3. Operations guidance | Microsoft Defender for Office 365
(Microsoft Security)
4. Protecting cloud apps in Microsoft 365 Defender
(Microsoft Security)
5. Azure Defender, Azure Sentinel, and M365 Defender - Better Together Webinar
(Microsoft Security Community)
6. Anti Spam Policies - Microsoft Defender for Office 365 | Configure Inbound & Outbound Spam policies.
(Office 365 Concepts)
Top Articles
Latest Posts
Article information

Author: Melvina Ondricka

Last Updated: 03/09/2023

Views: 5481

Rating: 4.8 / 5 (48 voted)

Reviews: 95% of readers found this page helpful

Author information

Name: Melvina Ondricka

Birthday: 2000-12-23

Address: Suite 382 139 Shaniqua Locks, Paulaborough, UT 90498

Phone: +636383657021

Job: Dynamic Government Specialist

Hobby: Kite flying, Watching movies, Knitting, Model building, Reading, Wood carving, Paintball

Introduction: My name is Melvina Ondricka, I am a helpful, fancy, friendly, innocent, outstanding, courageous, thoughtful person who loves writing and wants to share my knowledge and understanding with you.