Create and use Microsoft Sentinel automation rules to manage response

Important

Some features of automation rules are currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Features in preview will be so indicated when they are mentioned throughout this article.

This article explains how to create and use automation rules in Microsoft Sentinel to manage and orchestrate threat response, in order to maximize your SOC's efficiency and effectiveness.

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.

Design your automation rule

Determine the scope

The first step in designing and defining your automation rule is figuring out which incidents (or alerts, in preview) you want it to apply to. This determination will directly impact how you create the rule.

You also want to determine your use case. What are you trying to accomplish with this automation? Consider the following options:

  • Suppress noisy incidents (see this article on handling false positives instead)
  • Triage new incidents by changing their status from New to Active and assigning an owner.
  • Tag incidents to classify them.
  • Escalate an incident by assigning a new owner.
  • Close resolved incidents, specifying a reason and adding comments.
  • Analyze the incident's contents (alerts, entities, and other properties) and take further action by calling a playbook.
  • (Preview) Handle or respond to an alert without an associated incident.

Determine the trigger

Do you want this automation to be activated when new incidents (or alerts, in preview) are created? Or any time an incident gets updated?

Automation rules are triggered when an incident is created or updated (the update trigger is now in Preview) or when an alert is created (also in Preview). Recall that incidents include alerts, and that both alerts and incidents are created by analytics rules, of which there are several types, as explained in Detect threats with built-in analytics rules in Microsoft Sentinel.

The following table shows the different possible scenarios that will cause an automation rule to run.

Trigger type Events that cause the rule to run
When incident is created - A new incident is created by an analytics rule.
- An incident is ingested from Microsoft 365 Defender.
- A new incident is created manually.
When incident is updated
(Preview)
- An incident's status is changed (closed/reopened/triaged).
- An incident's owner is assigned or changed.
- An incident's severity is raised or lowered.
- Alerts are added to an incident.
- Comments, tags, or tactics are added to an incident.
When alert is created
(Preview)
- An alert is created by a scheduled analytics rule.

Create your automation rule

Most of the following instructions apply to any and all use cases for which you'll create automation rules.

  1. From the Automation blade in the Microsoft Sentinel navigation menu, select Create from the top menu and choose Automation rule.

    Screenshot of creating a new automation rule in the Automation blade.

  2. The Create new automation rule panel opens. Enter a name for your rule.

    Screenshot of Create new automation rule wizard.

  3. 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.

Choose your trigger

From the Trigger drop-down, select When incident is created, When incident is updated (Preview), or When alert is created (Preview), according to what you decided when designing your rule.

Screenshot of selecting the incident create or incident update trigger.

Add conditions (incidents only)

Add any other conditions you want this automation rule's activation to depend on. You now have two ways to add conditions:

  • AND conditions: individual conditions that will be evaluated as a group. The rule will execute if all the conditions of this type are met. This type of condition will be explained below.

  • OR conditions (also known as condition groups, now in Preview): groups of conditions, each of which will be evaluated independently. The rule will execute if one or more groups of conditions are true. To learn how to work with these complex types of conditions, see Add advanced conditions to automation rules.

Select the + Add expander and choose Condition (And) from the drop-down list. The list of conditions is populated by incident property and entity property fields.

