Skip to main content

Microsoft Defender for Endpoint

Microsoft Defender for Endpoint is an endpoint protection tool that organizations can use to detect malware, block exploits and network-based attacks, and flag phishing sites in their network. You can bring host and security data from Microsoft Defender into Brinqa to help you detect and respond to security threats, and gain a comprehensive view of your attack surface to strengthen your cybersecurity posture.

This document details the information you must provide for the connector to authenticate with Microsoft Defender for Endpoint and how to obtain that information from Microsoft. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings​

When setting up a data integration, select Microsoft Defender for Endpoint from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate Microsoft Defender for Endpoint with Brinqa:

  • API URL: The Microsoft Defender for Endpoint API URL. The default URL is https://api.securitycenter.microsoft.com.

  • Login URL: The Microsoft Azure authentication URL. The default URL is https://login.microsoftonline.com.

  • Client ID and Client secret: The client ID and client secret associated with the service principal, which must have permissions to log in to the Microsoft Azure Active Directory (Active AD) and return data from the Defender API.

  • Tenant ID: The unique identifier for the Active AD tenant associated with the service principal.

Register a Microsoft Azure application​

You must create a new application for the Microsoft Defender for Endpoint connector to authenticate with Azure AD and access the Microsoft Defender for Endpoint APIs. To register an application in your Azure AD tenant, follow these steps:

  1. Log in to your Microsoft Azure Portal as an administrator.

  2. Navigate to and click Microsoft Entra ID.

  3. On the left-hand side of the page, click App registrations, and then click New registration.

  4. Give your new application a name, select the supported account types, and provide an optional Redirect URI. If you do not have a redirect URI, you can leave the field as is.

    Microsoft Defender for Endpoint application registration

  5. Click Register.

note

For additional details about registering an application in Azure AD and creating a service principal, see Microsoft Azure documentation.

Obtain Microsoft Azure credentials​

After you have created your new Microsoft Azure application, your client and tenant ID display. Copy the Application (client) ID and Directory (tenant) ID as show below:

Microsoft Defender for Endpoint client and tenant ID

To obtain your client secret, follow these steps:

  1. Click Certificates & secrets and then click New client secret.

  2. Provide a description, set an expiry date, and then click Add.

    The new client secret displays. You cannot view the client secret again. There is both a Value and Secret ID. The Value field is what is needed for authentication. Copy the Value field and save it in a secure location.

    microsft defender client secret value

Assign permissions​

After you have created your new Microsoft Azure application and obtained the authentication credentials, you must assign the required permissions for the application to access your data. To do so, follow these steps:

  1. Navigate to API permissions > Add a permission > APIs my organization uses and select WindowsDefenderATP.

  2. Click Application permissions, grant the following permissions, and then click Add permissions:

    • Machine: Machine.Read.All

    • Security Recommendation: SecurityRecommendation.Read.All

    • Software: Software.Read.All

    • User: User.Read.All

    • Vulnerability: Vulnerability.Read.All

  3. Click Grant admin consent for default directory, and then click Yes in the confirmation dialog. Your API permissions should resemble the following:

    Microsoft Defender for Endpoint Permissions

note

For additional information about Azure AD permissions, see Microsoft Azure documentation.

Additional settings​

The Microsoft Defender for Endpoint connector contains an additional option for specific configuration:

  • Maximum retries: The maximum number of times that the integration attempts to connect to the Microsoft Defender for Endpoint API before giving up and reporting a failure. The default setting is 10.

Types of data to retrieve​

The Microsoft Defender for Endpoint connector can retrieve the following types of data from the Microsoft Defender API:

Table 1: Data retrieved from Microsoft Defender

Connector ObjectRequiredMaps to Data Model
MachineYesHost
VulnerabilityNoVulnerability
Vulnerability DefinitionNoVulnerability Definition
info

For detailed steps on how to view the data retrieved from Microsoft Defender for Endpoint in the Brinqa Platform, see How to view your data.

Operation options​

The Microsoft Defender for Endpoint connector supports the following operation options. See connector operation options for information about how to apply them.

Click the tabs below to view the supported operation options per connector object.

Table 2: Machine operation options

