Automate MDE Custom Indicators with PowerShell

Disclaimer: The information posted in this blog and on this website are not necessarily reflective of the views or recommendations of Microsoft. Though I am an employee of Microsoft, this is considered a personal project of mine that is not intended to be a recommendation or guide from Microsoft the company. I take no responsibility for any results this script may yield. Please use any scripts in this blog with your discretion and perform necessary testing.

Please review Microsoft’s license and terms of use for the MDE API here: MDE API License and Terms of Use

Also please note that the script provided in this blog uses Tenant ID, Application ID, and Application Secret hardcoded into the script to simplify testing. If you plan on using this in any enterprise application, I strongly recommend you consider a safer way to authenticate such as using certificates or Azure Key Vault. Detailing stronger authentication methods is beyond the scope of this blog.

Introduction

In this blog, I will be detailing a PowerShell script I wrote which takes a csv with one or more indicators as input and will then call the Submit Indicator API or the Import Indicators API to submit or import these indicators into Microsoft Defender for Endpoint (MDE).

Getting Started

To begin, you will need an active MDE tenant to use this script with and you will need to register an application in Microsoft Entra ID following the steps provided by Microsoft:
Create an app to access MDE

You will need to grant the Ti.ReadWrite or the Ti.ReadWrite.All permissions to your registered application.

Once you have registered your application and provided the above permissions, you can access my script here: My M365 Defender Github Repo

Note that there are a few other scripts in this repo. In the Custom Indicators folder, there is also an ‘MDE List Indicators.ps1‘ script which will call the List Indicators API and output your indicators into a CSV. There is also a sample CSV file which can be supplied to the ‘MDE Submit Indicator.ps1‘ script. In the future, I may add an additional script for deleting indicators too.
In this repo, you will also notice an ‘MDE Machine Actions API.ps1‘ script. This script can take many actions on MDE machines in bulk and is further detailed in the below blog.

Taking Actions on MDE Devices via PowerShell and MDE API

Using the Script

Once you have registered your application and downloaded the script from GitHub, you can replace the Tenant ID, App ID, and App Secret in the MDE Submit Indicator.ps1 script with your own (or create your own stronger authentication mechanism if you plan on using this beyond testing).

Upon running the script, you will be prompted to enter the path to a .csv file containing your indicator(s). A sample file is provided in the GitHub repo with all of the required fields pre-populated. If there are multiple indicators in the CSV, then the Import Indicators API will be called to import all of them in one API call. Otherwise, if only one indicator is supplied, the Submit or Update Indicator API will be called. You can refer to the corresponding documentation for further details.

Note: Not all properties which can be supplied to these APIs are present in the sample csv. You can see more of the properties here: Indicator Resource Type.

Once you begin working with the script, you can even make modifications of your own. For example, you can add the csv path as a parameter and run this script as a scheduled task. Perhaps, you use multiple platforms for IOCs, you can upload indicator CSVs to a location where the script can run and check for new CSVs or modifications and add the new IOCs to MDE automatically.

Some Potential Gotchas to be Aware of:

rbacGroupNames, rbacGroupIds, and mitreTechniques are expected to be arrays when provided to the API, even if there is only one value. The script should take care of any issues with this for you, but if you run into any problems, ensure the values of those properties are inside square brackets and separated with commas if there are multiple.

If you supply a value for mitreTechniques, you must also supply the corresponding category value.

If you supply both an rbacGroupNames value and an rbacGroupIds value for a single indicator, they must match, otherwise you will get a bad request. I would recommend just choosing either rbacGroupNames or rbacGroupIds for each indicator and avoid using both for the same indicator.

Some properties can be null (but not “null”). If you leave any property value blank in the csv file, the script should automatically convert these to null and depending on the property, this is completely acceptable. For example, the expiration date can be null. However, if you are testing this and you see any of your values are “null” instead of null, this will not be accepted by the API and will return a bad request response.

Conclusion

Thanks for reading my blog and checking out my script. I hope it was helpful for you! If you run into any issues outside of the ones mentioned above, I would recommend testing with Defender’s API Explorer. You can take the value of $jsonData from the script and supply it in the API Explorer for troubleshooting.

You are also welcome to reach out to me on LinkedIn if you have any questions regarding the script. If you enjoyed this, check out some of my other blogs on Defender and Automation!