ESET Protect Cloud

LAST UPDATED: 08/02/2024

Overview

ESET PROTECT CLOUD enables you to manage ESET products on workstations and servers in a networked environment from one central location without the requirement to have a physical or virtual server like for ESET PROTECT or ESET Security Management Center. This integration enables you to manage ESET endpoints, including retrieving endpoint information, policy assignment, taking actions on endpoints etc.

D3 SOAR is providing REST operations to function with ESET Protect Cloud.

ESET Protect Cloud is available for use in:

D3 SOAR	V16.8+
Category	SIEM & XDR
Deployment Options	Option II, Option IV

Known Limitations

All ESET Connect APIs are rate-limited. Please refer to Rate limits | ESET Connect for detailed information.

Connection

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

Parameter	Description	Example
Region	The region of the ESET Protect Cloud instance.	US
Username	The user name you created in your ESET Business Account (or ESET MSP Administrator).	test@example.com
Password	The password of the user you created in your ESET Business Account (or ESET MSP Administrator).	PASSWORD

Permission Requirements

Each endpoint in the ESET Protect Cloud API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Access Right (ESET PROTECT Cloud & ESET Inspect Cloud access)
Add Endpoints To Task	Write
Assign Policy To Endpoints	Write
Delete Policy Assignments	Write
Fetch Event	Read
Get Device Group Endpoints	Read
Get Endpoint Details	Read
Isolate Endpoints	Write
List Device Groups	Read
List Device Tasks	Read
List Policies	Read
List Policy Assignments	Read
List Task History	Read
On-Demand Scan	Write
Run Command	Write
Shutdown or Reboots Endpoints	Write
Stop Managing Endpoints	Write
Uninstall Third Party AV Software	Write
Unisolate Endpoints	Write
Update Operating System	Write
Update Task Trigger	Write
Test Connection	Read

As ESET Protect Cloud is using role-based access control (RBAC), the D3 connector will be generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the ESET Protect Cloud console for each command in this integration.

Configuring ESET Protect Cloud to Work with D3 SOAR

Only Root or Superuser can create a user with access to API endpoints. Please ensure you have these accounts to log in and create limited-access accounts for this integration.

Please refer to Create API User account | ESET Connect to create accounts.

Configuring D3 SOAR to Work with ESET Protect Cloud

Log in to D3 SOAR.
Find the ESET Protect Cloud integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type ESET Protect Cloud in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to ESET Protect Cloud.
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. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Choose your Region.
  2. Input your Username.
  3. Input your Password.
10. 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.
11. 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.
1. 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.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

ESET Protect Cloud 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 ESET Protect Cloud API, please refer to the ESET Protect Cloud API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring ESET Protect Cloud to Work with D3 SOAR for details.

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.

Add Endpoints To Task

Adds the specified endpoint target(s) to the task.

READER NOTE

Task UUID is a required parameter to run this command.

Run the List Device Tasks command to obtain Task UUIDs. Task UUIDs can be found in the raw data at the path $.tasks[*].uuid.

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task UUID	Required	The UUID of the task to which endpoint target(s) will be added. Task UUID can be obtained using the List Device Tasks command.	******
Device UUIDs	Optional	The UUID(s) of the device(s) that will be added to the task targets. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will be added to the task targets. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "targets": {
            "deviceGroupsUuids": [
                "******"
            ],
            "devicesUuids": [
                "******"
            ]
        },
        "displayName": "***",
        "uuid": "******",
        "versionId": "*****",
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-02-18T02:05:04Z"
                }
            }
        ],
        "description": "Execute ASAP",
        "action": {
            "name": "RunCommand",
            "params": {
                "currentDirectory": "d:\\data",
                "commandLine": "mkdir tmp",
                "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand"
            }
        }
    }
}

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

{
    "TaskName": "***",
    "TargetDeviceUUIDs": [
        "******"
    ],
    "TargetDeviceGroupUUIDs": [
        "******"
    ]
}

Result

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

SAMPLE DATA

task

{'targets': {'deviceGroupsUuids': ['******'], 'devicesUuids': ['******']}, 'displayName': '******', 'uuid': '******', 'versionId': '*****', 'triggers': [{'manual': {'expireTime': '2024-02-18T02:05:04Z'}}], 'description': 'Execute ASAP', 'action': {'name': 'RunCommand', 'params': {'currentDirectory': 'd:\\data', 'commandLine': 'mkdir tmp', '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand'}}}

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.	Add Endpoints To Task 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Add Endpoints To Task failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Assign Policy To Endpoints

Assigns the policy to the specified device(s) and/or device group(s). Assignments to the same targets are ordered and prioritized, with each new assignment added to the end of the stack. The assignment ranking corresponds to the number of assignments for the target, where ranking 1 is the highest priority, and policies are merged from rank 1 to lower ranks.

READER NOTE

Policy UUID is a required parameter to run this command.

Run the List Policies command to obtain Policy UUIDs. Policy UUIDs can be found in the raw data at the path $.policies[*].uuid.

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Policy UUID	Required	The UUID of the policy to be assigned. Policy UUID can be obtained using the List Policies command.	[ "******" ]
Device UUIDs	Optional	The UUID(s) of the device(s) to which the policy will be assigned. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) to which the policy will be assigned. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Results": [
        {
            "assignment": {
                "target": {
                    "deviceGroupUuid": "******"
                },
                "policyUuid": "******",
                "uuid": "******",
                "rank": 1
            }
        },
        {
            "assignment": {
                "policyUuid": "******",
                "target": {
                    "deviceUuid": "******"
                },
                "uuid": "******",
                "rank": 3
            }
        }
    ]
}

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

