Configure accounts and inputs¶
Configure a Microsoft Entra account, an optional proxy, and at least one input before the Splunk Add-on for Microsoft Security can collect data.
Configure an account¶
Before you add an account, create a Microsoft Entra application and grant the required permissions.
- In the add-on, select Configuration > Account.
- Select Add.
- Enter a unique Account Name that starts with an ASCII letter and contains only ASCII letters, digits, and underscores.
- Enter the application’s Client ID.
- Enter the application’s Client Secret.
- Enter the Microsoft Entra Tenant ID as a tenant GUID or tenant domain name.
- Select Add.
An input or alert action can override the tenant ID stored with the account.
New account names have a maximum length of 50 characters. New input names have a maximum length of 100 characters and follow the same naming rules. These rules are enforced when creating entries through Splunk Web or the add-on REST endpoints. New configuration-file deployments should follow the same rules.
Existing configuration is not rewritten automatically. The add-on REST edit path preserves unchanged safe legacy names containing letters, numbers, underscores, spaces, dots or hyphens, subject to Splunk’s reserved-name rules and 1023-character limit. For example, an account named prod-account can keep its name when its client secret is rotated. Account references and input checkpoint identities are not renamed. Names containing markup, URL delimiters or control characters remain unsupported for ordinary edits; tenant and proxy-host values must still meet their validation rules.
Existing inputs can still be enabled or disabled without changing their configuration, including inputs with legacy names that do not meet these naming rules.
Configure a proxy¶
Configure one global proxy for Microsoft API and Azure Event Hubs connections. Version 5.0.0 applies this proxy configuration to Event Hub authentication as well as data collection.
- In the add-on, select Configuration > Proxy Configuration.
- Select Enable Proxy.
- Enter the proxy host in Proxy Host. Do not include a URL scheme or path.
- Enter the proxy port in Proxy Port.
- Optional: Enter Proxy Username and Proxy Password for an authenticated proxy.
- Save the configuration.
For Event Hub connections that use an IPv6 proxy literal, enter the address without square brackets. The Event Hub connection code adds the brackets required in the proxy URL. Other Microsoft API inputs do not add IPv6 brackets automatically, so use a proxy host name for those inputs.
Configure an input¶
- In the add-on, select Inputs.
- Select Create New Input.
- Select an input type.
- Enter the common and input-specific values described in this topic.
- Select Add.
- Search the target index to verify data collection.
Common input settings¶
Most inputs use the following settings:
| Setting | Description |
|---|---|
| Name | A unique name for the input. |
| Azure App Account | The account configured on the Account page. |
| Tenant ID | An optional tenant ID that overrides the value stored with the account. |
| Start Date (optional) | The beginning of data collection in Coordinated Universal Time (UTC), in YYYY-MM-DDTHH:MM:SSZ format. If empty, the input starts 30 days before its first run. |
| Request Timeout (optional) | The Microsoft request timeout in seconds. The default is 60 seconds. Version 5.0.0 also applies this default to legacy configurations where the value is empty or missing. |
| Interval | The collection interval in seconds. |
| Index | The destination Splunk index. |
Select an environment or location that matches the Microsoft tenant and API permissions. A Microsoft 365 Defender API permission does not authorize a Microsoft Graph input, and a Microsoft Graph permission does not authorize a legacy API input.
Microsoft 365 Defender Incidents¶
Configure these additional settings:
| Setting | Description |
|---|---|
| Environment | The Microsoft 365 Defender or Microsoft Graph environment that contains the tenant. |
| Lookback (optional) | The number of seconds to delay 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 must be less than Interval. The default is 0. |
| Max Query Window (days, optional) | The maximum number of days in one Microsoft API query window. Use a smaller value for high-volume tenants. The valid range is 1 through 30, and the default is 7. |
The Graph input saves a checkpoint only after it processes every page in a query window. If a later page fails, the next run retries the incomplete window.
Microsoft Defender for Endpoint Alerts¶
Configure these additional settings:
| Setting | Description |
|---|---|
| Location | The Microsoft Defender for Endpoint or Microsoft Graph location that contains the tenant. |
| Lookback (optional) | The number of seconds to delay 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 must be less than Interval. The default is 0. |
| Max Query Window (days, optional) | The maximum number of days in one Microsoft API query window. Use a smaller value for high-volume tenants. The valid range is 1 through 30, and the default is 7. |
The Graph input saves a checkpoint only after it processes every page in a query window. If a later page fails, the next run retries the incomplete window.
Microsoft Defender Machines¶
Select the Location that contains the tenant. This input collects Microsoft Defender for Endpoint machine inventory and assigns the ms:defender:machines source type.
Max Collection Pages (optional) sets a positive, finite page ceiling for one collection. The default is 10,000, including existing inputs with an empty or missing value. The input follows Microsoft’s complete continuation links and does not change the configured start date or introduce a new inventory snapshot/cursor model. If the collection needs more pages, the input fails without saving a final checkpoint. Raise the finite ceiling to accommodate the tenant; events already written can replay on the next run.
The final checkpoint is saved only after every page and event write completes. Checkpoint storage errors fail the run rather than report successful completion. If a write was accepted but its acknowledgement was lost, the stored checkpoint might already have advanced. This is not an exactly-once delivery guarantee.
Microsoft Defender Simulations¶
Select the Microsoft Graph Environment that contains the tenant. This input requires AttackSimulation.Read.All.
Max Collection Pages (optional) has the same positive, finite ceiling and failure/replay behavior as Machines, with a default of 10,000. It does not change configured history or introduce new time windows. The final checkpoint requires storage acknowledgement after the whole collection; optional report failures do not prevent collection of the base simulation event.
Microsoft Defender Event Hub¶
Configure the following settings:
| Setting | Description |
|---|---|
| Event Hub Namespace(FQDN) | The fully qualified domain name of the Event Hubs namespace. |
| Event Hub Name | The event hub that receives Microsoft Defender XDR streaming events. |
| Consumer Group | The consumer group used by this input. Use a dedicated consumer group when another application also reads the event hub. |
| Streaming Event Types | An optional list of Advanced Hunting event categories to collect. If empty, the input collects every supported category. |
| Index | The destination Splunk index. |
The input keeps an active Event Hubs connection, so Splunk Web displays its interval as 0. Retention depends on the Azure Event Hubs tier and namespace configuration.
The consumer uses a prefetch of 300 events and callback batches of at most 300 events, with a 10-second batch wait. Azure SDK retry attempts and backoff are finite; these are per-operation controls, not a lifetime cutoff for this continuous input. A partition checkpoint is updated after all selected records in the callback batch are written. A propagated write/checkpoint failure can cause replay from the last stored checkpoint; this is not exactly-once delivery. Event-size limits depend on the Azure tier, so the add-on does not impose a universal 1 MiB payload cutoff.
After you create an Event Hub input, you cannot edit Event Hub Name or Consumer Group. You can edit Azure App Account, Event Hub Namespace(FQDN), Streaming Event Types, and Index.
The Event Hub checkpoint is associated with the input name. If you change Azure App Account or Event Hub Namespace(FQDN), create a new input with a new name to prevent the input from reusing checkpoints created for a different Event Hubs resource.
If partitions are added after collection begins, the input resets its partition checkpoints. Existing partitions can produce duplicate events after the input restarts.
Note
An IPv6-only collection host requires DNS64 and NAT64 when the Event Hubs FQDN does not provide an IPv6 address.
Microsoft Defender Threat Intelligence Datasets¶
Configure the following settings:
| Setting | Description |
|---|---|
| Datasets | One or more Microsoft Defender Threat Intelligence datasets to collect. |
| Identifiers File | A CSV or text file that contains one identifier per line for identifier-based datasets. |
| Interval | The collection interval in seconds. |
| Index | The destination Splunk index. |
The Microsoft Threat Intelligence APIs require a Microsoft Defender XDR or Microsoft Sentinel license. The Microsoft Entra application also requires the ThreatIntelligence.Read.All application permission. Microsoft does not require a separate API license. See Use the Microsoft Graph APIs for Microsoft Threat Intelligence.
Microsoft API response budgets¶
Microsoft HTTP data/report responses and MDTI SDK responses are limited to 64 MiB of decoded bytes per response, including compressed, error and redirect bodies. A response over this ceiling is rejected before JSON parsing; Content-Length is not trusted. A server-requested retry wait above 3,600 seconds is rejected rather than sleeping for that duration. Ordinary retries, configured timeouts, authentication, proxy and TLS behavior remain in place. MDTI also retains its configured page size, page limit and worker count. These controls are per-response/per-operation budgets, not a guarantee of a fixed total process memory footprint. An optional Simulations report can fail independently while the base event is collected.
Alerts and Incidents stage each time window in memory before publishing it. A window can hold up to 64 MiB of UTF-8 event payloads and 100,000 output events, including nested incident alerts. If a response, page or staging budget is exceeded, the unpublished window is discarded and retried as smaller chronological windows. The checkpoint advances only after a complete window has been written. If a one-second window still exceeds a budget, collection fails without publishing that window or advancing its checkpoint. Output or checkpoint failures retain the usual at-least-once delivery behavior: a later input run can replay events that were written before the failure.
Required Event Hubs ports¶
Allow outbound HTTPS on TCP port 443. Azure Event Hubs clients can also require TCP ports 5671 and 5672 for Advanced Message Queuing Protocol (AMQP) connections. Splunk Cloud Platform administrators can use the Admin Config Service to configure required outbound connectivity.
See What ports do I need to open on the firewall? in the Microsoft documentation.
Configure inputs with configuration files¶
Splunk Cloud Platform deployments must configure this add-on in Splunk Web. Splunk Enterprise administrators can configure it with files.
- On the heavy forwarder or deployment server, create
$SPLUNK_HOME/etc/apps/Splunk_TA_MS_Security/localif it does not exist. - Create
splunk_ta_ms_security_account.confin thelocaldirectory. - Use
$SPLUNK_HOME/etc/apps/Splunk_TA_MS_Security/README/splunk_ta_ms_security_account.conf.specto configure the account stanza. - If you configure encrypted credentials on a deployment server, enable the
script://$SPLUNK_HOME/etc/apps/Splunk_TA_MS_Security/bin/ms_security_encrypt_creds.pyinput ininputs.conf. - Create the required modular input stanzas by using
$SPLUNK_HOME/etc/apps/Splunk_TA_MS_Security/README/inputs.conf.spec. - Deploy the configuration to the heavy forwarder.
- Restart the heavy forwarder if required by your deployment method.
- Verify that the inputs are enabled and collecting data.
Security audit records¶
The add-on writes JSON security records to $SPLUNK_HOME/var/log/splunk/Splunk_TA_MS_Security_security_audit.log. These INFO records are independent of the configured operational log level. They cover account, proxy/logging and input changes through the add-on REST endpoints (including Splunk Web), incident updates through the legacy and Graph actions, and Azure alert dismissal.
Records identify the authenticated Splunk execution principal, operation, configuration stanza or Microsoft resource, configured/effective tenant where applicable, UTC timestamp and outcome. Alert records also retain the Splunk-supplied search owner and SID when available. A scheduled action’s execution principal is not necessarily the person who originally configured the search. Result fields cannot override the recorded principal. If session identity or configuration context cannot be resolved, the corresponding status is explicitly unavailable; investigate these records rather than treating the search owner as a verified actor.
For configuration changes, success means Splunk accepted the persistence request. For Microsoft mutations, it means the API returned success. A later local processing error does not reverse that outcome. failure identifies a rejected operation, not_attempted identifies an action that did not reach the API, and unknown identifies an unconfirmed outcome, for example after a lost connection. Check the resource before retrying an operation with an unknown outcome. Configuration records also expose processing_outcome separately.
Security records use an explicit metadata allowlist and JSON escaping. They do not include session keys, client secrets, bearer tokens, proxy passwords, full request/response bodies or exception messages. Metadata strings are limited to 1,024 characters.
Deployment administrators control log forwarding, index access and retention through the standard Splunk configuration model. Verify that the log is collected from every host that runs configuration handlers or alert actions, restrict access to authorized operators, and retain records according to your organization’s policy. Local rotated log files alone are not a long-term audit archive. When the deployment collects these files in _internal, use:
index=_internal source=*Splunk_TA_MS_Security_security_audit.log* "security_audit="
| rex "security_audit=(?<audit_json>.*)"
| spath input=audit_json
| table timestamp principal principal_status search_owner sid operation resource_type resource_id tenant_id subscription_id outcome processing_outcome
Use deployment/platform audit controls for direct configuration-file changes and native Splunk configuration endpoints that bypass the add-on handlers. The add-on does not replace those controls or enforce a separate execution-role policy.
Supported input endpoints¶
The following table lists the endpoints used by the inputs. Select the environment or location where the input provides that setting. The Threat Intelligence Datasets input uses a fixed public-cloud endpoint.
| Input | Environment or location | Endpoint |
|---|---|---|
| Microsoft Defender for Endpoint Alerts | General | api.securitycenter.microsoft.com |
| Microsoft Defender for Endpoint Alerts | US | api-us.securitycenter.microsoft.com |
| Microsoft Defender for Endpoint Alerts | EU | api-eu.securitycenter.microsoft.com |
| Microsoft Defender for Endpoint Alerts | UK | api-uk.securitycenter.microsoft.com |
| Microsoft Defender for Endpoint Alerts | GCC | api-gcc.securitycenter.microsoft.us |
| Microsoft Defender for Endpoint Alerts | GCC High/DoD | api-gov.securitycenter.microsoft.us |
| Microsoft Defender for Endpoint Alerts | Commercial & GCC - Graph API | graph.microsoft.com |
| Microsoft Defender for Endpoint Alerts | GCC High - Graph API | graph.microsoft.us |
| Microsoft 365 Defender Incidents | Commercial | api.security.microsoft.com |
| Microsoft 365 Defender Incidents | GCC | api-gcc.security.microsoft.us |
| Microsoft 365 Defender Incidents | GCC High | api-gov.security.microsoft.us |
| Microsoft 365 Defender Incidents | Commercial & GCC - Graph API | graph.microsoft.com |
| Microsoft 365 Defender Incidents | GCC High - Graph API | graph.microsoft.us |
| Microsoft Defender Simulations | Commercial & GCC - Graph API | graph.microsoft.com |
| Microsoft Defender Simulations | GCC High - Graph API | graph.microsoft.us |
| Microsoft Defender Machines | General | api.security.microsoft.com |
| Microsoft Defender Machines | US | api.security.microsoft.com |
| Microsoft Defender Machines | EU | api.security.microsoft.com |
| Microsoft Defender Machines | UK | api.security.microsoft.com |
| Microsoft Defender Machines | GCC | api-gcc.security.microsoft.us |
| Microsoft Defender Machines | GCC High/DoD | api-gov.security.microsoft.us |
| Microsoft Defender Threat Intelligence Datasets | Public cloud (fixed endpoint; no environment selector) | graph.microsoft.com |
Validate data collection¶
Run the following search after you configure an input:
index=<index>
(sourcetype IN (
"ms:defender:atp:alerts",
"ms365:defender:incident",
"ms365:defender:incident:alerts",
"m365:defender:incident:advanced_hunting",
"ms:defender:simulations",
"ms:defender:eventhub",
"ms:defender:machines"
) OR sourcetype="ms:defender:ti:*")
| stats count by sourcetype
Replace <index> with the input’s destination index. Verify that the expected source type appears and that its event count increases after the next collection interval.