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.


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.

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.


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 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.
7 days ago

How to identify devices that are affected by an alert in the Microsoft 365 Defender portal? ›

In the Microsoft 365 Defender portal, choose Endpoints > Device inventory. Select a device that has alerts, and then run an antivirus scan. Actions, such as antivirus scans, are tracked and are visible on the Device inventory page. To learn more, see Run Microsoft Defender Antivirus scan on devices.

How do I create an antimalware policy in Office 365? ›

Enable or disable custom anti-malware policies

You can't disable the default anti-malware policy. In the Microsoft 365 Defender portal at, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-Malware in the Policies section.

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 are the four categories of reporting found in the Microsoft 365 Defender Portal? ›

For more information, see Permissions in the Microsoft 365 Defender portal.
What permissions are needed to view the Defender for Office 365 reports?
  • Organization Management.
  • Security Administrator.
  • Security Reader.
  • Global Reader.
7 days ago

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 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 to configure determination for an incident from the Microsoft 365 defender portal? ›

You can display this pane from the Manage incident link on the: Alert story page. Properties pane of an incident in the incident queue.
Here are the ways you can manage your incidents:
  1. Edit the incident name.
  2. Add incident tags.
  3. Assign the incident to a user account.
  4. Resolve them.
  5. Specify its classification.
  6. Add comments.
7 days ago

How do I know if Windows Defender is blocking apps? ›

Click on Windows Defender Firewall. From the left pane Allow an app or feature through Windows Defender Firewall. In the allowed apps window, scroll through all the apps. Locate the app you want to review and see if the app is checked.

How do I create a custom DLP policy in Office 365? ›

Use the EAC to create a custom DLP policy without any existing rules
  1. In the EAC, navigate to Compliance management > Data loss prevention. ...
  2. Click the arrow that is beside the Add. ...
  3. On the New custom policy page, complete the following fields: ...
  4. Click Save to finish creating the new policy reference information.
Jan 27, 2023

How can I improve Office 365 security? ›

  1. Get started.
  2. Set up your infrastructure for hybrid work.
  3. Set up secure collaboration.
  4. Deploy threat protection.
  5. Data privacy and data protection.
  6. Microsoft 365 for smaller businesses and campaigns.
Dec 21, 2022

How to bypass anti malware policy in Office 365? ›

Bypass Exchange Online Protection in Office 365

Go to Admin Centers and then choose Exchange. Under Mailflow, select Rules. Click the +. Then add a new rule and select Bypass Spam Filtering from the menu.

How many notifications are too many? ›

As a rule of thumb, do not send more than 3-5 notifications every week. Even then, make sure that the notifications have something relevant for the user.

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.

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 the 5 classifications of reports? ›

Classification of Reports
  • Long and short reports.
  • Internal and external reports.
  • Vertical and lateral reports.
  • Formal and informal reports.
  • Informational and analytical reports.

What are the three phases of Microsoft 365 compliance? ›

Microsoft 365's internal compliance program is designed to ensure security and privacy are considered at all phases of the development process. Each service begins the assurance lifecycle with the execution of three related efforts: security, privacy, and compliance.

What is the difference between Defender 365 and Defender for Endpoint? ›

If you're looking for a comprehensive security solution that includes endpoint protection, Microsoft Defender for Endpoint is the way to go. If you're looking for a productivity suite that includes email, collaboration, and identity management tools, Office 365 is the product you need.

What is the difference between Microsoft Defender and Defender for Endpoint? ›

Microsoft Defender for Endpoint is different to Microsoft Defender antivirus, which is built into all Windows 10 devices. Instead, it offers enterprise security teams incident response and investigation tools and lives as an instance in the Azure cloud.

Which are two main rules categories in Windows Defender firewall? ›

To provide the security you need, the Windows Defender Firewall has a standard set of inbound and outbound rules, which are enabled depending on the location of the connected network.

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 Microsoft Defender good at detecting viruses? ›

It has almost 100% real-time protection rates, according to independent tests. It also has additional features for device protection against malware, such as scanning, app and browser control, and account protection options.

How do I manage security settings in Defender? ›

Access your settings in the Microsoft 365 Defender portal

