Microsoft Defender for Endpoint

LAST UPDATED: NOVEMBER 12, 2025

Overview

Microsoft Defender for Endpoint (previously Microsoft Defender Advanced Threat Protection) protects endpoints from cyber threats, detects attacks and infringements of data, and automates security incidents. Integration with Microsoft Defender for Endpoint covers the major actions such as quarantine host, scan host, get alerts, update alert, and so on.

D3 SOAR is providing REST operations to function with Microsoft Defender for Endpoint.

Microsoft Defender for Endpoint is available for use in:

D3 SOAR	V12.7.83.0+
Category	Endpoint Protection
Deployment Options	Option II, Option IV

Known Limitations

A server error may occur when accessing the service. Enabling cookies in the web browser settings may resolve the issue.
Some elements or data may be missing on Microsoft 365 Defender. They may be blocked by proxy settings. Ensure *.security.microsoft.com is included in the proxy allowlist.
If devices complete onboarding successfully but Microsoft Defender for Endpoint fails to start after a reboot and returns error 577, verify that Windows Defender is not disabled by policy.
Some known issues affect the time and date formats:
- The following formats are supported:
  - MM/dd/yyyy
  - dd/MM/yyyy
- The following formats are currently not supported:
  - yyyy/MM/dd
  - dd/MM/yy
  - Date formats with yy. Only yyyy will be shown for year.
  - HH:mm:ss (12-hour AM/PM format). Only the 24-hour time format is supported.
Commas cannot be used as number separators. In regions that use commas as the thousands separator, commas are replaced with periods. For example, 15,5K is displayed as 15.5K.

Refer to Troubleshoot Microsoft Defender for Endpoint server issues for more information.

Connection

Gather the following information to connect D3 SOAR to Microsoft Defender for Endpoint.

Parameter	Description	Example
Directory (tenant) ID	The directory ID to authenticate the API connection.	f62*****Eed
Client ID	The client ID to authenticate the API connection.	9c8*****f8a
Client Secret	The client secret to authenticate the API connection.	o14*****817

Permission Requirements

Each endpoint in the Microsoft Defender for Endpoint API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permissions (Permission Type: Application)
Advanced Query	AdvancedQuery.Read.All
Create Alert	Alert.ReadWrite.All
Create Domain Indicator	Ti.ReadWrite, Ti.ReadWrite.All
Create File Indicator	Ti.ReadWrite, Ti.ReadWrite.All
Create IP Indicator	Ti.ReadWrite, Ti.ReadWrite.All
Delete Indicator	Ti.ReadWrite, Ti.ReadWrite.All
Fetch Event	Alert.Read.All, Alert.ReadWrite.All
Fetch Related Events	Alert.Read.All, Alert.ReadWrite.All
Get Alerts By ID	Alert.Read.All, Alert.ReadWrite.All
Get File Related Alerts	Machine.Read.All, Machine.ReadWrite.All
Get Host By Hashes	Machine.Read.All, Machine.ReadWrite.All
Get Host By IP	Machine.Read.All, Machine.ReadWrite.All
Get Host By User	Machine.Read.All, Machine.ReadWrite.All
Get Host Details	Machine.Read.All, Machine.ReadWrite.All
Get Indicator By ID	Ti.ReadWrite, Ti.ReadWrite.All
Get Live Response Results	Machine.Read.All
Get Machine Logon Users	User.Read.All
Get User By Alert	User.Read.All
List Hosts	Machine.Read.All, Machine.ReadWrite.All
List Hosts Actions	Machine.Read.All, Machine.ReadWrite.All
List Indicator	Ti.ReadWrite, Ti.ReadWrite.All
List Live Response Library Files	Library.Manage
List Machine Actions	Machine.Read.All, Machine.ReadWrite.All
Offboard Machines	Machine.Offboard
Quarantine Files	Machine.StopAndQuarantine, Machine.Read.All, Machine.ReadWrite.All
Quarantine Hosts	Machine.Isolate
Run Live Response Commands	Machine.LiveResponse
Scan Hosts	Machine.Scan
Submit Indicator	Ti.ReadWrite, Ti.ReadWrite.All
Submit URL Indicators	Ti.ReadWrite, Ti.ReadWrite.All
Unquarantine Hosts	Machine.Isolate The user must have at least the following role permission: 'Active remediation actions' (see Create and manage roles for role-based access control - Microsoft Defender for Endpoint \| Microsoft Learn for more information). The user must have access to the device, based on device group settings (See Create and manage device groups in Microsoft Defender for Endpoint - Microsoft Defender for Endpoint \| Microsoft Learn for more information)
Update Alert	Alert.ReadWrite, Alert.ReadWrite.All
Upload File To Live Response Library	Library.Manage
Test Connection	Alert.Read.All, Alert.ReadWrite.All

Configuring Microsoft Defender for Endpoint to Work with D3 SOAR

Log into the Azure portal.
Navigate to the top search bar, then search and select App registrations.
If you already have created apps, you can use one of them. Skip to step 5 to obtain the Client ID & Tenant ID. If you do not have an app, click + New registration to create one.
Register the application.
1. Enter an application Name.
2. For Supported account types, select Accounts in this organizational directory only (<Your Directory Name> only - Single tenant).
3. Click Register.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID. They will be required to build the integration connection in D3 SOAR. Navigate to Client credentials, then click Add a certificate or secret.
Click + New Client Secret. Enter a Description for the client secret, and select a client secret expiry period using the Expires dropdown menu. Click Add. Note: The client ID will not be able to access the API resources after the client secret expires. You must renew the client secret to keep the client ID active.
Copy and save the Secret Value. It will be required to build the integration connection in D3 SOAR connection. Note: The created Client Secret can only be viewed once. Store it in a secure location before leaving the page.
Configure the API permissions. Click API permissions on the left navigation menu, then click + Add a permission.
Select the APIs my organization uses tab and type WindowsDefenderATP in the search box. Select WindowsDefenderATP when it populates below the search box.
Select the required Application permissions. After selecting the required permission, click Add permissions.

