Skip to content

Commit 94bedff

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #198318 from yelevin/yelevin/update-trigger
Update trigger documentation
2 parents cc53594 + f260f78 commit 94bedff

23 files changed

+289
-50
lines changed

‎articles/sentinel/TOC.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -298,7 +298,7 @@
298298
href: bookmarks.md
299299
- name: Hunt with livestream
300300
href: livestream.md
301-
- name: Investigate and respond
301+
- name: Investigate incidents
302302
items:
303303
- name: Investigate incidents
304304
href: investigate-cases.md
@@ -312,6 +312,10 @@
312312
href: customize-entity-activities.md
313313
- name: Collaborate in Microsoft Teams
314314
href: collaborate-in-microsoft-teams.md
315+
- name: Automate responses
316+
items:
317+
- name: Create automation rules
318+
href: create-manage-use-automation-rules.md
315319
- name: Authenticate playbooks to Microsoft Sentinel
316320
href: authenticate-playbooks-to-sentinel.md
317321
- name: Use triggers and actions in playbooks

‎articles/sentinel/automate-incident-handling-with-automation-rules.md

Lines changed: 107 additions & 31 deletions
Large diffs are not rendered by default.

‎articles/sentinel/automation.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Microsoft Sentinel, in addition to being a Security Information and Event Manage
2626

2727
## Automation rules
2828

29-
Automation rules (now generally available!) allow users to centrally manage the automation of incident handling. Besides letting you assign playbooks to incidents (not just to alerts as before), automation rules also allow you to automate responses for multiple analytics rules at once, automatically tag, assign, or close incidents without the need for playbooks, and control the order of actions that are executed. Automation rules will streamline automation use in Microsoft Sentinel and will enable you to simplify complex workflows for your incident orchestration processes.
29+
Automation rules (now generally available!) allow users to centrally manage the automation of incident handling. Besides letting you assign playbooks to incidents (not just to alerts as before), automation rules also allow you to automate responses for multiple analytics rules at once, automatically tag, assign, or close incidents without the need for playbooks, and control the order of actions that are executed. Automation rules also allow you to apply automations when an incident is **updated** (now in **Preview**), as well as when it's created. This new capability will further streamline automation use in Microsoft Sentinel and will enable you to simplify complex workflows for your incident orchestration processes.
3030

3131
Learn more with this [complete explanation of automation rules](automate-incident-handling-with-automation-rules.md).
3232

@@ -44,4 +44,5 @@ In this document, you learned how Microsoft Sentinel uses automation to help you
4444

4545
- To learn about automation of incident handling, see [Automate incident handling in Microsoft Sentinel](automate-incident-handling-with-automation-rules.md).
4646
- To learn more about advanced automation options, see [Automate threat response with playbooks in Microsoft Sentinel](automate-responses-with-playbooks.md).
47-
- For help in implementing automation rules and playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).
47+
- To get started creating automation rules, see [Create and use Microsoft Sentinel automation rules to manage incidents](create-manage-use-automation-rules.md)
48+
- For help in implementing advanced automation with playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).

