Merge pull request #1172 from MicrosoftDocs/lomayor-mdatp-ah-no-freq

Update documentation for MDATP custom detections

windows/security/threat-protection/TOC.md

@@ -121,7 +121,7 @@
 
 #### [Custom detections]()
 ##### [Understand custom detection rules](microsoft-defender-atp/overview-custom-detections.md)
-##### [Create custom detections rules](microsoft-defender-atp/custom-detection-rules.md)
+##### [Create and manage custom detections rules](microsoft-defender-atp/custom-detection-rules.md)
 
 ### [Management and APIs]()
 #### [Overview of management and APIs](microsoft-defender-atp/management-apis.md)

windows/security/threat-protection/microsoft-defender-atp/custom-detection-rules.md

@@ -1,16 +1,16 @@
 ---
-title: Create custom detection rules in Microsoft Defender ATP
+title: Create and manage custom detection rules in Microsoft Defender ATP
 ms.reviewer: 
-description: Learn how to create custom detections rules based on advanced hunting queries
+description: Learn how to create and manage custom detections rules based on advanced hunting queries
-keywords: create custom detections, detections, advanced hunting, hunt, detect, query
+keywords: custom detections, create, manage, alerts, edit, run on demand, frequency, interval, detection rules, advanced hunting, hunt, query, response actions, mdatp, microsoft defender atp
 search.product: eADQiWindows 10XVcnh
 search.appverid: met150
 ms.prod: w10
 ms.mktglfcycl: deploy
 ms.sitesec: library
 ms.pagetype: security
-ms.author: macapara
+ms.author: lomayor
-author: mjcaparas
+author: lomayor
 ms.localizationpriority: medium
 manager: dansimp
 audience: ITPro
@@ -19,53 +19,86 @@ ms.topic: article
 ---
 
 
