Use an analytic rule’s description for remediation steps


I am sure you know that each Analytic rule in Microsoft Sentinel has a “Description field, and its contents get copied into the incident that this rule creates. I am sure you are also aware that some of the problems with newer security analysts are not knowing what steps to take to resolve an issue.

There are programs that are external to Microsoft Sentinel that can help with this, for instance ServiceNow. As a matter of fact, one of the chapters in the last revision of the book I co-authored covers how to setup the integration between ServiceNow and Microsoft Sentinel.

But what if you don’t want your data to leave Microsoft Sentinel? If you are not aware, Microsoft Sentinel allows for the markdown language to be used in the analytic rule’s “Description” field. This will allow you to use the description to hold these remediation steps.

This post will take you through how to use the markdown language and then how you can use this for remediation steps.

Markdown language

If you have ever read a “Readme” on GitHub, you have seen the output of the markdown language. It is a way to represent enhanced text, much like HTML although there are far fewer commands. Actually, the “Description” field can use HTML as well as markdown so if there is something that markdown cannot do, you can try to do it in HTML.

To read up on the language, go to its official website at Markdown Guide. We will cover some of the more basic commands that you may use here and the website will show a comparison between markdown and HTML commands.

The ones listed below show the commands that I have used in a “Description” field.

# H1
## H2
### H3



***bold and italic***


```code block```


|Column 1 | column 2 | column 3|

1. First item
2. Second item
3. Third item

- First item
- Second item
- Third item

[Microsoft Sentinel](

URL with title
[MS Sentinel]( "Sentinel")

When pasted into an analytic rule’s description and looking at the “Review and update” tab, the correspond output will be

Figure 1 – Sample Markdown output

Use markdown for remediation

Now that you have seen the power of using markdown in the “Description” field, you can probably see how to use it with remediation steps.

Here is a sample of a remediation step. Disclaimer: This is just a train of thought I wrote down, not any actual remediation steps that I know of. I have found writing these outside of Microsoft Sentinel works best since the “Description” field is small. I use Visual Studio Code when I write markdown.

## Remediation steps  
1. Run the KQL function called "X" to see the dates this activity occurred
2. Enter comment that this was done.
3. Determine if the user was working during each date
4. For each date the user was not working, run KQL function "Y" to see devices that were accessed
5. Notify each owner of the devices of a possible breach and add comment that owner was notified.  Include Email text.
6. Change status to "High" and assign to L2 team group.

This will translate into:

Figure 2 – Markdown remediation steps

Of course, you can add whatever you want to dress this up however you want.

Next Steps

Now that you have seen how to do this, what is next? Are you aware that there is an “Alert Description Format” field on the “Set rule logic” tab when you add/edit an analytic rule? This will overwrite the “Description” field and allows you to use fields from the KQL query.

You could modify the third step to show the user in question like

1. Determine if the {{user}} was working during each date

So, when this was saved to the incident, {{user}} would be replaced with “Gary Bushey” as an example.

You could even take this one step further and save your remediation steps in a Watchlist and write your query such that the remediation steps are returned from that Watchlist. This way, if you have multiple rules that use the same remediation steps, you can just write them in one place and reuse them as needed.


This blog post gave a very brief introduction to the markdown language and how you can use it in your analytic rules’ “Description” field. It also showed how to use the “Alert Description Format” field to overwrite that field with more specific information.

Hopefully, this will help you add your remediation steps to your rules allowing your analysts to see what needs to be done without leaving Microsoft Sentinel.

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.