Create a Word document that describes your Microsoft Sentinel environment

Introduction

I have been asked numerous times if there was an easy way to document your Microsoft Sentinel configuration (most recently just last week). I didn’t know of any programs that did this, so I wrote my own.

It was something that I had wanted to do for quite some time, but only recently was the REST APIs available to do that (more on that later). When Microsoft moved everything into a solution, it was much easier to find the information I wanted.

I know it has been quite a while since I have posted. I was working on two other projects when I decided to work on this one. I will finish the other two (probably in reverse order) so there should be some more posts shortly 🙂

You can get the code from garybushey/SentinelConfigurationToWord: Create a Word document showing your Sentinel configuration (github.com)

REST API Gotchas

While I was using the latest and greatest Microsoft Sentinel REST APIs (for the most part), I did find some weirdness which I will describe below

• Content Packages – List (Content Packages – List – REST API (Azure Sentinel) | Microsoft Learn) This call will return all the solutions that you have deployed. It works great IF you are using a new Microsoft Sentinel instance that was deployed after Microsoft switched to using solutions. If you have an older installation, this only showed the solutions that were deployed after that cut-off. For this reason, I had to find a different way to determine ALL the solutions deployed.
• Data Connectors – List (Data Connectors – List – REST API (Azure Sentinel) | Microsoft Learn) This call will return all the data connectors that you have deployed in your Microsoft Sentinel instance. While this works perfectly in regards to listing the data connectors, the KQL code to determine if the data connector is connected is hit or miss. I need to look at the solutions and check if the code there is right or not. Although this does beg the question as to how the UI determines if a data connector is connected or not.
• Workbooks – There isn’t a REST API call to get the workbooks, which I think is an oversight. Granted, workbooks are actually part of Azure Monitor, but it would be nice to have a Microsoft Sentinel REST API to make it easier to obtain the information. In order to get the Workbook templates, I go through all the deployed solutions and look at the resources each solution includes. It would be much easier to call a REST API.

I also ran into a weirdness with creating a table in a Microsoft Word document using PowerShell. No clue what is wrong with the way I create the table, but when creating the table for the Custom Workbooks, the first column in the first row, which should just say “Name”, has a LOT (and I do mean a lot) of new lines before the text shows up. If anyone knows what I am doing wrong, please let me know. The other tables seem to work fine.

Finally, a lot of the descriptions of the Solutions and Hunts use HTML to format the text. I cannot for the life of me figure out how to convert the HTML into something that Word understands. If anyone knows an easy way to do this, please let me know. I could strip out all the HTML, but I don’t think that would make the text look any better. What are your thoughts?

The code

The code should be pretty self-explanatory. If you don’t know about creating a Microsoft Word document using PowerShell, check out my other blog post: Create a Word report of all Microsoft Sentinel solution resources – Yet Another Security Blog (garybushey.com)

I also made extensive use of the Programmer’s tools in my browser to figure out what REST APIs to call. I thought I had a blog post on that, but I do not see it anywhere. Odd.

What else?

What else would you like to see in the report? Expand the Automation rules to show the conditions & actions? Show playbook information? Something else?

I would love to show which data connectors are connected and maybe I will see if there is another way to get that information.

I also wanted to show table information (like you see in the Tables page in Log Analytics) but the REST API call returns way more tables than are shown on the page and there was nothing I could see to determine which ones to show. There is probably an internal list of the ones to hide. I will see what I can do about that.

Anything else? Think if you were going to hand this over to your CISO to show what your environment looks like. What other information would it need? I cannot guarantee I can add it, but I will definitely look.

Summary

This blog post talked about a new PowerShell script that can be used to create a new Word document that shows your Microsoft Sentinel information. It shows everything I can think of, but I am definitely open to other ideas! Let me know how this works for you.