Microsoft Defender XDR
App Vendor: Microsoft
App Category: Endpoint
Connector Version: 1.0.0
API Version: 1.0.0
About App
Microsoft Defender XDR provides a unified API for automating threat detection, investigation, and response across endpoints, identities, email, and cloud resources, enabling faster and coordinated security operations.
The Microsoft Defender XDR app is configured with Orchestrate to perform the following actions:
Action Name | Description |
|---|---|
Get Incident Details | This action retrieves the details of a specific incident. |
List Incidents | This action lists all incidents that have been created to track and manage attacks targeting your organization. |
Run Hunting Query | This action runs a query on a specified set of event, activity, or entity data to proactively search for specific threats in your environment. |
Update Incidents | This action updates the details of an existing incident. |
Generic Action | This is a generic action used to make requests to any Microsoft Defender XDR endpoint. |
Configuration Parameters
The following configuration parameters are required for the Microsoft Defender XDR app to communicate with the Microsoft Defender XDR enterprise application. The parameters can be configured by creating instances in the app.
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Tenant ID | Enter the tenant ID associated with your account for authentication. | Text | Required | |
Client ID | Enter the client ID for authentication. | Text | Required | |
Client Secret | Enter the client secret linked to your client ID. | Password | Required | |
Timeout | Enter the timeout value in seconds. This is the number of seconds requests will wait to connect to Microsoft Defender XDR and read the response. | Integer | Optional | Allowed range: 15–120 Default value: 15 |
Verify | Choose your preference to verify SSL or TLS while making requests. It is recommended to set this option to yes. Passing no may result in incorrectly establishing the connection. | Boolean | Optional | By default, verification is enabled. |
API Version | Enter the API version to be used while making requests. | Text | Optional | Default value: v1.0 |
Action: Get Incident Details
This action retrieves the details of a specific incident.
Note
You must have one of the Incident.Read.All (Read all incidents), Incident.ReadWrite.All (Read and write all incidents), Incident.Read (Read incidents), or Incident.ReadWrite (Read and write incidents) permissions to perform this action.
Permission type: Delegated (work or school account) or Application. Personal Microsoft accounts are not supported.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Incident ID | Enter the incident ID to retrieve incident information. Example: 2972395 | Text | Required | You can retrieve this using the action List Incidents. |
Example Request
[
{
"incident_id": "2972395"
}
]Action: List Incidents
This action lists all incidents that have been created to track and manage attacks targeting your organization.
Note
You must have one of the Incident.Read.All (Read all incidents), Incident.ReadWrite.All (Read and write all incidents), Incident.Read (Read incidents), or Incident.ReadWrite (Read and write incidents) permissions to perform this action.
Permission type: Delegated (work or school account) or Application. Personal Microsoft accounts are not supported.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Filter | Enter a query to filter incidents by specific fields. Example: status eq 'open' | Text | Optional | Allowed fields: assignedTo, classification, createdDateTime, determination, lastUpdateDateTime, severity, status |
Max Results | Enter the maximum number of incidents to retrieve. | Integer | Optional | Maximum allowed value: 50 |
Skip | Enter the number of incidents to skip in the result set. Example: 10 | Integer | Optional | |
Count | Choose true to include the total number of matching incidents in the response. | Boolean | Optional | |
Expand | Enter any related resources you want to include in the response. Example: alerts | Text | Optional |
Example Request
[
{
"skip": "2",
"count": true,
"expand": "alerts",
"filter": "status eq 'active' or severity eq 'medium' or determination eq 'unknown'",
"max_results": "10"
}
]Action: Run Hunting Query
This action runs a query on a specified set of event, activity, or entity data to proactively search for specific threats in your environment.
Note
You must have the AdvancedHunting.Read.All (Run advanced queries) or AdvancedHunting.Read (Run advanced queries) permissions to perform this action.
Permission type: Delegated (work or school account) or Application. Personal Microsoft accounts are not supported.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Query | Enter the query to run using Kusto Query Language (KQL). Example: DeviceNetworkEvents | where RemoteUrl contains 'malicious.com' | Text | Required | |
Time Span | Enter the time range in ISO 8601 duration format to limit the query scope. If your query also specifies a time filter, the shorter of the two will apply. | Text | Optional | Default value: P30D (last 30 days) |
Example Request
[
{
"query": "DeviceNetworkEvents | where RemoteUrl contains 'malicious'",
"time_span": "P1D"
}
]Action: Update Incident
This action updates the details of an existing incident.
Note
You must have one of the Incident.ReadWrite.All (Read and write all incidents) or Incident.ReadWrite (Read and write incidents) permissions to perform this action.
Permission type: Delegated (work or school account) or Application. Personal Microsoft accounts are not supported.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Incident ID | Enter the incident ID to update. Example: 2972395 | Text | Required | You can retrieve this using the action List Incidents. |
Status | Enter the status of the incident to update. | Text | Optional | Allowed values: active, resolved, redirected, unknownFutureValue |
Assigned To | Enter the user or owner to assign the incident to. This can be a user name or any identifier. Example: jdoe@domain.com | Text | Optional | |
Classification | Enter the classification of the incident. | Text | Optional | Allowed values: unknown, falsePositive, truePositive, informationalExpectedActivity, unknownFutureValue |
Determination | Enter the determination for the incident to indicate its confirmed nature. | Text | Optional | Allowed values for each classification type: For True Positive: MultiStagedAttack, MaliciousUserActivity, CompromisedAccount, Malware, Phishing, UnwantedSoftware, Other For Informational, expected activity: SecurityTesting, LineOfBusinessApplication, ConfirmedActivity, Other For False positive: Clean, NoEnoughDataToValidate, Other |
Description | Enter a description that provides additional context or findings related to the incident. | Text | Optional | |
Resolving Comment | Enter a comment to explain how the incident was resolved or justify the classification decision. | Text | Optional | |
Severity | Enter the severity level of the incident. | Text | Optional | Allowed values: unknown, informational, low, medium, high, unknownFutureValue |
Display Name | Enter a display name for the incident. This name will appear in the Microsoft XDR portal. Example: Credential Leak - Email Account | Text | Optional | |
Summary | Enter a brief summary of the attack, including what occurred, affected assets, and the attack type. | Text | Optional | |
Custom Tags | Enter one or more custom tags to categorize or label the incident. Example: $LIST[Phishing, CriticalAsset] | List | Optional |
Example Request
[
{
"status": "active",
"severity": "high",
"custom_tags": [
"Credential Theft",
"Phishing",
"Initial Access"
],
"description": "Suspicious login activity detected from a known malicious IP address. Potential compromise of user credentials.",
"incident_id": "2972395",
"display_name": "Possible Credential Leak via Phishing",
"determination": "apt",
"classification": "truePositive"
}
]Action: Generic Action
This is a generic action used to make requests to any Microsoft Defender XDR endpoint.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Method | Enter the HTTP method to make the request. | Text | Required | Allowed values: GET, PUT, POST, DELETE |
Endpoint | Enter the endpoint to make the request to. Example: security/alerts_v2 | Text | Required | |
Payload | Enter the payload to make the request. Example: $JSON[{ "key_1": "value_1", "key_2": "value_2" }] | Any | Optional | |
Query Params | Enter the query parameters to pass to the API. | Key_value | Optional | |
Extra Fields | Enter the extra fields to pass to the API. | Key_value | Optional | Allowed keys: headers, payload_json, download, files, filename, retry_wait, retry_count, custom_output, response_type |
Example Request
[
{
"method": "POST",
"payload": {
"Query": "DeviceNetworkEvents | where RemoteUrl contains 'malicious'"
},
"endpoint": "/security/runHuntingQuery",
"extra_fields": {},
"query_params": {}
}
]