READER NOTE*

An error may occur if an incorrect permission type is selected for this integration. When configuring permissions, distinguish between Delegated Permissions and Application Permissions.

Delegated Permissions allow the application to act on behalf of the signed-in user.
Application Permissions allow the application to access data independently, typically when no user is signed in or when the data cannot be scoped to a single user.

For more information, refer to Authentication and authorization basics.

Check the boxes for Alert.Read.All and Alert.ReadWrite.All in the Alert section, then click Add permissions. See Permission Requirements for the required permissions for each command in this integration.
Some permissions may need to be granted admin consent for your directory (d3uat in the sample screenshot) to use. Ensure Grant admin consent for <Your Directory> is checked.

The status column may display Not granted for <Your Directory> for permissions that have not yet been approved. After consent is granted, a green checkmark appears under the status column.

READER NOTE

Accounts without administrative privileges require an administrator to grant consent.

Configuring D3 SOAR to Work with Microsoft Defender for Endpoint

Log in to D3 SOAR.
Find the Microsoft Defender for Endpoint integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Microsoft Defender for Endpoint in the search box to find the integration, then click it to select it.
4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Defender for Endpoint.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your saved Directory (tenant) ID. See step 5 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.
  2. Input your saved Application (client) ID. See step 5 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.
  3. Input your saved Client Secret. Please refer to step 7 of Configuring Microsoft Defender for Endpoint to Work with D3 SOAR.
10. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Microsoft Defender for Endpoint includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Microsoft Defender for Endpoint API, refer to Microsoft Defender for Endpoint API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Microsoft Defender for Endpoint to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

Run Advanced Hunting Queries

Runs advanced hunting queries on Microsoft Defender for Endpoint. If you want to query email-related tables or other Microsoft 365 defender tables, please run the Advanced Hunting command from the Microsoft 365 Defender integration. Note: In order to run this command, your APP requires the AdvancedQuery.Read.All permission. Additionally, the command can only query data from the past 30 days.

READER NOTE

Limitations for this command:

You can only run a query on data from the last 30 days.
The results can include a maximum of 100,000 rows.
The number of executions is limited per tenant:
- API calls: Up to 45 calls per minute, up to 1500 calls per hour.
- Execution time: 10 minutes of running time every hour and 3 hours of running time a day.
The maximal execution time for a single request is 200 seconds.
429 response will represent reaching quota limit either by number of requests or by CPU. Read the response body to understand what limit has been reached.
The maximum query result size for a single request cannot exceed 124 MB. If exceeded, the HTTP 400 Bad Request error with the message "Query execution has exceeded the allowed result size. Optimize your query by limiting the number of results and try again" will return.

Refer to Advanced hunting API from Microsoft’s documentation for more details.

Input

Input Parameter

Required/Optional

Description

Example

Query

Required

The Kusto query string to search for results. For more information about Kusto Query Language (KQL), please refer to Kusto Query Language (KQL) overview from Microsoft’s documentation.

union DeviceProcessEvents, DeviceNetworkEvents

| where Timestamp > ago(30d)

| where InitiatingProcessFileName =~ 'powershell.exe'

| where ProcessCommandLine has_any('WebClient', 'appdata', 'DownloadFile', 'DownloadData', 'DownloadString', 'WebRequest', 'Shellcode', 'http', 'https')

| project Timestamp, DeviceName, ReportId, InitiatingProcessFileName, InitiatingProcessCommandLine, FileName, ProcessCommandLine, RemoteIP, RemoteUrl, RemotePort, RemoteIPType

| top 20 by Timestamp

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Run Advanced Hunting Queries failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Failed to resolve scalar expression named 'XXX'. Fix semantic errors in your query.

Error Sample Data

Run Advanced Hunting Queries failed.

Status Code: 400.

Message: Failed to resolve scalar expression named 'XXX'. Fix semantic errors in your query.

Create Alert

Creates an alert based on event data obtained from Advanced Query.

WARNING

To obtain Event Time, Machine ID, and Report ID, you must define the project operators' project Timestamp, DeviceId, ReportId using the Advanced Query command.

READER NOTE

Machine ID, Event Time and Report ID are required parameters to run this command.
- Run the Run Advanced Hunting Queries command to obtain Machine IDs, Event Time and Report IDs. Machine IDs can be found in the raw data at the path $.results[*].machineId.
- These three input parameters must match in order to run this command. Run the Run Advanced Hunting Queries command and select the three corresponding values from the same JSON object in the returned raw data. If the values do not match, the error message “NotFound” will be returned.
Limitations for this command:
- The rate limitation for this API is 15 calls per minute.
See Create alert from event API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Machine ID	Required	The ID of the device on which the event was identified. Machine IDs can be obtained using the Run Advanced Hunting Queries command.	*****************
Severity	Required	The severity of the alert. The available severity levels are: Low, Medium and High.	Low
Title	Required	The title for the alert.	example
Description	Required	The description for the alert.	example alert
Recommended Action	Required	The recommended course of action for the security officer when analyzing the alert.	nothing
Event Time	Required	The precise time (in UTC Time) of the event, as obtained from the Run Advanced Hunting Queries command. For example, 2020-08-03T16:45:21.7115183Z.	2020-07-29T21:35:33.2061566Z
Report ID	Required	The Report ID of the event, as obtained from advanced hunting. Report IDs can be obtained using the Run Advanced Hunting Queries command.	*****
Category	Required	The category of the alert. The available category values are: General CommandAndControl, Collection, CredentialAccess, DefenseEvasion, Discovery, Exfiltration, Exploit, Execution, InitialAccess, LateralMovement, Malware, Persistence, PrivilegeEscalation, Ransomware, and SuspiciousActivity.	Exploit

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Alert failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NotFound.

Error Sample Data

Create Alert failed.

Status Code: 404.

Message: NotFound.

Create Domain Indicator

Creates a domain indicator.

READER NOTE