{
      "PolicyAssignmentUUIDs": [
          "******",
          "******"
      ],
      "PolicyUUIDs": [
          "******",
          "******"
      ],
      "TargetUUIDs": [
          "******",
          "******"
      ],
      "Ranks": [
          1,
          3
      ]
}

Result

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

SAMPLE DATA

Results

{'assignment': {'target': {'deviceGroupUuid': '******'}, 'policyUuid': '******', 'uuid': '******', 'rank': 1}}
{'assignment': {'policyUuid': '******', 'target': {'deviceUuid': '******'}, 'uuid': '******', 'rank': 3}}

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.	Assign Policy To Endpoints 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Assign Policy To Endpoints failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Delete Policy Assignments

Deletes the specified policy assignment(s). Remaining assignments to the target are reordered.

READER NOTE

The parameter Policy Assignment UUIDs is required to run this command.

Run the List Policy Assignments command to obtain Policy Assignment UUIDs. Policy Assignment UUIDs can be found in the raw data at the path $.assignments[*].policyUuid.

Input

Input Parameter	Required/Optional	Description	Example
Policy Assignment UUIDs	Required	The UUID(s) of the policy assignment(s) to be deleted from the target(s). Policy Assignment UUIDs can be obtained using the List Policy Assignments command.	[ "******" ]

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Results": [
        {
            "PolicyAssignmentUUID": "******",
            "Message": "Policy Assignment is deleted successfully."
        }
    ]
}

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

{
    "PolicyAssignmentUUIDs": [
        "******"
    ]
}

Result

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

SAMPLE DATA

Results

{'PolicyAssignmentUUID': '******', 'Message': 'Policy Assignment is deleted successfully.'}

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.	Delete Policy Assignments 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 ESET Protect Cloud 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: Policy Assignment UUID: <sampleUUID> does not exist.

Error Sample Data

Delete Policy Assignments failed.

Status Code: 400.

Message: Policy Assignment UUID: <sampleUUID> does not exist.

Fetch Event

Ingests detection(s) from the ESET Protect Cloud platform based on specified criteria.

READER NOTE

Device UUID is an optional parameter to run this command.

Run the Get Device Group Endpoints command to obtain the Device UUID. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The Start Time of the time range for fetching detection(s), in UTC time. Only incidents whose detections occurred at or after this time will be returned.	2024-01-18 00:00
End Time	Required	The End Time of the time range for fetching detection(s), in UTC time. Only incidents whose detections occurred at or before this time will be returned.	2024-01-19 00:00
Number of Event(s) Fetched	Optional	The maximum number of detections to return. The valid value is an integer between 0 and 1000. If not specified, the default value is 100. To ingest all detections matching other criteria, input 0.	20
Device UUID	Optional	The detection(s) that occurred on the specified Device will be returned. Device UUID can be obtained using the Get Device Group Endpoints command.	******

Output

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "detections": [
        {
            "category": "DETECTION_CATEGORY_UNSPECIFIED",
            "context": {
                "circumstances": "string",
                "device_uuid": "string",
                "process": {
                    "path": "string"
                },
                "user_name": "string"
            },
            "display_name": "string",
            "network_communication": {
                "direction": "NETWORK_COMMUNICATION_DIRECTION_UNSPECIFIED",
                "local_ip_address": "string",
                "local_port": 0,
                "protocol_name": "string",
                "remote_ip_address": "string",
                "remote_port": 0
            },
            "object_hash_sha1": "string",
            "object_name": "string",
            "object_type_name": "string",
            "object_url": "string",
            "occur_time": "2024-01-18T20:03:10.273Z",
            "responses": [
                {
                    "description": "string",
                    "device_restart_required": true,
                    "display_name": "string",
                    "protection_name": "string"
                }
            ],
            "severity_level": "SEVERITY_LEVEL_UNSPECIFIED",
            "type_name": "string",
            "uuid": "string"
        }
    ],
    "next_page_token": "string",
    "total_size": 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

{
      "DetectionIDs": [
          "string"
      ],
      "DetectionNames": [
          "string"
      ]
}

Result

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

SAMPLE DATA

detections	{'category': 'DETECTION_CATEGORY_UNSPECIFIED', 'context': {'circumstances': 'string', 'device_uuid': 'string', 'process': {'path': 'string'}, 'user_name': 'string'}, 'display_name': 'string', 'network_communication': {'direction': 'NETWORK_COMMUNICATION_DIRECTION_UNSPECIFIED', 'local_ip_address': 'string', 'local_port': 0, 'protocol_name': 'string', 'remote_ip_address': 'string', 'remote_port': 0}, 'object_hash_sha1': 'string', 'object_name': 'string', 'object_type_name': 'string', 'object_url': 'string', 'occur_time': '2024-01-18T20:03:10.273Z', 'responses': [{'description': 'string', 'device_restart_required': True, 'display_name': 'string', 'protection_name': 'string'}], 'severity_level': 'SEVERITY_LEVEL_UNSPECIFIED', 'type_name': 'string', 'uuid': 'string'}
next_page_token	string
total_size	0

Fetch Event Field Mapping

Fetch Event commands require event field mapping. Field mapping plays a key role for data normalization within the event pipeline. Field mapping converts the original data fields from the different providers to standardized D3 fields as defined by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

