Microsoft Defender for Cloud Apps
Overview
Microsoft Defender for Cloud Apps is a Cloud Access Security Broker (CASB) that operates on multiple clouds. It provides rich visibility, control over data travel, and sophisticated analytics to identify and combat cyberthreats across all your cloud services.
D3 SOAR is providing REST operations to function with Microsoft Defender for Cloud Apps.
Microsoft Defender for Cloud Apps is available for use in:
Connection
To connect to Microsoft Defender for Cloud Apps from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Server URL | The Microsoft Defender for Cloud Apps server URL for the connection. | |
Token | The token to authenticate the API connection. | Sxx*************************Fhw |
API Version | The version of the API to use for the connection. | v1 |
Configuring Microsoft Defender for Cloud Apps to Work with D3 SOAR
Log in to your Microsoft Defender for Cloud Apps environment with your credentials.
Navigate to Settings > Security extensions.
Click Add Token.
Enter a name for the token, then click Generate. The API token will be generated. Copy and save the API token and the server URL in a secure location, you will need them to configure the integration connection in D3 SOAR.
Reader Note
The API token value can only be viewed once upon generation. Store it in a secure location for future use. You will need to generate a new token if you have lost a generated API token.
Configuring D3 SOAR to Work with Microsoft Defender for Cloud Apps
Log in to D3 SOAR.
Find the Microsoft Defender for Cloud Apps integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Microsoft Defender for Cloud Apps 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 Cloud Apps.
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.
1. Input the saved Server URL. See step 4 of Configuring Microsoft Defender for Cloud Apps to Work with D3 SOAR.
2. Input the saved Token. See step 4 of Configuring Microsoft Defender for Cloud Apps to Work with D3 SOAR.
3. Input the API Version. The default value is v1.Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.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 checkmark appear 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 Cloud Apps 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.
Integration API Note
For more information about the Microsoft Defender for Cloud Apps API, please refer to the Microsoft Defender for Cloud Apps API reference.
Note for Time-related parameters
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.
Close Alerts
Closes alerts in Microsoft Defender for Cloud Apps based on the specified filters.
Reader Note
If the Last Days and Search Condition parameters are not defined, all alerts under the specified State will be closed.
Input
Input Parameter | Required /Optional | Description | Example |
State | Required | The alert state to set the specified alerts to. The valid alert states are close_benign, close_false_positive and close_true_positive. | close_false_positive |
Last Days | Optional | The number of days before the current time to filter the alerts to close. | 30 |
Search Condition | Optional | The query string to filter the alerts to close. Two query syntaxes are supported: Simple syntax: The format is ip=ip1,ip2 severity=severity1,severity2 status=status1,status2 id=id1,id2. Multiple values can be defined for the ip, status, severity, and id fields, using a comma as a delimiter. The space character is used as a delimiter between the fields. A sample query string is ip=***.***.***.*** severity=1,2 status=0,5 id=*****. The valid values for the status field are 0(OPEN), 1(DISMISSED), 2(RESOLVED), 3(FALSE_POSITIVE) 4(BENIGN) and 5(TRUE_POSITIVE). The valid values for the severity field are 0(LOW),1(MEDIUM),2(HIGH), and 3(INFORMATIONAL). JSON syntax: For more information about this syntax, see Alerts API - Microsoft Defender for Cloud Apps. | severity=0,1,2 |
Output
The primary response data from the API request.
SAMPLE DATA
{
"closed_false_positive": 1
}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
{
"closed_false_positive": 1
}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
SuccessfulProvides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
closed_false_positive | 1 |
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Close 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 Cloud Apps portal. Refer to the HTTP Status Code Registry 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: No filter name 'test' found in metadata alerts |
Error Sample Data Close Alerts failed. Status Code: 400. Message: No filter name 'test' found in metadata alerts. |
Fetch Event
Retrieves alerts from Microsoft Defender for Cloud Apps based on the specified filters.
Input
Input Parameter | Required /Optional | Description | Example |
Start Time | Optional | The start time of the time range to fetch alerts in UTC time. | 2022-12-01 00:00 |
End Time | Optional | The end time of the time range to fetch alerts in UTC time. | 2022-12-20 00:00 |
Number of Event(s) Fetched | Optional | The maximum number of events to return. The default value is 10. | 10 |
Search Condition | Optional | The query string to filter the alerts to close. Two query syntaxes are supported: Simple syntax: The format is ip=ip1,ip2 severity=severity1,severity2 status=status1,status2 id=id1,id2. Multiple values can be defined for the ip, status, severity, and id fields, using a comma as a delimiter. The space character is used as a delimiter between the fields. A sample query string is ip=***.***.***.*** severity=1,2 status=0,5 id=*****. The valid values for the status field are 0(OPEN), 1(DISMISSED), 2(RESOLVED), 3(FALSE_POSITIVE) 4(BENIGN) and 5(TRUE_POSITIVE). The valid values for the severity field are 0(LOW),1(MEDIUM),2(HIGH), and 3(INFORMATIONAL). JSON syntax: For more information about this syntax, see Alerts API - Microsoft Defender for Cloud Apps. | entity.ip=***.***.***.*** severity=1,2 resolutionStatus=0,5 |
Output
The primary response data from the API request.
SAMPLE DATA
{
"data": [
{
"_id": "***************************************",
"contextId": "***************************************",
"description": "The user d3soar (***@example.com) perform failed sign in activities from remote locations that are considered an impossible travel activity.The user performed failed sign in activities from ***.***.***.*** in Turkey and ***.***.***.*** in Canada within 328 minutes.If these are IP addresses that are known and safe, add them in the IP address range page to improve the accuracy of the alerts.",
"entities": [
{
"label": "***@example.com",
"id": "***************************************",
"type": "user"
},
{
"countryCode": "CA",
"id": "***************************************",
"type": "ip",
"triggeredAlert": true,
"label": "***.***.***.***"
},
{
"policyType": "ANOMALY_DETECTION",
"id": "***************************************",
"label": "Impossible travel",
"type": "policyRule"
},
{
"id": ***************************************,
"type": "service",
"label": "Office 365"
},
{
"label": "CA",
"id": "***************************************",
"type": "country"
},
{
"label": "TR",
"id": "***************************************",
"type": "country"
},
{
"countryCode": "TR",
"id": "***************************************",
"type": "ip",
"triggeredAlert": true,
"label": "***.***.***.***"
},
{
"pa": "***@example.com",
"saas": 11161,
"entityType": 2,
"inst": 0,
"label": "d3soar",
"id": "***************************************",
"type": "account"
}
],
"evidence": [
{
"title": {
"template": "ALERTS_MITRE_TACTIC",
"parameters": {
"mitre": {
"label": "MITRE",
"alternateLink": "https://*****.com/***",
"type": "link"
},
"tactic": "INITIAL_ACCESS"
}
}
}
],
"idValue": 15859716,
"intent": [
2
],
"isPreview": false,
"isSystemAlert": false,
"resolutionStatusValue": 0,
"severityValue": 1,
"statusValue": 1,
"stories": [
0
],
"threatScore": 30,
"threatScoreReasoning": [],
"timestamp": 1623085338127,
"title": "Impossible travel activity",
"URL": "https://*****.com/***"
}
],
"hasNext": false,
"max": 100,
"total": 1,
"moreThanTotal": false
}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 $.data 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
[
{
"_id": "***************************************",
"contextId": "***************************************",
"description": "The user d3soar (***@example.com) perform failed sign in activities from remote locations that are considered an impossible travel activity.The user performed failed sign in activities from ***.***.***.*** in Turkey and ***.***.***.*** in Canada within 328 minutes.If these are IP addresses that are known and safe, add them in the IP address range page to improve the accuracy of the alerts.",
"entities": [
{
"label": "***@example.com",
"id": "***************************************",
"type": "user"
},
{
"countryCode": "CA",
"id": "***************************************",
"type": "ip",
"triggeredAlert": true,
"label": "***.***.***.***"
},
{
"policyType": "ANOMALY_DETECTION",
"id": "***************************************",
"label": "Impossible travel",
"type": "policyRule"
},
{
"id": *****,
"type": "service",
"label": "Office 365"
},
{
"label": "CA",
"id": "***************************************",
"type": "country"
},
{
"label": "TR",
"id": "***************************************",
"type": "country"
},
{
"countryCode": "TR",
"id": "***************************************",
"type": "ip",
"triggeredAlert": true,
"label": "***.***.***.***"
},
{
"pa": "***@example.com",
"saas": 11161,
"entityType": 2,
"inst": 0,
"label": "d3soar",
"id": "***************************************",
"type": "account"
}
],
"evidence": [
{
"title": {
"template": "ALERTS_MITRE_TACTIC",
"parameters": {
"mitre": {
"label": "MITRE",
"alternateLink": "https://*****.com/***",
"type": "link"
},
"tactic": "INITIAL_ACCESS"
}
}
}
],
"idValue": *****,
"intent": [
2
],
"isPreview": false,
"isSystemAlert": false,
"resolutionStatusValue": 0,
"severityValue": 1,
"statusValue": 1,
"stories": [
0
],
"threatScore": 30,
"threatScoreReasoning": [],
"timestamp": 1623085338127,
"title": "Impossible travel activity",
"URL": "https://*****.com/***"
}
]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
{
"AlertIDs": [
"***************************************"
],
"Descriptions": [
"The user d3soar (***@example.com) perform failed sign in activities from remote locations that are considered an impossible travel activity.The user performed failed sign in activities from ***.***.***.*** in Turkey and ***.***.***.*** in Canada within 328 minutes.If these are IP addresses that are known and safe, add them in the IP address range page to improve the accuracy of the alerts."
],
"Titles": [
"Impossible travel activity"
],
"SeverityValues": [
1
],
"ResolutionStatusValues": [
0
],
"Timestamps": [
1623085338127
],
"ThreatScores": [
30
]
}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
SuccessfulProvides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
_ID | CONTEXTID | DESCRIPTION | ENTITIES | EVIDENCE | IDVALUE | INTENT | ISPREVIEW | ISSYSTEMALERT | RESOLUTIONSTATUSVALUE | SEVERITYVALUE | STATUSVALUE | STORIES | THREATSCORE | THREATSCOREREASONING | TIMESTAMP | TITLE | URL |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
*** | *** | The user d3soar (*****@example.com/***) perform failed sign in activities from remote locations that are considered an impossible travel activity. | [ | [ | ** | [ | False | False | 0 | 1 | 1 | [ | 30 | [] | 1623085338127 | Impossible travel activity |
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 Cloud Apps 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 are 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. The default event source has a “Main Event JSON Path” (i.e., $.data) 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”.
Main Event JSON Path: $.data
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 data. The child node denoting the Unique Event Key field would be _id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.data.[*]._id.
The pre-configured field mappings are detailed below:
Field Name | Source Field |
Alert Timestamp | .timestamp |
Unique Event Key | ._id |
Event Type | .title |
Description | .description |
Severity | .severityValue |
Status | .resolutionStatusValue |
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | 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 Cloud Apps portal. Refer to the HTTP Status Code Registry 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: list index out of range. |
Error Sample Data Fetch Event failed. Status Code: 400. Message: list index out of range. |
Get IP Activities
Retrieves activities from Microsoft Defender for Cloud Apps related to the specified IP address.
Reader Note
If the command runs successfully with no results, there may be no activities related to your input IP addresses or the input IP addresses are invalid.
The input parameter IP Addresses is required to run this command.
You should already have your desired IP addresses on hand to run this command. If you don’t, you may run the Fetch Event command to retrieve the desired IP addresses. IP addresses can be found in the raw data at the path $.data.[*].entities. Entities with the “type” key that has a value of “user” are the IP addresses that have related activities.
Input
Input Parameter | Required /Optional | Description | Example |
IP Addresses | Required | The list of IP addresses to retrieve related activities. | ["***.***.***.***"] |
Last Days | Optional | The number of days before the current time to filter the returned list of activities. | 10 |
Limit | Optional | The maximum number of results to return. The default value is 20. | 20 |
Output
The primary response data from the API request.
SAMPLE DATA
{
"data": [
{
"_id": "***************************************",
"tenantId": ***************************************,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627673425082,
"timestampRaw": 1627673425082,
"instantiation": 1627674001821,
"instantiationRaw": 1627674001821,
"created": 1627674001899,
"createdRaw": 1627674001899,
"eventType": 917504,
"eventTypeValue": "EVENT_ADALLOM_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "***/*.* (***; ***; ***) AppleWebKit/***.***(KHTML, like Gecko) Chrome/*.*.*.* Safari/*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "CHROME",
"name": "Chrome",
"operatingSystem": {
"name": "Windows 10",
"version": "***************************************",
"family": "Windows"
},
"type": "Browser",
"typeName": "Browser",
"version": "***************************************",
"major": "92",
"minor": "0",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "CHROME"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": 0,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****"
],
"name": "sysint",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "login",
"prettyOperationName": "login",
"type": "login"
},
"confidenceLevel": 30,
"session": {
"sessionId": "***************************************"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "***",
"tags": [
"*****"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": ***
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": ***
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_LOGIN",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
},
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627672613515,
"timestampRaw": 1627672613515,
"instantiation": 1627672861987,
"instantiationRaw": 1627672861987,
"created": 1627676560986,
"createdRaw": 1627676560986,
"eventType": 2293760,
"eventTypeValue": "EVENT_AAD_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"lograbber": true,
"auditing": true,
"dispersed": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": ";Windows 8;Rich Client ***.***.***.***;",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****",
"*****"
]
},
"userAgent": {
"family": "UNKNOWN",
"name": "Unknown",
"operatingSystem": {
"name": "Windows",
"version": "***************************************",
"family": "Windows"
},
"type": "Unknown",
"typeName": "Unknown",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "UNKNOWN"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 6,
"role": 3,
"tags": [],
"name": "Microsoft Azure Active Directory Connect",
"id": "***************************************"
},
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Request ID",
"id": "***************************************"
},
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Pass-through authentication",
"value": "false"
},
{
"objType": 21,
"role": 4,
"tags": [],
"name": "On-Premises Directory Synchronization Service Account",
"instanceId": 0,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****",
"*****"
],
"name": "On-Premises Directory Synchronization Service Account",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "OAuth2:Token",
"prettyOperationName": "OAuth2:Token",
"type": "login"
},
"confidenceLevel": 30,
"source": 2,
"lograbberService": {
"scubaUnpacker": true
},
"srcAppId": 11161,
"collected": {
"aadLogins": {
"enqueueTime": 1627672848188,
"routingTime": 1627672848200,
"correlationId": "***************************************",
"MCAS_Router": false
}
},
"rawDataJson": {
"CorrelationId": "***************************************",
"IsDeviceCompliantAndManaged": false,
"UserTenantMsodsRegionScope": "NA",
"HomeTenantUserObjectId": "***************************************",
"MsodsTenantRegionScope": "NA",
"IsInteractiveComputed": true,
"UserPrincipalObjectID": "***************************************",
"MfaMaskedDeviceId": null,
"ApplicationId": "***************************************",
"ApplicationName": "Microsoft Azure Active Directory Connect",
"DeviceTrustType": "",
"LoginErrorCode": 0,
"UserIsPassthru": false,
"MfaAuthMethod": null,
"IsInteractive": null,
"MfaStatusRaw": null,
"UserTenantId": "***************************************",
"MfaRequired": false,
"LoginStatus": "Success",
"DataSource": null,
"DeviceInfo": ";Windows 8;Rich Client ***.***.***.***;",
"RequestId": "***************************************",
"MfaResult": null,
"BrowserId": null,
"SasStatus": null,
"TimeStamp": "2021-07-30T19****:****:****:***::****.5151425Z",
"EventType": "MCASLoginEvent",
"IpAddress": "***.***.***.***",
"UserName": "",
"TenantId": "***************************************",
"Call": "OAuth2:Token",
"Upn": "***@example.com"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "11161",
"instanceId": "***",
"tags": [
"*****",
"*****"
],
"objType": "23",
"name": "On-Premises Directory Synchronization Service Account",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Office 365",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "On-Premises Directory Synchronization Service Account",
"id": {
"id": "***************************************",
"saas": *****,
"inst": ***
},
"resolved": true
},
"1": null,
"2": {
"displayName": "On-Premises Directory Synchronization Service Account",
"id": {
"id": "***************************************",
"saas": *****,
"inst": ***
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_LOGIN",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
}
],
"hasNext": true,
"total": 5801
}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 $.data 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
[
{
"_id": "***************************************",
"tenantId": ***************************************,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627673425082,
"timestampRaw": 1627673425082,
"instantiation": 1627674001821,
"instantiationRaw": 1627674001821,
"created": 1627674001899,
"createdRaw": 1627674001899,
"eventType": 917504,
"eventTypeValue": "EVENT_ADALLOM_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "***.*** (***; ***; ***) AppleWebKit/*.* (KHTML, like Gecko) Chrome/*.*.*.* Safari/*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "CHROME",
"name": "Chrome",
"operatingSystem": {
"name": "Windows 10",
"version": "***************************************",
"family": "Windows"
},
"type": "Browser",
"typeName": "Browser",
"version": "***************************************",
"major": "92",
"minor": "0",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "CHROME"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": 0,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****"
],
"name": "sysint",
"instanceId": *****,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "login",
"prettyOperationName": "login",
"type": "login"
},
"confidenceLevel": 30,
"session": {
"sessionId": "***************************************"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"*****"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_LOGIN",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
},
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627672613515,
"timestampRaw": 1627672613515,
"instantiation": 1627672861987,
"instantiationRaw": 1627672861987,
"created": 1627676560986,
"createdRaw": 1627676560986,
"eventType": 2293760,
"eventTypeValue": "EVENT_AAD_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"lograbber": true,
"auditing": true,
"dispersed": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": ";Windows 8;Rich Client ***.***.***.***;",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****",
"*****"
]
},
"userAgent": {
"family": "UNKNOWN",
"name": "Unknown",
"operatingSystem": {
"name": "Windows",
"version": "***************************************",
"family": "Windows"
},
"type": "Unknown",
"typeName": "Unknown",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "UNKNOWN"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 6,
"role": 3,
"tags": [],
"name": "Microsoft Azure Active Directory Connect",
"id": "***************************************"
},
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Request ID",
"id": "***************************************"
},
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Pass-through authentication",
"value": "false"
},
{
"objType": 21,
"role": 4,
"tags": [],
"name": "On-Premises Directory Synchronization Service Account",
"instanceId": *****,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****",
"*****"
],
"name": "On-Premises Directory Synchronization Service Account",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "OAuth2:Token",
"prettyOperationName": "OAuth2:Token",
"type": "login"
},
"confidenceLevel": 30,
"source": 2,
"lograbberService": {
"scubaUnpacker": true
},
"srcAppId": 11161,
"collected": {
"aadLogins": {
"enqueueTime": 1627672848188,
"routingTime": 1627672848200,
"correlationId": "***************************************",
"MCAS_Router": false
}
},
"rawDataJson": {
"CorrelationId": "***************************************",
"IsDeviceCompliantAndManaged": false,
"UserTenantMsodsRegionScope": "NA",
"HomeTenantUserObjectId": "***************************************",
"MsodsTenantRegionScope": "NA",
"IsInteractiveComputed": true,
"UserPrincipalObjectID": "***************************************",
"MfaMaskedDeviceId": null,
"ApplicationId": "***************************************",
"ApplicationName": "Microsoft Azure Active Directory Connect",
"DeviceTrustType": "",
"LoginErrorCode": 0,
"UserIsPassthru": false,
"MfaAuthMethod": null,
"IsInteractive": null,
"MfaStatusRaw": null,
"UserTenantId": "***************************************",
"MfaRequired": false,
"LoginStatus": "Success",
"DataSource": null,
"DeviceInfo": ";Windows 8;Rich Client ***.***.***.***;",
"RequestId": "***************************************",
"MfaResult": null,
"BrowserId": null,
"SasStatus": null,
"TimeStamp": "2021-07-30T19****:****:****:***::****.*****",
"EventType": "MCASLoginEvent",
"IpAddress": "***.***.***.***",
"UserName": "",
"TenantId": "***************************************",
"Call": "OAuth2:Token",
"Upn": "***@example.com"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"*****",
"*****"
],
"objType": "23",
"name": "On-Premises Directory Synchronization Service Account",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Office 365",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "On-Premises Directory Synchronization Service Account",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "On-Premises Directory Synchronization Service Account",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "***************************************",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
}
]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
{
"AADTenantIDs": [
"***************************************",
"***************************************"
],
"AppNames": [
"Microsoft Teams",
"Office 365"
],
"Timestamps": [
1627660856991,
1627660724695
],
"EventTypeValues": [
"EVENT_AAD_LOGIN",
"EVENT_AAD_LOGIN"
],
"DeviceUserAgents": [
"***/*.* (***; ***; ***) AppleWebKit/*.* (KHTML, like Gecko) Chrome/***.***.***.*** Safari/*.*",
";Windows 8;Rich Client *.*.*.*;"
],
"LocationCountryCodes": [
"CA",
"CA"
],
"LocationCountryCities": [
"vancouver",
"vancouver"
],
"UserNames": [
"*****@example.com",
"*****@example.com"
],
"Severities": [
"INFO",
"INFO"
],
"Descriptions": [
"Log on",
"Log on"
]
}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
SuccessfulProvides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
_ID | TENANTID | AADTENANTID | APPID | SAASID | TIMESTAMP | TIMESTAMPRAW | INSTANTIATION | INSTANTIATIONRAW | CREATED | CREATEDRAW | EVENTTYPE | EVENTTYPEVALUE | EVENTROUTING | DEVICE | LOCATION | USER | USERAGENT | INTERNALS | MAININFO | CONFIDENCELEVEL | SESSION | RESOLVEDACTOR | UID | APPNAME | EVENTTYPENAME | CLASSIFICATIONS | ENTITYDATA | DESCRIPTION_ID | DESCRIPTION_METADATA | DESCRIPTION | GENERICEVENTTYPE | SEVERITY | SOURCE | LOGRABBERSERVICE | SRCAPPID | COLLECTED | RAWDATAJSON |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
*** | *** | *** | *** | *** | 1627673425082 | 1627673425082 | 1627674001821 | 1627674001821 | 1627674001899 | 1627674001899 | 917504 | EVENT_ADALLOM_LOGIN | { | { | { | { | { | { | { | 30 | { | { | *** | Microsoft Cloud App Security | EVENT_CATEGORY_LOGIN | [ | { | EVENT_DESCRIPTION_LOGIN | { | Log on | ENUM_ACTIVITY_GENERIC_TYPE_LOGIN | INFO |
|
|
|
|
|
*** | *** | *** | *** | *** | 1627672613515 | 1627672613515 | 1627672861987 | 1627672861987 | 1627676560986 | 1627676560986 | 2293760 | EVENT_AAD_LOGIN | { | { | { | { | { | { | { | 30 |
| { | *** | Office 365 | EVENT_CATEGORY_LOGIN | [ | { | EVENT_DESCRIPTION_LOGIN | { | Log on | ENUM_ACTIVITY_GENERIC_TYPE_LOGIN | INFO | 2 | { | *** | { | { |
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get IP Activities 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 Cloud Apps portal. Refer to the HTTP Status Code Registry for details. | Status Code: 443. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Max retries exceeded with url: /api/v1/entities. |
Error Sample Data Get IP Activities failed. Status Code: 443. Message: Max retries exceeded with url: /api/v1/entities. |
Get User Activities
Retrieves activities from Microsoft Defender for Cloud Apps related to the specified users.
Reader Note
The input parameter User Names is required to run this command.
Run the Get Users and Accounts command to obtain User Names. Set the Type parameter to Users, and in the returned raw data, refer to the path $.data.[*].email for the user emails (user names).
If the command runs successfully with no results, check that the input user names (emails) are valid.
Input
Input Parameter | Required /Optional | Description | Example |
User Names | Required | The email of the users to list related activities. | ["*****@example.com"] |
Last Days | Optional | The number of days before the current time to filter the returned list of user activities. | 30 |
Limit | Optional | The maximum number of results to return. The default value is 20. | 2 |
Output
The primary response data from the API request.
SAMPLE DATA
{
"data": [
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627673425082,
"timestampRaw": 1627673425082,
"instantiation": 1627674001821,
"instantiationRaw": 1627674001821,
"created": 1627674001899,
"createdRaw": 1627674001899,
"eventType": 917504,
"eventTypeValue": "EVENT_ADALLOM_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "Mozilla/*.* (***; ***; ***) AppleWebKit/*.* (KHTML, like Gecko) Chrome/*.*.*.* Safari/*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "CHROME",
"name": "Chrome",
"operatingSystem": {
"name": "Windows 10",
"version": "***************************************",
"family": "Windows"
},
"type": "Browser",
"typeName": "Browser",
"version": "***************************************",
"major": "92",
"minor": "0",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "CHROME"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": 0,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****"
],
"name": "sysint",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "login",
"prettyOperationName": "login",
"type": "login"
},
"confidenceLevel": 30,
"session": {
"sessionId": "***************************************"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"*****"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_LOGIN",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
},
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627671570750,
"timestampRaw": 1627671570750,
"instantiation": 1627674009881,
"instantiationRaw": 1627674009881,
"created": 1627674010167,
"createdRaw": 1627674010167,
"eventType": 917723,
"eventTypeValue": "EVENT_ADALLOM_ALERT_CLOSED_FALSE_POSITIVE_BULK",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true,
"adminEvent": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "***/*.*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "***",
"name": "***",
"operatingSystem": {
"name": "Unknown",
"family": "Unknown"
},
"type": "Library",
"typeName": "Library",
"version": "***************************************",
"major": "2",
"minor": "22",
"deviceType": "DESKTOP",
"nativeBrowser": true,
"tags": [
"000000000000000000000000"
],
"os": "OTHER",
"browser": "PYTHON_REQUESTS"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"tags": [
"*****"
],
"mainInfo": {
"eventObjects": [
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Resolution Status",
"value": "False Positive"
},
{
"objType": 7,
"role": 2,
"tags": [],
"name": "Alert Title",
"value": "Risky sign-in: Anonymous IP address"
},
{
"objType": 14,
"role": 3,
"tags": [],
"serviceObjectType": "Alert",
"id": "***************************************"
},
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": 0,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****"
],
"name": "sysint",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"rawOperationName": "Alert Closed",
"prettyOperationName": "Alert Closed",
"type": "basic"
},
"confidenceLevel": 20,
"session": {
"sessionId": "***************************************"
},
"adallom": {
"isLegacyAlertStatus": false,
"alertSeverityValue": 2,
"resolutionStatus": 3,
"alertTimestamp": 1626734418927,
"alertSeverity": 2,
"handledByUser": "***@example.com",
"operationTime": 1627671570722,
"alertMongoId": "60f5fff101c12d96b268bdf7",
"allowContact": false,
"contactEmail": "",
"sendFeedback": false,
"alertTypeId": *****,
"alertScore": "0",
"alertTitle": "Risky sign-in: Anonymous IP address",
"agentType": 3,
"alertBulk": false,
"alertDate": "2021-07-19T22****:****:****:***::****.927Z",
"alertUid": "***************************************",
"feedback": "",
"licenses": [
"AdallomForAATP",
"AdallomStandalone",
"AdallomForO365"
],
"alertActor": "***************************************",
"comment": "close_false_positive",
"bulkId": "***************************************",
"count": 6,
"title": "Risky sign-in: Anonymous IP address"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"***************************************"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_CLOSE_ALERT_FALSE_POSITIVE_-_BULK",
"classifications": [],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_BASIC_EVENT",
"description_metadata": {
"target_object": "property Alert Title Risky sign-in: Anonymous IP address",
"operation_name": "Alert Closed",
"colon": ": ",
"dash": ""
},
"description": "Alert Closed: property Alert Title Risky sign-in: Anonymous IP address",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_BASIC",
"severity": "INFO"
}
],
"hasNext": true,
"total": 4934
}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 $.data 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
[
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627673425082,
"timestampRaw": 1627673425082,
"instantiation": 1627674001821,
"instantiationRaw": 1627674001821,
"created": 1627674001899,
"createdRaw": 1627674001899,
"eventType": 917504,
"eventTypeValue": "EVENT_ADALLOM_LOGIN",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "***/*.* (***; ***; ***) AppleWebKit/*.*(KHTML, like Gecko) Chrome/*.*.*.* ***/*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "CHROME",
"name": "Chrome",
"operatingSystem": {
"name": "Windows 10",
"version": "***************************************",
"family": "Windows"
},
"type": "Browser",
"typeName": "Browser",
"version": "***************************************",
"major": "92",
"minor": "0",
"deviceType": "DESKTOP",
"nativeBrowser": false,
"os": "windows",
"browser": "CHROME"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"mainInfo": {
"eventObjects": [
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": ***,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"*****"
],
"name": "sysint",
"instanceId": *****,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"activityResult": {
"isSuccess": true
},
"rawOperationName": "login",
"prettyOperationName": "login",
"type": "login"
},
"confidenceLevel": 30,
"session": {
"sessionId": "***************************************"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"*****"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_LOGIN",
"classifications": [
"access"
],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_LOGIN",
"description_metadata": {
"event_category": "Log on",
"colon": "",
"dash": ""
},
"description": "Log on",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_LOGIN",
"severity": "INFO"
},
{
"_id": "***************************************",
"tenantId": *****,
"aadTenantId": "***************************************",
"appId": *****,
"saasId": *****,
"timestamp": 1627671570750,
"timestampRaw": 1627671570750,
"instantiation": 1627674009881,
"instantiationRaw": 1627674009881,
"created": 1627674010167,
"createdRaw": 1627674010167,
"eventType": 917723,
"eventTypeValue": "EVENT_ADALLOM_ALERT_CLOSED_FALSE_POSITIVE_BULK",
"eventRouting": {
"scubaUnpacker": false,
"auditing": true,
"adminEvent": true
},
"device": {
"clientIP": "***.***.***.***",
"userAgent": "***/*.*.*",
"countryCode": "CA"
},
"location": {
"countryCode": "CA",
"city": "vancouver",
"postalCode": "v6b 1v8",
"region": "british columbia",
"longitude": -123.11421,
"latitude": 49.28416,
"organizationSearchable": "skyway west",
"anonymousProxy": false,
"isSatelliteProvider": false,
"category": 0,
"categoryValue": "NONE",
"carrier": "skyway west"
},
"user": {
"userName": "***@example.com",
"userTags": [
"*****"
]
},
"userAgent": {
"family": "*****",
"name": "*****",
"operatingSystem": {
"name": "Unknown",
"family": "Unknown"
},
"type": "Library",
"typeName": "Library",
"version": "***************************************",
"major": "2",
"minor": "22",
"deviceType": "DESKTOP",
"nativeBrowser": true,
"tags": [
"*****"
],
"os": "*****",
"browser": "*****"
},
"internals": {
"otherIPs": [
"***.***.***.***"
]
},
"tags": [
"*****"
],
"mainInfo": {
"eventObjects": [
{
"objType": 7,
"role": 3,
"tags": [],
"name": "Resolution Status",
"value": "False Positive"
},
{
"objType": 7,
"role": 2,
"tags": [],
"name": "Alert Title",
"value": "Risky sign-in: Anonymous IP address"
},
{
"objType": 14,
"role": 3,
"tags": [],
"serviceObjectType": "Alert",
"id": "***************************************"
},
{
"objType": 21,
"role": 4,
"tags": [],
"name": "sysint",
"instanceId": *****,
"governable": false,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
},
{
"objType": 23,
"role": 4,
"tags": [
"607df40ff42627cad522a3ca"
],
"name": "sysint",
"instanceId": 0,
"governable": true,
"resolved": true,
"saasId": *****,
"link": *****,
"id": "***************************************"
}
],
"rawOperationName": "Alert Closed",
"prettyOperationName": "Alert Closed",
"type": "basic"
},
"confidenceLevel": 20,
"session": {
"sessionId": "***************************************"
},
"adallom": {
"isLegacyAlertStatus": false,
"alertSeverityValue": 2,
"resolutionStatus": 3,
"alertTimestamp": 1626734418927,
"alertSeverity": 2,
"handledByUser": "***@example.com",
"operationTime": 1627671570722,
"alertMongoId": "*****",
"allowContact": false,
"contactEmail": "",
"sendFeedback": false,
"alertTypeId": *****,
"alertScore": "0",
"alertTitle": "Risky sign-in: Anonymous IP address",
"agentType": 3,
"alertBulk": false,
"alertDate": "2021-07-19T22****:****:****:***::****.927Z",
"alertUid": "***************************************",
"feedback": "",
"licenses": [
"AdallomForAATP",
"AdallomStandalone",
"AdallomForO365"
],
"alertActor": "***************************************",
"comment": "close_false_positive",
"bulkId": "***************************************",
"count": 6,
"title": "Risky sign-in: Anonymous IP address"
},
"resolvedActor": {
"id": "***************************************",
"saasId": "*****",
"instanceId": "*****",
"tags": [
"*****"
],
"objType": "23",
"name": "sysint",
"role": "4",
"resolved": true,
"governable": true
},
"uid": "***************************************",
"appName": "Microsoft Cloud App Security",
"eventTypeName": "EVENT_CATEGORY_CLOSE_ALERT_FALSE_POSITIVE_-_BULK",
"classifications": [],
"entityData": {
"0": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
},
"1": null,
"2": {
"displayName": "sysint",
"id": {
"id": "***************************************",
"saas": *****,
"inst": *****
},
"resolved": true
}
},
"description_id": "EVENT_DESCRIPTION_BASIC_EVENT",
"description_metadata": {
"target_object": "property Alert Title Risky sign-in: Anonymous IP address",
"operation_name": "Alert Closed",
"colon": ": ",
"dash": ""
},
"description": "Alert Closed: property Alert Title Risky sign-in: Anonymous IP address",
"genericEventType": "ENUM_ACTIVITY_GENERIC_TYPE_BASIC",
"severity": "INFO"
}
]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
{
"AADTenantIDs": [
"***************************************",
"***************************************"
],
"AppNames": [
"Microsoft Teams",
"Microsoft Teams"
],
"Timestamps": [
1627660856991,
1627660666935
],
"EventTypeValues": [
"EVENT_AAD_LOGIN",
"EVENT_AAD_LOGIN"
],
"DeviceUserAgents": [
"***/*.* (***; ***; ***) AppleWebKit/*.*(KHTML, like Gecko) Chrome/*.*.*.* Safari/*.*",
"***/*.*.*"
],
"LocationCountryCodes": [
"CA",
"CA"
],
"LocationCountryCities": [
"vancouver",
"vancouver"
],
"UserNames": [
"*****@example.com",
"*****@example.com"
],
"Severities": [
"INFO",
"INFO"
],
"Descriptions": [
"Log on",
"Alert Closed: property Alert Title Risky sign-in: Anonymous IP address"
]
}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
SuccessfulProvides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
_ID | TENANTID | AADTENANTID | APPID | SAASID | TIMESTAMP | TIMESTAMPRAW | INSTANTIATION | INSTANTIATIONRAW | CREATED | CREATEDRAW | EVENTTYPE | EVENTTYPEVALUE | EVENTROUTING | DEVICE | LOCATION | USER | USERAGENT | INTERNALS | MAININFO | CONFIDENCELEVEL | SESSION | RESOLVEDACTOR | UID | APPNAME | EVENTTYPENAME | CLASSIFICATIONS | ENTITYDATA | DESCRIPTION_ID | DESCRIPTION_METADATA | DESCRIPTION | GENERICEVENTTYPE | SEVERITY | TAGS | ADALLOM |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
*** | *** | *** | *** | *** | 1627673425082 | 1627673425082 | 1627674001821 | 1627674001821 | 1627674001899 | 1627674001899 | 917504 | EVENT_ADALLOM_LOGIN | { | { | { | { | { | { | { | 30 | { | { | *** | Microsoft Cloud App Security | EVENT_CATEGORY_LOGIN | [ | { | EVENT_DESCRIPTION_LOGIN | { | Log on | ENUM_ACTIVITY_GENERIC_TYPE_LOGIN | INFO |
|
|
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get User Activities 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 Cloud Apps portal. Refer to the HTTP Status Code Registry 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: User Names Not Found. |
Error Sample Data Get User Activities failed. Status Code: 404. Message: User Names Not Found. |
Get Users And Accounts
Retrieves a list of users and/or accounts from Microsoft Defender for Cloud Apps based on the specified filters.
Input
Input Parameter | Required /Optional | Description | Example |
Type | Optional | The entity type to filter the returned results. The available types are Users, Accounts and User and Accounts. The default selection is User and Accounts. | UserandAccounts |
Statuses | Optional | The entity status to filter the returned results. The available statuses are N/A, Staged, Active, Suspended and Deleted. The default status is Active. | ["N/A","Staged","Active"] |
Is Admin | Optional | The option to filter entities that are admin-related. If set to Yes, only admin users will be returned; if set to No, all users will be returned. If this parameter is not defined, it will be removed from the request body. | No |
Is External | Optional | The option to filter entities that are external. If this parameter is not defined, it will be removed from the request body. | No |
Domains | Optional | The entities’ related domains to filter the returned results. If this parameter is not defined, it will be removed from the request body. | ["****************.com"] |
Limit | Optional | The maximum number of results to return. The default value is 20. | 2 |
Output
The primary response data from the API request.
SAMPLE DATA
{
"data": [
{
"type": 2,
"status": 2,
"displayName": "*****",
"id": "***************************************",
"_id": "***************************************",
"userGroups": [
{
"_id": "***************************************",
"id": "***************************************",
"name": "Office 365 administrator",
"description": "Company administrators, user account administrators, helpdesk administrators, service support administrators, and billing administrators",
"usersCount": 10,
"appId": *****
}
],
"identifiers": [],
"sid": null,
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"isAdmin": true,
"isExternal": false,
"email": "***@example.com",
"role": "Global Administrator",
"organization": null,
"domain": "https://*****.com/***",
"scoreTrends": null,
"subApps": [],
"threatScore": null,
"idType": 1,
"isFake": false,
"ii": "***************************************",
"actions": [
{
"task_name": "ConfirmUserCompromisedTask",
"display_title": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "InvalidateAllRefreshTokensForAUserTask",
"display_title": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "SuspendUserTask",
"display_title": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
],
"username": "{\"id\": \"***************************************\", \"saas\": *****, \"inst\": *****}",
"sctime": null,
"accounts": [
{
"_id": "***************************************",
"i": "***************************************",
"ii": "***************************************",
"inst": *****,
"saas": *****,
"t": *****,
"dn": "*****",
"ext": false,
"s": *****,
"aliases": [
"*****",
"***************************************",
"*****",
"***@example.com"
],
"isFake": true,
"pa": "***@example.com",
"em": null,
"sublst": [],
"p": "***************************************",
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"actions": [
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
]
}
],
"threatScoreHistory": []
},
{
"type": 2,
"status": 2,
"displayName": "*****",
"id": "***************************************",
"_id": "***************************************",
"userGroups": [
{
"_id": "***************************************",
"id": "***************************************",
"name": "Office 365 administrator",
"description": "Company administrators, user account administrators, helpdesk administrators, service support administrators, and billing administrators",
"usersCount": 10,
"appId": 11161
}
],
"identifiers": [],
"sid": null,
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"isAdmin": true,
"isExternal": false,
"email": "***@example.com",
"role": "Global Administrator",
"organization": null,
"domain": "https://*****.com/***",
"scoreTrends": {
"20210716": {
"event": {
"m365": 3
}
},
"20210717": {
"event": {
"m365": 3
}
},
"20210718": {
"event": {
"m365": 3
}
},
"20210719": {
"event": {
"m365": 3
}
},
"20210720": {
"event": {
"m365": 3
}
},
"20210721": {
"event": {
"m365": 3
}
},
"20210722": {
"event": {
"m365": 3
}
},
"20210723": {},
"20210724": {},
"20210725": {},
"20210726": {},
"20210727": {},
"20210728": {},
"20210729": {},
"20210730": {}
},
"subApps": [],
"threatScore": 0,
"idType": 1,
"isFake": false,
"ii": "***************************************",
"actions": [
{
"task_name": "ConfirmUserCompromisedTask",
"display_title": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "InvalidateAllRefreshTokensForAUserTask",
"display_title": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "SuspendUserTask",
"display_title": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
],
"username": "{\"id\": \"***************************************\", \"saas\": *****, \"inst\": *****}",
"sctime": 1627612203469,
"accounts": [
{
"_id": "***************************************",
"i": "***************************************",
"ii": "***************************************",
"inst": *****,
"saas": *****,
"t": *****,
"dn": "*****",
"ext": *****,
"s": *****,
"aliases": [
"***@example.com",
"***************************************",
"*****"
],
"isFake": true,
"pa": "***@example.com",
"em": "***@example.com",
"sublst": [
20893,
15600
],
"p": "***************************************",
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": 0*****
},
"actions": [
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
]
}
],
"threatScoreHistory": [
{
"dateFormatted": "20210730",
"dateUtc": 1627678806000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210729",
"dateUtc": 1627592406000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210728",
"dateUtc": 1627506006000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210727",
"dateUtc": 1627419606000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210726",
"dateUtc": 1627333206000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210725",
"dateUtc": 1627246806000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210724",
"dateUtc": 1627160406000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210723",
"dateUtc": 1627074006000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210722",
"dateUtc": 1626987606000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210721",
"dateUtc": 1626901206000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210720",
"dateUtc": 1626814806000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210719",
"dateUtc": 1626728406000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210718",
"dateUtc": 1626642006000,
"score": 3,
"percentile": 100,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210717",
"dateUtc": 1626555606000,
"score": 3,
"percentile": 0,
"breakdown": {
"event": {
"m365": 3
}
}
}
]
}
],
"hasNext": true,
"max": 100,
"total": 15,
"moreThanTotal": false
}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 $.data 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
[
{
"type": 2,
"status": 2,
"displayName": "*****",
"id": "***************************************",
"_id": "***************************************",
"userGroups": [
{
"_id": "***************************************",
"id": "***************************************",
"name": "Office 365 administrator",
"description": "Company administrators, user account administrators, helpdesk administrators, service support administrators, and billing administrators",
"usersCount": 10,
"appId": 11161
}
],
"identifiers": [],
"sid": null,
"appData": {
"appId": 11161,
"name": "Office 365",
"saas": 11161,
"instance": 0
},
"isAdmin": true,
"isExternal": false,
"email": "***@example.com",
"role": "Global Administrator",
"organization": null,
"domain": "https://*****.com/***",
"scoreTrends": null,
"subApps": [],
"threatScore": null,
"idType": 1,
"isFake": false,
"ii": "***************************************",
"actions": [
{
"task_name": "ConfirmUserCompromisedTask",
"display_title": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "InvalidateAllRefreshTokensForAUserTask",
"display_title": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "SuspendUserTask",
"display_title": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
],
"username": "{\"id\": \"***************************************\", \"saas\": *****, \"inst\": *****}",
"sctime": null,
"accounts": [
{
"_id": "***************************************",
"i": "***************************************",
"ii": "***************************************",
"inst": 0,
"saas": 11161,
"t": 1,
"dn": "Adrianna Chen",
"ext": false,
"s": 2,
"aliases": [
"*****",
"***************************************",
"*****",
"***@example.com"
],
"isFake": true,
"pa": "***@example.com",
"em": null,
"sublst": [],
"p": "***************************************",
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"actions": [
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
]
}
],
"threatScoreHistory": []
},
{
"type": 2,
"status": 2,
"displayName": "*****",
"id": "***************************************",
"_id": "***************************************",
"userGroups": [
{
"_id": "***************************************",
"id": "***************************************",
"name": "Office 365 administrator",
"description": "Company administrators, user account administrators, helpdesk administrators, service support administrators, and billing administrators",
"usersCount": 10,
"appId": *****
}
],
"identifiers": [],
"sid": null,
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"isAdmin": true,
"isExternal": false,
"email": "***@example.com",
"role": "Global Administrator",
"organization": null,
"domain": "https://*****.com/***",
"scoreTrends": {
"20210716": {
"event": {
"m365": 3
}
},
"20210717": {
"event": {
"m365": 3
}
},
"20210718": {
"event": {
"m365": 3
}
},
"20210719": {
"event": {
"m365": 3
}
},
"20210720": {
"event": {
"m365": 3
}
},
"20210721": {
"event": {
"m365": 3
}
},
"20210722": {
"event": {
"m365": 3
}
},
"20210723": {},
"20210724": {},
"20210725": {},
"20210726": {},
"20210727": {},
"20210728": {},
"20210729": {},
"20210730": {}
},
"subApps": [],
"threatScore": 0,
"idType": 1,
"isFake": false,
"ii": "***************************************",
"actions": [
{
"task_name": "ConfirmUserCompromisedTask",
"display_title": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_CONFIRM_USER_COMPROMISED_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "InvalidateAllRefreshTokensForAUserTask",
"display_title": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_INVALIDATE_ALL_REFRESH_TOKENS_FOR_A_USER_DISPLAY_ALERT_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "SuspendUserTask",
"display_title": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_TITLE",
"type": "user",
"governance_type": null,
"bulk_support": null,
"has_icon": true,
"display_description": {
"template": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_DESCRIPTION_O365",
"parameters": {
"user": "***@example.com"
}
},
"bulk_display_description": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_BULK_DISPLAY_DESCRIPTION_O365",
"preview_only": false,
"display_alert_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_TEXT",
"display_alert_success_text": "TASKS_ADALIBPY_SUSPEND_USER_SUSPENSION_DISPLAY_ALERT_SUCCESS_TEXT",
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
},
{
"task_name": "UserSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
],
"username": "{\"id\": \"***************************************\", \"saas\": *****, \"inst\": *****}",
"sctime": 1627612203469,
"accounts": [
{
"_id": "***************************************",
"i": "***************************************",
"ii": "***************************************",
"inst": *****,
"saas": *****,
"t": *****,
"dn": "*****",
"ext": false,
"s": 2,
"aliases": [
"***@example.com",
"***************************************",
"*****"
],
"isFake": true,
"pa": "***@example.com",
"em": "***@example.com",
"sublst": [
20893,
15600
],
"p": "***************************************",
"appData": {
"appId": *****,
"name": "*****",
"saas": *****,
"instance": *****
},
"actions": [
{
"task_name": "UserAADSettingsLink",
"display_title": "TASKS_ADALIBPY_USER_AAD_SETTINGS_LINK_DISPLAY_TITLE",
"type": "user",
"governance_type": "link",
"bulk_support": null,
"has_icon": true,
"display_description": "https://*****.com/***",
"bulk_display_description": null,
"preview_only": false,
"display_alert_text": null,
"display_alert_success_text": null,
"is_blocking": null,
"confirm_button_style": "red",
"optional_notify": null,
"uiGovernanceCategory": null,
"alert_display_title": null,
"confirmation_button_text": null,
"confirmation_link": null
}
]
}
],
"threatScoreHistory": [
{
"dateFormatted": "20210730",
"dateUtc": 1627678806000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210729",
"dateUtc": 1627592406000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210728",
"dateUtc": 1627506006000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210727",
"dateUtc": 1627419606000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210726",
"dateUtc": 1627333206000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210725",
"dateUtc": 1627246806000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210724",
"dateUtc": 1627160406000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210723",
"dateUtc": 1627074006000,
"score": 0,
"percentile": 0,
"breakdown": {}
},
{
"dateFormatted": "20210722",
"dateUtc": 1626987606000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210721",
"dateUtc": 1626901206000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210720",
"dateUtc": 1626814806000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210719",
"dateUtc": 1626728406000,
"score": 3,
"percentile": 66,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210718",
"dateUtc": 1626642006000,
"score": 3,
"percentile": 100,
"breakdown": {
"event": {
"m365": 3
}
}
},
{
"dateFormatted": "20210717",
"dateUtc": 1626555606000,
"score": 3,
"percentile": 0,
"breakdown": {
"event": {
"m365": 3
}
}
}
]
}
]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
{
"Types": [
2,
2
],
"Statuses": [
2,
2
],
"DisplayNames": [
"*****",
"*****"
],
"IDs": [
"***************************************",
"***************************************"
],
"AppIDs": [
*****,
*****
],
"AppNames": [
"Office 365",
"Office 365"
],
"IsAdmins": [
true,
true
],
"IsExternals": [
false,
false
],
"EmailAddresses": [
"*****@***.com",
"*****@***.com"
],
"Roles": [
"Global Administrator",
"Global Administrator"
],
"Domains": [
"*****.com",
"*****.com"
],
"ThreatScores": [
0
],
"IsFakes": [
false,
false
],
"Sctimes": [
1627612203469
]
}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
SuccessfulProvides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
TYPE | STATUS | DISPLAYNAME | ID | _ID | USERGROUPS | IDENTIFIERS | SID | APPDATA | ISADMIN | ISEXTERNAL | ROLE | ORGANIZATION | DOMAIN | SCORETRENDS | SUBAPPS | THREATSCORE | IDTYPE | ISFAKE | II | ACTIONS | USERNAME | SCTIME | ACCOUNTS | THREATSCOREHISTORY | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2 | 2 | *** | *** | *** | [ | [] | { | True | False | Global Administrator | ***.com | [] | 1 | False | *** | [ | {"id": "***", "saas": ***, "inst": ***} | [ | [] |
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Users And Accounts 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 Cloud Apps portal. Refer to the HTTP Status Code Registry 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: Invalid Statuses. |
Error Sample Data Get Users And Accounts failed. Status Code: 400. Message: Invalid Statuses. |
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
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.
SAMPLE DATA
SuccessfulError Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the responses from the 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. | Test Connection failed. Failed to check the connector. |
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 Cloud Apps portal. Refer to the HTTP Status Code Registry for details. | Status Code: 443. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Max retries exceeded with url: /api/v***/***. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 443. Message: Max retries exceeded with url: /api/v1/entities. |