Merge pull request #2356 from MicrosoftDocs/lomayor-ah-viz

WIP - AH chart/visualization feature

windows/security/threat-protection/TOC.md

@@ -105,6 +105,7 @@
 ### [Advanced hunting]()
 #### [Advanced hunting overview](microsoft-defender-atp/advanced-hunting-overview.md)
 #### [Learn the query language](microsoft-defender-atp/advanced-hunting-query-language.md)
+#### [Work with query results](microsoft-defender-atp/advanced-hunting-query-results.md)
 #### [Use shared queries](microsoft-defender-atp/advanced-hunting-shared-queries.md)
 #### [Advanced hunting schema reference]()
 ##### [Understand the schema](microsoft-defender-atp/advanced-hunting-schema-reference.md)

windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-overview.md

@@ -1,7 +1,7 @@
 ---
-title: Overview of advanced hunting
+title: Overview of advanced hunting in Microsoft Defender ATP
 description: Use threat hunting capabilities in Microsoft Defender ATP to build queries that find threats and weaknesses in your network
-keywords: advanced hunting, threat hunting, cyber threat hunting, mdatp, windows defender atp, wdatp search, query, telemetry, custom detections, schema, kusto
+keywords: advanced hunting, threat hunting, cyber threat hunting, mdatp, windows defender atp, wdatp, search, query, telemetry, custom detections, schema, kusto
 search.product: eADQiWindows 10XVcnh
 search.appverid: met150
 ms.prod: w10
@@ -15,7 +15,6 @@ manager: dansimp
 audience: ITPro
 ms.collection: M365-security-compliance 
 ms.topic: article
-ms.date: 10/08/2019
 ---
 
 # Proactively hunt for threats with advanced hunting
