Exabeam

LAST UPDATED: 03/12/2024

Overview

Exabeam is a User and Entity Behavior Analytics (UEBA) solution that uses innovative analytics technology, such as machine learning and deep learning, to detect threats and anomalies on a corporate network. The analytics platform allows security analysts access to the most relevant threat intelligence and other contextual data and help them prioritize remediation tasks.

D3's integration with the Exabeam Advanced Analytics latest REST API to provide the ability to ingest events, manage users and retrieve assets.

D3 SOAR is providing REST operations to function with Exabeam.

Exabeam is available for use in:

D3 SOAR	V15.0.31.0+
Category	SIEM
Deployment Options	Option II, Option IV

Connection

To connect to Exabeam from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Default
Server URL	The server URL of the Exabeam environment.	https://******.exabeam.com
Authentication Type	The authentication method for the connection. Note: If you select Basic Authentication (Username & Password), the Username and Password parameters are required.	Cluster Authentication Token (API Token)
Cluster Authentication Token (API Token)
API Token	The API token for authentication. Note: The Cluster Authentication Token is available to generate from Exabeam Advanced Analytics version i52 and higher.	********
Basic Authentication (Username & Password)
Username	The Exabeam username for basic authentication.	a*****g
Password	The Exabeam password for basic authentication.	********

READER NOTE

Exabeam no longer supports API authentication via basic authentication (using username and password). D3 SOAR still retains the basic authentication option for on-premise users that may still use it. Please use the Cluster Authentication Token authentication type to build any new integration connections with Exabeam. For more information, see Exambeam's notice regarding their API support.

Configuring Exabeam to Work with D3 SOAR

An Exabeam Cluster Authentication Token (API token) is required to build an integration connection in D3 SOAR. See Exabeam Cluster Authentication Token from Exabeam’s documentation for instructions on generating the API token.

Configuring D3 SOAR to Work with Exabeam

Log in to D3 SOAR.
Find the Exabeam integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Exabeam in the search box to find the integration, then click it to select it.
4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Exabeam.
1. Connection Name: The desired name for the connection.
2. 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.
3. 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.
4. 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.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your Server URL.
  2. Choose your Authentication Type to Cluster Authentication Token (API). Select Cluster Authentication Token (API Token) for Authentication Type.

READER NOTE

Exabeam no longer supports API authentication via basic authentication (using username and password). D3 SOAR still retains the basic authentication option for on-premise users that may still use it. Please use the Cluster Authentication Token authentication type to build any new integration connections with Exabeam. For more information, see Exambeam's notice regarding their API support.

3. Input your saved API Token. See Configuring Exabeam to Work with D3 SOAR.

i. 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.

j. 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.

4. Test the connection.

a. 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.

b. Click OK to close the alert window.

c. Click + Add to create and add the configured connection.

Commands

Exabeam 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 Exabeam API, please refer to the Exabeam 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.

Fetch Event

Retrieves events or alerts based on the specified search condition, such as filtering by users or assets. Users are sorted by $.riskScore, in descending order; assets are sorted by $.highestRiskScore, in descending order.

READER NOTE

The input parameter Notable Object Names is optional to run this command.
- The Notable Object Names can be Username (notable object type is undefined or Users) or Assets (notable object type is Assets)
  - Run the List Users command to obtain Usernames. Usernames can be found in the returned raw data at the path $.users[*].username.
  - Run the List Notable Assets command to obtain Assets. Both hostnames and IPs are valid inputs. Hostnames can be found in the returned raw data at the path $.assets[*].asset.hostName. IPs can be found in the returned raw data at the path $.assets[*].asset.ipAddress.
- If you define the Notable Object Names parameter, any input value for the Notable Objects Limit parameter will be ignored.
If only the Start Time and End Time parameters are defined, user notable summary events will be returned.
The Notable Object Names and Notable Objects Limit parameters are defined by the Notable Object Type parameter. For example, if the Notable Object Type is User, the input Notable Object Names should be usernames and the Notable Objects Limit will limit the number of returned users. Refer to the table below for a summary of the different input combinations and the expected output.

