Microsoft 365 Defender

View as Markdown

Community Platform

runZero imports Microsoft 365 Defender data to sync and enrich your asset, software, and vulnerability inventory. With Microsoft 365 Defender data in runZero, assets missing EDR protection are easier to find.

Getting started

To set up the Microsoft 365 Defender integration:

  1. Configure Microsoft 365 Defender to allow API access for runZero.
  2. Add the Microsoft 365 Defender credential in runZero.
  3. Choose whether to run the integration as a scan probe or connector task.
  4. Activate the Microsoft 365 Defender integration to sync your data with runZero.

Requirements

Before you set up the Microsoft 365 Defender integration:

  • Make sure you have access to the Microsoft Azure portal.

Step 1: Register an Azure application for Microsoft 365 Defender API access

runZero can authenticate to the Microsoft 365 Defender API with a client secret. To set that up, register an application with Microsoft 365 Defender API access.

  1. Sign in to the Microsoft Azure portal.

  2. Go to App registrations and click + New registration.

    • Provide a name.
    • Select the supported account types.
    • Optionally add a redirect URI.

  3. Click Register.

  4. After the application is created, you should see the Overview dashboard. Record these values:

    • Application (client) ID
    • Directory (tenant) ID

  5. On the application’s details page, go to Manage > API permissions and choose + Add a permission.

  6. Select the second tab, APIs my organization uses, to view the available APIs.

  7. Select WindowsDefenderATP from the list of Microsoft APIs.

  8. Select the Application permissions permission type to configure a client secret.

  9. Search for and select these required permissions:

    • Windows Defender ATP API permissions:
      • Machine.Read.All
      • Software.Read.All
      • Vulnerability.Read.All

  10. Click Add permissions to save them to the application.

  11. Click Grant admin consent to approve the permissions for the application.

  12. Generate the client secret from the app management pages:

    • Go to App registrations and select the application you created.
    • Go to Certificates & secrets and click + New client secret.
      • Enter a description.
      • Select the expiration.
    • Click Add to create the client secret, and save the client secret value.

Step 2: Add an Azure Client Secret credential to runZero

This credential type can sync all resources in a single directory, across multiple subscriptions.

  1. Go to the Credentials page in runZero and click Add Credential.

  2. Name the credential, for example Azure Client Secret.

  3. Choose Azure Client Secret from the list of credential types.

  4. Fill in the credential fields:

    • Azure application (client) ID is the unique ID of the registered application. Find it in the Azure portal under App registrations after selecting the application.
    • Azure client secret is generated under App registrations: select your application, go to Manage > Certificates & secrets, and click New client secret.
    • Azure directory (tenant) ID is the unique ID of the tenant. It is also in the Azure portal under App registrations after selecting the application.

  5. If other organizations should be able to use this credential, select the Make this a global credential option. Otherwise, you can grant access per organization.

  6. Save the credential.

Step 3: Choose how to configure the Microsoft 365 Defender integration

You can run the Microsoft 365 Defender integration as either a scan probe or a connector task. A scan probe gathers integration data during a scan task. A connector task runs on its own, from the cloud or from one of your Explorers, and performs only the integration sync.

Step 4: Set up and activate the Microsoft 365 Defender integration to sync data

With your Microsoft 365 Defender credential saved, set up a connector task or scan probe to sync your data.

Step 4a: Configure the Microsoft 365 Defender integration as a connector task

A connection needs a schedule and a site. The schedule sets when the sync runs, and the site is where runZero creates any new Microsoft 365 Defender-only assets.

  1. Activate a connection to Microsoft 365 Defender. All third-party connections are also available from the integrations page, your inventory, or the tasks page.

  2. Choose the credential you added earlier. If it is missing from the list, confirm that it has access to the organization you are working in.

  3. Name the task, for example Microsoft 365 Defender sync.

  4. Schedule the sync to run once or on a recurring schedule. The schedule starts on the date and time you set.

  5. Under Task configuration, choose the site to add your assets to.

  6. To leave out assets that runZero has not scanned, switch the Exclude unknown assets toggle to Yes. By default, the integration includes assets that runZero has not scanned.

  7. To include assets that have stopped reporting to the Microsoft 365 Defender service, switch the Include inactive assets toggle to Yes. By default, the integration leaves out assets marked as inactive.

  8. Activate the connection. The sync runs on the schedule you set, and the Scheduled tasks page shows when the next sync will occur.