The parameter rbac Group Names is optional to run this command.
- To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There is a limit of 15,000 active indicators per tenant.
See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Domain	Required	The identity of the indicator entity.	d3security.com
Action	Required	The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.	AlertAndBlock
Application	Optional	The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.	demo-test
Title	Required	The indicator alert title.	test
Description	Required	The description of the indicator.	test
Expiration Time	Optional	The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.	2022-12-12T00:00:00Z
Severity	Optional	The severity of the indicator. The available input options are Informational, Low, Medium, and High.	Informational
Recommended Actions	Optional	The recommended actions for the indicator alert.	nothing
rbac Group Names	Optional	A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "group1", "group2" ]`
Generate Alert	Optional	True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.	True

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Domain Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Request body is incorrect.

Error Sample Data

Create Domain Indicator failed.

Status Code: 400.

Message: Request body is incorrect.

Create File Indicator

Creates a file indicator.

READER NOTE

The parameter rbac Group Names is optional to run this command.
- To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There is a limit of 15,000 active indicators per tenant.
See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Hash Value	Required	The file hash value of the indicator.	*****
Hash Type	Required	The file hash type (i.e. FileSha1 or FileSha256 of the specified hash value.)	FileSha1
Action	Required	The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.	AlertAndBlock
Application	Optional	The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.	demo-test
Title	Required	The indicator alert title.	test
Description	Required	The description of the indicator.	test
Expiration Time	Optional	The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.	2022-12-12T00:00:00Z
Severity	Optional	The severity of the indicator. The available input options are Informational, Low, Medium, and High.	Informational
Recommended Actions	Optional	The recommended actions for the indicator alert.	nothing
rbac Group Names	Optional	A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "group1", "group2" ]`
Generate Alert	Optional	True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.	True

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create File Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: File SHA1 XXX is invalid.

Error Sample Data

Create File Indicator failed.

Status Code: 400.

Message: File SHA1 XXX is invalid.

Create IP Indicator

Creates an IP indicator.

READER NOTE

The parameter rbac Group Names is optional to run this command.
- To obtain rbac Group Names, you will need to find them on the Microsoft Defender for Endpoint platform under Permissions > Device groups. If the input group names are not found in the device groups, an error will return.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There is a limit of 15,000 active indicators per tenant.
See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
IP	Required	The identity of the indicator entity.	*...*
Action	Required	The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.	AlertAndBlock
Application	Optional	The application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.	demo-test
Title	Required	The indicator alert title.	test
Description	Required	The description of the indicator.	test
Expiration Time	Optional	The expiration time of the indicator. For example, 2022-12-12T00:00:00Z.	2022-12-12T00:00:00Z
Severity	Optional	The severity of the indicator. The available input options are Informational, Low, Medium, and High. If not specified, the default value is Informational.	Informational
Recommended Actions	Optional	The recommended actions for the indicator alert.	nothing
rbac Group Names	Optional	A comma-separated list of RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "group1", "group2" ]`
Generate Alert	Optional	True if alert generation is required, False if this indicator should not generate an alert. If not specified, the default value is True.	True

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create IP Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: IP XXX is invalid.

Error Sample Data

Create IP Indicator failed.

Status Code: 400.

Message: IP XXX is invalid.

Delete Indicator

Deletes an Indicator entity by ID.

READER NOTE

The parameter Indicator IDs is required to run this command.
- Run the List Indicator command to obtain Indicator IDs. Indicator IDs can be found in the returned raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Delete Indicator API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Indicator IDs	Required	The ID(s) of the indicator(s) to delete in an array format. Indicator IDs can be obtained using the List Indicator command.	JSON `[ "", "", "", "" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Received request with not existing indicators: 1.

Error Sample Data

Delete Indicator failed.

Status Code: 404.

Message: Received request with not existing indicators: 1.

Fetch Event

Retrieves events from Microsoft Defender for Endpoint based on the alert creation time, sorted in ascending order.

READER NOTE

Limitations for this command:
- You can get alerts last updated according to your configured retention period.
- Maximum page size is 10,000.
- The Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See to List alerts API | Microsoft Learn from Microsoft’s documentation for more details.
If you leave all optional input parameters empty, the ten oldest (in ascending order by default) created alerts will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to fetch events in UTC time.	2021-01-21 00:00
End Time	Optional	The end time of the time range to fetch events in UTC time.	2021-01-26 00:00
Number of Event(s) Fetched	Optional	The maximum number of events to return. If this parameter is not defined, the default input value will be 10.	10
Search Condition	Optional	The query to filter results. See OData queries with Microsoft Defender for Endpoint from Microsoft’s documentation for more information about the search syntax. Note: Not all properties are filterable. The available properties that support $filter for Alert are alertCreationTime, lastUpdateTime, incidentId, InvestigationId, status, severity, and category.	status eq 'New'
Tolerance Scope	Optional	The tolerance scope in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope}.	0

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

See Field Mappings.

The Microsoft Defender for Endpoint system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data.

The Main Event JSON Path can be viewed by clicking on the Edit Event Source button.

Main Event JSON Path: $.value
The value array contains the event objects. Within each event object, the key id denotes the Event code field. As such, the full JSONPath expression to extract the Event code is $.value.id.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Event code	.id
Severity	.severity
Source vendor name	.detectionSource
Category	.category
Title	.title
None	.description
Creation Time	.alertCreationTime
Host	.computerDnsName
Tenant ID	.aadTenantId
Techniques	.aadTenantId.mitreTechniques
Username	.relatedUser.userName

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Fetch Related Events

Retrieves related events from Microsoft Defender for Endpoint based on the alert creation time, sorted in ascending order.

READER NOTE

Limitations for this command:
- You can get alerts last updated according to your configured retention period.
- Maximum page size is 10,000.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See List alerts API | Microsoft Learn from Microsoft’s documentation for more details.
If you leave all optional input parameters empty, the ten oldest created alerts within the past 24 hours will be returned.

Input