Field mappings:
- Alerts will use the default field mapping.
- Events will use the exabeamEvent field mapping.
- Assets will use the exabeamAsset field mapping.
- Users will use the exabeamUser field mapping.
If you are fetching events or alerts and the Notable Object Names or Notable Objects Limit input parameters are not defined, all results within the specified time range will be returned. However, if you define one of those parameters, you may not see the number of expected results being returned due to one or more of the following reasons:
- The Notable Objects Limit parameter limits the number of users or assets returned, not events or alerts.
- Users or assets not meeting the time filter are also counted toward the defined limit value.
- The Start Time and End Time parameters filter the returned users or assets, and if the associated sequences do not match the time filter, they may not be returned.
If you are fetching users, the defined value for the Notable Object Names or Notable Objects Limit parameters may not return the expected number of results. Users are filtered by the defined Start Time and End Time parameters, then by the $.highestRiskSession time filter. If the $.highestRiskSession start time and end time values do not match the defined time filter, the users will not be returned. Users not meeting the time filter are also counted toward the defined limit value.
If you are fetching assets, the defined value for the Notable Object Names or Notable Objects Limit parameters may not return the expected number of results. Assets are filtered by the defined Start Time and End Time parameters, then by the $.highestRiskSession time filter. If the $.highestRiskSession start time and end time values do not match the defined time filter, the assets will not be returned. Assets not meeting the time filter are also counted toward the defined limit value.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to fetch users, events, alerts or assets in UTC time.	2022-04-01 00:00
End Time	Required	The end time of the time range to fetch users, events, alerts or assets in UTC time.	2022-04-02 00:00
Notable Object Names	Optional	The list of usernames or hostnames for fetching events of the given notable objects. When the parameter has value, the Max Notable Objects will be ignored. Note: If you are fetching for users, alerts, and events, this parameter will search for users; if you are fetching for assets, this parameter will search for hostnames.	[ "s**e", "s***2" ]
Notable Objects Limit	Optional	The maximum number of notable objects to fetch events from. Values up to 10,000 are valid. If this parameter is not defined, all objects will be returned. Note: If you are fetching for users, alerts, and events, this parameter will search for users; if you are fetching for assets, this parameter will search for hostnames.	20
Notable Object Type	Optional	The notable object type (i.e. Users or Assets) to retrieve events. The default value is Users.	Users
Event Type	Optional	The event type (i.e., Notable Summary, Events, or Alerts) to return. The default value is Notable Summary.	False
Tolerance Scope (Hours)	Optional	The tolerance scope in hours for query to get events between start and end time to avoid events loss. The event will be fetched between {Start Time - Tolerance Scope, End Time}.	12

Output

Raw Data

The primary response data from the API request.

D3 SOAR combines event, alert, user and asset raw data as a single piece of output raw data for this command.

SAMPLE DATA

CODE

