Microsoft Defender ATP
Copy link

You can start virus scans, stop execution of malicious code, manage isolation of network resources, get security recommendations in your Microsoft Defender ATP tenant, and trigger workflows on new security alerts with the Microsoft Defender ATP plugin for Automation (InsightConnect).

To use the Microsoft Defender ATP plugin, you must create an application in your Azure Active Directory and then configure the connection in Automation (InsightConnect). For more information on the functionality of the Microsoft Defender ATP plugin, see the Extension Library listing.

Create an application in Azure Active Directory
Copy link

  1. Log in to Azure Portal with a user that has the Global Administrator role.
  2. Click Azure Active Directory > App Registrations > New Registration.
Azure Portal New Registration
  1. Name your Application in a way that indicates its purpose and to help you keep track of it, then click Register.
Register an application
  1. Now that your application has been created, you must assign correct permissions to enable it to access Microsoft Defender ATP. To do this, click API Permissions > Add a permission.
API Permissions
  1. Select the APIs my organization uses tab, then type WindowsDefenderATP in the search box, and select WindowsDefenderATP.

Please note that WindowsDefenderATP does not appear in the original list; you need to start typing the name in the text box for it to appear.

APIs WindowsDefenderATP
  1. Click Application permissions and select the appropriate permissions to perform your action, then click Add permissions. The example below shows permissions required for the Isolate Machine action.

Please note that all actions require Machine.Read.All, Alert.ReadWrite.All, and Alert.Read.All permissions. To check what permissions are required for other actions, please refer to the permissions section for the actions in the Microsoft Documentation: https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-list.

Isolate Machine Example Permissions
  1. Grant administrator consent to the permissions selected. Please note, every time you add a permission, you must select Grant consent for the new permission to take effect.
Grant consent for new permission
  1. Now that you’ve configured your application, add an Application Secret to it by clicking Certificates & secrets > New client secret.
New client secret
  1. Enter an application secret description that indicates its purpose and click Add.
Add a client secret
  1. Copy the generated secret value. You won’t be able to retrieve this value after you leave this screen.
Copy generated secret value
  1. To get your Application ID and your Directory ID, select Overview and copy the values.
Application ID and Directory ID

Configure the Microsoft Defender ATP Connection in Automation (InsightConnect)
Copy link

Now that you’ve created your application in Azure Active Directory, you can configure the Microsoft Defender ATP connection in Automation (InsightConnect) to use the plugin.

  1. In Automation (InsightConnect), open the connection configuration for the Microsoft Defender ATP plugin. You can do this when selecting the Microsoft Defender ATP plugin during a workflow building session or by creating the connection independently by choosing Plugins & Tools from the Settings tab on the left menu. On the Plugins & Tools page, select the Connections tab and click Add Connection in the upper-right corner.
Add connection in Automation (InsightConnect)
  1. Configure the connection for the Microsoft Defender ATP plugin. Give the connection a unique and identifiable name, select where the plugin should run, and choose the Microsoft Windows Defender ATP plugin from the list. If it’s not available, then import the plugin from the Installed Plugins tab.

  2. Configure your Microsoft Defender ATP credentials. In the Secret Key field, create a credential and paste in the Microsoft Defender ATP Application Secret that you copied earlier. In addition, add the Application ID and Directory ID you copied earlier.

Success!

The Microsoft Defender ATP plugin is ready to use.

Microsoft Defender ATP Connection

Test in Progress
Copy link

Save the connection, and the connection test will attempt to authenticate to your Azure Active Directory Microsoft Defender ATP application. A blue circle on the Connection tile indicates that the Connection test is in progress.

In Progress

Success
Copy link

If there is no circle, the connection succeeded and you’re ready to begin orchestrating your processes with Microsoft Defender ATP.

Success

Failed
Copy link

A red circle indicates that the connection test failed. If this occurs, check your connection details (including the Application Secret, Application ID and Directory ID) before trying again.

Failed

The log may contain useful troubleshooting information. First, click View to see a list of your recent connection tests.

View recent connection test

Under the Test Status tab, expand the dropdown for the test that encountered an error to view its log.

View security team log