-# Create custom detections rules
+# Create and manage custom detections rules
 **Applies to:**
 - [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-Create custom detection rules from [Advanced hunting](overview-hunting.md) queries to automatically check for threat indicators and generate alerts whenever these indicators are found.
+Custom detection rules built from [Advanced hunting](overview-hunting.md) queries let you proactively monitor various events and system states, including suspected breach activity and misconfigured machines. The queries run every 24 hours, generating alerts and taking response actions whenever there are matches.
 
 >[!NOTE]
->To create and manage custom detections, [your role](user-roles.md#create-roles-and-assign-the-role-to-an-azure-active-directory-group) needs to have the **manage security settings** permission.  For the detection rule to work properly and create alerts, the query must return in each row a set of MachineId, ReportId, EventTime which match to an actual event in advanced hunting.
+>To create and manage custom detections, [your role](user-roles.md#create-roles-and-assign-the-role-to-an-azure-active-directory-group) needs to have the **manage security settings** permission.  
 
-1. In the navigation pane, select **Advanced hunting**.
+## Create a custom detection rule
+### 1. Prepare the query.
 
-2. Select an existing query that you'd like to base the monitor on or create a new query.
+In Microsoft Defender Security Center, go to **Advanced hunting** and select an existing query or create a new query. When using an new query, run the query to identify errors and understand possible results.
 
-3. Select **Create detection rule**.
+>[!NOTE]
+>To use a query for a custom detection rule, the query must return the `EventTime`, `MachineId`, and `ReportId` columns in the results. Queries that don’t use the `project` operator to customize results usually return these common columns.
 
-4. Specify the alert details:
+### 2. Create new rule and provide alert details.
 
-    - Alert title
+With the query in the query editor, select **Create detection rule** and specify the following alert details:
-    - Severity
-    - Category
-    - Description
-    - Recommended actions
 
-5. Click **Create**.
+- **Alert title**
+- **Severity**
+- **Category**
+- **Description**
+- **Recommended actions**
 
-> [!TIP]
+For more information about these alert details, [read about managing alerts](manage-alerts.md).
-> TIP #1: Running the query for the first time before saving it can help you find any mistakes or errors and give you a preview of the data you can expect to be returned.<br>
+
-> When a new detection rule is created, it will run for the first time (it might take a few minutes) and raise any alerts created by this rule. After that, the rule will automatically run every 24 hours. <br>
+### 3. Specify actions on files or machines.
-> TIP #2: Since the detection automatically runs every 24 hours, it's best to query data in the last 24 hours.
+Your custom detection rule can automatically take actions on files or machines that are returned by the query.
+
+#### Actions on machines
+These actions are applied to machines in the `MachineId` column of the query results:
+- **Isolate machine** — applies full network isolation, preventing the machine from connecting to any application or service, except for the Microsoft Defender ATP service. [Learn more about machine isolation](respond-machine-alerts.md#isolate-machines-from-the-network)
+- **Collect investigation package** — collects machine information in a ZIP file. [Learn more about the investigation package](respond-machine-alerts.md#collect-investigation-package-from-machines)
+- **Run antivirus scan** — performs a full Windows Defender Antivirus scan on the machine
+- **Initiate investigation** — initiates an [automated investigation](automated-investigations.md) on the machine
+
+#### Actions on files
+These actions are applied to files in the `SHA1` or the `InitiatingProcessSHA1` column of the query results:
+- **Allow/Block** — automatically adds the file to your [custom indicator list](manage-indicators.md) so that it is always allowed to run or blocked from running. You can set the scope of this action so that it is taken only on selected machine groups. This scope is independent of the scope of the rule.
+- **Quarantine file** — deletes the file from its current location and places a copy in quarantine
+
+### 4. Click **Create** to save and turn on the rule.
+When saved, the custom detection rule immediately runs. It runs again every 24 hours to check for matches, generate alerts, and take response actions.
 
 ## Manage existing custom detection rules
-View existing rules in your network, see the last results of each rule, navigate to view all alerts that were created by each rule. You can also modify existing rules.
+In **Settings** > **Custom detections**, 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.
 
-1. In the navigation pane, select **Settings** > **Custom detections**. You'll see all the detections  created in the system.
+### View existing rules
 
-2. Select one of the rules to take any of the following actions:
+To view all existing custom detection rules, navigate to **Settings** > **Custom detections**. The page lists all the rules with the following run information:
-   - Open related alerts - See all the alerts that were raised based to this rule
-   - Run - Run the selected detection immediately. 
 
-   > [!NOTE]
+- **Last run** — when a rule was last run to check for query matches and generate alerts
-   > The next run for the query will be in 24 hours after the last run.
+- **Last run status** — whether a rule ran successfully
-    
+- **Next run** — the next scheduled run
-   - Edit - Modify the settings of the rule.
+- **Status** — whether a rule has been turned on or off
-   - Modify query - View and edit the query itself. 
-   - Turn off - Stop the query from running.
-   - Delete
 
+### View rule details, modify rule, and run rule
+
+To view comprehensive information about a custom detection rule, select the name of rule from the list of rules in **Settings** > **Custom detections**. This opens a page about the custom detection rule with the following information:
+
+- General information about the rule, including the details of the alert, run status, and scope
+- List of triggered alerts
+- List of triggered actions
+
+![Custom detection rule page](images/atp-custom-detection-rule-details.png)<br>
+*Custom detection rule page*
+
+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
+
+>[!TIP]
+>To quickly view information and take action on an item in a table, use the selection column [&#10003;] at the left of the table.
 
 ## Related topic
 - [Custom detections overview](overview-custom-detections.md)

windows/security/threat-protection/microsoft-defender-atp/overview-custom-detections.md

@@ -1,16 +1,16 @@
 ---
-title: Custom detections overview
+title: Overview of custom detections in Microsoft Defender ATP
 ms.reviewer: 
-description: Understand how you can leverage the power of advanced hunting to create custom detections
+description: Understand how you can use Advanced hunting to create custom detections and generate alerts
-keywords: custom detections, detections, advanced hunting, hunt, detect, query
+keywords: custom detections, alerts, detection rules, advanced hunting, hunt, query, response actions, interval, mdatp, microsoft defender atp
 search.product: eADQiWindows 10XVcnh
 search.appverid: met150
 ms.prod: w10
 ms.mktglfcycl: deploy
 ms.sitesec: library
 ms.pagetype: security
-ms.author: macapara
+ms.author: lomayor
-author: mjcaparas
+author: lomayor
 ms.localizationpriority: medium
 manager: dansimp
 audience: ITPro
@@ -23,18 +23,16 @@ ms.topic: conceptual
 **Applies to:**
 - [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
+With custom detections, you can proactively monitor for and respond to various events and system states, including suspected breach activity and misconfigured machines. This is made possible by customizable detection rules that automatically trigger alerts as well as response actions.
 
-Alerts in Microsoft Defender ATP are surfaced through the system based on signals gathered from endpoints. With custom detections, you can create custom queries to monitor events for any kind of behavior such as suspicious events or emerging threats.
+Custom detections work with [Advanced hunting](overview-hunting.md), which provides a powerful, flexible query language that covers a broad set of event and system information from your network. The queries run every 24 hours, generating alerts and taking response actions whenever there are matches.
 
-This can be done by leveraging the power of [Advanced hunting](overview-hunting.md) through the creation of custom detection rules. 
+Custom detections provide:
-Custom detections are queries that run periodically every 24 hours and can be configured so that when the query meets the criteria you set, alerts are created and are surfaced in Microsoft Defender Security Center. These alerts will be treated like any other alert in the system.
+- Alerts from rule-based detections built from Advanced hunting queries
-
+- Automatic response actions that apply to files and machines
-This capability is particularly useful for scenarios when you want to pro-actively prevent threats and be notified quickly of emerging threats.
 
 >[!NOTE]
 >To create and manage custom detections, [your role](user-roles.md#create-roles-and-assign-the-role-to-an-azure-active-directory-group) needs to have the **manage security settings** permission.
 
 ## Related topic
-- [Create custom detection rules](custom-detection-rules.md)
+- [Create and manage custom detection rules](custom-detection-rules.md)
-
-