# Microsoft Defender
## Supported Products
### [Microsoft Defender For Endpoint](#microsoft-defender-for-endpoint-1)
The Microsoft Defender for Endpoint context integration provides enriched asset context to Netography Fusion from Microsoft Defender for Endpoint. It connects to the Microsoft Defender for Endpoint API, retrieves asset information associated with a collection of `Machines`, then adds it as [Context Labels](/enrich-traffic-with-context/labels.md) to Netography Fusion.
### [Microsoft Defender XDR](#microsoft-defender-xdr-1)
The Microsoft Defender XDR NetoFuse module provides enriched asset context to Netography Fusion from Microsoft Defender XDR. It connects to the Microsoft Security Graph API, allowing you to define a custom Kusto (KQL) query to retrieve data from any schema available in Microsoft Defender XDR's advanced hunting tool, and then adds the results as [Context Labels](/enrich-traffic-with-context/labels.md) to Netography Fusion.
{% hint style="info" %}
**⚖️Choosing which context integration to use**
Both Microsoft Defender context integrations can be used to provide enriched asset context to Netography Fusion from Microsoft Defender For Endpoint.
The Microsoft Defender for Endpoint NetoFuse module requires no configuration beyond setting up API access and works with all Microsoft Defender for Endpoint deployments.
The Microsoft Defender XDR context integration provides a flexible Kusto (KQL) integration to Microsoft Defender XDR's advanced hunting schemas and is built for advanced users in organizations with Microsoft Defender for Endpoint P2 licenses. This module can be used to query and join information across the full suite of Microsoft XDR products including Endpoint, Identity, Cloud, and E-Mail.
Use of the integrations is not mutually exclusive. You can start with the Microsoft Defender for Endpoint context integration to cover the basic asset information, and then extend that by building Kusto queries to use with the Microsoft Defender XDR context integration as you pinpoint additional context to use for enrichment. If you may want to use both in the future, add both the permissions listed below when creating the Microsoft Entra application used to provide access credentials for the APIs:
* `Machine.Read.All`permission in the `WindowsDefenderATP`API (Microsoft Defender for Endpoint)
* `ThreatHunting.Read.All`permission in the `Microsoft Graph`API (Microsoft Defender XDR)
{% endhint %}
***
## Microsoft Defender for Endpoint
The Microsoft Defender for Endpoint context integration provides enriched asset context to Netography Fusion from Microsoft Defender for Endpoint. It connects to the Microsoft Defender for Endpoint API, retrieves asset information associated with a collection of `Machines`, then adds it as [Context Labels](/enrich-traffic-with-context/labels.md) to Netography Fusion.
This utilizes the Microsoft Defender for Endpoint [List machines API](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/api/get-machines?view=o365-worldwide).
### Configuring
| Field | Required | Description |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tenant ID | Yes | Azure tenant ID |
| Application ID | Yes | Azure application id |
| App Secret | Yes | Azure application secret |
| Per Page | Yes | Number of results per API call to retrieve (default 1000) |
| Filter | No | If set, it limits what Machines are retrieved by the API. Microsoft documentation for the `filter` field is available at: [OData queries with Microsoft Defender for Endpoint](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-odata-samples?view=o365-worldwide). |
### Microsoft Defender for Endpoint Configuration
You need to create a Microsoft Entra application with`Machine.Read.All` permission in the `WindowsDefenderATP` API. An Azure user with the `Global Administrator` role must perform this step.
See: [Create an app to access Microsoft Defender for Endpoint without a user](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/api/exposed-apis-create-app-webapp?view=o365-worldwide)
### Transform
The **Advanced** section of the context integration contains the *Transform* field. This field allows you to add, remove, or change the mapping of fields returned by the vendor API to Netography Fusion context labels.
See the [Context Transforms](/netofuse/context-transforms.md) documentation section for more instructions on editing this field.
It may be helpful to first configure all the parameters and the transform field with a [NetoFuse](/netofuse/about.md) container on your local system and then copy those fields into the Portal once you have validated that everything is configured properly.
Comment and uncomment fields in the transform to select which are included as context labels.
***
## Microsoft Defender XDR
The Microsoft Defender XDR NetoFuse module provides enriched asset context to Netography Fusion from Microsoft Defender XDR. It connects to the Microsoft Security Graph API, allowing you to define a custom Kusto (KQL) query to retrieve data from any schema available in Microsoft Defender XDR's advanced hunting tool, and then adds the results as [Context Labels](/enrich-traffic-with-context/labels.md) to Netography Fusion.
This utilizes the `runHuntingQuery`API endpoint in the [Microsoft Security Graph API](https://learn.microsoft.com/en-us/graph/api/resources/security-api-overview?view=graph-rest-1.0#advanced-hunting).
### Requirements
{% hint style="danger" %}
**❗️The Microsoft Defender XDR context integration requires you are using a Microsoft Defender for Endpoint Plan 2 (P2) license from Microsoft to access device information**
Device level data collected through Microsoft Defender for Endpoint is only available through the API this module uses I with a Microsoft Defender for Endpoint Plan 2 (P2) license. If your organization is using a Plan 1 (P1) license, use the Microsoft Defender for Endpoint module and not the Microsoft Defender XDR module. For more details on this, see: [Compare Microsoft endpoint security plans](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/defender-endpoint-plan-1-2?view=o365-worldwide).
If you are a Microsoft Defender admin, you can go to , and click the Schemas tab to see what access you have to this feature. If you see a `Devices` schema with a `DeviceInfo` table, you have the right access. If that is missing, you may be on a P1 plan or do not have permissions for advanced hunting in your user role.
You could still theoretically use this module without access to the `Devices` schema, but you will need to determine if the schemas available to you can provide asset information that can be used as context labels.
{% endhint %}
### Configuring
| Field | Required | Description |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tenant ID | Yes | Azure tenant ID |
| Application ID | Yes | Azure application id |
| App Secret | Yes | Azure application secret |
| Queries | Yes | Kusto (KQL) query to use with integration |
| Skip Transform | Yes | KQL supports direct field mapping within the Kusto query, so separate transforms are unnecessary for this module. This is set to`True` by default, and will add context labels for all keys returned in the assets. The `ip` field is required to exist for labels to be uploaded. All other fields are optional.\*\* |
### Microsoft Defender XDR Configuration
You need to create a Microsoft Entra application with the `ThreatHunting.Read.All` permission in the `Microsoft Graph` API. An Azure user with the `Global Administrator` role must perform this step.
See: [Microsoft Graph Documentation > Develop > Authentication and authorization > Get access without a user](https://learn.microsoft.com/en-us/graph/auth-v2-service?tabs=http).
#### Configuring KQL Queries
KQL Queries are the base of the Microsoft Defender XDR module. Developing queries in the [Microsoft Defender Advanced Hunting Portal](https://learn.microsoft.com/en-us/microsoft-365/security/defender/advanced-hunting-overview?view=o365-worldwide) is recommended, and then copy the queries once they return the results you want into the module configuration.
The `DeviceInfo` table in the `Devices` schema is the source of the basic asset information in queries. More information on building KQL queries is available from Microsoft at [Proactively hunt for threats with advanced hunting in Microsoft Defender XDR](https://learn.microsoft.com/en-us/microsoft-365/security/defender/advanced-hunting-overview?view=o365-worldwide\&preserve-view=true) and [Microsoft Security Copilot in advanced hunting](https://learn.microsoft.com/en-us/microsoft-365/security/defender/advanced-hunting-security-copilot?view=o365-worldwide).
**KQL Query Examples**
Below are some KQL query configurations.
**Get Public IP and Device Platform**
{% tabs %}
{% tab title="YAML" %}
```
'DeviceInfo | distinct ip=PublicIP, os=OSPlatform'
```
{% endtab %}
{% endtabs %}
**Retrieve newest Device ID, OS, OS Version and Onboarding Status from Device Info**
{% tabs %}
{% tab title="YAML" %}
```
'DeviceInfo
| distinct ip=PublicIP, os=OSPlatform, osver=OSVersion, msd_exposurelevel=ExposureLevel, msd_devicevalue=AssetValue, msd_osbuild=OSBuild, msd_onboardingstatus=OnboardingStatus, msd_id=DeviceId, Timestamp
| summarize arg_max(Timestamp, *) by msd_id
| project-away Timestamp'
```
{% endtab %}
{% endtabs %}
**Add DeviceName, OS, OSVer, Architecture, Interface Name, Mac Address, Manufacturer, ip, and Logged On Users.**
{% tabs %}
{% tab title="YAML" %}
```
'let base = DeviceNetworkInfo
| where Timestamp > ago(24h)
| mv-expand parsejson(IPAddresses)
| distinct DeviceId, ip=tostring(IPAddresses.IPAddress), ifname=NetworkAdapterName, MacAddress
| join kind=fullouter DeviceEvents on DeviceId
| join kind=fullouter (DeviceInfo
| mv-expand parse_json(LoggedOnUsers)) on DeviceId
| distinct name=DeviceName, os=OSPlatform, osver=OSVersion, arch=OSArchitecture, ifname, manufacturer=Vendor, DeviceId, Timestamp, ip, PublicIP, eventuser=tostring(LoggedOnUsers.UserName), mac_addr=MacAddress
| summarize arg_max(Timestamp, *) by DeviceId;
base
| project-away PublicIP
| union (
base | project-away ip | project-rename ip=PublicIP)
| where not( isempty(ip))'
```
{% endtab %}
{% endtabs %}
### Transform
{% hint style="info" %}
**⚖️Context transforms are not needed for this module, but are supported**
KQL supports direct field mapping within the Kusto query, and as such separate transforms are not necessary for this module. The `skip_transform` setting is set to `True` by default, and will add labels for all keys returned in the assets.
**The `ip` field is required to exist for labels to be uploaded. All other fields are optional.**
If you set `skip_transform` to `False`, you can still use context transforms with this context integration. This would be useful if you wanted to do some more advanced post-processing of the data returned by the KQL query beyond what is natively available with Kusto.
{% endhint %}
The **Advanced** section of the context integration contains the *Transform* field. This field allows you to add, remove, or change the mapping of fields returned by the vendor API to Netography Fusion context labels.
See the [Context Transforms](/netofuse/context-transforms.md) documentation section for more instructions on editing this field.
It may be helpful to first configure all the parameters and the transform field with a [NetoFuse](/netofuse/about.md) container on your local system and then copy those fields into the Portal once you have validated that everything is configured properly.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fusion.vectra.ai/enrich-traffic-with-context/configure-context-integrations/microsoft-defender-context.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.