WatchGuard Aether ESM

LAST UPDATED: 05/30/2024

Overview

WatchGuard Panda Aether endpoint security products protect your devices from security threats. Use the Aether Endpoint Security Management integration to monitor and manage devices that run these Panda Aether platform endpoint security products: Adaptive Defense and Adaptive Defense 360 Endpoint Protection and Endpoint Protection Plus.

WatchGuard Aether ESM is available for use in:

D3 SOAR	V16.0.0+
Category	Endpoint Security
Deployment Options	Option II, Option IV

Connection

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

Parameter	Description	Example
Server URL	The server URL of the WatchGuard API.	https://api.*******************.com
Access ID (Read-Write)	The read-write access ID to authenticate the API connection.	**********************
Password	The password to authenticate the API connection.	m13***************************Setf
API Key	The API key to authenticate the connection.	Kc4***************************dQ1
Account ID	The account ID to authenticate the API connection.	acb***************************6a9
Managed Account	The managed account to submit API requests for. The is an optional parameter for users who are service providers.	wGi-*****************************6
API Version	The version of the API to use for the connection.	v1

Configuring WatchGuard Aether ESM to Work with D3 SOAR

To obtain your API key, log in to WatchGuard and navigate to Administration > Account > Managed Access. For more information, see WatchGuard Aether API Authorization.

Configuring D3 SOAR to Work with WatchGuard Aether ESM

Log in to D3 SOAR.
Find the WatchGuard Aether ESM integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type WatchGuard Aether ESM 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 WatchGuard Aether ESM.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the checkbox to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL. The default value is https://api.usa.cloud.watchguard.com.
  2. Input the Access ID (Read-Write). This value can be obtained from the WatchGuard platform. It is recommended to use read-write access ID, as it allows you to run all commands.
  3. Input your account Password.
  4. Input your API Key.
  5. Input your Account ID. This parameter is not mandatory to establish a connection, but it must be defined to execute commands.
  6. (Optional) Input your Managed Account.
  7. Input the API Version. The default value is v1. Currently, D3 SOAR supports v1 of WatchGuards API, which allows you to run all commands.
9. 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 tick box. 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.
10. 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

WatchGuard Aether ESM 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 WatchGuard Aether ESM API, please refer to the WatchGuard Aether ESM API reference.

Get Device Protection Status

Retrieves a list of devices with their protection status and other device information.

Input

Input Parameter	Required/Optional	Description	Example
Search	Optional	The full or partial text string defining the objects to include in the response data. For example, using "name" would return objects containing "hostname". The only supported search field is hostname. If this field is not specified, the protection status of all devices will be returned.	name

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
"data": [
{
"host_name": "***",
"device_id": "***-***-***-***-***",
"platform_id": ***,
"device_type": 3,
"accumulated_protection_status": 1,
"adaptive_defense_status": 2,
"file_antivirus_status": 1,
"isolation_state": 0,
"protection_engine_update_status": 1,
"protection_engine_version": "***.***.***.***",
"knowledge_catalog_update_status": 2,
"knowledge_catalog_date": "2020-10-23T17:36:04.401Z",
"last_connection_date": "2020-10-23T17:36:04.401Z",
"reboot_requested": true,
"reinstall_protection_requested": true,
"reinstall_agent_requested": true,
"license_status": 0
}
],
"total_items": 10
}

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

{
    "DeviceIDs": "\"[ \\\"***-***-***-***-***\\\", \\\"*************\\\" ]\"",
    "HostNames": "\"[ \\\"***\\\", \\\"***\\\" ]\"",
    "DeviceTypes": "\"[ 3, 1 ]\"",
    "PlatformIDs": "\"[ 1, 1 ]\"",
    "LastConnectionDate": "\"***.***\\\" ]\"",
    "GeneralProtectionStatuses": "\"[ 1, 1 ]\"",
    "AdaptiveDefenseStatuses": "\"[ 2, 1 ]\"",
    "AntivirusStatuses": "\"[ 1, 1 ]\"",
    "IsolationStates": "\"[ 0, 3 ]\""
}

Return Data

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Devices Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Device Protection Status 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Search String.

Error Sample Data

Get Device Protection Status failed.

Status Code: 400.

Message: Invalid Search String.

Isolate Devices

Isolates the specified devices. When you isolate a device, communication to and from the device is denied.

Reader Note

The parameter Device IDs is required to run this command.