[
    {
        "_Id": "632a****************d695",
        "ruleId": "ALERT-EXEC",
        "ruleType": "session",
        "eventId": "************",
        "sessionId": "********************",
        "lockoutId": "",
        "sequenceId": "",
        "username": "*****",
        "eType": "security-alert",
        "triggeringTime": 1663740588822,
        "riskScore": 7.94,
        "anchorScore": 10,
        "anomalyFactor": 0.79,
        "ruleData": {
            "featureValue": "true",
            "scopeValue": "NA",
            "modelName": "NA",
            "totalEvents": 0,
            "numBins": 0,
            "numObservations": 0,
            "probability": 0,
            "percentileThresholdValue": "NA",
            "percentileThresholdCount": 0,
            "confidenceFactor": 0,
            "distanceCountPercentile": 0,
            "distanceValuePercentile": 0,
            "histogramId": "NA"
        },
        "createdTime": 1663740615219,
        "scoreData": {
            "bayesAnchorScoreData": {
                "weight": 0.7949693593904597
            },
            "ruleDefScore": 10
        },
        "triggerReason": "Security violation by Executive: *****"
    },
    {
        "getvalue('country_code', src_ip)": "CH",
        "source": "Microsoft Office 365",
        "session_id": "*************-**************",
        "rawlog_time": 1658137055000,
        "host": "s********t",
        "src_ip": "*.*.*.**",
        "session_order": 3681,
        "user_email": "*******@**********.com",
        "object": "t:",
        "getvalue('zone_info', src)": "zscaler node",
        "account_status": "Account is active",
        "resource": "PublicEndpoint",
        "event_subtype": "Microsoft Office 365",
        "event_type": "app-activity",
        "src_network_type": "LAN",
        "app": "Office 365",
        "account": "*************",
        "time": 1658138049138,
        "activity": "SensitivityLabeledFileRenamed",
        "event_id": "*************",
        "user": "*************",
        "isEvent": true
    },
    {
        "asset": {
            "hostName": "ma******07",
            "ipAddress": "**.**.***.**",
            "assetType": "Windows",
            "firstSeen": 1655397350095,
            "lastSeen": 1666186083657
        },
        "highestRiskScore": 475,
        "highestRiskSequence": {
            "id": "asset@**********-********",
            "entityName": "*****",
            "entityValue": "**********",
            "day": 1665964800000,
            "triggeredRuleCountOpt": 98,
            "riskScoreOpt": 475
        },
        "incidentIds": [],
        "notable": "asset"
    },
    {
        "user": {
            "username": "***_**_*****",
            "riskScore": 540.41,
            "averageRiskScore": 240.26,
            "pastScores": [
                504.5577117884548,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ],
            "lastSessionId": "***_**_*****-**************",
            "firstSeen": 1652787643891,
            "lastSeen": 1666357363629,
            "lastActivityType": "Account is active",
            "accessStatus": "Account is active",
            "lastActivityTime": 1666303326032,
            "info": {
                "email": "******@*******.com",
                "fullName": "***_**_*****",
                "dn": "cn=***_**_*****,ou=applications,ou=microsoft,ou=service accounts,ou=administrative area,dc=pc,dc=pc,dc=local",
                "group": "data-apps-default",
                "sid": "s-*-*-**-********-**********-*********-*****"
            },
            "labels": [
                "service_account"
            ],
            "pendingRiskTransfers": []
        },
        "userFullName": "***_**_*****",
        "isExecutive": false,
        "highestRiskScore": 505,
        "highestRiskSession": {
            "sessionId": "***_**_*****-**************",
            "username": "***_**_*****",
            "startTime": 1666303326032,
            "endTime": 1666357363629,
            "initialRiskScore": 0,
            "riskScore": 505,
            "numOfReasons": 50,
            "loginHost": "*************",
            "label": "",
            "accounts": [
                "***_**_*****"
            ],
            "numOfAccounts": 1,
            "zones": [
                "***** **** ** *******"
            ],
            "numOfZones": 1,
            "numOfAssets": 54,
            "numOfEvents": 1094,
            "numOfSecurityEvents": 0,
            "riskTransferScore": 26.520000000000003
        },
        "notableSessionIds": [
            "***_**_*****-**************"
        ],
        "incidentIds": [],
        "notable": "user"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "EventIDs": 
      "44*****73@m",
      "44*****25@m",
      "as***@**********-******17",
      "s***********-************06"
}

Return Data

Indicates one of the possible command execution states: Successful, Successful with No Event Data, or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Start Time (UTC)	2022-04-01 20:00
End Time (UTC)	2022-04-01 20:30
EventsCount	2

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.

The Exabeam integration in D3 SOAR has some pre-configured field mappings for the Alerts, Events, Assets and Users, which correspond to the Default Event Source, exabeamEvent, exabeamAsset and exabeamUser mappings:

Default Event Source
Configures the field mapping which are specific to the alert-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. The default event source has a “Main Event JSON Path” (i.e., $) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”. Click Edit Event Source to view the “Main Event JSON Path”.
- Main Event JSON Path: $
  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 $. The child node denoting the Unique Event Key field would be eventId. Putting it together, the JSON Path expression to extract the Unique Event Key is $.eventId.
exabeamEvent

Configures the field mapping which is specific to the event-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the events have a character that the value of the isEvent field is True, the events can be defined by the Search String: {$.isEvent}=True. Click Edit Event Source to view the Search String.

exabeamAsset

Configures the field mapping which is specific to the asset-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the events have a character that the value of the notable field is True, the events can be defined by the Search String: {$.notable}=asset. Click Edit Event Source to view the Search String.

exabeamUser

Configures the field mapping which is specific to the user-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the events have a character that the value of the notable field is True, the events can be defined by the Search String: {$.notable}=user. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $)
Unique Event Key	.eventId
Event Type	.eType
Start Time	.createdTime
Username	.username
Risk Score	.riskScore
Session ID	.sessionId
Description	.triggerReason
exabeamEvent (Search String: {$.isEvent}=True) The search string format is {jsonpath}=value. If the value of the isEvent key is True in the event object under raw data, then the event-related events will use the field mapping below.
Unique Event Key	.event_id
Event Type	.event_type
Start Time	.time
Username	.user
Source IP address	.src_ip
Hostname	.host
Source	.source
Session ID	.session_id
Destination hostname	.dest_host
Description	.event_subtype
exabeamAsset (Search String: {$.notable}=asset) The search string format is {jsonpath}=value. If the value of the notable key is asset in the event object under raw data, then the asset-related events will use the field mapping below.
Unique Event Key	highestRiskSequence.id
Event Type	.notable
Start Time	.asset.lastSeen
Hostname	.asset.hostName
Source IP address	.asset.ipAddress
Risk Score	.highestRiskScore
Entity Name	.highestRiskSequence.entityName
Entity Value	.highestRiskSequence.entityValue
Description	*Please refer to the link for the details. https://<Exabeam serverUrl Replace_me>/uba/#{__Entity_Name}/{__Entity_Value}/timeline/{EventKey}
exabeamUser (Search String: {$.notable}=user) The search string format is {jsonpath}=value. If the value of the notable key is user in the event object under raw data, then the user-related events will use the field mapping below.
Unique Event Key	.highestRiskSession.sessionId
Event Type	.notable
Start Time	.highestRiskSession.startTime
Hostname	.highestRiskSession.loginHost
Username	.highestRiskSession.usemame
Risk Score	.highestRiskScore
Entity Name	.notable
Description	*Please refer to the link for the details. https://<Exabeam serverUrl Replace_me>/uba/#{__Entity_Name}/{Username}/timeline/{EventKey}