To customize field mapping, click + Add Field and add the custom field of your choice. You can 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 ESET Protect Cloud 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 detections. The default event source has a “Main Event JSON Path” (i.e., $.detections) 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: $.detections

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 detections. The child node denoting the Unique Event Key field would be uuid. Putting it together, the JSON Path expression to extract the Unique Event Key is $.detections.uuid.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Unique Event Key	.uuid
Start Time	.occurTime
Event category	.category
Description	.responses.description
Event name	.displayName
Device UUID	.context.deviceUuid
Process file path	.context.process.path
Username	.context.userName
Network Direction	.networkCommunication.direction
Local IP Address	.networkCommunication.localIpAddress
Local Port	.networkCommunication.localPort
Remote IP Address	.networkCommunication.remoteIpAddress
Remote port	.networkCommunication.remotePort
Protocol info	.networkCommunication.protocolName
Object Type	.objectTypeName
Object Name	.objectName
Object Hash SHA1	.objectHashSha1
Object URL	.objectUrl
Response Description	.responses.description
Response Name	.responses.displayName
Protection Name	.responses.protectionName
Severity	.severityLevel
Event Type	.typeName

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 ESET Protect Cloud 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: Bad Request.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Bad Request.

Get Device Group Endpoints

Returns a list of devices within the specified device group(s) or their subgroups.

READER NOTE

The parameter Device Group UUIDs is required to run this command.

Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Device Group UUIDs	Required	The UUID(s) of the device groups for which members are to be listed. Device Group UUIDs can be obtained using the List Device Groups command. To retrieve all devices, you can enter the Device Group UUID for the group with the display name 'All'.	[ "******" ]

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Results": [
        {
            "GroupUuid": "******",
            "nextPageToken": "",
            "devices": [
                {
                    "groupUuid": "******",
                    "uuid": "******",
                    "displayName": "******"
                }
            ],
            "totalSize": 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

{
      "DeviceGroupUUIDs": [
          "******"
      ],
      "DeviceNames": [
          "******"
      ],
      "DeviceUUIDs": [
          "******"
      ]
}

Result

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

SAMPLE DATA

Results

{'GroupUuid': '******', 'nextPageToken': '', 'devices': [{'groupUuid': '******', 'uuid': '******', 'displayName': '******'}], 'totalSize': 0}

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 Device Group Endpoints 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 ESET Protect Cloud 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: Request failed for Device Group UUID: <sampleID>.

Error Sample Data

Get Device Group Endpoints failed.

Status Code: 400.

Message: Request failed for Device Group UUID: <sampleID>.

Get Endpoint Details

Retrieves the details of the specified device(s).

READER NOTE

The parameter Device UUIDs is required to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Device UUIDs	Required	The UUID(s) of the device(s) for which to retrieve details. Device UUIDs can be obtained using the Get Device Group Endpoints command.	[ "******" ]

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "devices": [
        {
            "displayName": "******",
            "tags": [
                ""
            ],
            "deviceToken": "",
            "uuid": "******",
            "operatingSystem": {
                "displayName": "Microsoft Windows 10 Pro",
                "bitness": 0,
                "version": {
                    "major": 0,
                    "id": "0",
                    "patch": 0,
                    "name": "******",
                    "minor": 0
                }
            },
            "managementDomain": "",
            "deployedComponents": [
                {
                    "displayName": "ESET Management Agent",
                    "id": 0,
                    "name": "",
                    "version": {
                        "major": 0,
                        "id": "0",
                        "patch": 0,
                        "name": "******",
                        "minor": 0
                    }
                },
                {
                    "displayName": "ESET Endpoint Security",
                    "id": 0,
                    "name": "",
                    "version": {
                        "major": 0,
                        "id": "0",
                        "patch": 0,
                        "name": "******",
                        "minor": 0
                    }
                }
            ],
            "lastSyncTime": "2024-01-16T16:55:50Z",
            "description": "",
            "hardwareProfiles": [
                {
                    "salt": "",
                    "resettableIdentifier": "",
                    "bios": {
                        "serialNumber": "******",
                        "uuid": "",
                        "manufacturer": "VMware, Inc."
                    },
                    "manufacturer": "No Enclosure",
                    "processors": [],
                    "networkAdapters": [
                        {
                            "macAddress": "******",
                            "caption": "Intel(R) 82574L Gigabit Network Connection"
                        }
                    ],
                    "hardDrives": [
                        {
                            "serialNumber": ""
                        },
                        {
                            "serialNumber": ""
                        }
                    ],
                    "model": "System Enclosure"
                }
            ]
        }
    ]
}

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

{
      "DeviceNames": [
          "******"
      ],
      "DeviceUUIDs": [
          "******"
      ],
      "OperatingSystems": [
          "Microsoft Windows 10 Pro"
      ]
}

Result

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

SAMPLE DATA

devices

{'displayName': '*****', 'tags': [''], 'deviceToken': '', 'uuid': '*****', 'operatingSystem': {'displayName': 'Microsoft Windows 10 Pro', 'bitness': 0, 'version': {'major': 0, 'id': '0', 'patch': 0, 'name': '*****', 'minor': 0}}, 'managementDomain': '', 'deployedComponents': [{'displayName': 'ESET Management Agent', 'id': 0, 'name': '', 'version': {'major': 0, 'id': '0', 'patch': 0, 'name': '*****', 'minor': 0}}, {'displayName': 'ESET Endpoint Security', 'id': 0, 'name': '', 'version': {'major': 0, 'id': '0', 'patch': 0, 'name': '*****', 'minor': 0}}], 'lastSyncTime': '2024-01-16T16:55:50Z', 'description': '', 'hardwareProfiles': [{'salt': '', 'resettableIdentifier': '', 'bios': {'serialNumber': 'VMware-42 37******', 'uuid': '', 'manufacturer': 'VMware, Inc.'}, 'manufacturer': 'No Enclosure', 'processors': [], 'networkAdapters': [{'macAddress': '******', 'caption': 'Intel(R) 82574L Gigabit Network Connection'}], 'hardDrives': [{'serialNumber': ''}, {'serialNumber': ''}], 'model': 'System Enclosure'}]}

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 Endpoint Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the ESET Protect Cloud 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: Bad Request.