Input Parameter	Required/Optional	Description	Example
The hours before	Optional	The number of hours before the current time. The default value is 24.	10
Top Recent Number	Optional	The top recent event number. The default value is 10, the max value is 10,000.	1
Search Condition	Optional	The query to filter results. See OData queries with Microsoft Defender for Endpoint from Microsoft’s documentation for more information about the search syntax. Note: Not all properties are filterable. The available properties that support $filter for Alert are alertCreationTime, lastUpdateTime, incidentId, InvestigationId, status, severity, and category.	status eq 'New'
Tolerance Scope	Optional	The tolerance scope in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope}. The default value is 0.	0

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Related Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The query specified in the URI is not valid

Error Sample Data

Fetch Related Events failed.

Status Code: 400.

Message: The query specified in the URI is not valid.

Get Alerts By ID

Retrieves alerts from Microsoft Defender for Endpoint based on the specified Alert IDs.

READER NOTE

Limitations for this command:
- You can get alerts last updated according to your configured retention period.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get alert information by ID API from Microsoft’s documentation for more details.
The parameter Alert IDs is required to run this command.
- Run the Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Related Event command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Alert IDs	Required	The IDs of the alerts to retrieve. Alert IDs can be obtained using the Fetch Related Events command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Alerts By ID failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Error Sample Data

Get Alerts By ID failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Alert.ReadWrite.All, Alert.Read.All) to access the resource.

Get File Related Alerts

Retrieves alerts from Microsoft Defender for Endpoint related to the specified file hashes.

READER NOTE

The parameter File Hashes is required to run this command.
- You should already have your desired file hashes on hand to run this command. If you don’t, you may use the Fetch Related Events command with defined filters to retrieve the desired file hashes. The file hash values can be found in the raw data under the key “sha1”.
Limitations for this command:
- Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- Only the SHA-1 hash function is supported (no support for MD5 or SHA-256).
See Get file-related alerts API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
File Hashes	Required	The file hashes to search related alerts by. Note: Only SHA-1 file hashes are supported.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get File Related Alerts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Error Sample Data

Get File Related Alerts failed.

Status Code: 400.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Get Host By Hashes

Retrieves a collection of machines related to the specified file hashes.

READER NOTE

The parameter File Hashes is required to run this command.
- You should already have your desired file hashes on hand to run this command. If you don’t, you may use the Fetch Related Events command with defined filters to retrieve the desired file hashes. The file hash values can be found in the raw data under the key “sha1”.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- Only the SHA-1 hash function is supported (no support for MD5 or SHA-256).
See Get file-related machines API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
File Hashes	Required	The file hashes to search related hosts by. Note: Only SHA-1 file hashes are supported.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Host By Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Error Sample Data

Get Host By Hashes failed.

Status Code: 400.

Message: Currently only Sha1 is supported for this API. XXX is invalid Sha1.

Get Host By IP

Finds Machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.

READER NOTE

The parameter IP Addresses is required to run this command.
- Run the List Hosts command to obtain IP Addresses. The IP Addresses value can be found in raw data at the path $.value[*].lastIpAddress. Please note that IP addresses will only return when the value of the “healthStatus” field is active inside the JSON object. If you input other IP addresses, the command will run successfully with no returning results.
Limitations for this command:
- The given timestamp must be in the past 30 days.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Find devices by internal IP API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
IP Addresses	Required	The IP addresses to search related hosts by. IP addresses can be obtained using the List Hosts command.	JSON `[ "*...*" ]`
Timestamp	Required	The timestamp in UTC time to filter results. Machines seen with the input IP addresses after the defined timestamp will be returned. Note: The defined timestamp must be within 30 days before the current date.	2022-09-01 00:00

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Host By IP failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: XXX is not valid IP.

Error Sample Data

Get Host By IP failed.

Status Code: 400.

Message: XXX is not valid IP.

Get Host By User

Retrieves Machines related to the specified user names.

READER NOTE

The parameter User Names is required to run this command.
- Run the Get Machine Logon Users command to obtain User Names. User Names can be found in the returned raw data at the path $.value[*].accountName.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get user-related machines API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
User Names	Required	The user names to search related hosts by. User names can be obtained using the Get Machine Logon Users command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Host By User failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: No HTTP resource was found that matches the request URI.

Error Sample Data

Get Host By User failed.

Status Code: 404.

Message: No HTTP resource was found that matches the request URI.

Get Host Details

Retrieves Machines related to the specified device IDs or computer names.

READER NOTE

The parameter Hosts is required to run this command.
- Run the List Hosts command to obtain Machine IDs. Machine IDs can be found in the returned raw data at the path $.value[*].id.
Limitations for this command:
- You can get devices last seen according to your configured retention policy.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get machine by ID API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Hosts	Required	The device IDs or computer names to retrieve corresponding details. Device IDs and computer names can be obtained using the List Hosts command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Host Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Machine XXX was not found.

Error Sample Data

Get Host Details failed.

Status Code: 404.

Message: Machine XXX was not found.

Get Indicator By ID

Retrieves the specified indicators by Indicator IDs.

READER NOTE

The parameter Indicator IDs is required to run this command.
- Run the List Indicator command to obtain Indicator IDs. The Indicator IDs can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See List Indicators API | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Indicator IDs	Required	The array of Indicator IDs to retrieve corresponding indicators. Indicator IDs can be obtained using the List Indicator command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get indicator By ID failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Indicator 14 was not found.

Error Sample Data

Get indicator By ID failed.

Status Code: 404.

Message: Indicator 14 was not found.

Get Live Response Results

Retrieves the specific live response command result(s). Please note, this command applies to Microsoft Defender for Endpoint Plan 1 and Plan 2.

READER NOTE

