Guides

Microsoft Defender for Endpoint

Integrate Query with Microsoft Defender for Endpoint (MDE) to retrieve machine and alert data.

Suggest Edits

📘

TL;DR

To integrate Microsoft Defender for Endpoint with Query:

  • Register an Application Registration with a Client Secret that grants Defender for Endpoint permissions.
  • Onboard the MDE Connector in the Query Federated Search platform.
  • Use Query Search to provide decision support for Incident Response, Investigations, Threat Hunting, Red Team targeting operations, and/or Continuous Compliance Monitoring use cases.

Overview

Microsoft Defender for Endpoint (MDE, formerly known as Defender ATP) is the Endpoint Detection & Response (EDR) capability of the Microsoft Defender suite of security tools that is included with the Defender for Endpoint Plan 1, Plan 2, Vulnerability Management, and Defender XDR SKUs as well as M365 E3 and M365 E5 licenses.

Defender for Endpoint is described by Microsoft as "an enterprise endpoint security platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats." Defender for Endpoint provides behavior, signature, and statistical threat detection, Next-Gen Anti-Virus (NGAV) scanning, and integration into other Defender and Microsoft Security tools such as Microsoft Purview for DLP and Defender for Cloud Apps for additional network detection and prevention.

With Query Federated Search, you can search for any device (called machines by the Defender Security API) as well as their related Vulnerabilities and Detections (called alerts by the Defender Security API). You can search for these using Event-based searches as well as using the Machine ID, AAD (Entra ID) Device ID, IP Addresses, Hostname, and search for Vulnerabilities and impacted devices by CVE ID.

Prerequisites

You must do the following steps to use the APIs and create the connection credentials. You can access Defender API with Application Context or User Context. Query will use the Application Context (Link) to access the Defender API.

  • Create an Application Registration (Enterprise App) Link
  • Get an access token for using this application.

Microsoft Graph Security API permissions

The following API permissions at a minimum are necessary for Query to search Microsoft Defender for Endpoint for alerts, device information, and others.

  1. Select Organization's APIs:

    1. Navigate to the Request API permissions screen.
    2. Choose APIs my organization uses.
    3. Using the search bar search for: WindowsDefenderATP.
    4. Select WindowsDefenderATP from the search results.

  2. Set Application Permissions:

    1. Select Application Permissions. This allows Query to operate as a background service or daemon, independent of a signed-in user.
    2. Grant the following API permissions:
      1. AdvancedQuery.Read.All
      2. Alert.Read.All
      3. File.Read.All
      4. Ip.Read.All
      5. Machine.Read.All
      6. Score.Read.All
      7. Ti.Read.All
      8. Url.Read.All
      9. User.Read.All

  3. Confirm all Application Permissions were added, and select Grant admin consent for {your_environment_here}.

  4. Navigate to Certificates & Secrets -> Client Secrets -> New client secret. Enter a Description, choose an Expires data from the selector, and finally choose Add as shown below.

  5. Before navigating away copy the Value entry and save it somewhere secure, this is the Client Secret Value required to perform authentication into your Azure Subscriptions. If you did not copy it, no big deal, just delete the Client Secret and create another - but remember to copy the Value that time.

  6. Navigate to the Overview screen and copy the values for the Application (client) ID and Directory (tenant) ID as shown below. The App ID, Directory ID, and Client Secret Value are all required to configure the MDE Connector for Query Federated Search.

In the next sections you will learn how to configure a Connector and execute searches with it.

Configuring the Microsoft Defender for Endpoint (MDE) Connector