Error Sample Data

Get Endpoint Details failed.

Status Code: 400.

Message: Bad Request.

Isolate Endpoints

Isolates the specified target(s) from the network. CreateTask uses a deduplication algorithm to prevent the creation of tasks with the same configuration but different triggers.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the isolation task.	Isolate from network - via API3
Task Description	Required	The description of the isolation task. The maximum length is 1000 characters.	Execute ASAP Pls
Device UUIDs	Optional	The UUID(s) of device(s) to isolate. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will be isolated. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time of the isolation task. The isolation task will not be triggered after this time. If not specified, the default expiration time is 6 months from the current time.	2024-02-21 00:00

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "displayName": "******",
        "versionId": "545",
        "uuid": "******",
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-02-01T23:59:59Z"
                }
            }
        ],
        "action": {
            "name": "StartNetworkIsolation"
        },
        "description": "Execute ASAP Pls",
        "targets": {
            "devicesUuids": [
                "******"
            ],
            "deviceGroupsUuids": [
                "******"
            ]
        }
    }
}

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

{
      "TaskName": "Isolate from network - via API3",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task	{'displayName': '****', 'versionId': '545', 'uuid': '**', 'triggers': [{'manual': {'expireTime': '2024-02-01T23:59:59Z'}}], 'action': {'name': 'StartNetworkIsolation'}, 'description': 'Execute ASAP Pls', 'targets': {'devicesUuids': ['**'], 'deviceGroupsUuids': ['****']}}

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.	Isolate Endpoints 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Isolate Endpoints failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

List Device Groups

Returns all the device groups.

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "nextPageToken": "***",
    "totalSize": 0,
    "deviceGroups": [
        {
            "displayName": "All",
            "parentGroupUuid": "***",
            "linkedEntityType": "DEVICE_GROUP_ENTITY_TYPE_UNSPECIFIED",
            "uuid": "***",
            "isSecurityGroup": true
        }
    ]
}

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

{
      "DeviceGroupNames": [
          "All"
      ],
      "DeviceGroupUUIDs": [
          "***"
      ],
      "ParentGroupUUIDs": [
          "***"
      ]
}

Result

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

SAMPLE DATA

nextPageToken	******
totalSize	0
deviceGroups	{'displayName': 'All', 'parentGroupUuid': '*', 'linkedEntityType': 'DEVICE_GROUP_ENTITY_TYPE_UNSPECIFIED', 'uuid': '*', 'isSecurityGroup': True}

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 Device Groups 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 ESET Protect Cloud 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: Errors in Test Connection function.

Error Sample Data

List Device Groups failed.

Status Code: 400.

Message: Errors in Test Connection function.

List Device Tasks

Returns all device tasks.

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "tasks": [
        {
            "uuid": "******",
            "displayName": "Reboot Computer - via context menu",
            "targets": {
                "devicesUuids": [
                    "******"
                ],
                "deviceGroupsUuids": []
            },
            "versionId": "***",
            "action": {
                "params": {
                    "actions": {
                        "postpone": "Cannot",
                        "cancelAction": false
                    },
                    "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer",
                    "restart": true
                },
                "name": "ShutdownComputer"
            },
            "triggers": [
                {
                    "manual": {
                        "expireTime": "2024-02-17T01:22:03Z"
                    }
                }
            ],
            "description": "Execute ASAP"
        }
    ],
    "nextPageToken": "******",
    "totalSize": 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

{
      "TaskNames": [
          "Reboot Computer - via context menu"
      ],
      "TaskUUIDs": [
          "******"
      ],
      "ActionNames": [
          "ShutdownComputer"
      ],
      "Descriptions": [
          "Execute ASAP"
      ]
}

Result

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

SAMPLE DATA

tasks	{'uuid': '****', 'displayName': 'Reboot Computer - via context menu', 'targets': {'devicesUuids': ['**'], 'deviceGroupsUuids': []}, 'versionId': '*', 'action': {'params': {'actions': {'postpone': 'Cannot', 'cancelAction': False}, '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer', 'restart': True}, 'name': 'ShutdownComputer'}, 'triggers': [{'manual': {'expireTime': '2024-02-17T01:22:03Z'}}], 'description': 'Execute ASAP'}
nextPageToken	******
totalSize	0

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 Device Tasks 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 ESET Protect Cloud 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: Errors in Test Connection function.

Error Sample Data

List Device Tasks failed.

Status Code: 400.

Message: Errors in Test Connection function.

List Policies

Returns all the policies accessible to caller.

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "nextPageToken": "******",
    "totalSize": 0,
    "policies": [
        {
            "uuid": "******",
            "features": [
                {
                    "configuration": {
                        "product": "eset.local.products.endpoint_mac",
                        "@type": "type.googleapis.com/Era.Common.DataDefinition.Policy.PolicyData",
                        "data": "******",
                        "compressed": false
                    },
                    "featureId": ******,
                    "flags": {}
                }
            ],
            "builtIn": false,
            "displayName": "Antivirus - Balanced",
            "description": "ESET Security Product for macOS & Linux uses the security configuration recommended for most setups."
        }
    ]
}

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

{
      "PolicyNames": [
          "Antivirus - Balanced"
      ],
      "PolicyUUIDs": [
          "******"
      ],
      "Descriptions": [
          "ESET Security Product for macOS & Linux uses the security configuration recommended for most setups."
      ]
}

Result

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

SAMPLE DATA

