Skip to content

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

  1. Identify the Microsoft Entra application used by each Defender Advanced Hunting alert action.
  2. Add the Microsoft Graph Application permission ThreatHunting.Read.All.
  3. Grant administrator consent for ThreatHunting.Read.All.
  4. Keep the legacy AdvancedHunting.Read.All permission 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

  1. Upgrade the Splunk Add-on for Microsoft Security to version 5.0.0.
  2. Open every saved alert that uses Defender Advanced Hunting.
  3. Confirm that the selected Environment matches the Microsoft tenant.
  4. For each DoD tenant, explicitly select DoD.
  5. Save the alert.
  6. Run a test query and verify that the returned events use the m365:defender:incident:advanced_hunting source type.
  7. Review the alert-action log for authorization, endpoint, or query errors.
  8. 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/runHuntingQuery on the host for the selected environment and no longer calls the legacy /api/advancedhunting/run endpoint. If the trace does not show the request path, obtain that evidence before removing the legacy permission.
  9. After every action succeeds and endpoint verification is complete, remove AdvancedHunting.Read.All if 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.

  1. In the legacy add-on, disable every input.
  2. In Splunk Web, select Apps > Manage Apps.
  3. Find Microsoft 365 Defender Add-on for Splunk.
  4. Select Disable.
  5. Install and configure the Splunk Add-on for Microsoft Security.
  6. 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 Email
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.