Use the following steps to create a new Query Federated Search Connector for the MDE.

  1. Navigate to the Connections page, select Add Connections, and selectMicrosoft Defender for Endpoint from the Endpoint category as shown below you can speed this up by using the search bar as shown below.

  2. In the Configure Connector tab, add the following detail as shown below:

    1. Connector Alias Name: The human-readable name you want to give to this connector, you can name it whatever you want, but you can use this to differentiate multiple Defender licenses across different Entra ID tenants.

    2. Platform Login Method: Leave the default value: Default Login.

    3. Microsoft Entra ID Tenant ID : The Tenant ID (also known as the Directory ID) for the Microsoft Entra ID tenant associated with your Defender for Endpoint license.

    4. App Registration Client ID : The Client ID (also know as the Application ID) for the Entra ID App Registration you created in the Prerequisites section.

    5. App Registration Client Secret Value : The Client Secret Value for the credentials you created for your App Registration.

  3. Select Test Connection from the bottom-right of the pane to ensure that your credentials and information was entered correctly, you have the right permissions, you have the correct license, and that Query can use the credentials to authenticate to the Security Graph API. If there is something wrong, error flags will appear below. You can further request assistance by utilizing the Intercom functionality in the Query app.

  4. Finally, after a successfully test, select Save to finalize and enable the Connector.

You will now see Microsoft Defender for Endpoint as an available Platform within the Query Search and Query Summary Insights UI, the "platform" term is synonymous with Connector.

Querying the Microsoft Defender for Endpoint Connector

After you have onboarded the Microsoft Defender for Endpoint Connector, you are ready to begin searching! Within the Query Federated Search and Query Summary Insights UI, all Platforms are enabled by default.

To either ensure your Defender for Endpoint Connector is enabled, or to only query it specifically, navigate to the Endpoint section of the Selected Platforms dropdown menu and ensure the checkbox is (de)selected to match your desired search criteria, as shown below.

As of 15 JULY 2024, the following Entities, Events, and Objects are supported by Query for the Defender for Endpoint Connector. For more information about this terminology, refer to the Normalization and the Query Data Model (QDM) section of the docs or check out our QDM Schema website.

👍

TL;DR

MDE endpoints, called machines in the APIs, are normalized to Device Inventory Info. MDE alerts are normalized to Detection Findings. MDE vulnerabilities are normalized to Vulnerability Findings. Searches for nearly all are supported by IP Address, Hostname, Resource ID (Machine ID/AAD Device ID), CVE ID, File Hashes, and File Names.

Entities

  • IP Address: Lookup Device Inventory Info for MDE machines (and their related Detection and Vulnerability Findings) by the public or private IP address. This is mapped to device.ip in OCSF and is pulled from the Microsoft Security machines/ API fields of lastIpAddress and lastExternalIpAddress. All operators supported.
  • Hostname: Lookup Device Inventory Info for MDE machines (and their related Detection and Vulnerability Findings) by the hostname. This is mapped to device.hostname in OCSF and is pulled from the Microsoft Security machines/ API field of computerDnsName. All operators supported.
  • Resource ID: Lookup Device Inventory Info for MDE machines (and their related Detection and Vulnerability Findings) by the Resource ID. This can be either the Machine ID or the AADDeviceId if the device is tracked by Intune and/or EntraID. All operators supported.
  • CVE ID: Lookup Vulnerability Findings and their related Device Inventory Info entires by CVE ID. Maps to the id within the /machineVulnerabilities API. Only case-insensitive EQ operator is supported.
  • File Name: Lookup Detection Findings by file names located in the alert Evidence. This is mapped to file.name in OCSF and is pulled from the Microsoft Security /api/alerts/{id}/files API field of value.[*].fileProductName
  • File Hash: Lookup Detection Findings by SHA1, SHA256, and/or MD5 hashes located in the alert Evidence. This is mapped to file.signature.digest.value in OCSF and is pulled from the Microsoft Security /api/alerts/{id}/files API fields of value.[*].sha1, value.[*].sha256, and/or value.[*].md5
  • Command Line: Lookup Detection Findings by Command Line arguments in the alert Evidence.
  • Process Name: Lookup Detection Findings by Process Names implicated in alert Evidence.

Events

  • Detection Finding: Normalized from Defender Security alerts - you can search for ALL Events or curate by Severity
  • Security Finding: Normalized from Defender Security machineVulnerabilities - you can search for ALL Events or curate by Severity
  • Device Inventory Info: Normalized from Defender Security machines - you can search for ALL Events which pulls all devices or use Entity-based search for specific machines.

Resources

Updated 5 months ago