The parameter Machine Action IDs is required to run this command.
- Run the Run Live Response Command command to obtain Machine Action IDs. The Machine Action IDs can be found in the raw data at the path $.results[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get MachineAction object API - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Machine Action IDs	Required	The ID(s) of the Machine Action(s) to retrieve live response command result(s). Machine Action IDs can be obtained using the Run Live Response Command command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Live Response Results failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The key value (ExampleIncorrectMachineActionID) from request is not valid. The key value should be format of type 'Edm.Guid'.

Error Sample Data

Get Live Response Results failed.

Status Code: 400.

Message: The key value (ExampleIncorrectMachineActionID) from request is not valid. The key value should be format of type 'Edm.Guid'.

Get Machine Logon Users

Retrieves a collection of logged on users on a specific device.

READER NOTE

The parameter Machine IDs is required to run this command.
- Run the List Hosts command to obtain Machine IDs. The Machine IDs can be found in the raw data at the path $.value[*].id.
- Please note that some machines may not have a logon user. In this case, the command will run successfully with no returning results.
Limitations for this command:
- You can query on alerts last updated according to your configured retention period.
- Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get machine logon users API from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Machine IDs	Required	The ID(s) of the machine(s) to retrieve a collection of logged on users from. Machine IDs can be obtained using the List Hosts command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Machine Logon Users failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Machine XXX was not found.

Error Sample Data

Get Machine Logon Users failed.

Status Code: 404.

Message: Machine XXX was not found.

Get Users By Alert

Retrieves users related to specified Alert IDs.

READER NOTE

Limitations for this command:
- You can query alerts by the last updated time according to your configured retention period.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Get alert related user information API from Microsoft’s documentation for more details.
The parameter Alert IDs is required to run this command.
- Run the Fetch Event or Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Event or Fetch Related Events command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.
Not all alerts are related to a user. If you input an alert with no related users, the error message “There is no user related to alert…” will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Alert IDs	Required	The ID(s) of the alert(s) to retrieve related user information from. Alert IDs can be obtained using the Fetch Event or Fetch Related Events commands.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get User By Alert failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: There is no User related to the alert.

Error Sample Data

Get User By Alert failed.

Status Code: 404.

Message: There is no User related to the alert.

List Hosts Actions

Retrieves a list of host actions.

READER NOTE

Limitations for this command:
- Maximum page size is 10,000.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour
See List machineActions API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Hosts Actions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Hosts Actions failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

List Hosts

Retrieves a list of machines.

READER NOTE

Limitations for this command:
- You can get devices last seen according to your configured retention period.
- Maximum page size is 10,000.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See List machines API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Hosts failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

List Indicator

Retrieves a collection of all active Indicators.

READER NOTE

Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See List Indicators API | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Error Sample Data

List Indicator failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

List Live Response Library Files

Retrieves live response library files. Please note, this command applies to Microsoft Defender for Endpoint.

READER NOTE

Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

See List library files - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Live Response Library Files failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Failed to get Access Token.

Error Sample Data

List Live Response Library Files failed.

Status Code: 400.

Message: Failed to get Access Token.

List Machine Actions

Returns a collection of Machine Actions based on the specified criteria. The rate limitations for this command are 100 calls per minute and 1500 calls per hour.

READER NOTE

Machine Action IDs and Machine IDs are optional parameters to run this command.
- Run the List Host Actions command to obtain Machine Action IDs. Machine Action IDs can be found in the raw data at the path $.value.[*].id.
- Run the List Hosts or List Host Actions or List Host Actions command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id. For List Host Actions command, Machine IDs can be found in the raw data at the path $.value[*].machineId.
- Your input Machine ID and Machine Action ID must match in order to run this command. If the input values do not match, the command will run successfully with no result returned.
- If you input multiple Machine Action IDs and Machine IDs, only the matching pairs (i.e., a Machine ID and a Machine Action ID exist under the same JSON object in the returned raw data of the List Host Actions command) will be returned. For example, if multiple input Machine Action IDs correspond to one Machine ID, all of those successfully matched pairs will be returned. It is possible to have multiple Machine Action ID inputs but only one input Machine ID.
Limitations for this command:
- Maximum page size is 10,000.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See List machineActions API | Microsoft Learn from Microsoft’s documentation for more details.
If no input parameters are defined, all machine actions will be returned. You can use this command to retrieve Action IDs and Device IDs. The returned “id” key contains Machine Action IDs and the “machineId” key contains Machine IDs.

Input

Input Parameter	Required/Optional	Description	Example
Machine Action IDs	Optional	The IDs of the machine actions to filter results. Machine Action IDs can be obtained using List Host Actions command.	JSON `[ "*****" ]`
Machine IDs	Optional	The ID(s) of the machine(s) to list corresponding machine actions. Machine IDs can be obtained using the List Hosts or Get Host By IP or List Host Actions command.	JSON `[ "*****" ]`
Create Time	Optional	The creation time of the machine actions to filter results. The input is in UTC time.	2022-10-07 00:00
Time Operator	Optional	The operator for the defined Create Time to filter results. The available time operators are Greater Than, Greater Than Equal, Less Than, Less Than Equal.	Less Than
Types	Optional	The list of Machine Action types to filter results. The valid values are RunAntiVirusScan, Offboard, Live Response, CollectInvestigationPackage, Isolate, Unisolate, StopAndQuarantineFile, RestrictCodeExecution, and UnrestrictCodeExecution.	["Isolate"]
Requestors	Optional	The list of Machine Action requesters to filter results.	JSON `[ "***@example.com" ]`
Status	Optional	The list of Machine Action statuses to filter results. The valid values are Pending, InProgress, Succeeded, Failed, TimeOut, and Cancelled.	JSON `[ "InProgress", "Succeeded" ]`
Limit	Optional	The maximum number of records (up to 100) to return. The default value is 20.	3
Offset	Optional	The offset value to paginate the returned records.	0

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Machine Actions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Error Sample Data

List Machine Actions failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.Read.All, Machine.ReadWrite.All) to access the resource.

Offboard Machines

Offboard specified device(s) from Defender for Endpoint. This command has a rate limitation of 100 calls per minute and 1500 calls per hour. Also, the API endpoint used for the command is only supported on Windows 11, Windows 10, version 1703 and later; on Windows Server 2019 and later; and on Windows Server 2012 R2 and Windows Server 2016 when using the new, unified agent for Defender for Endpoint. macOS or Linux devices are not supported.