Run the List Devices command to obtain Device IDs. The Device IDs can be found in the raw data at the path $.data[*].device_id.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the device(s) to isolate. Device IDs can be obtained using the List Devices command.	["**********************"]
Exclusion Programs	Optional	The programs to exclude from the isolation action. These programs are allowed to be able to communicate as usual.	[ "*****************.exe" ]
Customized Message	Optional	The customized alert message to show on the isolated devices.	This computer has been isolated by an administrator.
Hide Customized Alert	Optional	The option to hide customized alert messages on the isolated devices, when set to True. If this parameter is not defined, the default value is False.	True

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "processed_device_ids": [
        "***************************************",
        "***************************************"
    ]
}

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

{
    "ProcessedDeviceIDs": "\"[\\\"************\\\", \\\"************\\\"]\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Isolated Devices Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Isolate Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID not found.

Error Sample Data

Isolate Devices failed.

Status Code: 404.

Message: Device ID not found.

List Devices

Retrieves a list of devices, and additional information, such as the device IP address and operating system.

Input

Input Parameter	Required/Optional	Description	Example
Search	Optional	The full or partial text string defining the devices to include in the response data. For example, using "name" would return objects containing "hostname". The supported search field includes host name, description, IP address, and logged on user. If this field is not specified, all devices will be returned.	name

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": [
        {
            "device_id": "***************************************",
            "account_id": "***************************************",
            "site_id": "***************************************",
            "site_name": "**************",
            "host_name": "**************",
            "type": 3,
            "description": "Marketing server",
            "domain": "WORKGROUP",
            "platform_id": 1,
            "ip_address": "1.1.1.1",
            "mac_addresses": [
                "**:**:**:**:**:**",
                "**:**:**:**:**:**",
                "**:**:**:**:**:**"
            ],
            "operating_system": "Windows Server 2019 Standard (1809)",
            "license_status": 0,
            "isolation_state": 0,
            "encryption": 0,
            "reinstall_protection_requested": true,
            "reinstall_agent_requested": true,
            "reboot_requested": true,
            "agent_version": "***.***.***.***",
            "last_connection": "2020-10-31T18:30:51.307Z",
            "security_configuration_name": "Virtual machines",
            "security_configuration_id": "******************************"
        }
    ],
    "total_items": 1
}

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

{
    "DeviceIDs": "\"[ \\\"***************************************\\\" ]\"",
    "SiteNames": "\"[ \\\"***\\\" ]\"",
    "Descriptions": "\"[ \\\"Marketing server\\\" ]\"",
    "HostNames": "\"[ \\\"***\\\" ]\"",
    "IPAddresses": "\"[ \\\"***.***.***.***\\\" ]\"",
    "OperatingSystems": "\"[ \\\"Windows Server 2019 Standard (1809)\\\" ]\"",
    "LastConnectionTime": "\"***.***\\\" ]\""
}

Return Data

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Devices Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Search String.

Error Sample Data

List Devices failed.

Status Code: 400.

Message: Invalid Search String.

List Unmanaged Devices

Retrieves a list of unmanaged devices discovered on the network.

Input

Input Parameter	Required/Optional	Description	Example
Search	Optional	The full or partial text string defining the unmanaged devices to include in the response data. For example, using "name" would return objects containing "hostname". The supported search field includes host name, description, IP address, and logged on user. If this field is not specified, all discovered unmanaged devices will be returned.	name

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": [
        {
            "device_id": "***************************************",
            "account_id": "***************************************",
            "site_id": "***************************************",
            "host_name": "***",
            "ip_address": "1.0.1.1",
            "mac_address": "***:***:***:***:***:***",
            "probe_name": "Probe computer 7",
            "last_seen_datetime": "2020-11-18T22:25:22.641Z",
            "network_interface_controller_vendor": "Intel",
            "visible": true,
            "description": "Finance mac01",
            "status": "0_Undefined",
            "installation_error": 200000
        }
    ],
    "total_items": null
}

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

