Understanding Microsoft 365 Defender APIs

Application programming interfaces (APIs) are a way to programmatically connect applications to other applications. In the context of Microsoft 365 Defender, this could mean connecting your PowerShell scripts to query data; an independent software vendor (ISV) connecting to provide additional value in their tool; or using a service such as Azure Logic Apps to automate a workflow based on Microsoft 365 Defender triggers.

In this chapter, you’ll learn the fundamentals regarding APIs for Microsoft 365 Defender and its related services, such as MDE, MDO, MDA, and MDVM. Specifically, we’re going to cover the following:

• The different APIs available, including their differences and when to use each
• Accessing the APIs and their permissions
• An example scenario, where we’ll use PowerShell to perform an MDE operation using APIs

Based on this chapter, you’ll start to think of your own creative possibilities...

Making sense of the different APIs

Microsoft has made five APIs available related to Microsoft 365 Defender and its associated services. Some of these APIs are exclusively related to Microsoft 365 Defender, and others are part of a broader collection. Let’s check them out.

Microsoft Graph security API

The Microsoft Graph security API is part of the Microsoft Graph API. Its production request URLs are found at graph.microsoft.com/v1.0/security and beta request URLs at graph.microsoft.com/beta/security, with the beta endpoint subject to change and therefore not recommended by Microsoft for production use.

Microsoft is investing heavily in Microsoft Graph, and it’s reasonable to say this should be your starting point and where to expect future investment. This means if an operation is available in the Microsoft Graph security API and another API, you may want to opt for the Graph version.

The following capabilities related to Microsoft 365 Defender are exposed...

Accessing the APIs

As APIs expose a lot of sensitive data and, in many cases, give you the ability to change significant settings, their exposure is protected by default. To get access, you’ll need to open up access, which is typically protected behind an access token or certificate.

For the APIs discussed in the last section, you’ll manage permissions to the APIs using Azure AD app registrations. So, we’ll guide you through creating an app registration, then use PowerShell as an example of using the APIs.

Creating an app registration for API access

As you create the app registration, you’ll get to choose which API permissions are exposed, then obtain the credentials to access those APIs. We’re going to use application permissions, which means they can run without a dedicated signed-in user (compared to delegated permissions, which access the API as an authenticated user).

To perform the following, you should be an Azure AD global administrator...

Summary

If you’re going to be managing multiple tenants, or want to otherwise programmatically manage as much as possible, you’re going to want to start mastering the APIs available for Microsoft 365 Defender and its associated services.

That’s why, in this chapter, you learned about the five main APIs available, and the kinds of operations each exposes:

• The Microsoft Graph security API
• Microsoft 365 Defender APIs
• Microsoft Defender for Endpoint APIs
• The Microsoft Defender for Cloud Apps API
• The Office 365 Management Activity API

As a rule, if it’s in Microsoft Graph, use it there to centralize efforts and stick with where Microsoft appears to be focusing most. However, you’ll still find lots in the other APIs only. Most of the APIs focus on operations of Microsoft 365 Defender rather than settings management, but hopefully, we’ll see this change over time so more things can be automated and managed as code...

Challenges

Rather than have questions for this chapter like the others, we’ve posed two challenges that can be attempted using the APIs learned about in this chapter:

1. Using an Azure Logic Apps app, try to update your team every time a new MDE alert is generated.
2. You have several scripts you want to add to the live response library for multiple tenants. Try to upload these using PowerShell.

Further reading

To continue your learning path of the world of Microsoft 365 Defender APIs, you can refer to the following resources:

• When you’re using APIs, you should always refer to the latest official documentation, which for each of the types discussed in this chapter is available at the following URLs:
  • Microsoft Graph security API: learn.microsoft.com/en-us/graph/api/resources/security-api-overview?view=graph-rest-1.0
  • Microsoft 365 Defender APIs: learn.microsoft.com/en-us/microsoft-365/security/defender/api-supported?view=o365-worldwide
  • Microsoft Defender for Endpoint APIs: learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide
  • Microsoft Defender for Cloud Apps API: learn.microsoft.com/en-us/defender-cloud-apps/api-introduction
  • Office 365 Management APIs: learn.microsoft.com/en-us/office/office-365-management-api/office-365-management-activity-api-reference
• At the time of publication, Microsoft does not officially...