Note: This API is supported on Windows 11, Windows 10, version 1703 and later; on Windows Server 2019 and later; and on Windows Server 2012 R2 and Windows Server 2016 when using the new, unified agent for Defender for Endpoint.

This API is not supported on macOS or Linux devices.

Running the offboarding API only stops the sensor service from running, but it does not remove the onboarding information from the registry like an offboarding script does.

READER NOTE

The parameter Machine IDs is required to run this command.
- Run the List Hosts command to obtain Machine IDs. Machine IDs can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.

See Offboard machine API - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter

Required/Optional

Description

Example

Machine IDs

Required

The ID(s) of the machine(s) to offboard. Machine IDs can be obtained using the List Hosts command.

JSON

[
  "*****"
]

Comment

Required

The comment associated with the offboard action.

Offboard machine by vsoc

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Offboard Machines failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Machine invalidTestMachine was not found.

Error Sample Data

Offboard Machines failed.

Status Code: 404.

Message: Machine invalidTestMachine was not found.

Quarantine Files

Quarantine files based on the specified machine ID and SHA-1 files hashes.

READER NOTE

Machine ID is a required parameter to run this command.
- Run the List Hosts or Get Host By IP command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id.
- Ensure the file to quarantine exists on your input machine and the file is not trusted.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Stop and quarantine file API | Microsoft Learn from Microsoft’s documentation for more details.
You can only take this action if:
- The device you're taking the action on is running Windows 10 (version 1703 or later) or Windows 11.
- The file does not belong to a trusted third-party publisher nor signed by Microsoft.
- Microsoft Defender Antivirus must at least be running on Passive mode.

Input

Input Parameter	Required/Optional	Description	Example
Machine ID	Required	The ID of the machine that the file(s) to quarantine is located on. Machine ID can be obtained using List Hosts or Get Host By IP command.	*****
Comment	Required	A comment associated with the quarantine action.	Stop and quarantine file on machine due to alert *_*
Hash Values	Required	The SHA-1 file hash value(s) of the file(s) to stop and quarantine on the device.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Quarantine Files failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Machine.StopAndQuarantine) to access the resource.

Error Sample Data

Quarantine Files failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Machine.StopAndQuarantine) to access the resource.

Quarantine Hosts

Isolates specified devices from accessing the external network.

READER NOTE

The parameter Hosts is required to run this command.
- Run the List Hosts command to obtain Hosts. Hosts can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Isolate machine API | Microsoft Learn from Microsoft’s documentation for more details.
The IsolationType parameter defines one of the following the type of isolation to perform:
- Full: Full isolation
- Selective: Restricts only limited set of applications from accessing the network (see Isolate devices from the network from Microsoft’s documentation for more details)

ALERT

Full isolation is available for devices running on Windows 10(version 1703), and Windows 11.
Selective isolation is available for devices on Windows 10 (version 1709 or later), and Windows 11.
When isolating a device, only certain processes and destinations are allowed. Devices that are behind a full VPN tunnel will not be able to reach the Microsoft Defender for Endpoint and Microsoft Defender Antivirus cloud-based protection-related traffic.

WARNING

You cannot isolate a device that is already isolated. Otherwise, an error will be returned.

The quarantine process may take some time. If the status is pending, the device is still in the isolation process. If you run the Unquarantined Host command during this process, an error will return. To check the status of the quarantine process, navigate to the device Action Center on the Microsoft Defender for Endpoint platform. Note: You cannot isolate a device that has already been isolated. If you do so, an error will return.

Input

Input Parameter	Required/Optional	Description	Example
Hosts	Required	The machine IDs of the hosts to quarantine. Hosts can be obtained using the List Hosts command.	JSON `[ "***", "***" ]`
Comment	Required	A comment associated with the action.	Isolate machine due to alert
IsolationType	Optional	The isolation type (i.e., Full or Selective) to apply. The default value is Full.	Full

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Quarantine Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Action is not supported for this client version.

Error Sample Data

Quarantine Hosts failed.

Status Code: 400.

Message: Action is not supported for this client version.

Run Live Response Commands

Runs a live response command on the specified device(s). Please note, this command applies to Microsoft Defender for Endpoint Plan 2.

READER NOTE

Machine IDs and Script Name are required parameters to run this command.
- Run the List Hosts or Get Host By IP command to obtain Machine IDs. For both the List Hosts and Get Host By IP command, Machine IDs can be found in the raw data at the path $.value[*].id.
- Run the List Live Response Library Files command to obtain Script Name. Script Name can be found in the raw data at the path fileName.
Limitations for this command:
- Rate limitations for this API are 10 calls per minute (additional requests are responded with HTTP 429).
- 25 concurrently running sessions (requests exceeding the throttling limit receives a "429 - Too many requests" response).
- If the machine isn't available, the session is queued for up to three days.
- RunScript command timeouts after 10 minutes.
- Live response commands can't be queued up and can only be executed one at a time.
- If the machine that you're trying to run this API call is in an RBAC device group that doesn't have an automated remediation level assigned to it, you need to at least enable the minimum Remediation Level for a given Device Group.
- Multiple live response commands can be run on a single API call. However, when a live response command fails all the subsequent actions won't be executed.
- Multiple live response sessions can't be executed on the same machine (if live response action is already running, subsequent requests are responded to with HTTP 400 - ActiveRequestAlreadyExists).

See Run live response commands on a device - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Machine IDs	Required	The Machine ID(s) on which to run live response commands. Machine IDs can be obtained using the List Hosts or Get Host By IP command.	JSON `[ "*****" ]`
Comment	Required	The comment associated with the action.	Testing Live Response API
Script Name	Required	The PowerShell script to run. Script Name can be obtained using the List Live Response Library Files command. Please note, if you plan to use an unsigned PowerShell script in the session, you will need to enable it in the Advanced features settings page. Please refer to Configure advanced features in Microsoft Defender for Endpoint.	ListItemsInFolder_v2.ps1
Script Argument	Optional	The PowerShell script arguments.	c:\\ProgramData\\USOPrivate

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Run Live Response Commands failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Missing application roles. API required roles: Machine.LiveResponse, application roles: Ti.ReadWrite,Ti.Read.All,Ti.ReadWrite.All,Alert.Read.All,Alert.ReadWrite.All.