{
    "DeviceIDs": "\"[ \\\"***************************************\\\" ]\"",
    "SiteIDs": "\"[ \\\"***************************************\\\" ]\"",
    "MacAddresses": "\"16\\\" ]\"",
    "HostNames": "\"[ \\\"***\\\" ]\"",
    "IPAddresses": "\"[ \\\"***.***.***.***\\\" ]\"",
    "Descriptions": "\"[ \\\"Finance mac01\\\" ]\"",
    "LastSeenTime": "\"***.***\\\" ]\"",
    "Statuses": "\"[ \\\"********************\\\" ]\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Unmanaged Devices Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Unmanaged Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Search String.

Error Sample Data

List Unmanaged Devices failed.

Status Code: 400.

Message: Invalid Search String.

Reboot Devices

Initiates reboot action on the specified devices.

Reader Note

The parameter Device IDs is required to run this command.

Run the List Devices command to obtain Device IDs. The Device IDs can be found in the raw data at the path $.data[*].device_id.

Input

Input Parameter

Required/Optional

Description

Example

Device IDs

Required

The IDs of the devices to reboot. Device IDs can be obtained using the List Devices command.

[ "******************" ]

Count Down Time

Required

Select the amount of time to count down to reboot devices.

The duration of the countdown before rebooting devices.

Two hours

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "processed_device_ids": [
        "***************************************",
        "***************************************"
    ]
}

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

{
    "ProcessedDeviceIDs": "\"[\\\"*************\\\", \\\"*************\\\"]\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Rebooting Devices Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Reboot Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Device IDs submitted.

Error Sample Data

Reboot Devices failed.

Status Code: 400.

Message: Invalid Device IDs submitted.

Retrieve Security Events

Retrieves a list of security events filtered by event type, time period and host names.

Reader Note

The parameter Host Names is optional to run this command.

Run the List Devices command to obtain Host Names. The Host Names can be found in the raw data at the path $.data[*].host_name.

Input

Input Parameter	Required/Optional	Description	Example
Event Type	Required	The type of security events to retrieve.	Malware URLs
Period	Required	The timeframe to retrieve security events. The available options are Previous 24 hours and Previous 7 days.	Previous 7 days
Host Names	Optional	The names of the hosts to retrieve associated security events. If this parameter is not specified, security events associated with all hosts will be returned. The Host Names can be obtained from the List Devices command.	["**********************"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": [
        {
            "accessed_data": true,
            "action": 10,
            "date": "2020-11-20T20:27:18.725Z",
            "device_id": "***************************************",
            "site_id": "***************************************",
            "event_id": ***************************************,
            "event_type": ***.***,
            "dwell_time": 51373899,
            "is_excluded": true,
            "hash": "***************************************",
            "host_name": "***",
            "item_name": "***",
            "made_external_connections": true,
            "path": "ThreatPath",
            "protection_mode": ***.***,
            "reclassified_to_type": ***.***,
            "like_lihood_of_being_malicious": ***.***,
            "discard_motive": ***.***,
            "lock_plus_rule_id": ***.***,
            "user_name": "Username",
            "was_run": true,
            "source_ip": "***.***.***.***",
            "source_machine_name": "SourceDeviceName",
            "source_user": "SourceUsername",
            "detection_technology": "DetectionTechnologyName",
            "exploit_technique": "ExploitTechnique",
            "risk": true,
            "description": "DeviceDescriptionName",
            "domain": "***",
            "detected_by": ***.***,
            "device_type": ***.***,
            "platform_id": ***.***,
            "excluded": true,
            "file_info_discard": "FileIndentifierHash",
            "id": "***************************************",
            "ip_address": "1.1.1.1",
            "malware_name": "MalwareName",
            "malware_category": ***.***,
            "malware_type": ***.***,
            "number_of_occurrences": 20674256,
            "security_event_date": "2021-07-20T20:27:18.725Z",
            "site_name": "SiteName",
            "network_activity_type": ***.***,
            "direction": ***.***,
            "protocol": ***.***,
            "local_endpoint": {},
            "remote_endpoint": {},
            "firewall_rule_definition": {},
            "rule_id": "**********************************",
            "rule_name": "RuleName",
            "rule_configuration_id": "**********************************",
            "rule_obsolete": false,
            "alias": "AliasName",
            "instance_id": "***-**-***-**-***",
            "type": -51429435.96722382,
            "rule_risk": -54492359.89028178,
            "rule_mitre": "tactic: TA0006, technique: T1003",
            "status": 31156035.444223955,
            "endpoint_event_date": "2021-07-20T20:27:18.725Z",
            "filed_date": "2021-07-20T20:27:18.725Z",
            "since_until_filed": "8.07:06:05",
            "count": -10808344,
            "custom_group_folder_id": "***************************************",
            "custom_group_folder_info": "*************************************"
        }
    ]
}

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