Go to the Microsoft 365 Defender portal (, and sign in. Select Settings, and then select a category (such as Security center, Microsoft 365 Defender, or Endpoints). In the list of settings, select an item to view or edit.

Which feature is unique to Windows 365? ›

Microsoft 365 Apps for enterprise includes exclusive intelligent capabilities like Ideas in Excel, Researcher in Word, real-time collaboration, Teams as the hub for teamwork, and advanced security features. As a user-based license, you can deploy Office on up to five PCs or Macs, five tablets, and five mobile devices.

What are the three main ways to deploy Office 365? ›

  • Deploy Microsoft 365 Apps from the cloud.
  • Deploy Microsoft 365 Apps from a local source.
  • Deploy with Configuration Manager (current branch)
5 days ago

What 3 Microsoft programs can you use to manage time? ›

Manage tasks and work with Microsoft 365
  • Teams.
  • Outlook.
  • To Do.
  • Planner.
  • Word.
  • Excel.
  • PowerPoint.

What is Windows Defender security alert? ›

What is the Windows Defender security warning? Windows Defender security warning is a type of scareware or a phishing scam. It redirects you to a page that looks like the official Microsoft website, even though its URL suggests otherwise.

What is defender alert? ›

Defender for Endpoint notifies you of possible malicious events, attributes, and contextual information through alerts. A summary of new alerts is displayed and you can access all alerts in the Alerts queue.

What should you use in the Microsoft 365 Defender? ›

Use Microsoft 365 Defender for Identity in your Microsoft 365 Defender XDR solution. Steps for the evaluation of Microsoft 365 Defender for Identity including requirements, enabling or activating the eval, and set up of the pilot or test.

What can Windows Defender detect? ›

Microsoft Defender Antivirus detects and protects against the following kinds of threats:
  • Viruses, malware, and web-based threats on devices.
  • Phishing attempts.
  • Data theft attempts.

Does Windows Defender always detect malware? ›

Like other anti-malware applications, Windows Defender automatically runs in the background, scanning files when they are accessed and before user open them. When a malware is detected, Windows Defender inform you. It won't ask you what you want to do with the malicious software it finds.

How do I know if my Defender for endpoint is running? ›

Troubleshoot onboarding issues
  1. Check that there is a Microsoft Defender for Endpoint Service running in the Processes tab in Task Manager. ...
  2. Check Event Viewer > Applications and Services Logs > Operation Manager to see if there are any errors.
  3. In Services, check if the Microsoft Monitoring Agent is running on the server.
7 days ago

How do I know if Windows Defender is blocking me? ›

How to check if Windows Firewall is blocking a program
  1. Press Windows Key + R to open Run.
  2. Type control and press OK to open Control Panel.
  3. Click on System and Security.
  4. Click on Windows Defender Firewall.
  5. From the left pane Allow an app or feature through Windows Defender Firewall.
Mar 14, 2022

How do I know if Windows Defender is ignored? ›

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.

Is using Microsoft Defender enough? ›

Is Microsoft Defender any good? 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.

What is the purpose of Microsoft 365 Defender? ›

Microsoft Defender for Office 365 is a cloud-based email filtering service that helps protect your organization against advanced threats to email and collaboration tools, like phishing, business email compromise, and malware attacks.

What is the difference between Defender 365 and Defender for endpoint? ›

If you're looking for a comprehensive security solution that includes endpoint protection, Microsoft Defender for Endpoint is the way to go. If you're looking for a productivity suite that includes email, collaboration, and identity management tools, Office 365 is the product you need.

Is Microsoft 365 Defender an EDR? ›

You can continue to set EDR in block mode tenant-wide in the Microsoft 365 Defender portal. EDR in block mode is primarily recommended for devices that are running Microsoft Defender Antivirus in passive mode (a non-Microsoft antivirus solution is installed and active on the device).

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.

Is Microsoft 365 Defender a firewall? ›

Defender for Business includes firewall capabilities through Windows Defender Firewall. Firewall protection helps secure devices by establishing rules that determine what network traffic is permitted to flow to and from devices.


Top Articles
Latest Posts
Article information

Author: Lakeisha Bayer VM

Last Updated: 01/04/2024

Views: 5403

Rating: 4.9 / 5 (49 voted)

Reviews: 88% of readers found this page helpful

Author information

Name: Lakeisha Bayer VM

Birthday: 1997-10-17

Address: Suite 835 34136 Adrian Mountains, Floydton, UT 81036

Phone: +3571527672278

Job: Manufacturing Agent

Hobby: Skimboarding, Photography, Roller skating, Knife making, Paintball, Embroidery, Gunsmithing

Introduction: My name is Lakeisha Bayer VM, I am a brainy, kind, enchanting, healthy, lovely, clean, witty person who loves writing and wants to share my knowledge and understanding with you.