Call a MS Sentinel playbook against an incident from a workbook

Introduction

Did you know you can call a Microsoft Sentinel playbook from a workbook against an existing incident?

It is actually quite easy to do, and this post will go into the details a bit more.

ARM Actions

One of the options available to use when you add a link to the “ARM Action” (currently in preview). It is quite understandable that people creating Microsoft Sentinel workbooks are not that familiar with this action as we don’t tend to play with ARM template too much.

What you can do, though, is call the Azure REST APIs using this action. You could, for instance, make a call to the Microsoft Sentinel Incident update REST API and update an incident from a workbook, but that is a subject for a different post.

The ARM Action path we are going to call is the new one that allows us to make the call. The format of the call is

{SentinelWorkspaceName}/providers/Microsoft.SecurityInsights/incidents/{IncidentID}/runPlaybook?api-version=2019-01-01-preview

(for some reason this call is not documented in any of the Microsoft Sentinel API versions)

You will need to use the POST Http method when making the call. In addition, you will need to add a Body that will tell the call which Playbook to call (even though the entry in the body is called “LogicAppResourceId”). This leads me to believe you can call Logic Apps as well, but I have not tested that. You will also need to pass in the TenantId where the Incident resides.

When you add the link, you will add the “Link text” as normal and for the “Action”, select “ARM Action (Preview). This will then enable a “Configure…” button as shown below. Also note that the “Context pane” checkbox is checked by default. Leave this checked and we will see why in a just a bit. I also set the “Style” to be a primary button since I think it looks the best.

Figure 1 – Add a new link

If you click the “Configure…” button, the “ARM Action Settings” blade will show up. Here is where you enter the “ARM Action path”, the “Http Method”, and the “Body” as shown below. If you have not worked with workbooks before, the text inside the curly brackets (e.g. {SentinelWorkspaceName}) means to replace the text with the value of the parameter of the same name

Figure 2 – ARM Action Settings

Once everything is filled in, click the “Save and Close” button. Assuming you have all the proper parameters filled in, when you click on the “Run Playbook” button, a new context pane will open (which is why we kept that checkbox checked) as shown below. This will provide you with a warning message and the ability to either continue or cancel.

Figure 3 – ARM Action warning

Edit the warning message

One nice feature of the ARM Action is that you can edit that warning message if you like. Edit your ARM Action link and click the “Configure…” button. In the “ARM Action Settings” pane, click on the “UX Settings” tab. It will look like the image below

Figure 4 – UX Settings

You can change the “Title” to change what the title of the context pane displays. The “Customize ARM action name” textbox will allow you to change the name of the ARM Action name that appears in notifications.

The “Description of ARM Action” textbox allows you to change the warning message using the markdown language. As you can see, the first line will be displayed as a Heading Level 1 (or <H1> in HTML) and the rest of the text as a Heading level 2 (or <H2> in HTML).

Finally, the “Run button label” will change the text of the button that shows on the context pane to continue to run the playbook.

The image below shows how I have modified the entries in my workbook.

Figure 5 – Customized UX Settings

This will then yield

Figure 6 – Context pane from customized UX Settings

If you check your Azure portal notifications, you will see the “Customized ARM action name” show up.

Summary

You have seen how you can call a playbook from a workbook. You can download a fully working version of a workbook showing how this works here: Sentinel/RunPlaybookFromTheWorkbook.json at main ยท BenjiSec/Sentinel (github.com) This is not my code (as you can tell from the URL) bur rather was released when the initial announcement was made.

Leave a Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.