{
    "DeviceIDs": "\"[ \\\"***************************************\\\" ]\"",
    "HostNames": "\"[ \\\"***************************************\\\" ]\"",
    "DeviceTypes": "\"[ 3 ]\"",
    "PlatformIDs": "\"[ 1 ]\"",
    "EventIDs": "\"[***]\"",
    "EventTypes": "\"[ 0 ]\"",
    "Hashes": "\"[ \\\"***************************************\\\" ]\"",
    "ThreatNames": "\"[ \\\"***************************************\\\" ]\"",
    "ThreatPaths": "\"[ \\\"***************************************\\\" ]\"",
    "ProtectionModes": "\"[ 1 ]\"",
    "UserNames": "\"[ \\\"***************************************\\\" ]\"",
    "SourceIPs": "\"[ \\\"***.***.***.***\\\" ]\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Events Count

1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Retrieve Security Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Event Type.

Error Sample Data

Retrieve Security Events failed.

Status Code: 400.

Message: Invalid Event Type.

Scan Devices

Starts a task to scan the specified devices immediately.

Reader Note

The parameter Device IDs is required to run this command.

Run the List Devices command to obtain Device IDs. The Device IDs can be found in the raw data at the path $.data[*].device_id.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to scan. Device IDs can be obtained using the List Devices command.	[ "*********************" ]
Task Name	Required	The name of the scan task.	Routine scan
Task Description	Optional	The description for the scan task.	Windows 8 machines only.
Scan Scope	Optional	The scope of the scan task. If this parameter is not defined, the default scope is Whole Computer.	Whole Computer
Specified Items To Scan	Optional	The locations or items to scan. All specified locations and/or items will be scanned. Note: This parameter is only valid when the Scan Scope parameter is set to Specified Items.	["C:\Downloads", "C:\Documents"]
Detect Hacking Tools	Optional	The option to enable hacking tool detection for the scan. This detects potentially unwanted programs, as well as programs used by adversaries. If this parameter is not defined, the default value is False.	False
Detect Suspicious Files	Optional	The option to enable suspicious file detection for the scan. During scheduled scans, the tool will scan the computer's software without executing it. Some threats may have a lower chance of detection. Setting this parameter to True will enable the scan to use heuristic algorithms to improve detection rates. If this parameter is not defined, the default value is False.	True
Scan Compressed Files	Optional	The option to scan compressed files. When enabled, compressed files will be decompressed and their contents will be scanned. If this parameter is not defined, the default value is False.	True
Apply Exclusions On Scan	Optional	The option to enable certain items, including specific files, file extensions, or directory to be excluded from the scan. If this parameter is not defined, the default value is True.	True
Extensions To Exclude	Optional	The list of file extensions to exclude from the scan. This parameter is only valid when the Apply Exclusions On Scan parameter is set to True.	["exe", "pdf"]
Files To Exclude	Optional	The list of file names (with their extensions) to exclude from the scan. This parameter is only valid when the Apply Exclusions On Scan parameter is set to True.	["************.exe", "************.exe" ]
Folders To Exclude	Optional	The list of full folder paths to exclude from the scan. This parameter is only valid when the Apply Exclusions On Scan parameter is set to True.	["D:/*/*"]
Execution Window Expiration	Optional	The duration for the scan to complete before it times out. This value is defined in the format of [Days].[Hours]:[Minutes]:[Seconds]. The default value is 7 days. For example, 8.07:06:05 denotes a duration of 8 days, 7 hours, 6 minutes, and 5 seconds.	*.::*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "task_id": "***************************************"
}

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

{
    "TaskID": "\"\\\"***************************************\\\"\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

task_id

*********************************

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.	Scan Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID not found

Error Sample Data

Scan Devices failed.

Status Code: 404.

Message: Device ID not found

Unisolate Devices

Stops isolating the specified devices.

Reader Note

The parameter Device IDs is required to run this command.

Run the List Devices command to obtain Device IDs. The Device IDs can be found in the raw data at the path $.data[*].device_id.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices to stop isolating. Device IDs can be obtained using the List Devices command.	["**********************"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "processed_device_ids": [
        "***************************************",
        "***************************************"
    ]
}

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

{
    "ProcessedDeviceIDs": "\"[\\\"************\\\", \\\"************\\\"]\""
}

Return Data

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

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

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

A connection issue with the integration

The API returned an error message

No response from the API

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

Unisolated Devices Count	1

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unisolate Devices 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 WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID not found.

Error Sample Data

Unisolate Devices failed.

Status Code: 404.

Message: Device ID not found.

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 responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the WatchGuard Aether ESM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: access denied, authorization failed.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: access denied, authorization failed.