Migrate and upgrade the Splunk Add-on for Microsoft Security¶
Review every section between your installed version and the target version before you upgrade.
Upgrade to version 5.0.0¶
Version 5.0.0 moves the Defender Advanced Hunting alert action from the legacy Microsoft Defender XDR endpoint to Microsoft Graph POST /v1.0/security/runHuntingQuery. Complete the permission change before you upgrade so scheduled alerts can continue to run.
Prepare the Microsoft Graph permission¶
- Identify the Microsoft Entra application used by each Defender Advanced Hunting alert action.
- Add the Microsoft Graph Application permission
ThreatHunting.Read.All. - Grant administrator consent for
ThreatHunting.Read.All. - Keep the legacy
AdvancedHunting.Read.Allpermission until you validate every migrated alert action.
The Advanced Hunting query remains required. The alert action does not expose a Timespan field. When the request omits Timespan, Microsoft Graph applies its default 30-day timespan.
Upgrade and validate alert actions¶
- Upgrade the Splunk Add-on for Microsoft Security to version 5.0.0.
- Open every saved alert that uses Defender Advanced Hunting.
- Confirm that the selected Environment matches the Microsoft tenant.
- For each DoD tenant, explicitly select DoD.
- Save the alert.
- Run a test query and verify that the returned events use the
m365:defender:incident:advanced_huntingsource type. - Review the alert-action log for authorization, endpoint, or query errors.
- For each migrated alert action, inspect the outbound HTTP request trace for its test execution. Confirm that the TA calls Microsoft Graph
POST /v1.0/security/runHuntingQueryon the host for the selected environment and no longer calls the legacy/api/advancedhunting/runendpoint. If the trace does not show the request path, obtain that evidence before removing the legacy permission. - After every action succeeds and endpoint verification is complete, remove
AdvancedHunting.Read.Allif no other application workload requires it.
Version 5.0.0 maps existing saved environment values as follows:
| Saved value | Environment in version 5.0.0 | Microsoft Graph host |
|---|---|---|
Missing, default, commercial, or gcc |
Commercial and GCC | graph.microsoft.com |
gcc-high |
GCC High | graph.microsoft.us |
commercial-graph-api |
Commercial and GCC | graph.microsoft.com |
gcc-high-graph-api |
GCC High | graph.microsoft.us |
dod-graph-api |
DoD | dod-graph.microsoft.us |
Warning
Previous saved values do not reliably distinguish GCC High from DoD. You must explicitly select DoD after upgrading each DoD alert action. Otherwise, the action sends its request to graph.microsoft.us instead of dod-graph.microsoft.us.
Microsoft publishes service retirement information in Microsoft 365 Message Center notice MC1220762.
Review CIM mapping changes¶
Version 5.0.0 changes the following Common Information Model (CIM) fields:
| Source type and event | Change | Upgrade impact |
|---|---|---|
ms:defender:machines |
The source type now maps to the Inventory Network dataset and adds scalar CIM ip and mac fields. ip uses lastIpAddress, then lastExternalIpAddress. mac uses the corresponding nonzero MAC address in lowercase, colon-delimited format. |
The ip and mac fields are new in version 5.0.0. The existing private_ipv4 and public_ipv4 fields remain available for IPv4 values. Raw multivalue ipAddresses{}.ipAddress and ipAddresses{}.macAddress fields remain in each event. |
ms:defender:eventhub with AdvancedHunting-DeviceFileCertificateInfo |
dest uses properties.DeviceName when present. |
Searches that used dest as a tenant identifier must use tenantId. |
m365:defender:incident:advanced_hunting and ms:defender:eventhub with DeviceNetworkEvents and ActionType=ConnectionFailed |
action is flow instead of blocked. |
Searches, dashboards, and alerts based on Network_Traffic.Blocked_Traffic can return fewer events. |
ms:defender:atp:alerts |
In version 4.0.0, src used serviceSource first and fell back to computerDnsName. In version 5.0.0, src uses computerDnsName first and falls back to the first nonempty evidence{}.deviceDnsName value. serviceSource no longer populates src. |
Use serviceSource directly when a search requires the Microsoft product value. Review searches that depend on the previous src precedence. |
Authentication events in m365:defender:incident:advanced_hunting |
signature_id uses the stable ActionType instead of the per-event ReportId_string. |
Use ReportId_string when a search requires the individual event identifier. |
m365:defender:incident:advanced_hunting with IdentityLogonEvents |
app uses a nonempty Application other than the literal null, with the existing ms:defender fallback otherwise. |
Review searches that filter on app=ms:defender. Use the source type or an appropriate vendor_product filter to identify product events, and app to identify the authenticating application. |
m365:defender:incident:advanced_hunting and ms:defender:eventhub filesystem timestamps; Event Hub certificate timestamps |
file_access_time, file_create_time, file_modify_time, ssl_start_time, and ssl_end_time use numeric Unix epoch seconds, including fractional seconds at Splunk’s available numeric precision. Invalid or missing source values leave the mapped field unset. |
Review searches that treated these fields as ISO8601 strings. Use strftime() when a formatted date is needed. Existing event and action conditions remain unchanged. |
ms365:defender:incident |
time_submitted uses the first valid creation time from createdDateTime, then legacy createdTime, as numeric Unix epoch seconds. Update times no longer populate this field. |
Searches that require the last update time must use lastUpdateDateTime or lastUpdateTime directly. Invalid or missing creation times leave time_submitted unset. |
m365:defender:incident:advanced_hunting |
process_id uses InitiatingProcessId for DeviceFileEvents and DeviceRegistryEvents, and ProcessId for other events. Numeric source values produce a numeric ID; missing, empty, literal null, and nonnumeric values leave the field unset. |
Review searches that tested process_id for the literal string null. File and registry events now expose the available initiating actor ID. |
Graph and Event Hub DeviceFileEvents and DeviceRegistryEvents |
process and process_name use the initiating process command line and file name from InitiatingProcessCommandLine and InitiatingProcessFileName. |
Review searches that used these process fields to identify the affected object. Use the corresponding file or registry fields for the object. |
Graph and Event Hub DeviceFileEvents and DeviceRegistryEvents |
process_path and process_exec describe the initiating process, using InitiatingProcessFolderPath and InitiatingProcessFileName. Graph process_hash contains the available named MD5, SHA1, and SHA256 actor hashes. Event Hub process_hash selects the first available actor hash: SHA256, then SHA1, then MD5. Missing, empty, and literal null actor values leave the corresponding fields unset. |
Review searches that used these process fields for the affected file. Use the existing file or registry fields and unchanged raw source fields for the affected object. Other event families retain their existing mappings. |
Graph DeviceFileEvents and DeviceRegistryEvents parent fields |
parent_process_id uses numeric InitiatingProcessParentId; parent_process_name and parent_process_exec use InitiatingProcessParentFileName. Missing or invalid parent values remain unset. Parent command line, path, hash, and GUID fields are omitted because the available source columns describe the initiating actor instead of its parent. |
Review searches that relied on the initiating actor being duplicated as its own parent. Use the available parent PID and executable name. Other Graph datasets and Event Hub parent mappings retain their existing behavior. |
Graph and Event Hub DeviceFileEvents and DeviceRegistryEvents integrity level |
process_integrity_level uses the available InitiatingProcessIntegrityLevel. Graph preserves the source casing; Event Hub uses lowercase values, following each transport’s existing convention. Missing, empty, and source null or none values leave the field unset. |
These events now expose the initiating actor’s integrity level instead of using an unrelated or unavailable target-process value. Other event families retain their existing mappings. |
Graph and Event Hub DeviceFileEvents, DeviceImageLoadEvents, and EmailAttachmentInfo |
The multivalue file_hashes field contains the available nonempty MD5, SHA1, and SHA256 source hashes. The existing file_hash field remains available. |
Searches that need every available hash can use file_hashes; existing searches that use file_hash can keep that field. |
Graph DeviceProcessEvents |
When ProcessCommandLine begins with an absolute executable path, process uses that command line without prepending the path again. Other command lines retain the existing reconstruction behavior. |
Review searches that depended on the duplicated path. The source command line remains unchanged. |
m365:defender:incident:advanced_hunting with DeviceNetworkEvents |
src, src_ip, dest, and dest_ip omit missing, empty, JSON-null, and literal null addresses. Genuine IPv4 and IPv6 values keep their source and destination roles. |
Use isnull() when testing for an unavailable address. The literal string null no longer identifies an endpoint. Other event families retain their existing mappings. |
m365:defender:incident:advanced_hunting with DeviceFileEvents |
CIM file_size is numeric kilobytes, converted from Microsoft FileSize bytes. Zero and fractional kilobytes are preserved; missing or nonnumeric source values leave the field unset. |
Review thresholds and calculations that assumed file_size contained bytes. Use the unchanged source FileSize when bytes are needed. Event Hub file/image mappings remain kilobytes, and Event Hub email attachment size fields remain bytes. |
ms:defender:eventhub with AdvancedHunting-DeviceInfo or AdvancedHunting-DeviceNetworkInfo |
CIM enabled is no longer derived from Defender onboarding or adapter operational status. These strings do not establish the optional CIM boolean resource-enabled state. |
Searches that used enabled=Onboarded or enabled=Down must use the unchanged properties.OnboardingStatus or properties.NetworkAdapterStatus source fields. The existing status mapping remains sensor health for DeviceInfo and adapter operational status for DeviceNetworkInfo. Genuine source enabled values are not suppressed. |
ms:defender:simulations |
src and dest no longer contain static product or portal names. |
The fields remain unset because the current payload does not contain a meaningful source or destination host or IP address. |
Explicit-zone ISO8601 timestamps with four-digit years from 0001 through 9999 convert to Unix epoch seconds. The mappings retain native strptime() results where supported and use calendar-equivalent years for valid dates outside its range. Existing numeric epoch values, including 0, remain supported. Contemporary fractional timestamps retain the native parser’s microsecond precision; fractional precision can be lower at very large absolute epoch values because Splunk stores the result as a floating-point number.
Version 5.0.0 also adds the multivalue detection_status field for available alert-evidence detectionStatus values.
Clarification of historical gateway mappings¶
The version 2.2.0 mapping table listed src_ip for Event Hub DeviceNetworkInfo gateway addresses. Gateway handling is unchanged between versions 4.0.0 and 5.0.0. Use the preserved properties.DefaultGateways source data for gateway information; a gateway address does not necessarily identify the originating system described by CIM src_ip. DeviceNetworkEvents continues to populate src_ip from properties.LocalIP.
To inspect Event Hub gateway addresses without assigning them the CIM source-IP role, extract the preserved JSON array:
sourcetype=ms:defender:eventhub category=AdvancedHunting-DeviceNetworkInfo
| spath input=properties.DefaultGateways path={} output=default_gateway
| table _time properties.DeviceName default_gateway
Upgrade to version 4.0.0¶
Version 4.0.0 removes Python 3.7 support. Verify that the Splunk platform deployment uses Python 3.9 or Python 3.13 before you upgrade.
Version 4.0.0 adds the following optional settings to the Microsoft 365 Defender Incidents and Microsoft Defender for Endpoint Alerts inputs:
- Lookback delays the end of collection to allow data to arrive. The upper bound is the current UTC time minus this value; collection resumes from its checkpoint. The value is in seconds, must be less than Interval, and defaults to 0.
- Max Query Window limits the number of days in one Microsoft API query window for both Microsoft Graph and legacy Defender API environments. The valid range is 1 through 30, and the default is 7. Use a smaller value for high-volume tenants.
Existing inputs use the default values until you change them.
Upgrade from version 2.1 to version 2.2.0 or later¶
After upgrading, clear the browser cache and reload the add-on. Version 2.2.0 adds inputs for attack simulations and real-time Advanced Hunting events streamed through Azure Event Hubs.
Upgrade from version 2.0.1 to version 2.1.1¶
After upgrading, clear the browser cache and reload the add-on to display the monitoring dashboards.
Upgrade from version 1.3.1 to version 2.0.1¶
After upgrading, clear the browser cache before you open the add-on.
Migrate from the Microsoft 365 Defender Add-on for Splunk¶
Disable the legacy Microsoft 365 Defender Add-on for Splunk before you enable the Splunk Add-on for Microsoft Security on the same Splunk platform instance. Running both add-ons can duplicate data and create conflicting knowledge objects.
- In the legacy add-on, disable every input.
- In Splunk Web, select Apps > Manage Apps.
- Find Microsoft 365 Defender Add-on for Splunk.
- Select Disable.
- Install and configure the Splunk Add-on for Microsoft Security.
- Verify the new source names and source types before enabling scheduled searches.
Source-name changes¶
| Legacy source name | Splunk Add-on for Microsoft Security source name |
|---|---|
microsoft_365_defender_incidents |
microsoft_365_defender_endpoint_incidents |
microsoft_defender_atp_alerts |
microsoft_defender_endpoint_atp_alerts |
ms_defender_apt_alerts |
ms_defender_endpoint_apt_alerts |
Event-type and data-model changes¶
| Event type | Legacy CIM mapping | Current CIM mapping |
|---|---|---|
ms_security_incident |
Alerts | Ticket Management: Incident |
ms_security_atp_alert |
Alerts | Alerts |
ms_security_advanced_hunting |
None | None |
ms_security_advanced_hunting_process |
Endpoint: Processes | Endpoint: Processes |
ms_security_advanced_hunting_network |
Network Traffic, Endpoint: Ports | Removed. Network events use ms_security_advanced_hunting_network_traffic. |
ms_security_advanced_hunting_filesystem |
Change: Endpoint, Endpoint: Filesystem | Endpoint: Filesystem |
ms_security_advanced_hunting_registry |
Change: Endpoint, Endpoint: Registry | Endpoint: Registry |
ms_security_advanced_hunting_delivery |
None | Email: Delivery |
ms_security_advanced_hunting_email |
None | |
ms_security_advanced_hunting_authentication |
None | Authentication |
ms_security_incident_alerts |
None | Alerts |
The current add-on separates incident data and associated alert data into ms365:defender:incident and ms365:defender:incident:alerts. The legacy m365:defender:incident source type contained both kinds of data.
The add-on can collect alerts directly in ms:defender:atp:alerts or as incident-associated alerts in ms365:defender:incident:alerts. The Microsoft APIs return different schemas for these collection paths. Choose the input and source type that provide the fields required by your searches.