@@ -39,38 +38,19 @@ You can also go through each of the following steps to ramp up your advanced hun
 | Learning goal | Description | Resource |
 |--|--|--|
 | **Get a feel for the language** | Advanced hunting is based on the [Kusto query language](https://docs.microsoft.com/azure/kusto/query/), supporting the same syntax and operators. Start learning the query language by running your first query. | [Query language overview](advanced-hunting-query-language.md) |
+| **Learn how to use the query results** | Learn about charts and various ways you can view or export your results. Explore how you can quickly tweak queries and drill down to get richer information. | [Work with query results](advanced-hunting-query-results.md) |
 | **Understand the schema** | Get a good, high-level understanding of the tables in the schema and their columns. This will help you determine where to look for data and how to construct your queries. | [Schema reference](advanced-hunting-schema-reference.md) |
 | **Use predefined queries** | Explore collections of predefined queries covering different threat hunting scenarios. | [Shared queries](advanced-hunting-shared-queries.md) |
-| **Learn about custom detections** | Understand how you can use advanced hunting queries to trigger alerts and apply response actions automatically. | [Custom detections overview](overview-custom-detections.md) |  
+| **Learn about custom detections** | Understand how you can use advanced hunting queries to trigger alerts and apply response actions automatically. | - [Custom detections overview](overview-custom-detections.md)<br>- [Custom detection rules](custom-detection-rules.md) |  
 
 ## Get help as you write queries
 Take advantage of the following functionality to write queries faster:
-- **Autosuggest** — as you write queries, advanced hunting provides suggestions. 
+- **Autosuggest** — as you write queries, advanced hunting provides suggestions from IntelliSense. 
 - **Schema reference** — a schema reference that includes the list of tables and their columns is provided next to your working area. For more information, hover over an item. Double-click an item to insert it to the query editor.
 
-## Drilldown from query results
-To view more information about entities, such as machines, files, users, IP addresses, and URLs, in your query results, simply click the entity identifier. This opens a detailed profile page for the selected entity in Microsoft Defender Security Center.
-
-## Tweak your queries from the results
-Right-click a value in the result set to quickly enhance your query. You can use the options to:
-
-- Explicitly look for the selected value (`==`)
-- Exclude the selected value from the query (`!=`)
-- Get more advanced operators for adding the value to your query, such as `contains`, `starts with` and `ends with` 
-
-![Image of Microsoft Defender ATP advanced hunting result set](images/atp-advanced-hunting-results-filter.png)
-
-## Filter the query results
-The filters displayed to the right provide a summary of the result set. Each column has its own section that lists the distinct values found for that column and the number of instances.
-
-Refine your query by selecting the "+" or "-" buttons next to the values that you want to include or exclude.
-
-![Image of advanced hunting filter](images/atp-filter-advanced-hunting.png)
-
-Once you apply the filter to modify the query and then run the query, the results are updated accordingly.
-
 ## Related topics
 - [Learn the query language](advanced-hunting-query-language.md)
+- [Work with query results](advanced-hunting-query-results.md)
 - [Use shared queries](advanced-hunting-shared-queries.md)
 - [Understand the schema](advanced-hunting-schema-reference.md)
 - [Apply query best practices](advanced-hunting-best-practices.md)

windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-query-language.md

@@ -137,6 +137,7 @@ For detailed information about the query language, see [Kusto query language doc
 
 ## Related topics
 - [Advanced hunting overview](advanced-hunting-overview.md)
+- [Work with query results](advanced-hunting-query-results.md)
 - [Understand the schema](advanced-hunting-schema-reference.md)
 - [Apply query best practices](advanced-hunting-best-practices.md)
 

windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-query-results.md

@@ -0,0 +1,142 @@
+---
+title: Work with advanced hunting query results in Microsoft Defender ATP
+description: Make the most of the query results returned by advanced hunting in Microsoft Defender ATP
+keywords: advanced hunting, threat hunting, cyber threat hunting, mdatp, windows defender atp, wdatp search, query, telemetry, custom detections, schema, kusto, visualization, chart, filters, drill down
+search.product: eADQiWindows 10XVcnh
+search.appverid: met150
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: lomayor
+author: lomayor
+ms.localizationpriority: medium
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance 
+ms.topic: article
+---
+
+# Work with advanced hunting query results
+
+**Applies to:**
+- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-advancedhunting-abovefoldlink)
+
+[!INCLUDE [Prerelease information](../../includes/prerelease.md)]
+
+While you can construct your [advanced hunting](advanced-hunting-overview.md) queries to return very precise information, you can also work with the query results to gain further insight and investigate specific activities and indicators. You can take the following actions on your query results:
+
+- View results as a table or chart
+- Export tables and charts
+- Drill down to detailed entity information
+- Tweak your queries directly from the results or apply filters
+
+## View query results as a table or chart
+By default, advanced hunting displays query results as tabular data. You can also display the same data as a chart. Advanced hunting supports the following views:
+
+| View type | Description |
+| -- | -- |
+| **Table** | Displays the query results in tabular format |
+| **Column chart** | Renders a series of unique items on the x-axis as vertical bars whose heights represent numeric values from another field |
+| **Stacked column chart** | Renders a series of unique items on the x-axis as stacked vertical bars whose heights represent numeric values from one or more other fields |
+| **Pie chart** | Renders sectional pies representing unique items. The size of each pie represents numeric values from another field. |
+| **Donut chart** | Renders sectional arcs representing unique items. The length of each arc represents numeric values from another field. |
+| **Line chart** | Plots numeric values for a series of unique items and connects the plotted values |
+| **Scatter chart** | Plots numeric values for a series of unique items |
+| **Area chart** | Plots numeric values for a series of unique items and fills the sections below the plotted values |
+
+### Construct queries for effective charts
+When rendering charts, advanced hunting automatically identifies columns of interest and the numeric values to aggregate. To get meaningful charts, construct your queries to return the specific values you want to see visualized. Here are some sample queries and the resulting charts.
+
+#### Alerts by severity
+Use the `summarize` operator to obtain a numeric count of the values you want to chart. The query below uses the `summarize` operator to get the number of alerts by severity.
+
+```kusto
+DeviceAlertEvents
+| summarize Total = count() by Severity
+```
+When rendering the results, a column chart displays each severity value as a separate column:
+
+![Image of advanced hunting query results displayed as a column chart](images/advanced-hunting-column-chart.jpg)
+*Query results for alerts by severity displayed as a column chart*
+
+#### Alert severity by operating system
+You could also use the `summarize` operator to prepare results for charting values from multiple fields. For example, you might want to understand how alert severities are distributed across operating systems (OS). 
+
+The query below uses a `join` operator to pull in OS information from the `DeviceInfo` table, and then uses `summarize` to count values in both the `OSPlatform` and `Severity` columns:
+
+```kusto
+DeviceAlertEvents
+| join DeviceInfo on DeviceId
+| summarize Count = count() by OSPlatform, Severity
+```
+These results are best visualized using a stacked column chart:
+
+![Image of advanced hunting query results displayed as a stacked chart](images/advanced-hunting-stacked-chart.jpg)
+*Query results for alerts by OS and severity displayed as a stacked chart*
+
+#### Top ten machine groups with alerts
+If you're dealing with a list of values that isn’t finite, you can use the `Top` operator to chart only the values with the most instances. For example, to get the top ten machine groups with the most alerts, use the query below:
+
+```kusto
+DeviceAlertEvents
+| join DeviceInfo on DeviceId
+| summarize Count = count() by MachineGroup
+| top 10 by Count
+```
+Use the pie chart view to effectively show distribution across the top groups:
+
+![Image of advanced hunting query results displayed as a pie chart](images/advanced-hunting-pie-chart.jpg)
+*Pie chart showing distribution of alerts across machine groups*
+
+#### Malware detections over time
+Using the `summarize` operator with the `bin()` function, you can check for events involving a particular indicator over time. The query below counts detections of an EICAR test file at 30 minute intervals to show spikes in detections of that file:
+
+```kusto
+DeviceEvents
+| where ActionType == "AntivirusDetection"
+| where SHA1 == "3395856ce81f2b7382dee72602f798b642f14140"
+| summarize Detections = count() by bin(Timestamp, 30m)
+```
+The line chart below clearly highlights time periods with more detections of the test malware: 
+
+![Image of advanced hunting query results displayed as a line chart](images/advanced-hunting-line-chart.jpg)
+*Line chart showing the number of detections of a test malware over time*
+
+
+## Export tables and charts
+After running a query, select **Export** to save the results to local file. Your chosen view determines how the results are exported:
+
+- **Table view** — the query results are exported in tabular form as a Microsoft Excel workbook
+- **Any chart** — the query results are exported as a JPEG image of the rendered chart
+
+## Drill down from query results
+To view more information about entities, such as machines, files, users, IP addresses, and URLs, in your query results, simply click the entity identifier. This opens a detailed profile page for the selected entity.
+
+## Tweak your queries from the results
+Right-click a value in the result set to quickly enhance your query. You can use the options to:
+
+- Explicitly look for the selected value (`==`)
+- Exclude the selected value from the query (`!=`)
+- Get more advanced operators for adding the value to your query, such as `contains`, `starts with` and `ends with` 
+
+![Image of advanced hunting result set](images/advanced-hunting-results-filter.png)
+
+## Filter the query results
+The filters displayed to the right provide a summary of the result set. Each column has its own section that lists the distinct values found for that column and the number of instances.
+
+Refine your query by selecting the `+` or `-` buttons on the values that you want to include or exclude and then selecting **Run query**.
+
+![Image of advanced hunting filter](images/advanced-hunting-filter.png)
+
+Once you apply the filter to modify the query and then run the query, the results are updated accordingly.
+
+## Related topics
+- [Advanced hunting overview](advanced-hunting-overview.md)
+- [Learn the query language](advanced-hunting-query-language.md)
+- [Use shared queries](advanced-hunting-shared-queries.md)
+- [Understand the schema](advanced-hunting-schema-reference.md)
+- [Apply query best practices](advanced-hunting-best-practices.md)
+- [Custom detections overview](overview-custom-detections.md)

windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-schema-reference.md

@@ -55,4 +55,5 @@ Table and column names are also listed within the Microsoft Defender Security Ce
 
 ## Related topics
 - [Advanced hunting overview](advanced-hunting-overview.md)
+- [Work with query results](advanced-hunting-query-results.md)
 - [Learn the query language](advanced-hunting-query-language.md)

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

@@ -63,14 +63,14 @@ With the query in the query editor, select **Create detection rule** and specify
 For more information about how alert details are displayed, [read about the alert queue](alerts-queue.md).
 
 #### Rule frequency
-When saved, custom detections rules immediately run. They then run again at fixed intervals based on the frequency you choose. Rules that run less frequently will have longer lookback durations:
+When saved, a new or edited custom detection rule immediately runs and checks for matches from the past 30 days of data. The rule then runs again at fixed intervals and lookback durations based on the frequency you choose:
 
-- **Every 24 hours** — checks data from the past 30 days
-- **Every 12 hours** — checks data from the past 24 hours
-- **Every 3 hours** — checks data from the past 6 hours
-- **Every hour** — checks data from the past 2 hours
+- **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 24 hours
+- **Every 3 hours** — runs every 3 hours, checking data from the past 6 hours
+- **Every hour** — runs hourly, checking data from the past 2 hours
 
-Whenever a rule runs, similar detections on the same machine could be aggregated into fewer alerts, so running a rule less frequently can generate fewer alerts. Select the frequency that matches how closely you want to monitor detections, and consider your organization's capacity to respond to the alerts.
+Select the frequency that matches how closely you want to monitor detections, and consider your organization's capacity to respond to the alerts.
 
 ### 3. Specify actions on files or machines.
 Your custom detection rule can automatically take actions on files or machines that are returned by the query.
@@ -88,7 +88,7 @@ These actions are applied to files in the `SHA1` or the `InitiatingProcessSHA1`
 - **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.
+After reviewing the rule, click **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.
 
 ## Manage existing custom detection 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.