Sentinel & SOAR: Part 2 - Developing your first playbook
Introduction
Hello there, welcome back to part 2 of my Sentinel & SOAR series! If you haven’t already, you might want to check out part 1 first.
Today’s blog is touching upon Playbooks. Playbooks contain the logic that Sentinel relies on when SOAR’ing, allowing for automation of manual labor and a faster incident response time. I’ll explain how you can create a Playbook and cover some of the different configuration options available along the way. We’re also getting acquainted with Sentinel’s service account and we’ll take a peak under the hood of a Playbook.
Creating a Logic App
Like so many things in Azure, there are multiple roads to Rome when it comes to creating a Logic App. I’m creating a Logic App from the marketplace tab, so I’d recommend doing the same to keep it simple. Simply click the ‘Create a resource’ button and search for Logic App. Click Create.
We’re now presented with some interesting choices to make. First off, start with selecting a subscription, resource group and region.
- We’ll leave Log Analytics disabled for now. Normally, you’d use Log Analytics to collect metrics and logs from your app for monitoring & tracking purposes. Since we’re not going to use that functionality right now, it can remain disabled.
- Select the Consumption plan. The standard plan has some really nice functionality, like integrating with Virtual Networks, allowing you to define static outgoing IP’s and such. Again, we’re not going to make it too complicated today, so let’s stick with consumption.
- Zone redundancy allows your app to leverage availability zones, decreasing the chance of downtime. Always choose this option for production workloads. Since the cost is negligible, I always enable this setting.
Select ‘Review + create’ and create the Logic App.
Getting started
Once you select your new Logic App, Azure will immediately drop you into the designer experience. There are many pre-build templates available, but today we’re going to start from scratch. Scroll down until you find the “Blank Logic App” template, which will allow you to define everything ground-up (and thus understand what you’re actually doing).
Clicking the Blank Logic App template button will drop you into an empty screen with a search bar in the middle. This UI will display all relevant triggers. Later on this search bar can also be used to find connectors, but since each Logic App needs to start with a trigger, it will only display triggers at first.
In essence, a Playbook is simply a Logic App with a specific trigger: A Sentinel trigger. There are three types of Sentinel triggers: alert, entity and incident. Inside the search bar, search for Sentinel and select the Sentinel incident trigger.
A trigger does nothing more then getting the aforementioned object in JSON and passing it down to the next step. The fetched object can consist of the entire incident or a part of the incident, like an alert or entity, depending on the chosen trigger. Once the trigger has pulled in the original object, you can start to play around with its properties.
If you haven’t created a Playbook before, you’ll be prompted to create a connection to Sentinel. For now, click the blue Sign in button, which will prompt you to enter your credentials. This means that the Playbook will now interact with Sentinel using your identity and will have the same privilege as your account has (Example: If you’re assigned the Sentinel Contributor role, the Playbook will functionally have the same access). This is definitely not ideal for a production scenario, but luckily a later blog in the series will address this, so keep an eye out for it!
Once you’ve signed in you’re able to save your Playbook using the Save button on the top left.
Running your first Playbook
Since Playbooks require an incident as input to be ran, they can’t be triggered using the standard Logic App UI. Instead, navigate to any incident in Sentinel and open up the incident actions. Select run playbook.
Select the playbook you’ve just created and select the Run button.
You’re probably getting slapped with an error in the face. Why? Well, Playbooks don’t just magically trigger. Sentinel’s service account has to go to the Playbook and ever so gently press the start button. To do so, Sentinel needs the right permission (Azure is zero trust, remember?).
Navigate to your Sentinel instance, select Settings and navigate to Playbook permissions. Click the Configure permissions button.
A fold out menu will appear on the right side. Navigate to whichever resource group contains your playbook and select the checkbox. Then click apply. This will assign the Microsoft Sentinel Automation Contributor role to the Azure Security Insights service principal, which is the identity Sentinel is using under the hood. Since you’re assigning permissions to the resource group, you’ll need to be an owner of said resource group.
Navigate back to your incident and try to run the playbook once more. You should now get a notification that Sentinel is triggering your playbook, followed by a success notification shortly after!
Evaluating a run
As you’ve noticed, Azure only informs you on whether or not the Playbook triggered successfully. This means that it is still possible that the Playbook failed later on in its run, so it’s a good practice to verify the run outcome of any triggered Playbook. For the time being we’ll do this manually, but a future entry in this series will dive into monitoring/alerting on issues related to your automation stack.
There are (at least) two ways of verifying the run outcome of your Playbook runs. The first way is navigating back to the menu from where you triggered the Playbook and selecting the “Runs” tab. This will show you the run results of the Playbooks that Sentinel has recently triggered.
The other option is navigating to the Logic App resource that’s hosting your Playbook. On the Overview page, you’ll find the Run history. If everything went well, the latest entry should be marked as succeeded. Click the entry to dive into the details of the run.
The run details display the outcome of each step within the Playbook and at which step the Playbook failed, in case it did. Clicking on a step displays, in a GUI friendly way, the different input and output the step received. It’s also possible to access the raw JSON being passed around inside the Playbook by clicking the “Show raw outputs” button.
Now we’re getting to where the magic truly happens: Playbooks are pumping JSON around between the different steps and based on those properties our Playbooks can act in a certain way. The JSON output of one step will serve as (part of) the input JSON for the next step. We can select specific properties of our object by navigating through the JSON properties and we can build our logic flows based on JSON properties. During development and testing the raw input/output buttons will be your best friends in understanding the objects you’re dealing with.
Wrapping up
In today’s blog we’ve gotten a taste of Playbooks, as well as understanding what’s happening behind the scenes. We now know how to create a Playbook, how to assign Sentinel the correct permissions to trigger Playbooks and what’s inside of Playbooks (JSON, JSON, and some more JSON).
We’re definitely not done though: The Playbook isn’t doing anything! And what about error handling? And how do we invoke a function or write an expression? Luckily all those topics and some more will be covered by the next blog entry in this series, so keep an eye out for it!
