Convert Sentinel Analytics Rules with PowerShell

If you have worked with Microsoft Sentinel you will, at one point, stumbled over two different file formats for Analytics Rules: YAML and ARM.

The YAML format is mostly used to distribute Analytics Rules between people. All Analytics Rules you will find in the official Sentinel GitHub repo and others out there are offered in this format.

The ARM format is what you need to deploy the Analytics Rules when using a pipeline or even if you want to import them using the UI in Microsoft Sentinel. The content of the file are in the JSON format.

While in theory YAML and JSON are interchangeable there are some things, that don’t convert easily because the JSON files used as ARM templates are based on the ARM template format, which defines all resource types in Azure and not just Sentinel Analytics Rules.

First, there is the definition of what type of resource an ARM template should deploy. In out case this is an Microsoft.OperationalInsights/workspaces/providers/alertRules which has an Id in the context of the Sentinel workspace, as well as a name, API version and type (kind).

All other content like the query itself is found in the properties value.

But there are a few property names that are different between those files. The property for MITRE techniques if called relevantTechniques in the YAML syntax and techniques when you use it within an ARM template.

Another difference are compare operators. While YAML uses eq in ARM you will see Equals.

And to add insult to injury, the time format that an ARM template uses is completely different from the YAML format as well. While the ARM template uses ISO 8601 for time formats (PT1H) but the YAML file will use 1h.

And because YAML is meant to be easily human readable, all information that the ARM template needs to be used as an deployment file is omitted. Stuff like $schema or APIVersion are stripped away.

Meet SentinelARConverter

To help with this problem I created a PowerShell module: SentinelARConverter

It has only two functions Convert-SentinelARArmToYaml and Convert-SentinelARYamlToArm

Each of those functions works the same. You can input an ARM template into Convert-SentinelARArmToYaml and it will output a valid YAML file and of course this works the other way around as well.

The easiest way is to provide a input file and use the switch UseOriginalFilename. This will convert the content of the file and safe the resulting file with the same filename, but the other extension.

Convert-SentinelARYamlToArm -Filename "C:\Users\User\Downloads\Azure_Sentinel_analytic_rule.yaml" -UseOriginalFilename

You can also input the contents using the pipeline and define the exact output location using the OutFile parameter.

Get-Content "C:\Users\User\Downloads\Azure_Sentinel_analytic_rule.yaml" | Convert-SentinelARYamlToArm -OutFile "C:\Users\User\Downloads\Azure_Sentinel_analytic_rule.json"

And if you don’t provide any output information it will return the converted file to the stdout.

Convert-SentinelARYamlToArm -Filename "C:\Users\User\Downloads\Azure_Sentinel_analytic_rule.yaml"

How to get started?

The module is published to the PowerShell Gallery and can be installed like any other module.

Install-Module SentinelARConverter

The next step would be to export your Analytics Rule in Microsoft Sentinel to download it in the ARM format.

Now convert it to YAML and share it on your personal GitHub repo or contribute it to the official Azure-Sentinel repo.

Convert-SentinelARYamlToArm -Filename "C:\Users\User\Downloads\Azure_Sentinel_analytic_rule.yaml" -UseOriginalFilename

I hope this helps others in the community to share their Analytics Rules more easily and also to deploy shared Analytics Rules using pipelines.

GitHub and how to contribute

You can find the source code in the GitHub repo https://github.com/f-bader/SentinelARConverter.

If you want to share feedback or contribute to the project, please feel free to open an issue on GitHub.

If you enjoyed this blog series, follow me on Twitter and subscribe to this blog. And if you feel like it, you can buy me a beer 🍺.