Error Sample Data

Run Live Response Commands failed.

Status Code: 403.

Message: Missing application roles. API required roles: Machine.LiveResponse, application roles: Ti.ReadWrite,Ti.Read.All,Ti.ReadWrite.All,Alert.Read.All,Alert.ReadWrite.All.

Scan Hosts

Initiates Microsoft Defender Antivirus scan on the device.

READER NOTE

The parameter Hosts is required to run this command.
- Run the List Hosts or Get Host By IP command to obtain Hosts. For both the List Hosts and Get Host By IP command, Hosts can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Run antivirus scan API | Microsoft Learn from Microsoft’s documentation for more details.
The ScanType input parameter defines one of the following types of scans to perform:
- Quick: Performs a quick scan on the device
- Full: Performs a full scan on the device

ALERT

This action is available for devices on Windows 10 (version 1709 or later), and Windows 11.
A Microsoft Defender Antivirus (Microsoft Defender AV) scan can run alongside other antivirus solutions, regardless if Microsoft Defender Antivirus is the active antivirus solution. Microsoft Defender Antivirus can be running in Passive mode. For more information, see Microsoft Defender Antivirus compatibility from Microsoft’s documentation.

Input

Input Parameter	Required/Optional	Description	Example
Hosts	Required	The machine IDs of the hosts to initiate an antivirus scan. Hosts can be obtained using the List Hosts or Get Host By IP command.	JSON `[ "***", "***" ]`
Comment	Optional	A comment associated with the action.	Check machine for viruses due to alert
Scan Type	Required	The scan type (i.e., Quick or Full) to perform. The default value is Quick.	Full

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Scan Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Machine XXX was not found.

Error Sample Data

Scan Hosts failed.

Status Code: 404.

Message: Machine XXX was not found.

Submit Indicator

Updates an indicator.

READER NOTE

Indicator Value is a required parameter to run this command.
- Run the List Indicator command to obtain the Indicator Value. Indicator Values can be found in the raw data at the path $.value[*].indicatorValue.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There is a limit of 15,000 active indicators per tenant.
See Submit or Update Indicator API | Microsoft Learn from Microsoft’s documentation for more details.
If you leave some parameters empty, any existing values will still be kept. If optional parameters are left undefined with previously existing values, those values will also be kept.

Input

Input Parameter	Required/Optional	Description	Example
Indicator Value	Required	The identity of the Indicator entity to update. Indicator Values can be obtained using the List Indicator command.	d3security.com
Indicator Type	Required	The updated type of the indicator. The available indicator types are FileSha1, FileMd5, CertificateThumbprint, FileSha256, IpAddress, DomainName and Url.	DomainName
Action	Required	The action that will be taken if the indicator will be discovered in the organization. The available actions are Alert, AlertAndBlock, and Allowed.	AlertAndBlock
Application	Optional	The updated application associated with the indicator. This field only works for new indicators. It will not update the value on an existing indicator.	demo-test
Title	Required	The updated indicator alert title.	test
Description	Required	The updated description of the indicator.	test
Expiration Time	Optional	The updated expiration time of the indicator. For example, 2022-12-12T00:00:00Z.	2022-12-12T00:00:00Z
Severity	Optional	The updated severity of the indicator. The available input options are Informational, Low, Medium, and High.	Informational
Recommended Actions	Optional	The updated recommended actions for the indicator alert.	nothing
rbac Group Names	Optional	A comma-separated list of updated RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "group1", "group2" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Error Sample Data

Update Indicator failed.

Status Code: 401.

Message: The application does not have any of the required application permissions (Ti.ReadWrite, Ti.ReadWrite.All) to access the resource.

Submit URL Indicators

Create new or update existing URL Indicator(s) with different action and alert settings. This command can be used to block, allow, audit or warn about specified URLs. Microsoft Defender for Endpoint will evaluate the command parameters and decide whether to create new indicators or update the existing ones.

READER NOTE

Limitations for this command:
- Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There's a limit of 15,000 active indicators per tenant.
See Submit or Update Indicator API - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
URLs	Required	The URLs used to create new or update existing URL indicators. There can be a maximum of 100 URLs; any additional URLs will be deleted.	JSON `[ "https://www.examples.com", "https://www.malware.com" ]`
Action	Required	The action to be taken when the indicator is detected within the organization. The available actions are Allow, Audit, Warn, and Block Execution.	Block Execution
Application	Optional	The application associated with the new indicators only. This parameter applies to the submission of new URL indicators, and will not update the application value of existing indicators.	demo-block
Alert Title	Optional	The URL indicator alert title.	Block the URLs
Description	Required	The description of the URL indicator.	Malware sites
Expiration Time	Optional	The expiration UTC time of the URL indicator. When not specified, the indicator will be Never Expired. Once an expired time is set, it cannot be changed back to Never Expired.	2024-07-29 00:00
Generate Alert	Optional	The choice for whether to generate an alert for the URL block indicators. The default value is False. When the action parameter is set to Allow, this parameter will automatically be set to False. When the action parameter is set to Audit, the Generate Alert parameter will be automatically set to True.	False
Alert Severity	Optional	The severity level of the alert for the URL indicator. Possible values are Informational, Low, Medium, and High. If not specified, the default value is Informational.	Informational
Recommended Actions	Optional	The recommended actions for addressing the indicator alert.	Action suggested
Device Groups Scope	Optional	The comma-separated list of updated RBAC group names to which the indicator will be applied. The input RBAC device groups are where the indicator will be exposed and active. Indicators created for certain target groups will be exposed to all devices in the group. Leave this parameter empty to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "UnassignedGroup", "Lab1Group", "group1" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Submit URL Indicators failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The parameter Expiration Time should be set to a future date time.

