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.

   

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:

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.

   

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:

   

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 5.

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 Object	Required	Maps to Data Model
Installed Package	No	Installed Package
Machine	Yes	Host
Package	No	Package
Vulnerability	No	Vulnerability
Vulnerability Definition	No	Vulnerability 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.

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes.

Installed Package

Table 2: Installed Package attribute mappings

Source Field Name	Maps to Attribute
computerDnsName	dnsNames
machine.id	targets
name	name
osPlatform	os
rbacGroupId	Local variable
rbacGroupName	Local variable
software.id	type
status	status
uid	uid

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Machine

Table 3: Machine attribute mappings

Source Field Name	Maps to Attribute
aadDeviceId	aadDeviceId, name
agentVersion	Local variable
CATEGORIES	categories
cloudProvider	cloudProvider
computerDnsName	hostnames, privateDnsNames, publicDnsNames
defenderAvStatus	Local variable
deviceValue	Local variable
exclusionReason	Local variable
exposureLevel	Local variable
healthStatus	status
id	uid
ipAddresses	ipAddresses, privateIpAddresses, publicIpAddress
isAadJoined	Local variable
isExcluded	Local variable
isPotentialDuplication	Local variable
lastSeen	lastSeen
macAddresses	macAddresses
machineTags	tags, instanceId
managedBy	Local variable
managedByStatus	Local variable
mergedIntoMachineId	Local variable
onBoardingStatus	Local variable
osArchitecture	description, os
osBuild	description, os
osPlatform	description, os
osProcessor	Local variable
osVersion	os
rbacGroupId	Local variable
rbacGroupName	Local variable
resourceId	Local variable
riskScore	Local variable
subscriptionId	Local variable
team_id	Local variable
team_name	Local variable
uptime	Local variable

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Package

Table 4: Package attribute mappings

Source Field Name	Maps to Attribute
activeAlert	Local variable
categories	categories
exposedMachines	Local variable
id	uid
impactScore	Local variable
name	name
publicExploit	Local variable
Status	status
vendor	Local variable
versions	Local variable

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Vulnerability

Table 5: Vulnerability attribute mappings

Source Field Name	Maps to Attribute
cveId	type
deviceId	targets
deviceName	hostnames
eventTimestamp	sourceLastModified, lastFixed
firstSeenTimestamp	firstFound
id	uid
lastSeenTimestamp	lastFound
results	results
status	status, statusCategory
vulnerabilitySeverityLevel	severity, sourceSeverity

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Vulnerability Definition

Table 6: Vulnerability Definition attribute mappings

Source Field Name	Maps to Attribute
cvssV3	cvssV3BaseScore
description	description, summary
exploitTypes	Local variable
exploitUris	exploits, references
exploitVerified, publicExploit, exploitInKit	exploitability
id	cveIds, cveRecords, uid
name	name
publishedOn	publishedDate
recommendation.isHasUnpatchableCve	patchAvailable
recommendations.getRelatedComponent	affected
recommendation.getRecommendationName	recommendation
severity	severity, sourceSeverity
updatedOn	sourceLastModified

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

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.

Installed Package

Table 7: Installed Package operation options

Connector Object	Option	All Possible Values	Description	Example
Package	id	Any installed package ID	Retrieve installed packages with the specified ID.	Key: id Value: microsoft-_-edge. This key and value combination only retrieves installed packages with the microsoft-_-edge ID.
	name	Any installed package name	Retrieve installed packages with the specified name.	Key: name Value: edge. This key and value combination only retrieves installed packages with the edge name.
	vendor	Any installed package vendor	Retrieve installed packages with the specified vendor name.	Key: vendor Value: microsoft. This key and value combination only retrieves installed packages with the microsoft vendor name.

Machine

Table 8: Machine operation options

Connector Object	Option	All Possible Values	Description	Example
Machine	aadDeviceId	Any unique identifier for a Azure Active Directory machine	Retrieve machines with the specified Azure Active Directory device ID.	Key: aadDeviceId Value: 12345678-abcd-1234-ef00-123456abcdef. This key and value combination only retrieves machines whose Azure Active Directory device ID is 12345678-abcd-1234-ef00-123456abcdef.
	computerDnsName	Any 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.
	exposureLevel	None, Low, Medium, High	Retrieve 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.
	healthStatus	Active, Inactive, ImpairedCoummunication, NoSensorData, NoSensorDataImpairedCommunication, Unknown	Retrieve 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.
	lastIpAddress	Any IP address associated with a machine	Retrieve machines with the associated IP address.	Key: lastIpAddress Value: 192.0.2.53. This key and value combination only retrieves machines associated with an IP address of 192.0.2.53.
	lastSeen	Any 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.
	onboardingStatus	onboarded, CanBeOnboarded, InsufficientInfo, Unsupported	Retrieve machines with the specified onboarding status.	Key: onboardingStatus Value: Unsupported. This key and value combination only retrieves machines that have an unsupported onboarding status.
	osPlatform	A 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.
	rbacGroupId	Any RBAC group ID	Retrieve machines with the specified RBAC group ID.	Key: rbacGroupId Value: 7b3f5c5c-c4c4 This key and value combination only retrieves machines with the RBAC group ID of 7b3f5c5c-c4c4.
	riskScore	None, Informational, Low, Medium, High	Retrieve 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.

Package

Table 9: Package operation options

Connector Object	Option	All Possible Values	Description	Example
Package	id	Any package ID	Retrieve packages with the specified ID.	Key: id Value: microsoft-_-edge. This key and value combination only retrieves packages with the microsoft-_-edge ID.
	name	Any package name	Retrieve packages with the specified name.	Key: name Value: edge. This key and value combination only retrieves packages with the edge name.
	vendor	Any package vendor	Retrieve packages with the specified vendor name.	Key: vendor Value: microsoft. This key and value combination only retrieves packages with the microsoft vendor name.