‎articles/sentinel/create-manage-use-automation-rules.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: Create and use Microsoft Sentinel automation rules to manage incidents | Microsoft Docs
3+
description: This article explains how to create and use automation rules in Microsoft Sentinel to manage and handle incidents, in order to maximize your SOC's efficiency and effectiveness in response to security threats.
4+
author: yelevin
5+
ms.topic: how-to
6+
ms.date: 05/23/2022
7+
ms.author: yelevin
8+
---
9+
10+
# Create and use Microsoft Sentinel automation rules to manage incidents
11+
12+
[!INCLUDE [Banner for top of topics](./includes/banner.md)]
13+
14+
This article explains how to create and use automation rules in Microsoft Sentinel to manage and handle incidents, in order to maximize your SOC's efficiency and effectiveness in response to security threats.
15+
16+
In this article you'll learn how to define the triggers and conditions that will determine when your automation rule will run, the various actions that you can have the rule perform, and the remaining features and functionalities.
17+
18+
## Design your automation rule
19+
20+
### Determine the scope
21+
22+
The first step in designing and defining your automation rule is figuring out which incidents you want it to apply to. This determination will directly impact how you create the rule.
23+
24+
You also want to determine your use case. What are you trying to accomplish with this automation? Consider the following options:
25+
26+
- Suppress noisy incidents (see [this article on handling false positives](false-positives.md#add-exceptions-by-using-automation-rules) instead)
27+
- Triage new incidents by changing their status from New to Active and assigning an owner.
28+
- Tag incidents to classify them.
29+
- Escalate an incident by assigning a new owner.
30+
- Close resolved incidents, specifying a reason and adding comments.
31+
- Analyze the incident's contents (alerts, entities, and other properties) and take further action by calling a playbook.
32+
33+
### Determine the trigger
34+
35+
Do you want this automation to be activated when new incidents are created? Or any time an incident gets updated?
36+
37+
Automation rules are triggered **when an incident is created or updated** (the update trigger is now in **Preview**). Recall that incidents are created from alerts by analytics rules, of which there are several types, as explained in [Detect threats with built-in analytics rules in Microsoft Sentinel](detect-threats-built-in.md).
38+
39+
The following table shows the different possible ways that incidents can be created or updated that will cause an automation rule to run.
40+
41+
| Trigger type | Events that cause the rule to run |
42+
| --------- | ------------ |
43+
| **When incident is created** | - A new incident is created by an analytics rule.<br>- An incident is ingested from Microsoft 365 Defender.<br>- A new incident is created manually. |
44+
| **When incident is updated**<br>(Preview) | - An incident's status is changed (closed/reopened/triaged).<br>- An incident's owner is assigned or changed.<br>- An incident's severity is raised or lowered.<br>- Alerts are added to an incident.<br>- Comments, tags, or tactics are added to an incident. |
45+
46+
## Create your automation rule
47+
48+
Most of the following instructions apply to any and all use cases for which you'll create automation rules.
49+
50+
- For the use case of suppressing noisy incidents, see [this article on handling false positives](false-positives.md#add-exceptions-by-using-automation-rules).
51+
- For creating an automation rule that will apply to a single specific analytics rule, see [this article on configuring automated response in analytics rules](detect-threats-custom.md#set-automated-responses-and-create-the-rule).
52+
53+
1. From the **Automation** blade in the Microsoft Sentinel navigation menu, select **Create** from the top menu and choose **Automation rule**.
54+
55+
:::image type="content" source="./media/create-manage-use-automation-rules/add-rule-automation.png" alt-text="Screenshot of creating a new automation rule in the Automation blade." lightbox="./media/create-manage-use-automation-rules/add-rule-automation.png":::
56+
57+
1. The **Create new automation rule** panel opens. Enter a name for your rule.
58+
59+
:::image type="content" source="media/create-manage-use-automation-rules/create-automation-rule.png" alt-text="Screenshot of Create new automation rule wizard.":::
60+
61+
1. If you want the automation rule to take effect only on certain analytics rules, specify which ones by modifying the **If Analytics rule name** condition.
62+
63+
### Choose your trigger
64+
65+
From the **Trigger** drop-down, select **When incident is created** or **When incident is updated (Preview)** according to what you decided when designing your rule.
66+
67+
:::image type="content" source="media/create-manage-use-automation-rules/select-trigger.png" alt-text="Screenshot of selecting the incident create or incident update trigger.":::
68+
69+
### Add conditions
70+
71+
Add any other conditions you want this automation rule's activation to depend on. Select **+ Add condition** and choose conditions from the drop-down list. The list of conditions is populated by incident property and [entity property](entities-reference.md) fields.
72+
73+
1. Select a property from the first drop-down box on the left. You can begin typing any part of a property name in the search box to dynamically filter the list, so you can find what you're looking for quickly.
74+
:::image type="content" source="media/create-manage-use-automation-rules/filter-list.png" alt-text="Screenshot of typing in a search box to filter the list of choices.":::
75+
76+
1. Select an operator from the next drop-down box to the right.
77+
:::image type="content" source="media/create-manage-use-automation-rules/select-operator.png" alt-text="Screenshot of selecting a condition operator for automation rules.":::
78+
79+
The list of operators you can choose from varies according to the selected trigger and property. Here's a summary of what's available:
80+
81+
#### Conditions available with the create trigger
82+
83+
| Property | Operator set |
84+
| -------- | -------- |
85+
| - Title<br>- Description<br>- Tag<br>- All listed entity properties | - Equals/Does not equal<br>- Contains/Does not contain<br>- Starts with/Does not start with<br>- Ends with/Does not end with |
86+
| - Severity<br>- Status<br>- Incident provider | - Equals/Does not equal |
87+
| - Tactics<br>- Alert product names | - Contains/Does not contain |
88+
89+
#### Conditions available with the update trigger
90+
91+
| Property | Operator set |
92+
| -------- | -------- |
93+
| - Title<br>- Description<br>- Tag<br>- All listed entity properties | - Equals/Does not equal<br>- Contains/Does not contain<br>- Starts with/Does not start with<br>- Ends with/Does not end with |
94+
| - Tag (in addition to above)<br>- Alerts<br>- Comments | - Added |
95+
| - Severity<br>- Status | - Equals/Does not equal<br>- Changed<br>- Changed from<br>- Changed to |
96+
| - Owner | - Changed |
97+
| - Incident provider<br>- Updated by | - Equals/Does not equal |
98+
| - Tactics | - Contains/Does not contain<br>- Added |
99+
| - Alert product names | - Contains/Does not contain |
100+
101+
1. Enter a value in the text box on the right. Depending on the property you chose, this might be a drop-down list from which you would select the values you choose. You might also be able to add several values by selecting the icon to the right of the text box (highlighted by the red arrow below).
102+
103+
:::image type="content" source="media/create-manage-use-automation-rules/add-values-to-condition.png" alt-text="Screenshot of adding values to your condition in automation rules.":::
104+
105+
### Add actions
106+
107+
Choose the actions you want this automation rule to take. Available actions include **Assign owner**, **Change status**, **Change severity**, **Add tags**, and **Run playbook**. You can add as many actions as you like.
108+
109+
:::image type="content" source="media/create-manage-use-automation-rules/select-action.png" alt-text="Screenshot of list of actions to select in automation rule.":::
110+
111+
If you add a **Run playbook** action, you will be prompted to choose from the drop-down list of available playbooks.
112+
113+
- Only playbooks that start with the **incident trigger** can be run from automation rules, so only they will appear in the list.
114+
115+
- <a name="explicit-permissions"></a>Microsoft Sentinel must be granted explicit permissions in order to run playbooks based on the incident trigger. If a playbook appears "grayed out" in the drop-down list, it means Sentinel does not have permission to that playbook's resource group. Click the **Manage playbook permissions** link to assign permissions.
116+
117+
In the **Manage permissions** panel that opens up, mark the check boxes of the resource groups containing the playbooks you want to run, and click **Apply**.
118+
:::image type="content" source="./media/tutorial-respond-threats-playbook/manage-permissions.png" alt-text="Manage permissions":::
119+
120+
You yourself must have **owner** permissions on any resource group to which you want to grant Microsoft Sentinel permissions, and you must have the **Logic App Contributor** role on any resource group containing playbooks you want to run.
121+
122+
- If you don't yet have a playbook that will take the action you have in mind, [create a new playbook](tutorial-respond-threats-playbook.md). You will have to exit the automation rule creation process and restart it after you have created your playbook.
123+
124+
### Finish creating your rule
125+
126+
1. Set an **expiration date** for your automation rule if you want it to have one.
127+
128+
1. Enter a number under **Order** to determine where in the sequence of automation rules this rule will run.
129+
130+
1. Click **Apply**. You're done!
131+
132+
## Audit automation rule activity
133+
134+
Find out what automation rules may have done to a given incident. You have a full record of incident chronicles available to you in the *SecurityIncident* table in the **Logs** blade. Use the following query to see all your automation rule activity:
135+
136+
```kusto
137+
SecurityIncident
138+
| where ModifiedBy contains "Automation"
139+
```
140+
141+
## Automation rules execution
142+
143+
Automation rules are run sequentially, according to the order you determine. Each automation rule is executed after the previous one has finished its run. Within an automation rule, all actions are run sequentially in the order in which they are defined.
144+
145+
Playbook actions within an automation rule may be treated differently under some circumstances, according to the following criteria:
146+
147+
| Playbook run time | Automation rule advances to the next action... |
148+
| ----------------- | --------------------------------------------------- |
149+
| Less than a second | Immediately after playbook is completed |
150+
| Less than two minutes | Up to two minutes after playbook began running,<br>but no more than 10 seconds after the playbook is completed |
151+
| More than two minutes | Two minutes after playbook began running,<br>regardless of whether or not it was completed |
152+
|
153+
154+
## Next steps
155+
156+
In this document, you learned how to use automation rules to manage your Microsoft Sentinel incidents queue and implement some basic incident-handling automation.
157+
158+
- To learn more about advanced automation options, see [Automate threat response with playbooks in Microsoft Sentinel](automate-responses-with-playbooks.md).
159+
- For help in implementing automation rules and playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).

‎articles/sentinel/detect-threats-custom.md

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,6 @@ In the **Set rule logic** tab, you can either write a query directly in the **Ru
8484
8585
### Alert enrichment
8686
87-
> [!IMPORTANT]
88-
> The alert enrichment features are currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
89-
9087
- Use the **Entity mapping** configuration section to map parameters from your query results to Microsoft Sentinel-recognized entities. Entities enrich the rules' output (alerts and incidents) with essential information that serves as the building blocks of any investigative processes and remedial actions that follow. They are also the criteria by which you can group alerts together into incidents in the **Incident settings** tab.
9188
9289
Learn more about [entities in Microsoft Sentinel](entities.md).
@@ -144,9 +141,6 @@ If you see that your query would trigger too many or too frequent alerts, you ca
144141
145142
### Event grouping and rule suppression
146143
147-
> [!IMPORTANT]
148-
> Event grouping is currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
149-
150144
- Under **Event grouping**, choose one of two ways to handle the grouping of **events** into **alerts**:
151145
152146
- **Group all events into a single alert** (the default setting). The rule generates a single alert every time it runs, as long as the query returns more results than the specified **alert threshold** above. The alert includes a summary of all the events returned in the results.
@@ -181,9 +175,6 @@ If you see that your query would trigger too many or too frequent alerts, you ca
181175
182176
In the **Incident Settings** tab, you can choose whether and how Microsoft Sentinel turns alerts into actionable incidents. If this tab is left alone, Microsoft Sentinel will create a single, separate incident from each and every alert. You can choose to have no incidents created, or to group several alerts into a single incident, by changing the settings in this tab.
183177
184-
> [!IMPORTANT]
185-
> The incident settings tab is currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
186-
187178
For example:
188179
189180
:::image type="content" source="media/tutorial-detect-threats-custom/incident-settings-tab.png" alt-text="Define the incident creation and alert grouping settings":::
@@ -219,9 +210,15 @@ In the **Alert grouping** section, if you want a single incident to be generated
219210
## Set automated responses and create the rule
220211
221212
1. In the **Automated responses** tab, you can set automation based on the alert or alerts generated by this analytics rule, or based on the incident created by the alerts.
213+
222214
- For alert-based automation, select from the drop-down list under **Alert automation** any playbooks you want to run automatically when an alert is generated.
223-
- For incident-based automation, select or create an automation rule under **Incident automation (preview)**. You can call playbooks (those based on the **incident trigger**) from these automation rules, as well as automate triage, assignment, and closing.
215+
216+
- For incident-based automation, the grid displayed under **Incident automation** shows the automation rules that already apply to this analytics rule (by virtue of it meeting the conditions defined in those rules). You can edit any of these by selecting the ellipsis at the end of each row. Or, you can [create a new automation rule](create-manage-use-automation-rules.md).
217+
218+
You can call playbooks (those based on the **incident trigger**) from these automation rules, as well as automate triage, assignment, and closing.
219+
224220
- For more information and instructions on creating playbooks and automation rules, see [Automate threat responses](tutorial-respond-threats-playbook.md#automate-threat-responses).
221+
225222
- For more information about when to use the **alert trigger** or the **incident trigger**, see [Use triggers and actions in Microsoft Sentinel playbooks](playbook-triggers-actions.md#microsoft-sentinel-triggers-summary).
226223
227224
:::image type="content" source="media/tutorial-detect-threats-custom/automated-response-tab.png" alt-text="Define the automated response settings":::

0 commit comments

Comments
 (0)