nextPageToken	******
totalSize	0
policies	{'uuid': '****', 'features': [{'configuration': {'product': 'eset.local.products.endpoint_mac', '@type': 'type.googleapis.com/Era.Common.DataDefinition.Policy.PolicyData', 'data': '**', 'compressed': False}, 'featureId': ****, 'flags': {}}], 'builtIn': False, 'displayName': 'Antivirus - Balanced', 'description': 'ESET Security Product for macOS & Linux uses the security configuration recommended for most setups.'}

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 Policies 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 ESET Protect Cloud 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: Errors in Test Connection function.

Error Sample Data

List Policies failed.

Status Code: 400.

Message: Errors in Test Connection function.

List Policy Assignments

Returns all the policy assignments accessible to the caller.

READER NOTE

Policy UUID, Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the List Policies command to obtain the Policy UUID. Policy UUIDs can be found in the raw data at the path $.policies[*].uuid.
Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Policy UUID	Optional	The Policy UUID to filter the policy assignments. If specified, only assignments for the given policy will be returned. Policy UUID can be obtained using the List Policies command.	******
Device UUIDs	Optional	The Device UUIDs to filter the policy assignments. If specified, only assignments assigned to the specific device(s) will be returned. Device UUIDs can be obtained using the Get Device Group Endpoints command.	[ "******" ]
Device Group UUIDs	Optional	The Device Group UUIDs to filter the policy assignments. If specified, only assignments assigned to the specific device group(s) will be returned. Device Group UUIDs can be obtained using the List Device Groups command.	[ "******" ]

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "totalSize": 0,
    "nextPageToken": "",
    "assignments": [
        {
            "rank": 3,
            "policyUuid": "******",
            "target": {
                "deviceUuid": "******"
            },
            "uuid": "******"
        },
        {
            "rank": 1,
            "policyUuid": "******",
            "target": {
                "deviceGroupUuid": "******"
            },
            "uuid": "******"
        }
    ]
}

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

{
      "PolicyUUIDs": [
          "******",
          "******"
      ],
      "TargetUUIDs": [
          "******",
          "******"
      ],
      "PolicyAssignmentUUIDs": [
          "******",
          "******"
      ]
}

Result

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

SAMPLE DATA

totalSize	0
nextPageToken
assignments	{'rank': 3, 'policyUuid': '****', 'target': {'deviceUuid': '**'}, 'uuid': '**'} {'rank': 1, 'policyUuid': '**', 'target': {'deviceGroupUuid': '**'}, 'uuid': '****'}

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 Policy Assignments 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 ESET Protect Cloud 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: Bad Request.

Error Sample Data

List Policy Assignments failed.

Status Code: 400.

Message: Bad Request.

List Task History

Returns the task history, including all runs of the task.

READER NOTE

The parameter Task UUIDs is required to run this command.

Run the List Device Tasks command to obtain Task UUIDs. Task UUIDs can be found in the raw data at the path $.tasks[*].uuid.

Device UUID is an optional parameter to run this command.

Run the Get Device Group Endpoints command to obtain the Device UUID. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Task UUIDs	Required	The UUID(s) of the task(s) to get task history. Task UUIDs can be obtained using the List Device Tasks command.	[ "******" ]
Device UUID	Optional	The Device UUID filters the tasks. If specified, only task runs for the specific device will be returned. Device UUID can be obtained using the Get Device Group Endpoints command.	******
Last Runs	Optional	The option to return results that only contain the latest runs per device. If not specified, all task runs will be returned.	True

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Results": [
        {
            "nextPageToken": "",
            "taskRuns": [
                {
                    "uuid": "******",
                    "endTime": "2024-01-17T01:22:09Z",
                    "status": "TASK_RUN_STATUS_FINISHED",
                    "deviceUuid": "******",
                    "taskUuid": "******",
                    "startTime": "2024-01-17T01:22:09Z"
                }
            ],
            "totalSize": 0
        }
    ]
}

Result

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

SAMPLE DATA

Results

{'nextPageToken': '', 'taskRuns': [{'uuid': '******', 'endTime': '2024-01-17T01:22:09Z', 'status': 'TASK_RUN_STATUS_FINISHED', 'deviceUuid': '******', 'taskUuid': '******', 'startTime': '2024-01-17T01:22:09Z'}], 'totalSize': 0}

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.	List Task History 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 ESET Protect Cloud 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: Request failed for Task UUID: <sampleID>.

Error Sample Data

List Task History failed.

Status Code: 400.

Message: Request failed for Task UUID: <sampleID>.

On-Demand Scan