Screenshot of conditions section of automation rule wizard. Screenshot of menu with types of conditions to add to automation rules.

  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. Screenshot of typing in a search box to filter the list of choices.

  2. Select an operator from the next drop-down box to the right. Screenshot of selecting a condition operator for automation rules.

    The list of operators you can choose from varies according to the selected trigger and property. Here's a summary of what's available:

    Conditions available with the create trigger

    Property Operator set
    - Title
    - Description
    - Tag
    - All listed entity properties
    - Equals/Does not equal
    - Contains/Does not contain
    - Starts with/Does not start with
    - Ends with/Does not end with
    - Severity
    - Status
    - Incident provider
    - Custom details key (Preview)
    - Equals/Does not equal
    - Tactics
    - Alert product names
    - Custom details value (Preview)
    - Contains/Does not contain

    Conditions available with the update trigger

    Property Operator set
    - Title
    - Description
    - Tag
    - All listed entity properties
    - Equals/Does not equal
    - Contains/Does not contain
    - Starts with/Does not start with
    - Ends with/Does not end with
    - Tag (in addition to above)
    - Alerts
    - Comments
    - Added
    - Severity
    - Status
    - Equals/Does not equal
    - Changed
    - Changed from
    - Changed to
    - Owner - Changed
    - Incident provider
    - Updated by
    - Custom details key (Preview)
    - Equals/Does not equal
    - Tactics - Contains/Does not contain
    - Added
    - Alert product names
    - Custom details value (Preview)
    - Contains/Does not contain
  3. 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).

    Screenshot of adding values to your condition in automation rules.

Again, for setting complex Or conditions with different fields, see Add advanced conditions to automation rules.

Conditions based on custom details (Preview)

You can set the value of a custom detail surfaced in an incident as a condition of an automation rule. Recall that custom details are data points in raw event log records that can be surfaced and displayed in alerts and the incidents generated from them. Through custom details you can get to the actual relevant content in your alerts without having to dig through query results.

To add a condition based on a custom detail, take the following steps:

  1. Create a new automation rule as described above.

  2. Add a condition or a condition group.

  3. Select Custom details key (Preview) from the properties drop-down list. Select Equals or Does not equal from the operators drop-down list.

    For the custom details condition, the values in the last drop-down list come from the custom details that were surfaced in all the analytics rules listed in the first condition. Select the custom detail you want to use as a condition.

    Screenshot of adding a custom detail key as a condition.

  4. You've now chosen the field you want to evaluate for this condition. Now you have to specify the value appearing in that field that will make this condition evaluate to true.
    Select + Add item condition.

    Screenshot of selecting add item condition for automation rules.

    The value condition line appears below.

    Screenshot of the custom detail value field appearing.

  5. Select Contains or Does not contain from the operators drop-down list. In the text box to the right, enter the value for which you want the condition to evaluate to true.

    Screenshot of the custom detail value field filled in.

In this example, if the incident has the custom detail DestinationEmail, and if the value of that detail is pwned@bad-botnet.com, the actions defined in the automation rule will run.

Add actions

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.

Note

Only the Run playbook action is available in automation rules using the alert trigger.

Screenshot of list of actions to select in automation rule.

If you add a Run playbook action, you will be prompted to choose from the drop-down list of available playbooks.

  • Only playbooks that start with the incident trigger can be run from automation rules using one of the incident triggers, so only they will appear in the list. Likewise, only playbooks that start with the alert trigger are available in automation rules using the alert trigger.

  • Microsoft Sentinel must be granted explicit permissions in order to run playbooks. 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.

    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. Manage permissions

    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.

  • If you don't yet have a playbook that will take the action you have in mind, create a new playbook. You will have to exit the automation rule creation process and restart it after you have created your playbook.

Finish creating your rule

  1. Set an expiration date for your automation rule if you want it to have one.

  2. Enter a number under Order to determine where in the sequence of automation rules this rule will run.

  3. Click Apply. You're done!

Audit automation rule activity

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:

SecurityIncident
| where ModifiedBy contains "Automation"

Automation rules execution

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.

Playbook actions within an automation rule may be treated differently under some circumstances, according to the following criteria:

Playbook run time Automation rule advances to the next action...
Less than a second Immediately after playbook is completed
Less than two minutes Up to two minutes after playbook began running,
but no more than 10 seconds after the playbook is completed
More than two minutes Two minutes after playbook began running,
regardless of whether or not it was completed

Next steps

In this document, you learned how to use automation rules to centrally manage response automation for Microsoft Sentinel incidents and alerts.