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 machine within the MDE API, these correlate to Endpoint Assets within the Defender console. In addition, any alert generated by MDE such as files found by NGAV scans, complex attack chains disrupted, Attack Surface Reduction (ASR) rule violations, and otherwise can be retrieved. You can retrieve alerts for the machines automatically as well as data on the machine itself by IP Address (private or public) and hostname. Additionally, you can search for specific alerts by their indicators such as File Name or Hash.

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 1 FEB 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 OCSF/QDM Device. MDE alerts are normalized to Security Finding.

Entities

  • IP Address: Lookup Devices (and their related Security 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.
  • Hostname: Lookup Devices (and their related Security Findings) by the hostname. This is mapped to device.hostname in OCSF and is pulled from the Microsoft Security machines/ API field of computerDnsName.
  • File Name: Lookup Security 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 Security 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

Events

  • Security Finding: Several OCSF normalized values such as Severity, Status, Action, and Type are stored here, mapped from the Alert itself.

Objects

  • Device: Mapped from machines.

Resources

Updated 1 day ago