Skip to main content
Skip table of contents

Blackberry Cylance Endpoint Security

LAST UPDATED: SEPTEMBER 18, 2025

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

Option I, Option III

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

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

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

  1. Log in to Cylance.

  2. Navigate to Settings > Integrations.

  3. Click Copy to save the Tenant ID to the clipboard. Click + Add Application to create an application.

    Skip this step if an application has already been created.

  4. Name the application, then select privileges. Save the application configurations. Enable all privileges listed in the table below to allow the connection to run all Cylance integration commands.

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

  1. After creating an application, the corresponding Application ID and Application Secret will be shown. Store these values securely for building a D3 connection. Click OK.

  2. View the Application ID and Secret by clicking the Pencil icon.

Configuring D3 SOAR to Work with Cylance Endpoint Security.

  1. Log in to D3 SOAR.

  2. Find the Cylance Endpoint Security integration.

    screenshot_1 (3).png

    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type Cylance Endpoint Security in the search box to find the integration, then click it to select it.

    4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.

  3. Configure the following fields to create a connection to Cylance Endpoint Security.

    screenshot_2 (3).png

    1. Connection Name: The desired name for the connection.

    2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all 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 is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.

    4. Agent Name (Optional): 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): The description for the connection.

    6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.

      att_1_for_211845286.png

    7. Configure User Permissions: Defines which users have access to the connection.

    8. Active: The checkbox that enables the connection to be used when selected.

      screenshot_3 (3).png

    9. 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. Refer to step 3 of Configuring Cylance Endpoint Security to Work with D3 SOAR for more details.
      3. Input your Application ID. Refer to step 5 of Configuring Cylance Endpoint Security to Work with D3 SOAR for more details.
      4. Input your Application Secret. Refer to 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.

    10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.

    11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.

  4. Test the connection.

    screenshot_4 (2).png

    1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.

    2. Click OK to close the alert window.

    3. 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, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Cylance Endpoint Security API, refer to the Cylance Endpoint Security API reference.

READER NOTE

Certain permissions are required for each command. 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 user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

  1. Navigate to Configuration > Application Settings. Select Date/Time Format.

  2. Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

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.

View Sample Code

JSON 
{
  "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

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***",
  "***"
]

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

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***",
  "***"
]

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

To view the sample output data for all commands, refer to this article.

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

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

See Field Mappings. 

The Cylance system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data. 

The Main Event JSON Path can be viewed by clicking on the Edit Main JSON Path button.

field_mapping (4).png

  • Main Event JSON Path: $.page_items
    The page_items array contains the event objects. Within each object, the key sha256 denotes the Unique Event Key field. As such, the full JSONPath expression to extract the Unique Event Key is $.page_items.sha256.

The pre-configured field mappings are detailed below:

Field Name

Source Field

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

JSON 
[
  "***-**-***-***-***",
  "***-**-***-***-***"
]

Output

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***-**-***-***-***",
  "***-**-***-***-***"
]

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.

JSON 
[
  "***-**-***",
  "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

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***-**-***-***-***",
  "***-**-***-***-***"
]

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.

JSON 
[
  "**-**-**-**-**-**",
  "**-**-**-**-**-**"
]

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.

JSON 
[
  "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

To view the sample output data for all commands, refer to this article.

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

To view the sample output data for all commands, refer to this article.

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

d75a*****5ca2

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

To view the sample output data for all commands, refer to this article.

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

To view the sample output data for all commands, refer to this article.

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 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[ "e75c*****6d14" ] will be transformed to [ "E75C*****6D14" ].

JSON 
[
  "***-***-***-***-***",
  "***-***-***-***-***",
  "***-***-***-***-***"
]

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

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***",
  "***"
]

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

To view the sample output data for all commands, refer to this article.

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

View Sample Code

JSON 
{
  "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

To view the sample output data for all commands, refer to this article.

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

JSON 
[
  "***-***-***-***-***",
  "***-***-***-***-***"
]

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

To view the sample output data for all commands, refer to this article.

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

To view the sample output data for all commands, refer to this article.

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

Output Type

Description

Return Data Type

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

More details about an error can be viewed in the Error tab.

String

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

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

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close