Error Sample Data

Submit URL Indicators failed.

Status Code: 400.

Message: The parameter Expiration Time should be set to a future date time.

Unquarantine Hosts

Undoes the isolation of the specified host(s).

READER NOTE

The parameter Hosts is required to run this command.
- Run the List Hosts or Get Host By IP command to obtain Hosts. For both the List Hosts and Get Host By IP command, Hosts can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Release device from isolation API from Microsoft’s documentation for more details.

WARNING

The quarantine process may take some time. If the status is pending, the device is still in the isolation process. If you run the Unquarantined Host command during this process, an error will return. To check the status of the quarantine process, navigate to the device Action Center on the Microsoft Defender for Endpoint platform. Note: You cannot unisolate a device that has already been isolated. If you do so, an error will return.

Input

Input Parameter	Required/Optional	Description	Example
Hosts	Required	TThe machine IDs of the hosts to unquarantine. Hosts can be obtained using the List Hosts or Get Host By IP command.	JSON `[ "***", "***" ]`
Comment	Required	A comment associated with the action.	Unisolate machine since it was clean and validated

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unquarantine Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Cannot unisolate a device that is unisolated.

Error Sample Data

Unquarantine Hosts failed.

Status Code: 400.

Message: Cannot unisolate a device that is unisolated.

Update Alert

Updates the properties of a specified existing alert.

READER NOTE

Alert ID is a required parameter to run this command.
- Run the Fetch Event or Fetch Related Events command to obtain Alert IDs. You should already have your desired Alert IDs on hand to run this command. If you don’t, you may use the Fetch Event or Fetch Related Events command with defined filters to retrieve the desired Alert IDs. The Alert IDs can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- You can update alerts that are available in the API. For more information, see List Alerts.
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Update alert from Microsoft’s documentation for more details.

Input

Input Parameter	Required/Optional	Description	Example
Alert ID	Required	The ID of the alert to update. Alert ID can be obtained using the Fetch Event or Fetch Related Events command.	***_***
Status	Required	The updated status of the alert. The available statuses are New, InProgress and Resolved.	Resolved
Assigned To	Optional	The owner of the alert.	***@example.com
Classification	Optional	The classification of the alert. The valid property values are Unknown, FalsePositive, and TruePositive.	FalsePositive
Determination	Optional	The determination of the alert. The valid property values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.	Malware
Comment	Optional	A comment about the alert.	Resolve my alert and assign to secop2

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Alert failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Authorization payload.

Error Sample Data

Update Alert failed.

Status Code: 401.

Message: Invalid Authorization payload.

Update Indicator V2

Updates a specific indicator identified by its indicator ID.

READER NOTE

Indicator ID is a required parameter to run this command.
- Run the List Indicator command to obtain the Indicator ID. Indicator IDs can be found in the raw data at the path $.value[*].id.
Limitations for this command:
- The rate limitations for this API are 100 calls per minute and 1500 calls per hour.
- There's a limit of 15,000 active indicators per tenant.

Input

Input Parameter	Required/Optional	Description	Example
Indicator ID	Required	The ID of the Indicator entity to update. Indicator ID can be obtained using the List Indicator command.	798
Action	Optional	The action to be taken if the indicator is detected within the organization. Available actions include Warn, Block, Audit, Block And Remediate, Alert, Alert And Block, and Allowed. When the Alert action is selected, the effective action will be Audit, and GenerateAlert will be set to True. When the Alert And Block action is selected, the effective action will be Block, and GenerateAlert will be set to True.	AlertAndBlock
Application	Optional	The application associated with the indicator.	WebServer apache
Title	Optional	The updated indicator alert title.	test-2024a
Description	Optional	The updated description of the indicator.	test-update2024a
Expiration Time	Optional	The updated expiration time of the indicator.	2024-10-01T00:00:00Z
Severity	Optional	The updated severity of the indicator. The available input options are Informational, Low, Medium, and High.	High
Recommended Actions	Optional	The updated recommended actions for addressing the indicator alert.	Monitoring
RBAC Group Names	Optional	The comma-separated list of updated RBAC group names to apply the indicator to. The input RBAC device groups are where the indicator will be exposed and active. The indicators created for some target groups will be exposed to all devices in the group. Leave this parameter empty if you want to avoid unwanted access exposure. RBAC group names can be found on the Microsoft Defender for Endpoint platform under Permissions > Device groups.	JSON `[ "group1", "group2" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Alert failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Failed to get Access Token.

Error Sample Data

Update Alert failed.

Status Code: 400.

Message: Failed to get Access Token.

Upload File To Live Response Library

Uploads files to the live response library. Please note that the maximum file size limit is 20 MB.

READER NOTE

Limitations for this command:
- File max size limitation is 20MB.
- Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
See Upload files to the live response library - Microsoft Defender for Endpoint | Microsoft Learn from Microsoft’s documentation for more details.

File ID and File Source

It is not recommended to use the Test Command feature with the Upload File To Live Response Library command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
File ID	Required	The file ID of the file to be uploaded to the live response library.	d3security.com
File Source	Required	The file source of the file to be uploaded to the live response library. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	DomainName
File Description	Required	The description of the file to be uploaded.	Sample file description
Has Parameters	Optional	Indicates whether the script file to be uploaded includes parameters.	True
Parameters Description	Optional	The parameters required for the script to run. The default value is an empty string.	Sample parameter description
Override If Exists	Optional	Specifies whether to override the file if it already exists. If not specified, the default value is False.	True

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Indicator failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Failed to get Access Token.

Error Sample Data

Update Indicator failed.

Status Code: 400.

Message: Failed to get Access Token.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Defender for Endpoint portal. Refer to the Microsoft Endpoint Common REST API Error Codes for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Failed to get Access Token.

Error Sample Data

Test Connection failed.

Status Code: 400.

Message: Failed to get Access Token.