Scans the specified target(s) on-demand. CreateTask uses a deduplication algorithm to prevent the creation of tasks with the same configuration but different triggers.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the on-demand scan task.	ondemand scan API a33
Task Description	Required	The description of the on-demand scan task. The maximum length is 1000 characters.	Execute ASAP 20240117 a33
Device UUIDs	Optional	The UUID(s) of the device(s) for the on-demand scan. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will undergo an on-demand scan. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time of the on-demand scan task. The on-demand scan task will not be triggered after this time. If not specified, the default expiration time is 6 months from the current time.	2024-03-31 00:00
Shutdown Enabled	Optional	The option to shut down the computer(s) after the scan. If not specified, the default value is False.	True
Shutdown Locked	Optional	The option to lock the shutdown to prevent the user from canceling it. If set to False, the user can cancel the shutdown. If not specified, the default value is False. This parameter is valid only when the Shutdown Enabled parameter is set to True.	True
Postpone	Optional	The allowed shutdown postpone time. If not specified, the default value is Can Not Postpone. This parameter is valid only when the Shutdown Enabled parameter is set to True.	One Day
Cancel Action	Optional	The option for the user to be able to cancel the action. If not specified, the default value is False.	True
Cleaning Enabled	Optional	The option to enable the Scan with Cleaning feature. If not specified, the default value is True.	True
Scan Profile	Optional	The scan profile to be used during the scan. If not specified, the default scan profile is In-Depth. The available options are In-Depth, Smart, Context Menu, My Profile, and Custom. Please note that if you choose Custom, the Custom Profile Name must also be specified.	Smart
Custom Profile Name	Optional	The custom profile name for the custom scan profile. Please note that if you choose the Custom option for the Scan Profile parameter, this parameter must be specified. You must define a custom profile in the client configuration before it can be applied.	CustomScanProfile1
Scan Targets	Optional	The list of scan targets. If not specified, a full scan will be implemented.	eset://AllTargets

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-03-31T00:00:00Z"
                }
            }
        ],
        "uuid": "******",
        "targets": {
            "devicesUuids": [
                "******"
            ],
            "deviceGroupsUuids": [
                "******"
            ]
        },
        "displayName": "ondemand scan API a33",
        "versionId": "***",
        "action": {
            "params": {
                "powerActions": {
                    "postpone": "OneDay",
                    "cancelAction": true
                },
                "cleaningEnabled": true,
                "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.ESS.OnDemandScan",
                "shutdownEnabled": true,
                "scanTargets": [
                    "eset://AllTargets"
                ],
                "scanProfile": "Smart",
                "shutdownLocked": true,
                "customProfileName": ""
            },
            "name": "OnDemandScan"
        },
        "description": "Execute ASAP 20240117 a33"
    }
}

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

{
      "TaskName": "ondemand scan API a33",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'triggers': [{'manual': {'expireTime': '2024-03-31T00:00:00Z'}}], 'uuid': '******', 'targets': {'devicesUuids': ['******'], 'deviceGroupsUuids': ['******']}, 'displayName': 'ondemand scan API a33', 'versionId': '***', 'action': {'params': {'powerActions': {'postpone': 'OneDay', 'cancelAction': True}, 'cleaningEnabled': True, '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.ESS.OnDemandScan', 'shutdownEnabled': True, 'scanTargets': ['eset://AllTargets'], 'scanProfile': 'Smart', 'shutdownLocked': True, 'customProfileName': ''}, 'name': 'OnDemandScan'}, 'description': 'Execute ASAP 20240117 a33'}

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.	On-Demand Scan 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

On-Demand Scan failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Run Command

Executes a command on the specified target endpoint(s).

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the run command task.	Run Command API r4
Task Description	Required	The description of the run command task. The maximum length is 1000 characters.	Run Command ASAP
Device UUIDs	Optional	The UUID(s) of the device(s) on which to run the command. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will run the command. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) of the run command task. The run command task will not be triggered after this time. If not specified, the default expiration time is 6 months from the current time.	2024-01-30 00:00
Command Line	Required	The command line you want to run on the specified target endpoint(s).	dir
Current Directory	Optional	The directory in which the command line will be executed.	C:\temp

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "targets": {
            "deviceGroupsUuids": [
                "******"
            ],
            "devicesUuids": [
                "******"
            ]
        },
        "uuid": "******",
        "versionId": "***",
        "displayName": "Run Command API r4",
        "action": {
            "name": "RunCommand",
            "params": {
                "commandLine": "dir",
                "currentDirectory": "c:\\temp",
                "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand"
            }
        },
        "description": "Run Command ASAP",
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-01-20T00:00:00Z"
                }
            }
        ]
    }
}

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

{
      "TaskName": "Run Command API r4",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'targets': {'deviceGroupsUuids': ['******'], ‘devicesUuids': ['******’]}, 'uuid': '******', 'versionId': '***', 'displayName': 'Run Command API r4', 'action': {'name': 'RunCommand', 'params': {'commandLine': 'dir', 'currentDirectory': 'c:\\temp', '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand'}}, 'description': 'Run Command ASAP', 'triggers': [{'manual': {'expireTime': '2024-01-20T00:00:00Z'}}]}

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.	Run Command 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Run Command failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Shutdown or Reboots Endpoints

Shuts down or reboots the specified targets.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the shutdown/reboot task.	Reboot Computer - api a1
Task Description	Required	The description of the shutdown/reboot task. The maximum length is 1000 characters.	Reboot Computer ASAP
Device UUIDs	Optional	The UUID(s) of the device(s) to shut down or reboot. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will be shut down or rebooted. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) of the shutdown/reboot task. The shutdown/reboot task will not be triggered after this time. If not specified, the default expiration time is 6 months from the current time.	2024-03-31 00:00
Restart	Required	The option indicating whether the target computer(s) will reboot. If set to False, the target computer(s) will shut down.	True
Postpone	Optional	The allowed postpone time for shutdown/reboot. If not specified, the default value is Can Not Postpone.	Three Hours
Cancel Action	Optional	The option allowing the user to cancel the action. If not specified, the default value is False.	True

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "displayName": "Reboot Computer - api a1",
        "action": {
            "name": "ShutdownComputer",
            "params": {
                "actions": {
                    "cancelAction": true,
                    "postpone": "ThreeHours"
                },
                "restart": true,
                "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer"
            }
        },
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-02-17T00:00:00Z"
                }
            }
        ],
        "uuid": "******",
        "versionId": "***",
        "description": "Reboot Computer ASAP",
        "targets": {
            "devicesUuids": [
                "******"
            ],
            "deviceGroupsUuids": [
                "******"
            ]
        }
    }
}

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

