Blackberry Cylance Endpoint Security
Overview
Cylance Endpoint Security (CES) provides advanced cyber threat detection and operations via products. Such as CylancePROTECT, CylanceOPTICS and CylancePERSONA.
D3 SOAR’s integration with CES uses the latest CES API (2.0) to retrieve threats to ingest as events into D3 SOAR, update threats, quarantine devices and block hashes.
D3 SOAR is providing REST operations to function with Cylance Endpoint Security.
Cylance Endpoint Security is available for use in:
D3 SOAR | V15.2.26.0+ |
Category | Endpoint Protection |
Deployment Options |
Known Limitations
A rate limit of 100,000 requests per day.
Or a rate limit of 20 requests per second
When encounter a 429 error, wait 60 seconds before retry
Please refer to API rate limit from BlackBerry’s documentation for more information.
Connection
To connect to Cylance Endpoint Security from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Server URL | The server URL of the Cylance PROTECT. | https://protectapi.cylance.com |
Tenant ID | The Tenant ID of the Cylance PROTECT integration. | 8e******-*fd*-4**a-*4*7-acd********* |
Application ID | The Application ID of the Cylance PROTECT. | ba******-*fd*-4**c-*b*d-2c8********* |
Application Secret | The Application Secret of the Cylance PROTECT. | **************** |
Version | The version of the integration. | v2 |
Permission Requirements
Each endpoint in the Cylance Endpoint Security API requires a certain permission scope. The following are required scopes for the commands in this integration:
Command | Required Permission |
Add Device Policy | Policies:WRITE |
Add Hashes To Global List | Global Lists:WRITE |
Check Hashes In Global List | Global Lists:READ |
Fetch Event | Threats:READ |
Get Policy Details | Policies:READ |
Get Threats By Device | Devices:READ |
List Devices | Devices:READ |
List Global List Items | Global Lists:READ |
List Memory Protection Events | Memory Protection:READ |
List Policies | Policies:READ |
Quarantine Devices | CylanceOPTICS Commands:READ, CylanceOPTICS Commands:WRITE |
Remove Hashes From Global List | Global Lists:DELETE |
Update Device Policy | Policies:MODIFY, Policies:READ |
Update Devices | Devices:UPDATE, Devices:READ |
Update Device Threat | Threats:MODIFY |
Test Connection | Threats:READ |
Please refer to step 4 of Configuring Cylance Endpoint Security to Work with D3 SOAR for the overall required permissions.
Configuring Cylance Endpoint Security to Work with D3 SOAR
Log in to Cylance with your credentials.
Navigate to Settings > Integrations.
Click Copy to save your Tenant ID to the clipboard. Click + Add Application to create an application. You may skip this step if you already have created applications.
Name your application, then select privileges. Save your application configurations. It is recommended to select enable all privileges listed in the table below. This will allow the connection to run all Cylance integration commands in D3 SOAR.
PRIVILEGE | READ/WRITE/MODIFY/DELETE |
Devices | READ and MODIFY |
Global Lists | READ, WRITE and DELETE |
Policies | READ, WRITE and MODIFY |
Threats | READ and MODIFY |
Users | READ |
Memory Protection | READ |
CylanceOPTICS Commands | READ and WRITE |
CylanceOPTICS Detections | READ |
After you create an application, the corresponding Application ID and Application Secret will be shown. Store these values securely for building integrations in D3 SOAR later on. Click OK.
You may view the Application ID and Secret by clicking the Pencil icon. This may be useful if you did not save the Application ID and Secret upon creating an application.
Configuring D3 SOAR to Work with Cylance Endpoint Security.
Log in to D3 SOAR.
Find the Cylance Endpoint Security integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Cylance Endpoint Security in the search box to find the integration, then click it to select it.
Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Cylance Endpoint Security.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input your domain-level Server URL. The default value is https://protectapi.cylance.com.
2. Input your saved Tenant ID. Please check step 3 of Configuring Cylance Endpoint Security to Work with D3 SOAR for more details.
3. Input your Application ID. Please check step 5 of Configuring Cylance Endpoint Security to Work with D3 SOAR for more details.
4. Input your Application Secret. Please check step 5 of Configuring Cylance Endpoint Security to Work with D3 SOAR for more details.
5. Input your API Version. The default value is v2. It is suggested you use the default v2 when building connections since it is applicable for all D3 commands for now.Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Cylance Endpoint Security 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 Cylance Endpoint Security API, please refer to the Cylance Endpoint Security API reference.
Reader Note
Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Cylance Endpoint Security 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 Device Policy
Creates a new device policy based on the provided configuration. It is highly recommended to create a policy from Cylance’s console UI.
Reader Note
This command is used for creating device policies. Do not define a value for full_dic_scan for the Policy Configuration parameter for policy threat detection. Instead, use the Full Disc Scan Setting input parameter, as any full_disc_scan value defined in the Policy Configuration parameter will be ignored.
Input
Input Parameter | Required/Optional | Description | Example |
Policy Name | Required | The name of the device policy. | examplePolicy |
Policy Configuration | Required | The JSON-formatted configuration object for the policy. The input value will be set in the request body policy. It is recommended to use the provided sample data as a template to build your JSON object. See Create policy from BlackBerry’s documentation for more about the syntax format and predefined values. | { "memoryviolation_actions": { "memory_violations_ext_v2": [{ "violation_type": "syscallprobe", "action": "Alert" }, { "action": "Alert", "violation_type": "directsyscall" }, { "violation_type": "systemdllwrite", "action": "Alert" }, { "action": "Alert", "violation_type": "dangerouscomobject" }, { "violation_type": "doppelganger", "action": "Alert" }, { "violation_type": "dangerousenvvariable", "action": "Alert" }, { "violation_type": "oopprotect", "action": "Alert" }, { "action": "Alert", "violation_type": "childprocessprotect" }, { "action": "Alert", "violation_type": "stolensystemtoken" }, { "violation_type": "maliciouslowintegrity", "action": "Alert" }, { "violation_type": "injectionviaapc", "action": "Alert" }, { "action": "Alert", "violation_type": "runmacroscript" } ], "memory_violations": [{ "violation_type": "lsassread", "action": "Alert" }, { "violation_type": "outofprocessunmapmemory", "action": "Alert" }, { "violation_type": "stackpivot", "action": "Alert" }, { "violation_type": "stackprotect", "action": "Alert" }, { "violation_type": "outofprocessoverwritecode", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocesscreatethread" }, { "violation_type": "overwritecode", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocesswritepe" }, { "violation_type": "outofprocessallocation", "action": "Alert" }, { "violation_type": "outofprocessmap", "action": "Alert" }, { "violation_type": "outofprocesswrite", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocessapc" } ], "memory_violations_ext": [{ "violation_type": "dyldinjection", "action": "Alert" }, { "violation_type": "trackdataread", "action": "Alert" }, { "action": "Alert", "violation_type": "zeroallocate" }, { "action": "Alert", "violation_type": "maliciouspayload" } ], "memory_exclusion_list_v2": [{ "violations": [], "path": "\\Application\\TestApp\\MyApp\\program.exe" } ] }, "persona": { "mitigation_actions": [{ "action": "alertsOnly", "threshold": "70" }, { "threshold": "30", "action": "promptUsernameAndPassword" } ], "admin_whitelist": [{ "username": "admin" } ], "mode": "1" }, "device_control": { "configurations": [{ "device_class": "AndroidUSB", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "iOS" }, { "control_mode": "FullAccess", "device_class": "StillImage" }, { "device_class": "USBCDDVDRW", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "USBDrive" }, { "device_class": "VMWareMount", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "WPD" } ], "exclusion_list": [{ "vendor_id": "1234", "comment": "Test external device", "serial_number": null, "product_id": "5678", "control_mode": "FullAccess", "date_added": "2022-02-01T23:56:32.479Z" } ] }, "policy": [{ "value": "1", "name": "auto_blocking" }, { "value": "1", "name": "auto_uploading" }, { "value": "500", "name": "threat_report_limit" }, { "value": "2", "name": "full_disc_scan" }, { "name": "watch_for_new_files", "value": "1" }, { "value": "1", "name": "memory_exploit_detection" }, { "value": "0", "name": "trust_files_in_scan_exception_list" }, { "name": "logpolicy", "value": "1" }, { "name": "script_control", "value": "1" }, { "value": "1", "name": "prevent_service_shutdown" }, { "name": "scan_max_archive_size", "value": "0" }, { "name": "sample_copy_path", "value": "\\\\server_name\\shared_folder" }, { "name": "kill_running_threats", "value": "1" }, { "name": "show_notifications", "value": "1" }, { "value": "1000", "name": "optics_set_disk_usage_maximum_fixed" }, { "name": "optics_malware_auto_upload", "value": "1" }, { "value": "1", "name": "optics_memory_defense_auto_upload" }, { "value": "0", "name": "optics_script_control_auto_upload" }, { "value": "0", "name": "optics_application_control_auto_upload" }, { "name": "optics_sensors_dns_visibility", "value": "1" }, { "value": "1", "name": "optics_sensors_private_network_address_visibility" }, { "name": "optics_sensors_windows_event_log_visibility", "value": "1" }, { "name": "optics_sensors_windows_advanced_audit_visibility", "value": "1" }, { "name": "optics_sensors_advanced_powershell_visibility", "value": "1" }, { "name": "optics_sensors_advanced_wmi_visibility", "value": "1" }, { "name": "optics_sensors_advanced_executable_parsing", "value": "1" }, { "value": "1", "name": "optics_sensors_enhanced_process_hooking_visibility" }, { "value": "1", "name": "optics_sensors_enhanced_file_read_visibility" }, { "name": "device_control", "value": "1" }, { "name": "optics", "value": "1" }, { "name": "auto_delete", "value": "1" }, { "name": "days_until_deleted", "value": "14" }, { "name": "pdf_auto_uploading", "value": "0" }, { "name": "ole_auto_uploading", "value": "0" }, { "value": "0", "name": "docx_auto_uploading" }, { "value": "0", "name": "python_auto_uploading" }, { "value": "0", "name": "autoit_auto_uploading" }, { "value": "0", "name": "powershell_auto_uploading" }, { "value": null, "name": "custom_thumbprint" }, { "value": [ "C:\\Test" ], "name": "scan_exception_list" }, { "value": "1", "name": "optics_show_notifications" } ], "script_control": { "powershell_settings": { "control_mode": "Alert", "console_mode": "Allow" }, "macro_settings": { "control_mode": "Alert" }, "global_settings": { "control_mode": "Alert", "allowed_folders": [ "/users/*/temp/*" ] }, "activescript_settings": { "control_mode": "Alert" } }, "filetype_actions": { "suspicious_files": [{ "actions": "3", "file_type": "executable" } ], "threat_files": [{ "actions": "3", "file_type": "executable" } ] }, "logpolicy": { "retentiondays": "30", "log_upload": { "compress": "True", "delete": "False" }, "maxlogsize": "100" }, "file_exclusions": [{ "reason": "SHA256 for testing", "category_id": "2", "md5": null, "research_class_id": "0", "file_hash": "443010d98917908efb64a1e8c4a560ec126649bd7e4d0ddd87643356e6f3506f", "cloud_score": null, "av_industry": false, "file_name": "Test file", "file_type": 1, "research_subclass_id": "0", "infinity": null } ], "checksum": "", "script_control_v2": { "python_settings": { "control_mode": "Alert" }, "dotnet_dlr_settings": { "control_mode": "Alert" } } } |
Full Disc Scan Setting | Optional | The setting to toggle the policy threat detection setting to full_disc_scan, which enables Cylance to analyze all executable files on disk to detect any dormant threats. The available options are Disable, Run Recurring and Run Once. The default setting is Disabled. | Run Once |
Output
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 Hashes To Global List 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 Cylance Endpoint Security portal. Refer to the HTTP Status Code Registry for details. | Status Code: 409. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: policy name conflicts. |
Error Sample Data Add Hashes To Global List failed. Status Code: 409. Message: policy name conflicts. |
Add Hashes To Global List
Adds threats (hashes) to the global list.
Reader Note
The input parameter SHA256 Hashes is required to run this command.
You should already have your desired SHA256 hash values on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired hash values. The hash values can be found in the raw data at the path $.page_items[*].sha256.
The input parameter Category is required if you set the Global List Type parameter to Global Safe List. If this parameter is not defined, the default value None will be used.
If the selected Global List Type is Global Quarantine List or the parameter is left empty (the default value Global Quarantine List will be used), any input value in the Category parameter will be omitted.
If the command does not execute successfully, verify that the SHA256 hash value entered is correct, and confirm that it has not already been included in the global list. Note that any hash value listed under either Global List type will be considered as already added. The following error messages may occur:
Error: There's already an entry for this threat.
Invalid Hash Error: The value supplied for the sha256 is not valid.
Input
Input Parameter | Required/Optional | Description | Example |
SHA256 Hashes | Required | The list of SHA256 hashes (threat IDs) to add to the global list. SHA256 hash values can be obtained using the Fetch Event command. | [ "***", "***" ] |
Global List Type | Optional | The global list type to add hash values to. The available global list types are Global Quarantine List and Global Safe List. The default value is Global Quarantine List. | Global Quarantine List |
Reason | Required | The reason for adding the file hash to the global list. A maximum of 65 characters are allowed. Any characters exceeding the character limit will be removed. | Malware |
Category | Optional | The category to group the input file hash value if it is added to the Global Safe List. The valid input values are: None, Admin Tool, Commercial Software, Drivers, Internal Application, Operating System and Security Software. The default value is None. This parameter will be omitted if the selected Global List Type is Global Quarantine List. | Commercial Software |
Output
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. | Add Hashes To Global List 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 Cylance Endpoint Security 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 Add Hashes To Global List failed. Status Code: 400. Message: Bad Request. |
Check Hashes In Global List
Checks if file hash values are present on the selected global list type. If the hashes are found on the global list, return the included hashes; if they do not exist, return excluded hashes.
Reader Note
The input parameter SHA256 Hashes is required to run this command.
You should already have your desired SHA256 hash values on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired hash values. The hash values can be found in the raw data at the path $.page_items[*].sha256.
If the returned result is "ExcludedHash," it indicates that the hash value you provided is not found in the current global list. It is recommended that you check the other global list type to see if the hash value is included in that list.
Input
Input Parameter | Required/Optional | Description | Example |
SHA256 Hashes | Required | The list of SHA256 hashes to check in the global list. SHA256 hashes can be obtained using the Fetch Event command. | [ "***", "***"] |
Global List Type | Optional | The global list type to check the hash value. The available global list types are Global Quarantine List and Global Safe List. The default value is Global Quarantine List. | Global Quarantine List |
Output
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 Hashes To Global List 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 Cylance Endpoint Security portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The value supplied for the sha256 is not valid. |
Error Sample Data Add Hashes To Global List failed. Status Code: 400. Message: The value supplied for the sha256 is not valid. |
Fetch Event
Retrieves threats from Cylance based on the given time range and provides a snapshot of the relevant threat details.
Reader Note
Start Time is the only required parameter for this command. If you only input start time and leave all other parameters empty, all threats with threat devices historical information from that time will be returned as events.
Input
Input Parameter | Required/Optional | Description | Example |
Start Time | Required | The start time of the time range to fetch events in UTC time. | 2022-04-01 00:00 |
End Time | Optional | The send time of the time range to fetch events in UTC time. | 2022-04-20 00:00 |
Number of Event(s) Fetched | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, all events within the given time range will be returned. Otherwise, the number indicated by your input value will be returned. | 100 |
Include Threat Devices | Optional | The option to include device historical information when retrieving threats. Selecting True will return threats with all device historical information. Selecting False will only return the threats. The default setting is True. | True |
Tolerance Scope (Seconds) | Optional | The tolerance scope (in seconds) for the query to fetch events between the specified start and end time to avoid event loss or fetch failure due to system time differences between D3 and Cylance. The events will be fetched between {Start Time - Tolerance Scope, End Time}. | 60 |
Output
Fetch Event Field Mapping
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Cylance integration has some pre-configured field mappings for default field mapping.
Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a “Main Event JSON Path” (i.e., $.page_items) 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: $.page_items
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 page_items. The child node denoting the Unique Event Key field would be .sha256. Putting it together, the JSON Path expression to extract the Unique Event Key is $.page_items.sha256.
The pre-configured field mappings are detailed below:
Field Name | Source Field |
Default Event Source (Main Event JSON Path: $.page_items) | |
Unique Event Key | .sha256 |
Event Type | .sub_classification |
Risk Score | .riskScore |
Filename | .name |
Description | .description |
Start Time | .last_found |
Event name | .name |
File Hash SHA256 | .sha256 |
File Hash MD5 | .md5 |
Hostname | .deviceDetails[*].name |
Device IDs | .deviceDetails[*].id |
IP Addresses | .deviceDetails[*].ip_addresses |
MAC Addresses | .deviceDetails[*].mac_addresses |
File Paths | .deviceDetails[*].file_path |
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 Cylance Endpoint Security 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: Forbidden, failed to get the access token, please check your connection fields. |
Error Sample Data Fetch Event failed. Status Code: 403. Message: Forbidden, failed to get the access token, please check your connection fields. |
Get Device Policy Details
Returns the details of the specified device policies.
Reader Note
The input parameter Policy IDs is required to run this command.
Run the List Device Policies command to obtain Policy IDs. Policy IDs can be found in the returned raw data at the path $.page_items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Policy IDs | Required | The IDs of the policies to return details. Policy IDs can be obtained using the List Device Policies command. | [ "***-**-***-***-***", "***-**-***-***-***" ] |
Output
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 Cylance Endpoint Security 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 Devices failed. Status Code: 400. Message: Bad Request. |
Get Threats By Device
Returns threat information of the specified Device IDs or hostnames.
Reader Note
Device IDs and Device Hostnames are optional parameters to run this command.
Run the List Devices command to obtain Device IDs and Device Hostnames. Device IDs can be found in the raw data at the path $.page_items[*].id; Device Hostnames can be found in the raw data a the path $.page_items[*].name.
At least one of these parameters must be defined before running the command.
Both Device IDs and Device Hostnames can be used to retrieve threats. If the IDs and hostnames correspond to the same devices, the threat will be listed once. If the IDs and hostnames correspond to different devices, the devices will be returned under the device array with their associated threats. The defined value for the Limit parameter will apply to the different devices (not unique devices).
Input
Input Parameter | Required/Optional | Description | Example |
Device IDs | Optional | The IDs of the device to return threat information. Device IDs can be obtained using the List Devices command. Note: At least one of the Device IDs or Device Hostnames parameters must be defined. | [ "***-**-***-***-***", "***-**-***-***-***" ] |
Device Hostnames | Optional | The hostnames of the devices to return threat information. Device Hostnames can be obtained using the List Devices command. Note: At least of the Device IDs or Device Hostnames parameters must be defined. | [ "***-**-***", "WIN-***" ] |
Limit | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, the command will return 10 results by default. Otherwise, the number indicated by your input value will be returned. | 3 |
Output
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 Cylance Endpoint Security 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: Not Found. |
Error Sample Data List Devices failed. Status Code: 404. Message: Not Found. |
List Devices
Returns details of CylancePROTECT managed endpoints. Note: Hostnames will not be included in the returned details if the first three input parameters are not defined.
Reader Note
Device IDs, MAC Addresses and Hostnames are optional parameters to run this command.
You should already have your desired Device IDs, MAC Addresses and Hostnames on hand to run this command. If you don’t, you may run this command with the Device IDs, MAC Addresses and Hostnames parameters left empty. Device IDs can be found in the returned raw data at the path $.page_items.id; MAC Addresses can be found in the returned raw data at the path $.page_items[*].mac_addresses.[*]; Hostnames can be found in the returned raw data at the path $.page_items[*].host_name.
If these three inputs are not provided, the returned raw data will be limited. The missing information includes the keys "last_logged_in_user", "update_type", "update_available", "date_last_modified", and "distinguished_name". To see these keys, make sure to specify at least one of the three parameters.
Input
Input Parameter | Required/Optional | Description | Example |
Device IDs | Optional | The list of device IDs to return corresponding details. Note: Only one of the Device IDs, MAC Addresses, or Hostnames parameters will be in effect per instance of running the command. Choose to define only one of the three. If more than one of these parameters are defined, the order of priority (Device IDs, MAC Addresses, Hostnames) will determine the effective parameter, with the first listed being the one that will take effect. | [ "***-***-***-***-***", "***-***-***-***-***" ] |
MAC Addresses | Optional | The list of MAC Addresses to return corresponding details. Note: Only one of the Device IDs, MAC Addresses, or Hostnames parameters will be in effect per instance of running the command. Choose to define only one of the three. If more than one of these parameters are defined, the order of priority (Device IDs, MAC Addresses, Hostnames) will determine the effective parameter, with the first listed being the one that will take effect. | [ "00-0C-00-00-00-00", "00-0C-00-00-00-E0" ] |
Hostnames | Optional | The list of Hostnames to return corresponding details. Note: Only one of the Device IDs, MAC Addresses, or Hostnames parameters will be in effect per instance of running the command. Choose to define only one of the three. If more than one of these parameters are defined, the order of priority (Device IDs, MAC Addresses, Hostnames) will determine the effective parameter, with the first listed being the one that will take effect. | [ "WIN-*** ***", "WIN2016-**-**" ] |
Limit | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, the command will return 10 results by default. Otherwise, the number indicated by your input value will be returned. Note: This parameter will be ignored if one of the Device IDs, MAC Addresses or Hostnames parameters are defined. | 3 |
Output
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 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 Cylance Endpoint Security 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: Not Found |
Error Sample Data List Devices failed. Status Code: 404. Message: Not Found. |
List Global List Items
Returns items in the global list.
Input
Input Parameter | Required/Optional | Description | Example |
Global List Type | Optional | The global list type to list items. The available global list types are Global Quarantine List and Global Safe List. The default value is Global Quarantine List. | Global Quarantine List |
Limit | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, the command will return 10 results by default. Otherwise, the number indicated by your input value will be returned. | 3 |
Output
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 Global List Items 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 Cylance Endpoint Security 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: Forbidden, failed to get the access token, please check your connection fields. |
Error Sample Data List Global List Items failed. Status Code: 403. Message: Forbidden, failed to get the access token, please check your connection fields. |
List Memory Protection Events
Returns memory protection threats based on the specified device IDs.
Reader Note
Device ID is an optional parameter to run this command.
Run the List Devices command to obtain Device ID. Device IDs can be found in the raw data at the path $.page_items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Start Time | Optional | The start time for the time range used to filter memory protection events, in UTC time. The time range between the Start Time and End Time must not exceed 90 days. | 2022-04-01 00:00 |
End Time | Optional | The end time for the time range used to filter memory protection events, in UTC time. The time range between the Start Time and End Time must not exceed 90 days. | 2022-04-20 00:00 |
Device ID | Optional | The device ID to list corresponding memory protection events. Device ID can be obtained using the List Devices command. | d75ad4f4-3057-4fce-b13c-d026d7bf5ca2 |
Limit | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, the command will return 10 results by default. Otherwise, the number indicated by your input value will be returned. | 100 |
Output
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 Global List Items 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 Cylance Endpoint Security 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: Forbidden, failed to get the access token, please check your connection fields. |
Error Sample Data List Global List Items failed. Status Code: 403. Message: Forbidden, failed to get the access token, please check your connection fields. |
List Device Policies
Returns device policies.
Input
Input Parameter | Required/Optional | Description | Example |
Limit | Optional | The maximum number of results to return. If the input value is 0, a negative number or not specified, the command will return 10 results by default. Otherwise, the number indicated by your input value will be returned. | 3 |
Output
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 Cylance Endpoint Security 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: Forbidden, failed to get the access token, please check your connection fields. |
Error Sample Data List Policies failed. Status Code: 403. Message: Forbidden, failed to get the access token, please check your connection fields. |
Quarantine Devices
Quarantines the specified devices within the given duration.
Reader Note
Input parameter Device IDs is required to run this command.
Run the List Devices command to obtain Device IDs. Device IDs can be found in the raw data at the path $.page_items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Device IDs | Required | The list of device IDs to update corresponding devices. Device IDs can be obtained using the List Devices command with no input parameters defined. The input device ID will be converted to CylanceOPTICS format (uppercase without dashes) automatically. For example, the input device ID[ "e75c4c49-b432-46fd-ad0f-348a3ff16d14", "e75c4c49b43246fdad0f348a3ff16d14" ] will be transformed to [ "E75C4C49B43246FDAD0F348A3FF16D14", "E75C4C49B43246FDAD0F348A3FF16D14" ]. | [ "***-***-***-***-***", "***-***-***-***-***", "***-***-***-***-***" ] |
Expire Duration | Optional | The duration of the quarantine (lockdown in CylancePROTECT). The input value must be in the format “d:hh:mm”. The maximum value is 3 days (3:00:00) and the minimum value is 5 minutes (0:00:05). The default value is 5 minutes (0:00:05). For example, 2 days 10 hours and 35 minutes lockdown will be 2:10:35. | 1:30:15 |
Output
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. | Quarantine 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 Cylance Endpoint Security 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 Quarantine Devices failed. Status Code: 400. Message: Bad Request. |
Remove Hashes From Global List
Removes the hashes from the global list.
Reader Note
Input parameter SHA256 Hashes is required to run this command.
Run the List Global List Items command to obtain SHA256 Hashes.
The input SHA256 hash value must correspond to the selected Global List Type. If the value does not match the type, an error 400 "bad request" will be returned. To obtain the correct pair of values, use the List Global List Items command with the desired Global List Type. Use the returned hash values to input into this command.
The default value for the Global List Type parameter is Global Quarantine List. If an error occurs, verify that the input SHA256 hash is included in the global list and that the correct global list type has been selected.
Input
Input Parameter | Required/Optional | Description | Example |
SHA256 Hashes | Required | The list of SHA256 hashes (threat IDs) to remove from the global list. SHA256 hash values can be obtained using the List Global List Items command. | [ "***", "***" ] |
Global List Type | Optional | The global list type to remove hash values from. The available global list types are Global Quarantine List and Global Safe List. The default value is Global Quarantine List. | Global Quarantine List |
Output
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. | Remove Hashes From Global List 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 Cylance Endpoint Security 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: Not Found. |
Error Sample Data Remove Hashes From Global List failed. Status Code: 404. Message: Not Found. |
Update Device Policy
Updates the specified policy based on the input configuration. It is highly recommended to update the policy from Cylance’s console UI.
Reader Note
Policy ID is a required parameter to run this command.
Run the List Device Policies command to obtain Policy ID. Policy ID can be found in the raw data at the path $.page_items[*].id.
This command is used for updating device policies. Do not define a value for full_dic_scan for the Policy Configuration parameter for policy threat detection. Instead, use the Full Disc Scan Setting input parameter, as any full_disc_scan value defined in the Policy Configuration parameter will be ignored.
To update the policy name, use a new policy name to define the Policy Name parameter. If you do not wish to change the policy name, use your original policy name.
Input
Input Parameter | Required/Optional | Description | Example |
Policy ID | Required | The policy ID to update corresponding policy details. Policy IDs can be obtained using the List Policies command. | ***-***-***-***-*** |
Policy Name | Required | The new name of the policy. If you do not want to change the policy name, enter the original policy name. | examplePolicy2-update |
Policy Configuration | Required | The JSON-formatted configuration object for the policy. The input value will be set in the request body policy. It is recommended to use the provided sample data as a template to build your JSON object. See Create policy from BlackBerry’s documentation for more about the syntax format and predefined values. | { "memoryviolation_actions": {"memory_violations_ext_v2": [ { "violation_type": "syscallprobe", "action": "Alert" }, { "action": "Alert", "violation_type": "directsyscall" }, { "violation_type": "systemdllwrite", "action": "Alert" }, { "action": "Alert", "violation_type": "dangerouscomobject" }, { "violation_type": "doppelganger", "action": "Alert" }, { "violation_type": "dangerousenvvariable", "action": "Alert" }, { "violation_type": "oopprotect", "action": "Alert" }, { "action": "Alert", "violation_type": "childprocessprotect" }, { "action": "Alert", "violation_type": "stolensystemtoken" }, { "violation_type": "maliciouslowintegrity", "action": "Alert" }, { "violation_type": "injectionviaapc", "action": "Alert" }, { "action": "Alert", "violation_type": "runmacroscript" } ], "memory_violations": [ { "violation_type": "lsassread", "action": "Alert" }, { "violation_type": "outofprocessunmapmemory", "action": "Alert" }, { "violation_type": "stackpivot", "action": "Alert" }, { "violation_type": "stackprotect", "action": "Alert" }, { "violation_type": "outofprocessoverwritecode", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocesscreatethread" }, { "violation_type": "overwritecode", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocesswritepe" }, { "violation_type": "outofprocessallocation", "action": "Alert" }, { "violation_type": "outofprocessmap", "action": "Alert" }, { "violation_type": "outofprocesswrite", "action": "Alert" }, { "action": "Alert", "violation_type": "outofprocessapc" } ], "memory_violations_ext": [ { "violation_type": "dyldinjection", "action": "Alert" }, { "violation_type": "trackdataread", "action": "Alert" }, { "action": "Alert", "violation_type": "zeroallocate" }, { "action": "Alert", "violation_type": "maliciouspayload" } ], "memory_exclusion_list_v2": [ { "violations": [], "path": "\\Application\\TestApp\\MyApp\\program.exe" } ] }, "persona": { "mitigation_actions": [ { "action": "alertsOnly", "threshold": "70" }, { "threshold": "30", "action": "promptUsernameAndPassword" } ], "admin_whitelist": [ { "username": "admin" } ], "mode": "1" }, "device_control": { "configurations": [ { "device_class": "AndroidUSB", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "iOS" }, { "control_mode": "FullAccess", "device_class": "StillImage" }, { "device_class": "USBCDDVDRW", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "USBDrive" }, { "device_class": "VMWareMount", "control_mode": "FullAccess" }, { "control_mode": "FullAccess", "device_class": "WPD" } ], "exclusion_list": [ { "vendor_id": "1234", "comment": "Test external device", "serial_number": null, "product_id": "5678", "control_mode": "FullAccess", "date_added": "2022-02-01T23:56:32.479Z" } ] }, "policy": [ { "value": "1", "name": "auto_blocking" }, { "value": "1", "name": "auto_uploading" }, { "value": "500", "name": "threat_report_limit" }, { "name": "watch_for_new_files", "value": "1" }, { "value": "1", "name": "memory_exploit_detection" }, { "value": "0", "name": "trust_files_in_scan_exception_list" }, { "name": "logpolicy", "value": "1" }, { "name": "script_control", "value": "1" }, { "value": "1", "name": "prevent_service_shutdown" }, { "name": "scan_max_archive_size", "value": "0" }, { "name": "sample_copy_path", "value": "\\\\server_name\\shared_folder" }, { "name": "kill_running_threats", "value": "1" }, { "name": "show_notifications", "value": "1" }, { "value": "1000", "name": "optics_set_disk_usage_maximum_fixed" }, { "name": "optics_malware_auto_upload", "value": "1" }, { "value": "1", "name": "optics_memory_defense_auto_upload" }, { "value": "0", "name": "optics_script_control_auto_upload" }, { "value": "0", "name": "optics_application_control_auto_upload" }, { "name": "optics_sensors_dns_visibility", "value": "1" }, { "value": "1", "name": "optics_sensors_private_network_address_visibility" }, { "name": "optics_sensors_windows_event_log_visibility", "value": "1" }, { "name": "optics_sensors_windows_advanced_audit_visibility", "value": "1" }, { "name": "optics_sensors_advanced_powershell_visibility", "value": "1" }, { "name": "optics_sensors_advanced_wmi_visibility", "value": "1" }, { "name": "optics_sensors_advanced_executable_parsing", "value": "1" }, { "value": "1", "name": "optics_sensors_enhanced_process_hooking_visibility" }, { "value": "1", "name": "optics_sensors_enhanced_file_read_visibility" }, { "name": "device_control", "value": "1" }, { "name": "optics", "value": "1" }, { "name": "auto_delete", "value": "1" }, { "name": "days_until_deleted", "value": "14" }, { "name": "pdf_auto_uploading", "value": "0" }, { "name": "ole_auto_uploading", "value": "0" }, { "value": "0", "name": "docx_auto_uploading" }, { "value": "0", "name": "python_auto_uploading" }, { "value": "0", "name": "autoit_auto_uploading" }, { "value": "0", "name": "powershell_auto_uploading" }, { "value": null, "name": "custom_thumbprint" }, { "value": [ "C:\\Test" ], "name": "scan_exception_list" }, { "value": "1", "name": "optics_show_notifications" } ], "script_control": { "powershell_settings": { "control_mode": "Alert", "console_mode": "Allow" }, "macro_settings": { "control_mode": "Alert" }, "global_settings": { "control_mode": "Alert", "allowed_folders": [ "/users/*/temp/*" ] }, "activescript_settings": { "control_mode": "Alert" } }, "filetype_actions": { "suspicious_files": [ { "actions": "3", "file_type": "executable" } ], "threat_files": [ { "actions": "3", "file_type": "executable" } ] }, "logpolicy": { "retentiondays": "30", "log_upload": { "compress": "True", "delete": "False" }, "maxlogsize": "100" }, "file_exclusions": [ { "reason": "SHA256 for testing", "category_id": "2", "md5": null, "research_class_id": "0", "file_hash": "443010d98917908efb64a1e8c4a560ec126649bd7e4d0ddd87643356e6f3506f", "cloud_score": null, "av_industry": false, "file_name": "Test file", "file_type": 1, "research_subclass_id": "0", "infinity": null } ], "checksum": "", "script_control_v2": { "python_settings": { "control_mode": "Alert" }, "dotnet_dlr_settings": { "control_mode": "Alert" } } } |
Full Disc Scan Setting | Optional | Toggles the policy threat detection setting to full_disc_scan, which enables Cylance to analyze all executable files on disk to detect any dormant threats. Available options are Disable, Run Recurring and Run Once. The default setting is Disabled. | Run Once |
Output
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 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 Cylance Endpoint Security 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: Not Found. |
Error Sample Data Update Devices failed. Status Code: 404. Message: Not Found. |
Update Devices
Updates the devices with the specified policy ID. This command can also be used to initiate a scan task on the devices when the policy is configured to run a scan under Device Policy > Protection Settings > Background Threat Detection > Run Once.
Reader Note
Device IDs and Policy ID are required parameters to run this command.
Run the List Devices command to obtain Device IDs. Device IDs can be found in the raw data at the path $.page_items[*].id.
Run the List Device Policies command to obtain Policy ID. Policy ID can be found in the raw data at the path $.page_items[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Device IDs | Required | The IDs of the devices to update. Device IDs can be obtained by running the List Devices command with no defined parameters. | [ "***-***-***-***-***", "***-***-***-***-***" ] |
Policy ID | Required | The ID of the policy to set on the specified devices. Policy IDs can be obtained by running the List Policies command with no defined parameters. | ***-***-***-***-*** |
Output
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 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 Cylance Endpoint Security 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: Not Found. |
Error Sample Data Update Devices failed. Status Code: 404. Message: Not Found. |
Update Device Threat
Updates the status (i.e. Waive or Quarantine) of the specified threat from an online device.
Reader Note
Device ID and Threat ID are required parameters to run this command.
You should already have your desired Device ID and Threat ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired values.
The input Device ID and Threat ID must correspond in order to run this command. This command can only be used to change the threat status. If the input values do not match, the error message "The threat specified does not exist for this device" will be returned.
Please refer to the screenshot provided to locate the matching Device ID and Threat ID in the returned raw data.
There may be a delay for the threat status to be updated in the API's response data.
If you try to update the device threat with its current status (i.e. quarantine or waive), an error 409 conflict will be returned with the message "____ is already set."
The request will always be successful when you update the device threat status from one status to another. When you update the threat status of an online device, it will take some time for the change to reflect in the API's response data. It's important to note that you cannot change the threat status of an offline device.
To check if the threat status has been updated successfully, you can use the Get Threats By Device command with the device ID. Note: "Waive" corresponds to "Whitelist."
Input
Input Parameter | Required/Optional | Description | Example |
Device ID | Required | The ID of the device to update its threat status. Device IDs can be obtained using the Fetch Event command. | ***-***-***-***-*** |
Threat ID | Required | The threat ID (SHA256 hash) to update. Threat IDs can be obtained using the Fetch Event command. | |
Threat Status | Optional | The status type of the threat. The available input values are Quarantine and Waive. The default value is Quarantine. | Quarantine |
Output
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 Device Threat 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 Cylance Endpoint Security 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 Update Device Threat failed. Status Code: 400. Message: Bad Request. |
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
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 Cylance Endpoint Security 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: Forbidden, failed to get the access token, please check your connection fields. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 403. Message: Forbidden, failed to get the access token, please check your connection fields. |
Use Cases
If you receive the error message "There's already an entry for this threat" while adding hashes using the Add Hashes To Global List command, it means the hash value is already in a global list. You can use the Check Hashes In Global List command with different global list values to determine which list the hash value is in. If you want to switch the global list type, use the Remove Hashes From Global List command with the hash value and current global list type, then add the hash to a different list type using the Add Hashes To Global List command.
The List Device Policies and Get Device Policy Details commands are different in functionality. The List Device Policies command only lists basic information, such as the policy ID and name, whereas the Get Policy Device Details command uses the policy ID to retrieve a more comprehensive set of information, potentially resulting in a large amount of returned data. To prevent impact on system performance, it is recommended to refrain from using the List Device Policies command unless necessary.