playbook-triggers-actions.md

title	description	author	ms.topic	ms.date	ms.author	ms.custom
Use triggers and actions in Microsoft Sentinel playbooks | Microsoft Docs	Learn in greater depth how to give your playbooks access to the information in your Microsoft Sentinel alerts and incidents and use that information to take remedial actions.	yelevin	how-to	11/09/2021	yelevin	ignite-fall-2021

Use triggers and actions in Microsoft Sentinel playbooks

[!INCLUDE Banner for top of topics]

This document explains the types of triggers and actions in the Logic Apps Microsoft Sentinel connector, that playbooks can use to interact with Microsoft Sentinel and the information in your workspace's tables. It further shows you how to get to specific types of Microsoft Sentinel information that you are likely to need.

This document, along with our guide to Authenticating playbooks to Microsoft Sentinel, is a companion to our other playbook documentation - Tutorial: Use playbooks with automation rules in Microsoft Sentinel. These three documents will refer to each other back and forth.

For an introduction to playbooks, see Automate threat response with playbooks in Microsoft Sentinel.

For the complete specification of the Microsoft Sentinel connector, see the Logic Apps connector documentation.

Permissions required

Roles \ Connector components	Triggers	"Get" actions	Update incident, add a comment
Microsoft Sentinel Reader	✓	✓	✗
Microsoft Sentinel Responder/Contributor	✓	✓	✓

Learn more about permissions in Microsoft Sentinel.

Microsoft Sentinel triggers summary

Though the Microsoft Sentinel connector can be used in a variety of ways, the connector's components can be divided into 2 flows, each triggered by a different Microsoft Sentinel occurrence:

Trigger	Full trigger name in Logic Apps Designer	When to use it	Known limitations
Incident trigger	"Microsoft Sentinel incident (Preview)"	Recommended for most incident automation scenarios. The playbook receives incident objects, including entities and alerts. Using this trigger allows the playbook to be attached to an Automation rule, so it can be triggered when an incident is created (and now, updated as well) in Microsoft Sentinel, and all the benefits of automation rules can be applied to the incident.	Playbooks with this trigger do not support alert grouping, meaning they will receive only the first alert sent with each incident.
Alert trigger	"Microsoft Sentinel alert"	Advisable for playbooks that need to be run on alerts manually from the Microsoft Sentinel portal, or for scheduled analytics rules that don't generate incidents for their alerts.	This trigger cannot be used to automate responses for alerts generated by Microsoft security analytics rules. Playbooks using this trigger cannot be called by automation rules.

The schemas used by these two flows are not identical. The recommended practice is to use the Microsoft Sentinel incident trigger flow, which is applicable to most scenarios.

Incident dynamic fields

The Incident object received from Microsoft Sentinel incident includes the following dynamic fields:

• Incident properties (Shown as "Incident: field name")

• Alerts (array)

  • Alert properties (Shown as "Alert: field name")

    When selecting an alert property such as Alert: <property name>, a for each loop is automatically generated, since an incident can include multiple alerts.

• Entities (array of all an alert's entities)

• Workspace info fields (applies to the Sentinel workspace where the incident was created)

  • Subscription ID
  • Workspace name
  • Workspace ID
  • Resource group name

Microsoft Sentinel actions summary

Component	When to use it
Alert - Get Incident	In playbooks that start with Alert trigger. Useful for getting the incident properties, or retrieving the Incident ARM ID to use with the Update incident or Add comment to incident actions.
Get Incident	When triggering a playbook from an external source or with a non-Sentinel trigger. Identify with an Incident ARM ID. Retrieves the incident properties and comments.
Update Incident	To change an incident's Status (for example, when closing the incident), assign an Owner, add or remove a tag, or to change its Severity, Title, or Description.
Add comments to incident	To enrich the incident with information collected from external sources; to audit the actions taken by the playbook on the entities; to supply additional information valuable for incident investigation.
Entities - Get <entity type>	In playbooks that work on a specific entity type (IP, Account, Host, URL or FileHash) which is known at playbook creation time, and you need to be able to parse it and work on its unique fields.

|

Work with incidents - Usage Examples

Tip

The actions Update Incident and Add a Comment to Incident require the Incident ARM ID.

Use the Alert - Get Incident action beforehand to get the Incident ARM ID.

Update an incident

• Playbook is triggered by Microsoft Sentinel incident

  

• Playbook is triggered by Microsoft Sentinel alert

  

Use Incident Information

Basic playbook to send incident details over mail:

• Playbook is triggered by Microsoft Sentinel incident

  

• Playbook is triggered by Microsoft Sentinel alert

  

Add a comment to the incident

• Playbook is triggered by Microsoft Sentinel incident

  

• Playbook is triggered by Microsoft Sentinel alert

  

Work with specific Entity types

The Entities dynamic field is an array of JSON objects, each of which represents an entity. Each entity type has its own schema, depending on its unique properties.

The "Entities - Get <entity type>" action allows you to do the following:

• Filter the array of entities by the requested type.
• Parse the specific fields of this type, so they can be used as dynamic fields in further actions.

The input is the Entities dynamic field.

The response is an array of entities, where the special properties are parsed and can be directly used in a For each loop.

Currently supported entity types are:

• IP

• Host

• Account

• URL

• FileHash

  :::image type="content" source="media/playbook-triggers-actions/entities-actions.png" alt-text="Entities Actions List":::

For other entity types, similar functionality can be achieved using Logic Apps' built-in actions:

• Filter the array of entities by the requested type using Filter Array.

• Parse the specific fields of this type, so they can be used as dynamic fields in further actions using Parse JSON.

Work with custom details

The Alert custom details dynamic field, available in the incident trigger, is an array of JSON objects, each of which represents a custom detail of an alert. Custom details, you will recall, are key-value pairs that allow you to surface information from events in the alert so they can be represented, tracked, and analyzed as part of the incident.

Since this field in the alert is customizable, its schema depends on the type of event being surfaced. You will have to supply data from an instance of this event to generate the schema that will determine how the custom details field will be parsed.

See the following example:

In these key-value pairs, the key (the left-hand column) represents the custom fields you create, and the value (the right-hand column) represents the fields from the event data that populate the custom fields.

You can supply the following JSON code to generate the schema. The code shows the key names as arrays, and the values (shown as the actual values, not the column that contains the values) as items in the arrays.

{ "FirstCustomField": [ "1", "2" ], "SecondCustomField": [ "a", "b" ] }

1. Add a new step using the Parse JSON built-in action. You can enter 'parse json' in the Search field to find it.

2. Find and select Alert Custom Details in the Dynamic content list, under the incident trigger.

   

   This will create a For each loop, since an incident contains an array of alerts.

3. Click on the Use sample payload to generate schema link.

   

4. Supply a sample payload. You can find a sample payload by looking in Log Analytics (the Logs blade) for another instance of this alert, and copying the custom details object (under Extended Properties). In the screenshot below, we used the JSON code shown above.

   

5. The custom fields are ready to be used dynamic fields of type Array. You can see here the array and its items, both in the schema and in the list that appears under Dynamic content, that we described above.

   

Next steps

In this article, you learned more about using the triggers and actions in Microsoft Sentinel playbooks to respond to threats.

• Learn how to proactively hunt for threats using Microsoft Sentinel.