Microsoft Defender for Endpoint
Endpoint Protection- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The Microsoft Defender for Endpoint connector integrates with the Microsoft Defender for Endpoint (ATP) REST API to synchronize endpoint inventory and threat-and-vulnerability-management (TVM) data into the Brinqa platform. It retrieves onboarded machines, installed software, and software vulnerabilities, and maps them to hosts, packages, installed packages, vulnerability findings, and vulnerability definitions.
The connector synchronizes the following categories of data:
- Machines — Onboarded devices from the Defender for Endpoint inventory, mapped to hosts
- Packages — Distinct software products discovered across machines
- Installed Packages — Software installations linking a package to the machine it is installed on
- Vulnerabilities — Per-device software vulnerability findings
- Vulnerability Definitions — CVE/recommendation definitions behind the vulnerability findings
Category: Endpoint Protection
Data retrieved from Microsoft Defender for Endpoint
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Machine | Yes | Host |
| Vulnerability | Yes | Vulnerability |
| Vulnerability Definition | Yes | Vulnerability Definition |
| Package | Yes | Package |
| Installed Package | Yes | Installed Package |
Model relationships
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.
Connection settings
When setting up a data integration, select Microsoft Defender for Endpoint from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | https://api.securitycenter.microsoft.com | Microsoft Defender for Endpoint API URL |
| Login URL | Yes | https://login.microsoftonline.com | Microsoft Identity Platform authentication URL |
| Client ID | Yes | — | The service principal client ID. The client ID is generated during service principal registration. |
| Client secret | No | — | The service principal client secret or password. |
| Tenant ID | Yes | — | The tenant or domain the credential is authorized for. The tenant ID is generated during service principal registration. |
| Private key | No | — | The service principal certificate credential's private key and public key. |
| Maximum retries | No | 5 | The maximum number of retry attempts before giving up a request |
| Parallelism | No | number of processors | The number of threads to use for parallel processing |
| Fail sync on error | No | false | Fail sync when and error is encountered on export file download/processing |
Authentication
The connector authenticates a service principal using the OAuth 2.0 client-credentials flow, and supports two mutually exclusive credential types — a client secret or a certificate (private key). When a private key is configured, certificate-based authentication is used and the client secret is ignored; otherwise the client secret is used.
Endpoint
| Method | URL |
|---|---|
POST | {loginUrl}/{tenantId}/oauth2/v2.0/token |
Request Body (form-urlencoded)
| Parameter | Value |
|---|---|
grant_type | client_credentials |
client_id | {clientId} |
client_secret | {clientSecret} |
scope | https://securitycenter.onmicrosoft.com/windowsatpservice/.default |
Usage
Once authenticated, all subsequent API requests include the bearer token, which is cached until expiry and refreshed automatically:
Authorization: Bearer <access_token>
The OAuth scope https://securitycenter.onmicrosoft.com/windowsatpservice/.default is used for both the client-secret and certificate flows.
Key and Certificate Generation
-
Generate the private key and certificate in a terminal:
# Generate private keyopenssl genpkey -algorithm RSA -out private_key.pem# Generate certificate signing request (enter the requested information at the prompts)openssl req -new -key private_key.pem -out csr.pem# Generate self-signed certificateopenssl x509 -req -in csr.pem -signkey private_key.pem -out certificate.pem -
Upload
certificate.pemin the Azure portal. -
Pass
private_key.pemandcertificate.pemtogether in the Private key input field (concatenated):-----BEGIN PRIVATE KEY-----<private_key.pem>-----END PRIVATE KEY----------BEGIN CERTIFICATE-----<certificate.pem>-----END CERTIFICATE-----
Sync Behavior
The connector supports both full and incremental (delta) syncs, and the effective behavior depends on the model and whether a sync-since timestamp is provided:
- Machine — Incremental. When a
sincetimestamp is set,lastSeen gt {since}is added to the$filter; otherwise all machines are enumerated. - Vulnerability — Incremental with full fallback. When
sinceis null, a full software-vulnerabilities export is downloaded; whensinceis set, only changes since that time are fetched (SoftwareVulnerabilityChangesByMachine, capped to a maximum of 14 days in the past). - Vulnerability Definition — Incremental. When a
sincetimestamp is set,updatedOn ge {since}is added to the CVE-catalog$filter; otherwise the full catalog is enumerated. - Package and Installed Package — Full only. The software listing has no time-based change filter, so every sync enumerates all software and its machine references.
Per-model incremental details are documented under each model's Sync Duration Parameter below.
How to obtain Microsoft Defender for Endpoint credentials
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:
-
Log in to your Microsoft Azure Portal as an administrator.
-
Navigate to and click Microsoft Entra ID.
-
On the left-hand side of the page, click App registrations, and then click New registration.
-
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.
-
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:
-
Click Certificates & secrets and then click New client secret.
-
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:
-
Navigate to API permissions > Add a permission > APIs my organization uses and select WindowsDefenderATP.
-
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
-
-
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.
Generate a private key and certificate
If you choose to authenticate using a private key, you must generate a private key and certificate, upload the certificate to Azure, and then enter the combined string into the Private key field in the integration configuration.
Use your organization's approved method to generate the private key and certificate. If no method is available, or for testing purposes, you can follow the steps below to create a self-signed certificate using OpenSSL:
-
Open your terminal and generate a new private key:
openssl genpkey -algorithm RSA -out private_key.pem -
Generate a certificate signing request (CSR). Enter the required information when prompted:
openssl req -new -key private_key.pem -out csr.pem -
Generate a self-signed certificate:
openssl x509 -req -in csr.pem -signkey private_key.pem -out certificate.pem -
In the Microsoft Azure Portal, navigate to your registered Azure application.
-
On the left-hand side of the page, click Certificates & secrets, click the Certificates tab, and then click Upload certificate.
Upload the
certificate.pemfile you created in step 3. -
Click Add.
-
Combine
private_key.pemandcertificate.peminto a single string, and paste the result into the Private key field in the integration configuration. Use the following format:-----BEGIN PRIVATE KEY-----<contents of private_key.pem>-----END PRIVATE KEY----------BEGIN CERTIFICATE-----<contents of certificate.pem>-----END CERTIFICATE-----
Note: For more information, see the Microsoft documentation on certificate credentials.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Machine
| Source Field Name | SDM Attribute |
|---|---|
aadDeviceId (excludes all-zero GUID) | AAD_DEVICE_ID |
agentVersion | AGENT_VERSION |
computerDnsName (normalized) | HOSTNAMES |
computerDnsName (private) | PRIVATE_DNS_NAMES |
computerDnsName (public) | PUBLIC_DNS_NAMES |
| computerDnsName → lastExternalIpAddress → lastIpAddress → first ipAddress → aadDeviceId | NAME |
constants | CATEGORIES |
defenderAvStatus | AV_STATUS |
| derived from healthStatus | STATUS |
deviceValue | DEVICE_VALUE |
exclusionReason | EXCLUSION_REASON |
exposureLevel | EXPOSURE_LEVEL |
firstSeen | FIRST_SEEN |
healthStatus | HEALTH_STATUS |
ipAddresses (Ethernet), lastIpAddress, lastExternalIpAddress | IP_ADDRESSES |
ipAddresses[].macAddress (normalized) | MAC_ADDRESSES |
isAadJoined | IS_AAD_JOINED |
isExcluded | IS_EXCLUDED |
isPotentialDuplication | POTENTIAL_DUPLICATION |
lastSeen | LAST_SEEN |
| local IPs from ipAddresses, lastIpAddress | PRIVATE_IP_ADDRESSES |
machine tags (InstanceId) or vmMetadata.vmId | INSTANCE_ID |
machine.id | UID |
machineTags | TAGS |
managedBy | MANAGED_BY |
managedByStatus | MANAGED_BY_STATUS |
mergedIntoMachineId | MERGED_INFO_MACHINE_ID |
| non-local IP / lastExternalIpAddress | PUBLIC_IP_ADDRESSES |
onboardingStatus | ONBOARDING_STATUS |
| operatingSystem else computerDnsName | DESCRIPTION |
osArchitecture | OS_ARCHITECTURE |
osBuild | OS_BUILD |
osPlatform | OS_PLATFORM |
| osPlatform + version + osArchitecture + osBuild | OPERATING_SYSTEM |
osProcessor | OS_PROCESSOR |
osVersion | OS_VERSION |
rbacGroupId | RBAC_GROUP_ID |
rbacGroupName | RBAC_GROUP_NAME |
riskScore | SOURCE_RISK_RATING |
| sync timestamp | LAST_CAPTURED |
vmMetadata.cloudProvider | CLOUD_PROVIDER |
vmMetadata.resourceId | CLOUD_RESOURCE_ID |
vmMetadata.subscriptionId | CLOUD_SUBSCRIPTION_ID |
Vulnerability
| Source Field Name | SDM Attribute |
|---|---|
cveId | CVE_ID |
derived (software + disk/registry paths) | RESULTS |
| derived from status | STATUS_CATEGORY |
deviceId | TARGETS |
deviceId | DEVICE_ID |
deviceName | HOSTNAMES |
deviceName | DEVICE_NAME |
diskPaths | DISK_PATHS |
eventTimestamp | SOURCE_LAST_MODIFIED |
| eventTimestamp when status is Fixed | LAST_FIXED |
firstSeenTimestamp | FIRST_FOUND |
joined MachineResource.lastSeen | DEVICE_LAST_SEEN |
lastSeenTimestamp | LAST_FOUND |
| MSID-{cveId}-{recommendationReference} | TYPE |
| normalized status | STATUS |
normalized status (default active) | SOURCE_STATUS |
| normalized vulnerabilitySeverityLevel | SEVERITY |
rbacGroupName | RBAC_GROUP_NAME |
recommendationReference | RECOMMENDATION_REFERENCE |
recommendedSecurityUpdate | RECOMMENDED_SECURITY_UPDATE |
recommendedSecurityUpdateId | RECOMMENDED_SECURITY_UPDATE_ID |
registryPaths | REGISTRY_PATHS |
softwareName | SOFTWARE_NAME |
softwareVendor | SOFTWARE_VENDOR |
softwareVersion | SOFTWARE_VERSION |
status | PROVIDER_STATUS |
| sync timestamp | LAST_CAPTURED |
vuln.id | UID |
vuln.id | NAME |
vulnerabilitySeverityLevel | SOURCE_SEVERITY |
Vulnerability Definition
| Source Field Name | SDM Attribute |
|---|---|
!recommendation.hasUnpatchableCve (fallback securityUpdateAvailable) | PATCHABLE |
cvssV3 | CVSS_V3_BASE_SCORE |
cvssVector (parsed by the CVSS utility) | CVSS metrics (CVSS_V2_, CVSS_V3_) |
| derived from exploitVerified / publicExploit / exploitInKit | EXPLOITABILITY |
exploitTypes | EXPLOIT_TYPES |
exploitUris | EXPLOITS |
exploitUris | REFERENCES |
MSID-{cveId}-{recommendationReference} (or MSID-{cveId} / MSID-{recommendation}) | UID |
| normalized severity | SEVERITY |
publishedOn | PUBLISHED_DATE |
recommendation.recommendationName (fallback recommendedSecurityUpdate) | RECOMMENDATION |
recommendation.relatedComponent (fallback software) | AFFECTED |
severity | SOURCE_SEVERITY |
updatedOn | SOURCE_LAST_MODIFIED |
vulnerability.description | SUMMARY |
vulnerability.description | DESCRIPTION |
vulnerability.id (when CVE-*) | CVE_IDS |
vulnerability.id (when CVE-*) | CVE_RECORDS |
vulnerability.id, then vulnerability.name / recommendation name | NAME |
Package
| Source Field Name | SDM Attribute |
|---|---|
| constant active | STATUS |
| constant Package | CATEGORIES |
distributions[].version | VERSIONS |
software.activeAlert | ACTIVE_ALERT |
software.exposedMachines | EXPOSED_MACHINES |
software.id | UID |
software.impactScore | IMPACT_SCORE |
software.name | NAME |
software.publicExploit | PUBLIC_EXPLOIT |
software.vendor | VENDOR |
Installed Package
| Source Field Name | SDM Attribute |
|---|---|
| constant active | STATUS |
machine.computerDnsName | DNS_NAMES |
machine.id | TARGETS |
machine.osPlatform | OPERATING_SYSTEM |
machine.rbacGroupId | RBAC_GROUP_ID |
machine.rbacGroupName | RBAC_GROUP_NAME |
MD5 of (software.id, machine.id) | UID |
software.id | TYPE |
software.id + :: + machine.id | NAME |
Operations & API
Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).
Machine
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
filter | String | Raw OData $filter expression | |
computerDnsName | String | Filter by computerDnsName eq | |
machineTags | String | Filter by machineTags eq | |
exposureLevel | String | Filter by exposureLevel eq | |
onboardingStatus | String | Filter by onboardingStatus eq | |
healthStatus | String | Filter by healthStatus eq | |
osPlatform | String | Filter by osPlatform eq | |
riskScore | String | Filter by riskScore eq | |
rbacGroupId | String | Filter by rbacGroupId eq (unquoted) |
Delta sync
The connector README does not document delta sync behavior for this object.
API
- Type: REST — Defender for Endpoint API (base
https://api.securitycenter.microsoft.com) · Endpoint:GET api/machines
Vulnerability
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
rbacGroupId | String | Comma-separated RBAC group IDs (in-memory filter) | |
severity | String | Comma-separated severities (in-memory filter) | |
status | String | Comma-separated statuses (in-memory filter) |
Delta sync
The connector README does not document delta sync behavior for this object.
API
- Type: REST — Defender for Endpoint API
Vulnerability Definition
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
filter | String | Raw OData $filter expression | |
id | String | Filter by id eq | |
cvssV3 | Number | Filter by cvssV3 ge | |
severity | String | Filter by severity eq |
Delta sync
The connector README does not document delta sync behavior for this object.
API
- Type: REST — Defender for Endpoint API
Package
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
filter | String | Raw OData $filter expression | |
id | String | Filter by id eq | |
name | String | Filter by name eq | |
vendor | String | Filter by vendor eq |
Delta sync
The connector README does not document delta sync behavior for this object.
API
- Type: REST — Defender for Endpoint API
Installed Package
Operation options
This object does not support any operation options.
Delta sync
The connector README does not document delta sync behavior for this object.
API
- Type: REST — Defender for Endpoint API
Changelog
The Microsoft Defender for Endpoint connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.5.9 | No changes in this release. | N/A |
| 3.5.8 | No changes in this release. | N/A |
| 3.5.7 | Bug Fixes - Vulnerability findings now reliably link to their Vulnerability Definitions. Definitions are now built from the same per-device vulnerability data as the findings, so every finding that carries a CVE or a recommendation resolves to a definition — including cases where Microsoft's security-recommendation catalog did not associate a device's CVE with its recommendation (for example, certain Linux/Red Hat packages), which previously left those findings without a matching definition. Improvements - Vulnerability Definitions now reflect the specific recommendation reported for a device, while still keeping a definition for every CVE in the catalog. - When a recommendation is not present in the recommendation catalog, the affected software and recommended update shown on the definition fall back to the values reported on the device. - Vulnerability findings expose the source CVE ID and recommendation reference as their own attributes ( CVE_ID, RECOMMENDATION_REFERENCE), making the definition linkage easy to verify. | • Vulnerability Definition: Definition identifiers and sources have changed. — Action: Delete existing Vulnerability Definition data, then run a full sync of Vulnerability Definitions and Vulnerabilities so findings re-link to the new definitions. |
| 3.5.6 | No changes in this release. | N/A |
| 3.5.5 | No changes in this release. | N/A |
| 3.5.4 | No changes in this release. | N/A |
| 3.5.3 | No changes in this release. | N/A |
| 3.5.2 | No changes in this release. | N/A |
| 3.5.1 | No changes in this release. | N/A |
| 3.5.0 | No changes in this release. | N/A |
| 3.4.32 | No changes in this release. | N/A |
| 3.4.31 | No changes in this release. | N/A |
| 3.4.30 | No changes in this release. | N/A |
| 3.4.29 | Improvements - Vulnerabilities that map to more than one Defender security recommendation are now synchronized as one record per recommendation, giving a more complete view of remediation options for each finding. - Vulnerability definitions that lack a CVE identifier now fall back to the associated recommendation reference so they are still synchronized instead of being dropped. | • Vulnerability: A single source vulnerability may now produce multiple records (one per recommendation). Re-sync the Defender for Endpoint connector to rebuild vulnerability data. |
| 3.4.28 | No changes in this release. | N/A |
| 3.4.27 | No changes in this release. | N/A |
| 3.4.26 | No changes in this release. | N/A |
| 3.4.25 | No changes in this release. | N/A |
| 3.4.24 | No changes in this release. | N/A |
| 3.4.23 | New Features - Added a "Device last seen" attribute to the Machine model, recording when each device was most recently observed by Defender for Endpoint. | N/A |
| 3.4.22 | No changes in this release. | N/A |
| 3.4.21 | Improvements - Reverted the vulnerability definition identifier scheme introduced in the previous release back to the original CVE-based identifier. | • Vulnerability Definition: Vulnerability definition identifiers changed. Re-sync the Defender for Endpoint connector to rebuild vulnerability definition data. |
| 3.4.20 | Improvements - Vulnerability definition identifiers are now generated using a shared utility that combines the CVE and recommendation references, improving consistency of definition keys. | • Vulnerability Definition: Vulnerability definition identifiers changed. Re-sync the Defender for Endpoint connector to rebuild vulnerability definition data. |
| 3.4.19 | No changes in this release. | N/A |
| 3.4.18 | No changes in this release. | N/A |
| 3.4.17 | New Features - Added software, recommendation, and device-context attributes to the Machine model — including software name, version and vendor, recommended security update details, disk and registry paths, RBAC group, and device ID. | N/A |
| 3.4.16 | No changes in this release. | N/A |
| 3.4.15 | No changes in this release. | N/A |
| 3.4.14 | No changes in this release. | N/A |
| 3.4.13 | No changes in this release. | N/A |
| 3.4.12 | No changes in this release. | N/A |
| 3.4.11 | No changes in this release. | N/A |
| 3.4.10 | No changes in this release. | N/A |
| 3.4.9 | No changes in this release. | N/A |
| 3.4.8 | No changes in this release. | N/A |
| 3.4.7 | No changes in this release. | N/A |
| 3.4.6 | No changes in this release. | N/A |
| 3.4.5 | No changes in this release. | N/A |
| 3.4.4 | No changes in this release. | N/A |
| 3.4.3 | No changes in this release. | N/A |
| 3.4.2 | No changes in this release. | N/A |
| 3.4.1 | No changes in this release. | N/A |
| 3.4.0 | No changes in this release. | N/A |
| 3.3.10 | No changes in this release. | N/A |
| 3.3.9 | No changes in this release. | N/A |
| 3.3.8 | No changes in this release. | N/A |
| 3.3.7 | No changes in this release. | N/A |
| 3.3.6 | No changes in this release. | N/A |
| 3.3.5 | No changes in this release. | N/A |
| 3.3.4 | Improvements - Renamed the machine "Source risk score" attribute to "Source risk rating" to better reflect the categorical risk value reported by Defender for Endpoint. | • Machine: The "Source risk score" attribute was renamed to "Source risk rating". Re-sync the Defender for Endpoint connector so machine data reflects the new attribute. |
| 3.3.3 | No changes in this release. | N/A |
| 3.3.2 | Bug Fixes - The machine "Source risk score" attribute is now stored as text rather than a number, matching the categorical risk values (for example, "High") returned by Defender for Endpoint. | • Machine: The "Source risk score" attribute changed type from numeric to text. Re-sync the Defender for Endpoint connector to rebuild machine data with the corrected type. |
| 3.3.1 | New Features - Added the Package and Installed Package models, synchronizing the software packages discovered by Defender for Endpoint and the per-device installed package inventory. | N/A |
| 3.3.0 | No changes in this release. | N/A |
| 3.2.2 | No changes in this release. | N/A |
| 3.2.1 | No changes in this release. | N/A |
| 3.2.0 | No changes in this release. | N/A |
| 3.1.18 | Dependency Upgrades - Added the CVSS calculator library used for normalizing vulnerability severity scores. | N/A |
| 3.1.17 | No changes in this release. | N/A |
| 3.1.16 | New Features - Added "Potential duplication" and "Merged info machine ID" attributes to the Machine model, surfacing devices that Defender for Endpoint has flagged as potential duplicates or merged. | N/A |
| 3.1.15 | No changes in this release. | N/A |
| 3.1.14 | Improvements - Machine tags are now split into key/value pairs, making tag values easier to consume downstream. | N/A |
| 3.1.13 | No changes in this release. | N/A |
| 3.1.12 | Dependency Upgrades - Updated the local storage and data model libraries used during synchronization. | N/A |
| 3.1.11 | No changes in this release. | N/A |
| 3.1.9 | No changes in this release. | N/A |
| 3.1.8 | No changes in this release. | N/A |
| 3.1.7 | No changes in this release. | N/A |
| 3.1.6 | No changes in this release. | N/A |
| 3.1.5 | No changes in this release. | N/A |
| 3.1.4 | No changes in this release. | N/A |
| 3.1.3 | No changes in this release. | N/A |
| 3.1.2 | No changes in this release. | N/A |
| 3.1.1 | No changes in this release. | N/A |
| 3.1.0 | Improvements - Vulnerability definitions now fall back to the related component when a product name is unavailable, reducing blank product values. - Software vulnerability export downloads now recover gracefully from individual file errors instead of failing the sync. | N/A |
| 3.0.3 | New Features - Added the Vulnerability and Vulnerability Definition models, synchronizing per-device vulnerability findings and the underlying vulnerability definitions (including exploit type information) from Defender for Endpoint. | N/A |
| 3.0.2 | Overview The Defender for Endpoint connector integrates with Microsoft Defender for Endpoint to synchronize managed devices and their security posture. Category: Endpoint Protection Models | N/A |