# Microsoft
{% hint style="info" %}
**☁️NetoFuse Modules: Cloud deployment vs. On-Prem deployment**
This page documents how to add and configure the NetoFuse module for an on-prem deployment with a container or Python package. If you want to use the cloud deployment model and have this integration run in the Netography Fusion SaaS, you can add it as a context integration in the Netography Fusion Portal instead by consulting the [Context Integrations](https://docs.netography.com/enrich-traffic-with-context/configure-context-integrations) documentation.
{% endhint %}
Supported Products
### [Microsoft Defender For Endpoint](#microsoft-defender-for-endpoint-1)
The Microsoft Defender for Endpoint NetoFuse module 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 uploads it as [Context Labels](https://docs.netography.com/enrich-traffic-with-context/labels) to the Netography Fusion API.
### [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 uploads the results as [Context Labels](https://docs.netography.com/enrich-traffic-with-context/labels) to the Netography Fusion API.
{% hint style="info" %}
**⚖️Choosing between the two NetoFuse modules or using both**
Both Microsoft NetoFuse modules 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 NetoFuse module 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 modules is not mutually exclusive. You can start with the Microsoft Defender for Endpoint NetoFuse module to cover the basic asset information, and then extend that by building Kusto queries to use with the Microsoft Defender XDR module as you pinpoint additional context to use for enrichment. If you may want to use both modules 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 NetoFuse module 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 uploads it as [Context Labels](https://docs.netography.com/enrich-traffic-with-context/labels) to the Netography Fusion API.
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).
### API Configuration Parameters for Microsoft Defender for Endpoint
All the fields required for this integration are listed here, along with the corresponding environment variable name used to set that field in the NetoFuse module.
| Microsoft Field | Required | NetoFuse Environment Variable | Description |
| --------------- | -------- | ----------------------------------------- | ------------------------ |
| tenant ID | Yes | `NETO__DEFENDER__CREDENTIALS__TENANT_IT` | Azure tenant ID |
| Application ID | Yes | `NETO__DEFENDER__CREDENTIALS__APP_ID` | Azure application id |
| App Secret | Yes | `NETO__DEFENDER__CREDENTIALS__APP_SECRET` | Azure application secret |
### 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)
### `defender` NetoFuse Module Configuration
The Microsoft Defender For Endpoint module is named `defender` in NetoFuse.
All the fields required for this integration are listed above in the [Microsoft Defender for Endpoint API Configuration Parameters](#api-configuration-parameters) section above. See [Configure > module](https://docs.netography.com/configure#module) for additional options for setting configuration fields and [Security Considerations](https://docs.netography.com/netofuse/security-considerations) for additional options for setting credentials.
#### Advanced Configuration Options
You can edit the module configuration to add a `filter:` that 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).
**default `defender` module configuration**
{% tabs %}
{% tab title="YAML" %}
```
defender:
filter: null
credentials:
tenant_id:
app_id:
app_secret:
transform:
lastIpAddress:
context: ip
lastSeen:
context: mde_lastseen
lastExternalIpAddress:
context: external_ip
riskScore:
context: mde_risk
osPlatform:
context: os
function:
function: transform_os
version:
context: osver
# id:
# context: mde_id
# computerDnsName:
# context: mde_dnsname
# firstSeen:
# context: mde_firstseen
# onboardingstatus:
# context: mde_onboardingstatus
# osProcessor:
# context: mde_osprocessor
# osBuild:
# context: mde_osbuild
# healthStatus:
# context: mde_healthstatus
# rbacGroupName:
# context: mde_rbacgroupname
# rbacGroupId:
# context: mde_rbacgroupid
# aadDeviceId:
# context: mde_aaddeviceid
# machineTags:
# context: mde_machinetags
# exposureLevel:
# context: mde_exposurelevel
# deviceValue:
# context: mde_devicevalue
# ipAddresses:
# context: mde_ipaddresses
# osArchitecture:
# context: mde_osarchitecture
```
{% endtab %}
{% endtabs %}
## 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 uploads the results as [Context Labels](https://docs.netography.com/enrich-traffic-with-context/labels) to the Netography Fusion API.
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 NetoFuse module 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 %}
### API Configuration Parameters for Microsoft Defender XDR
All the fields required for this integration are listed here, along with the corresponding environment variable name used to set that field in the NetoFuse module.
| Microsoft Field | Required | NetoFuse Environment Variable | Description |
| --------------- | -------- | --------------------------------------------- | ------------------------ |
| tenant ID | Yes | `NETO__MICROSOFTXDR_CREDENTIALS__TENANT_ID` | Azure tenant ID |
| Application ID | Yes | `NETO__MICROSOFTXDR__CREDENTIALS__APP_ID` | Azure application id |
| App Secret | Yes | `NETO__MICROSOFTXDR__CREDENTIALS__APP_SECRET` | Azure application secret |
### 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).
### `microsoftxdr` NetoFuse Module Configuration
The Microsoft XDR module is named `microsoftxdr` in NetoFuse.
All the fields required for this integration are listed above in the [Microsoft Defender XDR API Configuration Parameters](#api-configuration-parameters-for-microsoft-defender-xdr) section above. See [Configure > module](https://docs.netography.com/configure#module) for additional options for setting configuration fields and [Security Considerations](https://docs.netography.com/netofuse/security-considerations) for additional options for setting credentials.
#### 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).
{% hint style="info" %}
**📘Unique Field Mapping for KQL Queries**
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.**
{% endhint %}
**KQL Query Examples**
Below are some KQL query configurations.
**Get Public IP and Device Platform**
{% tabs %}
{% tab title="YAML" %}
```
queries:
- '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" %}
```
queries:
- '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" %}
```
queries:
- '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 %}
#### default `microsoftxdr` module configuration
{% tabs %}
{% tab title="YAML" %}
```
microsoftxdr:
queries:
- '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, mde_id=DeviceId, Timestamp, ip, PublicIP, mde_eventuser=tostring(LoggedOnUsers.UserName), mac_addr=MacAddress
| summarize arg_max(Timestamp, *) by mde_id;
base
| project-away PublicIP
| union (
base | project-away ip | project-rename ip=PublicIP)
| where not( isempty(ip))'
skip_transform: true
credentials:
tenant_id:
app_id:
app_secret:
```
{% endtab %}
{% endtabs %}
#### `microsoftxdr` NetoFuse Context 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` or omit it, and define a `transform` value that maps to a transform in the configuration, you can still use context transforms with this module as with any other module. 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. For example, using a custom Python transform function in NetoFuse you could add additional filtering and converting of context values based on data that is available on your local host.
{% endhint %}