READER NOTE

*In D3 SOAR, the events from Exabeam will be predefined with “Please refer to the link for the details. https://<Exabeam serverUrl Replace_me>/uba/#{__Entity_Name}/{__Entity_Value}/timeline/{EventKey}” as the Description.

The source type for Event Type is defined as Placeholder. “Please refer to the link for the details. https://<Exabeam serverUrl Replace_me>/uba/#{__Entity_Name}/{__Entity_Value}/timeline/{EventKey}” is a default mapping value provided by D3.
Modify this field mapping, otherwise, the placeholder value will be returned in the description.
See Source Field Type from Event and Incident Intake Field Mapping for more details on event field mapping field types.

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 Exabeam portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_AUTHENTICATED.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: NOT_AUTHENTICATED.

List Asset Data

Retrieves asset details matching the specified criteria by hostname or IP address.

READER NOTE

Input parameter Assets is required to run this command.

Run the List Notable Assets command to obtain Assets. Both hostnames and IPs are valid inputs. Hostnames can be found in the returned raw data at the path $.assets[*].asset.hostName. IPs can be found in the returned raw data at the path $.assets[*].asset.ipAddress.
If you input a hostname and an IP address of an asset, the asset will be listed twice in the output data. However, if you input the same hostname or IP address twice, the asset will only be listed once in the output data.
Invalid assets (hostnames and IPs) will be ignored.

Input