Vulnerability

Table 10: Vulnerability operation options

Connector Object	Option	All Possible Values	Description	Example
Vulnerability	rbacGroupId	Any RBAC group ID	Retrieve vulnerabilities associated with the specified RBAC group ID.	Key: rbacGroupId Value: 7b3f5c5c-c4c4 This key and value combination only retrieves vulnerabilities associated with the RBAC group ID of 7b3f5c5c-c4c4.
	severity	Low, Medium, High, or Critical	Retrieve vulnerabilities with the specified severity level.	Key: severity Value: Critical. This key and value combination only retrieves the critical vulnerabilities.
	status	active, fixed	Retrieve only active or fixed vulnerabilities.	Key: status Value: active. This key and value combination only retrieves active vulnerabilities.

Vulnerability Definition

Table 11: Vulnerability Definition operation options

Connector Object	Option	All Possible Values	Description	Example
Vulnerability Definition	id	A comma-separated list of vulnerability IDs.	Retrieve vulnerabilities with the specified IDs.	Key: id Value: CVE-2023-22664. This key and value combination only retrieves vulnerabilities pertaining to CVE-2023-22664.
	cvssV3	Any CVSS v3 (Common Vulnerability Scoring System) score	Retrieve vulnerabilities with the specified CVSS v3 score.	Key: cvssV3 Value: 6.3. This key and value combination only retrieves vulnerabilities that have a CVSS v3 score of 6.3.
	description	Any CVE description	Retrieve vulnerabilities with the specified description.	Key: description Value: A memory corruption vulnerability exists in Microsoft Exchange Server when the server fails to properly handle objects in memory. This key and value combination only retrieves vulnerabilities associated with the specified CVE description.
	name	Any CVE name	Retrieve vulnerabilities with the specified CVE name.	Key: name Value: CVE-2019-0608. This key and value combination only retrieves vulnerabilities associated with CVE-2019-0608.
	publishedOn	Any date and time value in the ISO 8601 format	Retrieve vulnerabilities published on the specified date.	Key: publishedOn Value: 2023-02-09TO9:45:00Z. This key and value combination only retrieves vulnerabilities published on February 9th, 2023 at 9:45AM.
	severity	Low, Medium, High, or Critical	Retrieve vulnerabilities with the specified severity level.	Key: severity Value: Critical. This key and value combination only retrieves the critical vulnerabilities.
	updatedOn	Any date and time value in the ISO 8601 format	Retrieve vulnerabilities that were last updated on the specified date.	Key: updatedOn Value: 2023-02-09TO9:45:00Z. This key and value combination only retrieves vulnerabilities updated on February 9th, 2023 at 9:45AM.

note

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

Synchronization types

When using the Microsoft Defender for Endpoint connector, it's important to understand the different sync interval types available:

1. Beginning of Time (BoT)

   • BoT syncs comprehensively pull all available data from your Microsoft Defender for Endpoint environment, as specified by your integration configuration. You should use a BoT sync for initial setups or complete data refreshes.

2. Delta

   • Delta syncs retrieve only the data that has changed over the last 14 days since your last sync. You should use delta syncs after running an initial BoT sync for regular updates, capturing new, resolved, or updated data without reprocessing all historical data.

APIs

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

Table 12: Microsoft Defender for Endpoint API Endpoints

Connector Object	API Endpoints
Installed Package	GET /api/software/{softwareId}/distributions GET /api/Software/{softwareId}/machineReferences
Machine	GET /api/machines
Package	GET /api/software/{softwareId}/distributions
Vulnerability	GET /api/machines/SoftwareVulnerabilityChangesByMachine
	GET /api/machines/SoftwareVulnerabilitiesExport
Vulnerability Definition	GET /api/recommendations
	GET /api/recommendationsId/vulnerabilities
	GET /api/vulnerabilities

Changelog

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

3.4.5

• Added support for CVSS calculations to the Vulnerability Definition object. As a result, the following attributes have been added to Vulnerability Definition:

  • CVSS_V2_AC
  • CVSS_V2_AI
  • CVSS_V2_AU
  • CVSS_V2_AV
  • CVSS_V2_BASE_SCORE
  • CVSS_V2_CI
  • CVSS_V2_E
  • CVSS_V2_II
  • CVSS_V2_RC
  • CVSS_V2_RL
  • CVSS_V2_TEMPORAL_SCORE
  • CVSS_V2_VECTOR
  • CVSS_V3_AC
  • CVSS_V3_AI
  • CVSS_V3_AV
  • CVSS_V3_BASE_SCORE
  • CVSS_V3_CI
  • CVSS_V3_E
  • CVSS_V3_II
  • CVSS_V3_PR
  • CVSS_V3_RC
  • CVSS_V3_RL
  • CVSS_V3_UI
  • CVSS_V3_VECTOR

3.4.4

• No change.

3.4.3

• No change.

3.4.2

• No change.

3.4.1

• Added support for Data lifecycle management to the Machine and Vulnerability objects.

3.4.0

• No change.

3.3.9

• No change.

3.3.8

• Removed the WEAKNESSES attribute from the Package object.

3.3.6

• Changed the WEAKNESS attribute type on the Package object from integer to string.

3.3.5

• Added three new operation options for the Vulnerability object: rbacGroupId, severity, and status.

• Changed the SOURCE_RISK_SCORE attribute on the Machine object to SOURCE_RISK_RATING.

3.3.1

• Added the Installed Package and Package connector objects.

3.2.2

• Mapped Affected Software in a CVE to the AFFECTED attribute in the Vulnerability Definition object.

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

• Initial Integration+ release.