Step 4b: Configure the Microsoft 365 Defender integration as a scan probe

  1. Create a new scan task, or select a future or recurring scan task from your Tasks page.

  2. Add or update the scan parameters as needed.

  3. On the Probes and SNMP tab, choose any additional probes to include, set the Defender365 toggle to Yes, and adjust the default options if needed.

  4. On the Credentials tab, set the MS365Defender toggle to Yes for the credential you want to use.

  5. Click Initialize scan to save the scan task. It runs immediately or at the scheduled time.

Step 5: View Microsoft 365 Defender assets

After a successful sync, open your inventory to see your Microsoft 365 Defender assets. They show an Active Directory icon in the Source column.

To filter for Microsoft 365 Defender assets, run these queries:

Click into any asset to see its attributes, including those returned by Microsoft 365 Defender. To search and filter the vulnerabilities this integration imports, see the vulnerability instance inventory keywords.

Filtering Microsoft 365 Defender assets

You can apply an optional filter to Microsoft 365 Defender integration tasks. runZero uses the Microsoft Graph $filter query parameter to filter assets. A filter follows the syntax <property> [operator] <value>, and you can combine expressions with and or or for more complex filtering.

Properties

You can filter on any property that runZero imports from Microsoft 365 Defender. Some examples:

Defender Property runZero Attribute Description Example
computerDNSName @ms365defender.dev.computerDNSname The hostname of the device EXPLORER-01
osPlatform @ms365defender.dev.osPlatform The operating system of the device Windows11, Android
heatlhStatus @ms365defender.dev.heatlhStatus The health status of the Defender agent that is installed Active, Inactive
isAADJoined @ms365defender.dev.isAADJoined Boolean value specifying whether the device is registered in Azure AD true, false
managedBy @ms365defender.dev.managedBy Description of how the device is managed Intune

Operators

Common operators in a Microsoft 365 Defender filter:

  • Equal to (eq)
  • Not equal to (ne)
  • Has (has)
  • Less than (lt)
  • Greater than (gt)
  • Less than or equal to (le)
  • Greater than or equal to (ge)

Common functions in a Microsoft 365 Defender filter follow the syntax function(<property>, <value>):

  • Starts with (startswith)
  • Ends with (endswith)
  • Contains (contains)

Example filters

Search Filter Description
not(osPlatform eq 'Android') Import all assets except those with an Android operating system
not(osPlatform eq 'Android') and not(osPlatform eq 'iOS') Import all assets except those with an Android or iOS operating system
startswith(computerDNSname, 'PROD') Import all devices with a hostname that starts with PROD
not(startswith(computerDNSname, 'DEV')) Import all devices except those with a hostname that starts with DEV

Troubleshooting

If you are having trouble with this integration, the questions and answers below may help.

Why is the Microsoft 365 Defender integration unable to connect?

  1. Check whether the Microsoft 365 Defender integration is returning any data.

    • Query the inventory rather than the task details to review all the data available from this integration.
    • In some cases, an integration’s configuration limits how much data reaches the runZero console.

  2. Some integrations require specific actions that are easy to overlook. If you miss a step during setup, the integration may not work correctly. Review this page and follow the steps exactly.

  3. If the Microsoft 365 Defender integration can’t connect, check the task log for errors. Common errors include:

    • 500: server error, unable to connect to the endpoint
    • 404: hitting an unknown endpoint on the server
    • 403: not authorized, likely a credential issue
Updated