Connector ObjectOptionAll Possible ValuesDescriptionExample
MachinecomputerDnsNameAny fully-qualified name of a machine.Retrieve machines with the specified DNS name.Key: computerDnsName Value: desktop-1212.brinqa.com. This key and value combination only retrieves the machine whose DNS name is desktop-1212.brinqa.com.
exposureLevelNone, Low, Medium, HighRetrieve machines with the specified exposure level as evaluated by Microsoft Defender for Endpoint.Key: exposureLevel Value: Medium. This key and value combination only retrieves machines with a medium exposure level.
healthStatusActive, Inactive, ImpairedCoummunication, NoSensorData, NoSensorDataImpairedCommunication, UnknownRetrieve machines with the specified heatlh status as evaluated by Microsoft Defender for Endpoint.Key: healthStatus Value: Active. This key and value combination only retrieves machines with an active health status.
lastSeenAny date and time value in the ISO 8601 format.Retrieve machines based on the last time Microsoft Defender for Endpoint received a full device report for the machine.Key: lastSeen Value: 2023-01-01TO0:00:00Z. This key and value combination only retrieves machines whose full device report was received on January 1st, 2023.
machineTagsA comma separated list of machine tags.Retrieve machines with the specified machine tags.Key: machineTags Value: Tag3. This key and value combination only retrieves machines with the tag Tag3.
onboardingStatusonboarded, CanBeOnboarded, Unsupported, InsufficientInfoRetrieve machines with the specified onboarding status.Key: onboardingStatus Value: Unsupported. This key and value combination only retrieves machines that have an unsupported onboarding status.
osPlatformA comma-separated list of operating systems.Retrieve machines running on the specified operating systems.Key: osPlatform Value: Windows 11, macOS. This key and value combination only retrieves machines running on Windows 11 and macOS.
rbacGroupIdAny machine group IDRetrieve machines with the specified machine group ID.Key: rbacGroupId Value: 7b3f5c5c-c4c4 This key and value combination only retrieves machines with the machine group ID of 7b3f5c5c-c4c4.
riskScoreNone, Informational, Low, Medium, HighRetrieve machines with the specified risk score as evaluated by Microsoft Defender for Endpoint.Key: riskScore Value: High. This key and value combination only retrieves machines with a high risk score.
note

The option keys and values are case-sensitive as they are shown in this documentation.

APIs​

The Microsoft defender connector uses the Microsoft Defender for Endpoint API. Specifically, it uses the following endpoints:

Table 5: Microsoft Defender for Endpoint API Endpoints

Connector ObjectAPI Endpoints
MachineGET https://api.securitycenter.microsoft.com/api/machines
VulnerabilityGET https://api.securitycenter.microsoft.com/api/machines/SoftwareVulnerabilityChangesByMachine
GET https://api-us.securitycenter.contoso.com/api/machines/SoftwareVulnerabilitiesExport
Vulnerability DefinitionGET https://api.securitycenter.microsoft.com/api/recommendations
GET https://api.securitycenter.microsoft.com/api/recommendations/{id}/vulnerabilities
GET https://api.securitycenter.microsoft.com/api/vulnerabilities

Changelog​

The Microsoft Defender for Endpoint connector has undergone the following changes:

3.1.17

  • Added the following attributes to the Machine object:

    • MERGED_INFO_MACHINE_ID

    • POTENTIAL_DUPLICATION

    • SOURCE_STATUS

3.1.15

  • Fixed an issue where the EXPLOITABILITY attribute in all Vulnerability Definition records was incorrectly set to 'Actively used'.

3.1.14

  • Set the INSTANCE_ID attribute in the Machine object if the source specifies a value using the instanceId tag.

3.1.13

  • Made Vulnerability and Vulnerability Definition objects as optional in data integration.

3.1.9

  • Added a delay in deleting temporary storage to avoid syncing issues.

3.1.8

  • Used 'updatedOn' instead of 'publishedOn' to fetch updates for the Vulnerability Definition object.

3.1.7

  • Enhanced to make concurrent attempts to retrieve recommendations for vulnerabilities. However, in the event of failure, it proceeds without this data.
  • Increased the default setting for Maximum Retries to 10.

3.1.6

  • Excluded 00000000-0000-0000-0000-000000000000 as a valid Azure Active Directory device ID.
  • Updated dependencies.

3.1.5

  • Fixed a null pointer exception when there's no filter provided.
  • Fixed a null pointer exception when the machine is synced from the beginning of time.

3.1.4

  • Added filtering capability to the Machine and Vulnerability Definition objects.

3.1.2

  • Made the value of the HOSTNAME attribute consistent.

3.1.1

  • Tried to generate a name for the Machine object based on its DNS name, IP addresses, or Azure Active Directory device ID.

3.1.0

  • Ignored exceptions when downloading export files.

3.0.3