Microsoft 365 Defender Provider

This driver lets you query the Microsoft Defender APIs.

Note

This section applies to both Microsoft 365 Defender and Microsoft Defender for Endpoint (MDE). The former supersedes and is a subset of the the latter but both are still available to use.

Many components in MSTICPy still use the old abbreviation MDATP (Microsoft Advanced Threat Protection).

M365 Defender Configuration

Creating a Client App for M365 Defender

Details on registering an Azure AD application for MS 365 Defender can be found here. Once you have registered the application, you can use it to connect to the MS Defender API.

M365 Defender Configuration in MSTICPy

You can store your connection details in msticpyconfig.yaml.

For more information on using and configuring msticpyconfig.yaml see msticpy Package Configuration and MSTICPy Settings Editor

The settings in the file should look like the following:

DataProviders:
  ...
  MicrosoftDefender:
      Args:
        ClientId: "CLIENT ID"
        ClientSecret: "CLIENT SECRET"
        TenantId: "TENANT ID"
        UserName: "User Name"

We strongly recommend storing the client secret value in Azure Key Vault. You can replace the text value with a referenced to a Key Vault secret using the MSTICPy configuration editor. See msticpy Settings Editor)

Your configuration when using Key Vault should look like the following:

MicrosoftDefender:
    Args:
      ClientId: "CLIENT ID"
      ClientSecret:
          KeyVault:
      TenantId: "TENANT ID"

You can create multiple instances of M365 Defender settings by adding an instance string to the “MicrosoftDefender” section name.

MicrosoftDefender-Tenant1:
    Args:
      ClientId: "CLIENT ID"
      ClientSecret:
          KeyVault:
      TenantId: "TENANT ID"
MicrosoftDefender-Tenant2:
    Args:
      ClientId: "CLIENT ID"
      UserName: "USER NAME"
      TenantId: "TENANT ID"

Loading a QueryProvider for M365 Defender

mdatp_prov = QueryProvider("M365D")

You can also use the aliases “MDE” and “MDATP”.

Connecting to M365 Defender

The parameters required for connection to Defender can be passed in a number of ways. The simplest is to configure your settings in msticpyconfig. You can then just call connect with no parameters.

mdatp_prov.connect()

If you have configured multiple instances you must specify an instance name when you call connect.

mdatp_prov.connect(instance="Tenant2")

If you want to use delegated authentication for your application you can specify this when you call connect. By default, this will attempt to use browser-based authentication, however you can also use device code authentication (needed if using Azure ML) by setting auth_type to “device”.

mdatp_prov.connect(delegated_auth=True, auth_type="device")

You can also pass connection parameters as keyword arguments or a connection string.

To specify connection parameters as keyword arguments in the function call, the required parameters are:

tenant_id – The tenant ID of the Defender workspace to connect to.
client_id – The ID of the application registered for MS Defender.
client_secret – The secret used for by the application.
username – If using delegated auth for your application.

ten_id = input('Tenant ID')
client_id = input('Client ID')
client_secret = input('Client Secret')
md_prov = QueryProvider('M365D')
md_prov.connect(tenant_id=ten_id, client_id=client_id, client_secret=client_secret)

You can also specify these parameters as a connection string of the form:

“tenant_id=’my_tenant’; client_id=’my_appid’; client_secret=’my_secret’”

# The use of parentheses here is just to concatenate the strings
# inside the parentheses, to create a single string.
conn_str = (
    "tenant_id='243bb6be-4136-4b64-9055-fb661594199a'; "
    "client_id='a5b24e23-a96a-4472-b729-9e5310c83e20'; "
    "client_secret='[PLACEHOLDER]'"
)
md_prov.connect(conn_str)