{
      "TaskName": "Reboot Computer - api a1",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

ask

{'displayName': 'Reboot Computer - api a1', 'action': {'name': 'ShutdownComputer', 'params': {'actions': {'cancelAction': True, 'postpone': 'ThreeHours'}, 'restart': True, '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer'}}, 'triggers': [{'manual': {'expireTime': '2024-02-17T00:00:00Z'}}], 'uuid': '******', 'versionId': '***', 'description': 'Reboot Computer ASAP', 'targets': {'devicesUuids': ['******'], 'deviceGroupsUuids': ['******']}}

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.	Shutdown or Reboots Endpoints 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Shutdown or Reboots Endpoints failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Stop Managing Endpoints

Stops managing the specified targets, which means uninstalling the ESET Management Agent. Run this task with caution. After the device is no longer managed (i.e., the agent is removed), some settings may remain locked in the managed products. To unlock settings in the managed products, remove all policies from the computer and its groups before executing this task.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the stop managing task.	stop management API s2
Task Description	Required	The description of the stop managing task. The maximum length is 1000 characters.	Stop Management Endpoints 20240117.
Device UUIDs	Optional	The UUID(s) of the device(s) to stop managing. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) whose endpoints will be stopped from being managed. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) of the stop managing task. This task will not be triggered after the specified time. If not specified, the default expiration time is 6 months from the current time.	2024-03-31 00:00

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-03-31T00:00:00Z"
                }
            }
        ],
        "versionId": "***",
        "targets": {
            "deviceGroupsUuids": [
                "******"
            ],
            "devicesUuids": [
                "******"
            ]
        },
        "uuid": "******",
        "description": "Stop Management Endpoints 20240117.",
        "displayName": "stop management API s2",
        "action": {
            "name": "StopManaging"
        }
    }
}

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

{
      "TaskName": "stop management API s2",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'triggers': [{'manual': {'expireTime': '2024-03-31T00:00:00Z'}}], 'versionId': '***', 'targets': {'deviceGroupsUuids': ['******'], 'devicesUuids': ['******']}, 'uuid': '******', 'description': 'Stop Management Endpoints 20240117.', 'displayName': 'stop management API s2', 'action': {'name': 'StopManaging'}}

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.	Stop Managing Endpoints 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Stop Managing Endpoints failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Uninstall Third Party AV Software

Removes third party antivirus software from the specified endpoint targets.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the uninstall software task.	uninstall sw API u2
Task Description	Required	The description of the uninstall software task. The maximum length is 1000 characters.	Uninstall Software from Endpoints 20240117.
Device UUIDs	Optional	The UUID(s) of the device(s) from which to uninstall software. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) from which all endpoints will have software uninstalled. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) for the uninstall software task. The task will not be triggered after this specified time. If not provided, the default expiration time is set to 6 months from the current time.	2024-03-31 00:00

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "uuid": "******",
        "versionId": "***",
        "targets": {
            "devicesUuids": [
                "******"
            ],
            "deviceGroupsUuids": [
                "******"
            ]
        },
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-01-31T08:00:00Z"
                }
            }
        ],
        "description": "Uninstall Software from Endpoints 20240117.",
        "action": {
            "name": "ThirdPartyAVRemove"
        },
        "displayName": "uninstall sw API u2"
    }
}

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

{
    "TaskName": "uninstall sw API u2",
    "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'uuid': '******', 'versionId': '***', 'targets': {'devicesUuids': ['******], 'deviceGroupsUuids': ['******']}, 'triggers': [{'manual': {'expireTime': '2024-01-31T08:00:00Z'}}], 'description': 'Uninstall Software from Endpoints 20240117.', 'action': {'name': 'ThirdPartyAVRemove'}, 'displayName': 'uninstall sw API u2'}

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.	Uninstall Third Party AV Software 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Uninstall Third Party AV Software failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Unisolate Endpoints

Ends the specified endpoints' isolation from the network. CreateTask uses a deduplication algorithm to prevent the creation of tasks with the same configuration but different triggers.

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the unisolation task.	Unisolate from API 4
Task Description	Required	The description of the unisolation task. The maximum length is 1000 characters.	Execute unisolation ASAP 20240117
Device UUIDs	Optional	The UUID(s) of the device(s) to unisolate. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of the device group(s) from which all endpoints will be unisolated. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) of the unisolation task. The unisolation task will not be triggered after this time. If not specified, the default expiration time is 6 months from the current time.	2024-02-21 00:00

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "targets": {
            "devicesUuids": [
                "******"
            ],
            "deviceGroupsUuids": [
                "******"
            ]
        },
        "displayName": "Unisolate from API 4",
        "uuid": "******",
        "action": {
            "name": "EndNetworkIsolation"
        },
        "versionId": "***",
        "description": "Execute unisolation ASAP 20240117",
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-02-21T23:59:59Z"
                }
            }
        ]
    }
}

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

{
      "TaskName": "Unisolate from API 4",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'targets': {'devicesUuids': ['******'], 'deviceGroupsUuids': ['******']}, 'displayName': 'Unisolate from API 4', 'uuid': '******', 'action': {'name': 'EndNetworkIsolation'}, 'versionId': '***', 'description': 'Execute unisolation ASAP 20240117', 'triggers': [{'manual': {'expireTime': '2024-02-21T23:59:59Z'}}]}

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.	Unisolate Endpoints 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Unisolate Endpoints failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Update Operating System

Updates the Operating System(s) on the specified target endpoint(s).

READER NOTE

Device UUIDs and Device Group UUIDs are optional parameters to run this command.

Run the Get Device Group Endpoints command to obtain Device UUIDs. Device UUIDs can be found in the raw data at the path $.Results[*].devices[*].uuid.
Run the List Device Groups command to obtain Device Group UUIDs. Device Group UUIDs can be found in the raw data at the path $.deviceGroups[*].uuid.
Either Device UUIDs, Device Group UUIDs, or both must be specified.