Input Parameter	Required/Optional	Description	Example
Assets	Required	A list of the hostname or IP address to retrieve corresponding asset details. Assets can be obtained using the List Notable Assets command.	[ "172...", "l*******9" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

[
    {
        "asset": {
            "hostName": "h****1",
            "ipAddress": "1.*.*.*",
            "assetGroup": "Asset Group VDI PCs",
            "assetType": "Windows",
            "firstSeen": 165**********,
            "lastSeen": 165**********
        },
        "labels": [
            "Workstation",
            "LdifFile"
        ],
        "commentCount": 0
    },
    {
        "asset": {
            "hostName": "h****2",
            "assetType": "Windows",
            "firstSeen": 165**********,
            "lastSeen": 166**********
        },
        "labels": [
            "Workstation",
            "LdifFile"
        ],
        "topUsers": {
            "key": "A****_****_****_*****S#h***2#t#NA",
            "modelName": "A****_****_****_*****S",
            "groupingFeatureValue": "xyz",
            "histSpan": "t",
            "histogramDate": "NA",
            "histClassName": "CategoricalHist",
            "confidenceFactor": 0,
            "totalBinCount": 1,
            "totalCount": 1,
            "lastUpdate": 166**********,
            "hist": {},
            "usersInBinList": {
                "millerd": {
                    "username": "s*****2",
                    "fullName": "S*****2 D********y",
                    "photo": "",
                    "title": "p******** ******* *******r",
                    "riskScore": 0.33
                }
            },
            "peerGroupsInBinList": {},
            "disabled": false
        },
        "topGroups": {
            "key": "A****_****_*****_*******Y#h***3#t#NA",
            "modelName": "A****_****_*****_*******Y",
            "groupingFeatureValue": "xyz",
            "histSpan": "t",
            "histogramDate": "NA",
            "histClassName": "CategoricalHist",
            "confidenceFactor": 0,
            "totalBinCount": 3,
            "totalCount": 3,
            "lastUpdate": 166**********,
            "hist": {
                "binList": [
                    [
                        "_other",
                        2
                    ]
                ],
                "minX": "data-project-lon-itprod-it admin-projects-webscale-modify",
                "maxX": "_other",
                "minY": 1,
                "maxY": 2,
                "histogramType": "CATEGORICAL",
                "topTalkers": []
            },
            "usersInBinList": {},
            "peerGroupsInBinList": {
                "_other": {
                    "name": "_*****",
                    "memberCount": 0,
                    "groupType": "",
                    "isMultiPeerGroup": true
                },
                "data-project-lon-itprod-it admin-projects-webscale-modify": {
                    "name": "xyz-modify",
                    "memberCount": 7,
                    "groupType": "Group",
                    "isMultiPeerGroup": true
                }
            },
            "disabled": false
        },
        "commentCount": 0
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "HostNames": "h***1, h***2", 
    "IPAddresses": "1.*.*.*", ""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

AssetCount

2

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.	List Asset Data 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 Exabeam 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: The value for parameter (Assets) is invalid.

Error Sample Data

List Asset Data failed.

Status Code: 400.

Message: The value for parameter (Assets) is invalid.

List Notable Assets

Retrieves notable assets matching the specified time duration.

READER NOTE

The Time Duration Unit and Time Duration parameters are used to set the search time range. The time range will be {Current Time} - {Current time-your input time}. The default search time range will be an hour before the current time.

Input

Input Parameter	Required/Optional	Description	Example
Time Duration Unit	Optional	The time unit of the specified time duration. The valid time duration units are Hours, Days, Months and Years. The default value is Hours.	Hours
Time Duration	Optional	The time duration value. If the input value is 0, a negative number, or not defined, a default value of 1 will be used.	2
Limit	Optional	The maximum number of results to return on each page. The maximum limit value is 10,000. The default value is 20.	20

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "assets": [
        {
            "asset": {
                "hostName": "h***1",
                "assetType": "Windows",
                "firstSeen": 165**********,
                "lastSeen": 166**********
            },
            "highestRiskScore": 257,
            "highestRiskSequence": {
                "id": "asset@h***1-********",
                "entityName": "a***t",
                "entityValue": "h***3",
                "day": 166**********,
                "triggeredRuleCountOpt": 61,
                "riskScoreOpt": 257
            },
            "incidentIds": []
        },
        {
            "asset": {
                "hostName": "h***2",
                "ipAddress": "10.***.***.***",
                "assetType": "Windows",
                "firstSeen": 165**********,
                "lastSeen": 166**********
            },
            "highestRiskScore": 139,
            "highestRiskSequence": {
                "id": "a***t@******-********",
                "entityName": "a***t",
                "entityValue": "h****1",
                "day": 166**********,
                "triggeredRuleCountOpt": 35,
                "riskScoreOpt": 139
            },
            "incidentIds": []
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "HostNames": "h***1, h***2", 
    "IPAddresses": "", "1.*.*.**"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

AssetCount

2

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.	List Notable Assets 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 Exabeam portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_AUTHENTICATED.

Error Sample Data

List Notable Assets failed.

Status Code: 403.

Message: NOT_AUTHENTICATED.

List Sessions By User

Returns sessions from the specified user.

READER NOTE

Input parameter Usernames is required to run this command.

Run the List Users command to obtain Usernames. Usernames can be found in the returned raw data at the path $.users[*].username.
If the input username does not exist, the command will run successfully with no returned results.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to retrieve user sessions in UTC time.	2022-04-01 00:00
End Time	Required	The end time of the time range to retrieve user sessions in UTC time.	2022-04-03 00:00
Username	Required	The username to retrieve sessions from. Usernames can be obtained using the List Users command.	s*****1

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "assets": [
        {
            "asset": {
                "hostName": "h***1",
                "assetType": "Windows",
                "firstSeen": 165**********,
                "lastSeen": 166**********
            },
            "highestRiskScore": 257,
            "highestRiskSequence": {
                "id": "a***t@h***1-********",
                "entityName": "a***t",
                "entityValue": "h***3",
                "day": 166**********,
                "triggeredRuleCountOpt": 61,
                "riskScoreOpt": 257
            },
            "incidentIds": []
        },
        {
            "asset": {
                "hostName": "h***2",
                "ipAddress": "10.***.***.***",
                "assetType": "Windows",
                "firstSeen": 165**********,
                "lastSeen": 166**********
            },
            "highestRiskScore": 139,
            "highestRiskSequence": {
                "id": "a***t@******-********",
                "entityName": "a***t",
                "entityValue": "h****1",
                "day": 166**********,
                "triggeredRuleCountOpt": 35,
                "riskScoreOpt": 139
            },
            "incidentIds": []
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "HostNames": "h***1, h***2", 
    "IPAddresses": "", "*.*.*.**"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

AssetCount

2

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.	List Sessions By User failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Exabeam portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_AUTHENTICATED.

Error Sample Data

List Sessions By User failed.

Status Code: 401.

Message: NOT_AUTHENTICATED.

List Users

Returns users matching the specified criteria.

READER NOTE

If no input parameters are defined, up to ten users will be returned with no user photos.
If the Include User Photo command is set to True, the users’ corresponding user photos (if existing) will be returned in the raw data
The Username accepts full usernames and keyword inputs. Usernames matching any input keywords will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Username	Optional	The full usernames or keywords to filter returned users.	a***l
Limit	Optional	The maximum number of results to return on each page. The maximum limit value is 10,000. The default value is 10.	20
Include User Photo	Optional	Specifies if user photos will be returned with the corresponding list of users. The default value is False.	True

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "users": [
        {
            "username": "s*****1",
            "riskScore": 96.02,
            "averageRiskScore": 45.72,
            "pastScores": [
                96.0283181177369,
                0,
                0
            ],
            "lastSessionId": "s*****1-**************",
            "firstSeen": 165**********,
            "lastSeen": 166**********,
            "lastActivityType": "Account is active",
            "lastActivityTime": 166**********,
            "info": {
                "location": "Johannesburg",
                "photo": "/9j/4A==",
                "email": "s*****1.********@**.********",
                "fullName": "S*****1 ********",
                "dn": "cn=s*****1 ********,ou=d3southafrica,ou=d3group,ou=d3 users,dc=d3i,dc=d3,dc=local",
                "country": "South Africa",
                "department": "marketing",
                "manager": "cn=sample manager,ou=d3southafrica,ou=d3group,ou=d3 users,dc=d3i,dc=d3,dc=local",
                "phoneOffice": "2*****",
                "title": "*** *********",
                "group": "rg-***-******-*********-users",
                "sid": "*-*-*-**-********-**********-*********-******"
            },
            "labels": [],
            "pendingRiskTransfers": []
        },
        {
            "username": "s*****2",
            "riskScore": 83.28,
            "averageRiskScore": 39.66,
            "pastScores": [
                83.28988513838559,
                0,
                0
            ],
            "lastSessionId": "s*****2-**************",
            "firstSeen": 165**********,
            "lastSeen": 166**********,
            "lastActivityType": "Account is active",
            "lastActivityTime": 166**********,
            "info": {
                "location": "Johannesburg",
                "photo": "/9j/4A==",
                "email": "s*****2.********@**.********",
                "fullName": "S*****2 ********",
                "dn": "cn=s*****2 ********,ou=d3southafrica,ou=d3group,ou=d3 users,dc=d3i,dc=d3,dc=local",
                "country": "South Africa",
                "department": "*********",
                "manager": "cn=sample3 Manager,ou=d3southafrica,ou=d3group,ou=d3 users,dc=d3i,dc=d3,dc=local",
                "phoneOffice": "270206",
                "title": "design & production lead",
                "group": "rg-***-******-*********-users",
                "sid": "*-*-*-**-********-**********-********-******"
            },
            "labels": [],
            "pendingRiskTransfers": []
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Usernames": "s*****1, s*****2" 
    "FullNames": "s*****1 ********, S*****2 ********"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

UserCount

2

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.	List Users failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Exabeam portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_AUTHENTICATED.

Error Sample Data

List Users failed.

Status Code: 401.

Message: NOT_AUTHENTICATED.

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

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

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.	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 Exabeam portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NOT_AUTHENTICATED.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 401.

Message: NOT_AUTHENTICATED.