Input

Input Parameter	Required/Optional	Description	Example
Task Name	Required	The name of the update operating system task.	OS Update API os1
Task Description	Required	The description of the update operating system task. The maximum length is 1000 characters.	Update Operating System ASAP
Device UUIDs	Optional	The UUID(s) of the device(s) for which the operating system(s) will be updated. Device UUIDs can be obtained using the Get Device Group Endpoints command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Device Group UUIDs	Optional	The UUID(s) of device group(s) that all endpoints in the device group(s) will update operating systems. Device Group UUIDs can be obtained using the List Device Groups command. Either Device UUIDs, Device Group UUIDs, or both must be specified.	[ "******" ]
Expire Time	Optional	The expiration time (in UTC) of the update operating system task. The update operating system task will not be triggered after this time. If not specified, the default Expire time is 6 months from current time.	2024-01-30 00:00
Allow Reboot	Optional	The option to choose whether the endpoint will be restarted when OS installs updates that require a system restart. If set to False, the endpoint will not be restarted. If not specified, the default value is True.	True
Accept EULA	Optional	The option to automatically accept the End-User License Agreement (EULA) when an update requires it. If not specified, the default value is False. This setting is only applicable to Windows operating systems.	True
Install Optional Updates	Optional	The option to install updates that are marked as optional. If False, optional updates won't be installed. If not specified, the default value is False. This setting applies only to Windows operating systems.	True
Postpone	Optional	The allowed time for postponing an endpoint reboot. If not specified, the default value is Can Not Postpone. This parameter is only applicable if the Allow Reboot parameter is set to True.	One Hours
Cancel Action	Optional	The option for users to cancel the endpoint reboot action. If not specified, the default value is False.	True

Output

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "task": {
        "targets": {
            "deviceGroupsUuids": [
                "******"
            ],
            "devicesUuids": [
                "******"
            ]
        },
        "displayName": "OS Update API os1",
        "uuid": "******,
        "action": {
            "name": "SystemUpdate",
            "params": {
                "rebootActions": {
                    "cancelAction": false,
                    "postpone": "OneHour"
                },
                "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.SystemUpdate",
                "allowReboot": true,
                "acceptEula": true,
                "installOptionalUpdates": true
            }
        },
        "versionId": "***",
        "description": "Update Operating System ASAP",
        "triggers": [
            {
                "manual": {
                    "expireTime": "2024-01-30T00:00:00Z"
                }
            }
        ]
    }
}

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

{
      "TaskName": "OS Update API os1",
      "TaskUUID": "******"
}

Result

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

SAMPLE DATA

task

{'targets': {'deviceGroupsUuids': ['******'], 'devicesUuids': ['******']}, 'displayName': 'OS Update API os1', 'uuid': '******', 'action': {'name': 'SystemUpdate', 'params': {'rebootActions': {'cancelAction': False, 'postpone': 'OneHour'}, '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.SystemUpdate', 'allowReboot': True, 'acceptEula': True, 'installOptionalUpdates': True}}, 'versionId': '***', 'description': 'Update Operating System ASAP', 'triggers': [{'manual': {'expireTime': '2024-01-30T00:00:00Z'}}]}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Operating System 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 ESET Protect Cloud 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: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Error Sample Data

Update Operating System failed.

Status Code: 400.

Message: Either or both Device UUIDs parameter and Device Group UUIDs parameter should have values.

Update Task Trigger

Updates expire time of the specified task(s).

READER NOTE

The parameter Task UUIDs is required to run this command.

Run the List Device Tasks command to obtain Task UUIDs. Task UUIDs can be found in the raw data at the path $.tasks[*].uuid.

Input

Input Parameter	Required/Optional	Description	Example
Task UUIDs	Required	The UUID(s) of the task(s) to update the expiration time. Task UUIDs can be obtained using the List Device Tasks command.	[ "******" ]
Expire Time	Optional	The updated expiration time for the specified task(s). If not specified, the default expiration time is 6 months from the current time.	2024-01-22 00:00

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Results": [
        {
            "task": {
                "targets": {
                    "deviceGroupsUuids": [
                        "******"
                    ],
                    "devicesUuids": []
                },
                "action": {
                    "name": "RunCommand",
                    "params": {
                        "currentDirectory": "d:\\data",
                        "commandLine": "mkdir tmp",
                        "@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand"
                    }
                },
                "uuid": "******",
                "versionId": "***",
                "triggers": [
                    {
                        "manual": {
                            "expireTime": "2024-01-22T00:00:00Z"
                        }
                    }
                ],
                "displayName": "******",
                "description": "Execute ASAP"
            }
        }
    ]
}

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

{
    "TaskNames": "*****",
    "TaskExpireTime": [
        "2024-01-22T00:00:00Z"
    ]
}

Result

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

SAMPLE DATA

Results

{'task': {'targets': {'deviceGroupsUuids': ['******'], 'devicesUuids': []}, 'action': {'name': 'RunCommand', 'params': {'currentDirectory': 'd:\\data', 'commandLine': 'mkdir tmp', '@type': 'type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand'}}, 'uuid': '******', 'versionId': '***', 'triggers': [{'manual': {'expireTime': '2024-01-22T00:00:00Z'}}], 'displayName': '*****', 'description': 'Execute ASAP'}}

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.	Update Task Trigger 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 ESET Protect Cloud 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: Request failed when when updating trigger for TaskUUID: <sample TaskUUID>.

Error Sample Data

Update Task Trigger failed.

Status Code: 400.

Message: Request failed when when updating trigger for TaskUUID: <sample TaskUUID>.

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 ESET Protect Cloud 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: Errors in Test Connection function.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Errors in Test Connection function.