Fortinet Document Library

Version:


Table of Contents

Cylance Protect

1.1.0
Copy Link

About the connector

CylancePROTECT is an antivirus and application control solution for fixed-function devices that leverages artificial intelligence to detect and prevent malware from executing on endpoints in real time. CylanceV is a solution for local integration into network appliances, endpoint software, and services platforms.

This document provides information about the CylancePROTECT connector, which facilitates automated interactions, with a CylancePROTECT API server using FortiSOAR™ playbooks. Add the CylancePROTECT connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving information about devices connected to CylancePROTECT, retrieving a list of threats for a specific device from CylancePROTECT, and retrieving a list of device policies from CylancePROTECT.

Version information

Connector Version: 1.1.0

FortiSOAR™ Version Tested on: 5.0.0-866

CylancePROTECT Version Tested on: v2 and later

Release Notes for version 1.1.0

Following enhancements have been made to the CylancePROTECT connector in version 1.1.0:

  • Added the Found Since parameter to the "Get Threats" operation using which you can specify the datetime from when you want to pull threats found in CylancePROTECT. 

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-cylance-protect

Prerequisites to configuring the connector

  • You must have the URL of the CylancePROTECT server to which you will connect and perform the automated operations and the Application ID and Secret and Tenant ID to access that server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
  • For the Update Device Information operation to work, you must know how to work with the Field Value parameter, which is explained in the Working with the Field Value parameter section.
  • Ensure that your CylancePROTECT server time and  FortiSOAR™ instance time is synchronized.

Working with the Field Value parameter

This section is optional and only required if you are going to perform the Update Device Information operation. The Update Device Information operation has the Field Value as an input parameter. The Field Value parameter requires to be in the dictionary (dict) format. Following is the explanation of how the Field Value parameter works and how you must enter the value for this parameter in FortiSOAR™. A Fields Value parameter contains a Key-Value pair.

Key: The Key contains the name of the device or the policy ID of the device or the add zone IDs or the remove zone IDs.

Value: The value of the fields are in the following value formats:

{
    "name": "string",
    "policy_id": "string:{policy guid}",
     "add_zone_ids": [“string:{zone guid}" ],
    "remove_zone_ids": [ “string:{zone guid}"]
 }

Example of what you can enter in the Device Schema parameter in the Update Device Information operation as an input:

{
    "name": "prod",
    "policy_id": "0c9ca537-583f-406a-bf68-530421fadeee"
 }

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the CylancePROTECT connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
API Server URL URL of the CylancePROTECT API server to which you will connect and perform the automated operations.
Tenant ID Tenant ID that you have been provided for your instance.
Application ID CylancePROTECT API application has a unique API ID that is used to create an authentication token that you can use to access the API.
Application Secret CylancePROTECT API application has a unique API Secret that is used to create an authentication token that you can use to access the API.
API Token Timeout (1 - 1800 seconds) Time in seconds after which the token for the CylancePROTECT API will timeout.
For example, if you set this to 600 then after every 600 seconds the CylancePROTECT API will generate a new token.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Devices Retrieves a list that contains the information about all the devices connected to CylancePROTECT. get_endpoints
Investigation
Get Device Information Retrieves information about a device that you have specified using the device ID from CylancePROTECT. get_endpoint_info
Investigation
Get Device Threats Retrieves a list of threats associated with a device that you have specified using the device ID from CylancePROTECT. get_endpoint_threat
Investigation
Update Device Information Updates information of a device on CylancePROTECT based on the device ID and parameters that you have specified in CylancePROTECT. update_endpoint
Miscellaneous
Update Device Threat Updates the status that you have set for a specified filehash on a specific device on CylancePROTECT based on the device ID that you have specified. You can set the status for the threat as either Quarantine or Waive. update_threat_status
Miscellaneous
Get Policies Retrieves a list of policies associated with devices connected to CylancePROTECT. get_policy
Investigation
Get Threat Details Retrieves information about a threat that you have specified using the filehash (SHA256 only) value from CylancePROTECT. get_threat_details
Investigation
Get Threat Devices Retrieves a list of devices on which the threat that you have specified using the filehash (SHA256 only) value is found in CylancePROTECT. get_endpoint_threat
Investigation
Get Threats Retrieves a list of all threats detected on your organization's tenant(s) from CylancePROTECT. get_threats
Investigation
Get Zones Retrieves information about your organization's zones from CylancePROTECT.  
Get Device Zones Retrieves a list of zones that are assigned to the device you have specified using device ID from CylancePROTECT.  
Get Global List Retrieves a list of file hashes from the global quarantine list or the global safe list in CylancePROTECT. get_files_details
Investigation
Block Hash Adds a filehash to the global quarantine list or the global safe list in CylancePROTECT. block_hash
Containment
Unblock Hash Removes a filehash to the global quarantine list or the global safe list in CylancePROTECT. unblock_hash
Remediation

operation: Get Devices

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.  

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list containing the information of all the devices connected to CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "state": "", 
             "agent_version": "", 
             "ip_addresses": [], 
             "name": "", 
             "date_first_registered": "", 
             "policy": { 
                 "name": "", 
                 "id": "" 
             }, 
             "mac_addresses": [], 
             "id": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Device Information

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve information from CylancePROTECT.

Output

The JSON output retrieves information about a device connected to CylancePROTECT based on the device ID you have specified.

The output contains the following populated JSON schema:

     "policy": { 
         "name": "", 
         "id": "" 
     }, 
     "update_available": "", 
     "mac_addresses": [], 
     "name": "", 
     "last_logged_in_user": "", 
     "id": "", 
     "date_offline": " ", 
     "background_detection": "", 
     "state": "", 
     "agent_version": "", 
     "ip_addresses": [], 
     "is_safe": "", 
     "update_type": "", 
     "date_first_registered": "", 
     "date_last_modified": "" 
}

operation: Get Device Threats

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve associated threats from CylancePROTECT.
Page Number  (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of threats associated with a device based on the device ID you have specified.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "file_path": "", 
             "classification": "", 
             "cylance_score": "", 
             "date_found": "", 
             "file_status": "", 
             "sha256": "", 
             "name": "", 
             "sub_classification": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Update Device Information

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to update information in CylancePROTECT.
Device Schema This parameter must be in the dict format and contains a Key-Value pair. For more information, see the Working with the Field Value parameter section.

Output

The JSON output returns a Success message if the specified device is updated with the specified inputs, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Update Device Threat

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to update threat status in CylancePROTECT.
Filehash (Only SHA256) Filehash of the threat whose status you want to update on the specific device in CylancePROTECT.
Event Status of the threat that you want to set. Choose between Quarantine or Waive.
Important: You cannot change the status of the threat if you set the status of the threat to Quarantine.
For example, if you have set the status of the threat to Quarantine, then you cannot change the status of this threat to Waive. However, if you have set the status of the threat to Waive, then you can change the status of this threat to Quarantine.

Output

The JSON output returns a Success message if the specified device is updated with the status that you have set for the specified filehash, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Get Policies

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned. 

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of policies associated with devices connected to CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "device_count": "", 
             "date_added": "", 
             "zone_count": "", 
             "id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Threat Details

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat for which you want to retrieve information from CylancePROTECT.

Output

The JSON output retrieves information about the threat from CylancePROTECT based on the Filehash you have specified.

The output contains the following populated JSON schema:

     "global_quarantine": "", 
     "file_size": "", 
     "classification": "", 
     "running": "", 
     "av_industry": "", 
     "detected_by": "", 
     "name": "", 
     "md5": "", 
     "cert_issuer": "", 
     "sub_classification": "", 
     "cert_timestamp": "", 
     "cylance_score": "", 
     "signed": "", 
     "unique_to_cylance": "", 
     "sha256": "", 
     "auto_run": "", 
     "safelisted": "", 
     "cert_publisher": "" 
}

operation: Get Threat Devices

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat for which you want to retrieve associated device information from CylancePROTECT.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of all devices on which the specified threat (using the threat's Filehash value) is found.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "state": "", 
             "agent_version": "", 
             "ip_addresses": [], 
             "date_found": "", 
             "policy_id": "", 
             "id": "", 
             "mac_addresses": [], 
             "file_status": "", 
             "name": "", 
             "file_path": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Threats

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.   

Parameter Description
Found Since

Datetime from when you want to pull threats that are found in CylancePROTECT.

Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of all threats detected on your organization's tenant(s) from CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "last_found": "", 
             "file_size": "", 
             "classification": "", 
             "av_industry": "", 
             "name": "", 
             "md5": "", 
             "sub_classification": "", 
             "global_quarantined": "", 
             "cylance_score": "", 
             "unique_to_cylance": "", 
             "sha256": "", 
             "safelisted": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Zones

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.   

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves information about your organization's zones from CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "criticality": "", 
             "date_created": "", 
             "policy_id": "", 
             "update_type": "", 
             "id": "", 
             "zone_rule_id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Device Zone

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve zone information from CylancePROTECT.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of zones that are assigned to the device you have specified using device ID.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "criticality": "", 
             "date_created": "", 
             "policy_id": "", 
             "update_type": "", 
             "id": "", 
             "zone_rule_id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Global List

Input parameters

Parameter Description
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of file hashes from the Global Quarantine List or the Global Safe List in CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "added_by": "", 
             "added": "", 
             "classification": "", 
             "av_industry": "", 
             "category": "", 
             "name": "", 
             "md5": "", 
             "sub_classification": "", 
             "cylance_score": "", 
             "sha256": "", 
             "reason": "", 
             "list_type": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Block Hash

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat that you want to add to the Global Quarantine List or the Global Safe List in CylancePROTECT.
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.
Category Required only if the list type is the Global Safe List. Choose one of the following categories:
Drivers
None
Important: There are other categories, such as Admin Tool, Internal Application, etc, present in the Global Safe List, which are currently not supported.
Reason Reason why you want to add this file to the Global Quarantine List or the Global Safe List.
File Name (Optional) Name of the file that you want to add to the Global Quarantine List or the Global Safe List.

Output

The JSON output returns a Success message if the filehash you have specified is successfully added to the Global Quarantine List or the Global Safe List in CylancePROTECT or an Errormessage containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Unblock Hash

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat that you want to remove from the Global Quarantine List or Global Safe List in CylancePROTECT.
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.

Output

The JSON output returns a Success message if the filehash you have specified is successfully removed from the Global Quarantine List or the Global Safe List in CylancePROTECT or an Errormessage containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

Included playbooks

The Sample-CylancePROTECT-1.1.0 playbook collection comes bundled with the CylancePROTECT connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CylancePROTECT connector.

  • Block Hash
  • Get Device Information
  • Get Devices
  • Get Device Threats
  • Get Global List
  • Get Policies
  • Get Threat Details
  • Get Threat Devices
  • Get Threats
  • Get Device Zones
  • Get Zones
  • Unblock Hash
  • Update Device Information
  • Update Device Threat

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

About the connector

CylancePROTECT is an antivirus and application control solution for fixed-function devices that leverages artificial intelligence to detect and prevent malware from executing on endpoints in real time. CylanceV is a solution for local integration into network appliances, endpoint software, and services platforms.

This document provides information about the CylancePROTECT connector, which facilitates automated interactions, with a CylancePROTECT API server using FortiSOAR™ playbooks. Add the CylancePROTECT connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving information about devices connected to CylancePROTECT, retrieving a list of threats for a specific device from CylancePROTECT, and retrieving a list of device policies from CylancePROTECT.

Version information

Connector Version: 1.1.0

FortiSOAR™ Version Tested on: 5.0.0-866

CylancePROTECT Version Tested on: v2 and later

Release Notes for version 1.1.0

Following enhancements have been made to the CylancePROTECT connector in version 1.1.0:

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-cylance-protect

Prerequisites to configuring the connector

Working with the Field Value parameter

This section is optional and only required if you are going to perform the Update Device Information operation. The Update Device Information operation has the Field Value as an input parameter. The Field Value parameter requires to be in the dictionary (dict) format. Following is the explanation of how the Field Value parameter works and how you must enter the value for this parameter in FortiSOAR™. A Fields Value parameter contains a Key-Value pair.

Key: The Key contains the name of the device or the policy ID of the device or the add zone IDs or the remove zone IDs.

Value: The value of the fields are in the following value formats:

{
    "name": "string",
    "policy_id": "string:{policy guid}",
     "add_zone_ids": [“string:{zone guid}" ],
    "remove_zone_ids": [ “string:{zone guid}"]
 }

Example of what you can enter in the Device Schema parameter in the Update Device Information operation as an input:

{
    "name": "prod",
    "policy_id": "0c9ca537-583f-406a-bf68-530421fadeee"
 }

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the CylancePROTECT connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
API Server URL URL of the CylancePROTECT API server to which you will connect and perform the automated operations.
Tenant ID Tenant ID that you have been provided for your instance.
Application ID CylancePROTECT API application has a unique API ID that is used to create an authentication token that you can use to access the API.
Application Secret CylancePROTECT API application has a unique API Secret that is used to create an authentication token that you can use to access the API.
API Token Timeout (1 - 1800 seconds) Time in seconds after which the token for the CylancePROTECT API will timeout.
For example, if you set this to 600 then after every 600 seconds the CylancePROTECT API will generate a new token.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Devices Retrieves a list that contains the information about all the devices connected to CylancePROTECT. get_endpoints
Investigation
Get Device Information Retrieves information about a device that you have specified using the device ID from CylancePROTECT. get_endpoint_info
Investigation
Get Device Threats Retrieves a list of threats associated with a device that you have specified using the device ID from CylancePROTECT. get_endpoint_threat
Investigation
Update Device Information Updates information of a device on CylancePROTECT based on the device ID and parameters that you have specified in CylancePROTECT. update_endpoint
Miscellaneous
Update Device Threat Updates the status that you have set for a specified filehash on a specific device on CylancePROTECT based on the device ID that you have specified. You can set the status for the threat as either Quarantine or Waive. update_threat_status
Miscellaneous
Get Policies Retrieves a list of policies associated with devices connected to CylancePROTECT. get_policy
Investigation
Get Threat Details Retrieves information about a threat that you have specified using the filehash (SHA256 only) value from CylancePROTECT. get_threat_details
Investigation
Get Threat Devices Retrieves a list of devices on which the threat that you have specified using the filehash (SHA256 only) value is found in CylancePROTECT. get_endpoint_threat
Investigation
Get Threats Retrieves a list of all threats detected on your organization's tenant(s) from CylancePROTECT. get_threats
Investigation
Get Zones Retrieves information about your organization's zones from CylancePROTECT.  
Get Device Zones Retrieves a list of zones that are assigned to the device you have specified using device ID from CylancePROTECT.  
Get Global List Retrieves a list of file hashes from the global quarantine list or the global safe list in CylancePROTECT. get_files_details
Investigation
Block Hash Adds a filehash to the global quarantine list or the global safe list in CylancePROTECT. block_hash
Containment
Unblock Hash Removes a filehash to the global quarantine list or the global safe list in CylancePROTECT. unblock_hash
Remediation

operation: Get Devices

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.  

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list containing the information of all the devices connected to CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "state": "", 
             "agent_version": "", 
             "ip_addresses": [], 
             "name": "", 
             "date_first_registered": "", 
             "policy": { 
                 "name": "", 
                 "id": "" 
             }, 
             "mac_addresses": [], 
             "id": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Device Information

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve information from CylancePROTECT.

Output

The JSON output retrieves information about a device connected to CylancePROTECT based on the device ID you have specified.

The output contains the following populated JSON schema:

     "policy": { 
         "name": "", 
         "id": "" 
     }, 
     "update_available": "", 
     "mac_addresses": [], 
     "name": "", 
     "last_logged_in_user": "", 
     "id": "", 
     "date_offline": " ", 
     "background_detection": "", 
     "state": "", 
     "agent_version": "", 
     "ip_addresses": [], 
     "is_safe": "", 
     "update_type": "", 
     "date_first_registered": "", 
     "date_last_modified": "" 
}

operation: Get Device Threats

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve associated threats from CylancePROTECT.
Page Number  (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of threats associated with a device based on the device ID you have specified.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "file_path": "", 
             "classification": "", 
             "cylance_score": "", 
             "date_found": "", 
             "file_status": "", 
             "sha256": "", 
             "name": "", 
             "sub_classification": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Update Device Information

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to update information in CylancePROTECT.
Device Schema This parameter must be in the dict format and contains a Key-Value pair. For more information, see the Working with the Field Value parameter section.

Output

The JSON output returns a Success message if the specified device is updated with the specified inputs, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Update Device Threat

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to update threat status in CylancePROTECT.
Filehash (Only SHA256) Filehash of the threat whose status you want to update on the specific device in CylancePROTECT.
Event Status of the threat that you want to set. Choose between Quarantine or Waive.
Important: You cannot change the status of the threat if you set the status of the threat to Quarantine.
For example, if you have set the status of the threat to Quarantine, then you cannot change the status of this threat to Waive. However, if you have set the status of the threat to Waive, then you can change the status of this threat to Quarantine.

Output

The JSON output returns a Success message if the specified device is updated with the status that you have set for the specified filehash, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Get Policies

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned. 

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of policies associated with devices connected to CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "device_count": "", 
             "date_added": "", 
             "zone_count": "", 
             "id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Threat Details

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat for which you want to retrieve information from CylancePROTECT.

Output

The JSON output retrieves information about the threat from CylancePROTECT based on the Filehash you have specified.

The output contains the following populated JSON schema:

     "global_quarantine": "", 
     "file_size": "", 
     "classification": "", 
     "running": "", 
     "av_industry": "", 
     "detected_by": "", 
     "name": "", 
     "md5": "", 
     "cert_issuer": "", 
     "sub_classification": "", 
     "cert_timestamp": "", 
     "cylance_score": "", 
     "signed": "", 
     "unique_to_cylance": "", 
     "sha256": "", 
     "auto_run": "", 
     "safelisted": "", 
     "cert_publisher": "" 
}

operation: Get Threat Devices

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat for which you want to retrieve associated device information from CylancePROTECT.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of all devices on which the specified threat (using the threat's Filehash value) is found.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "state": "", 
             "agent_version": "", 
             "ip_addresses": [], 
             "date_found": "", 
             "policy_id": "", 
             "id": "", 
             "mac_addresses": [], 
             "file_status": "", 
             "name": "", 
             "file_path": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Threats

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.   

Parameter Description
Found Since

Datetime from when you want to pull threats that are found in CylancePROTECT.

Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of all threats detected on your organization's tenant(s) from CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "last_found": "", 
             "file_size": "", 
             "classification": "", 
             "av_industry": "", 
             "name": "", 
             "md5": "", 
             "sub_classification": "", 
             "global_quarantined": "", 
             "cylance_score": "", 
             "unique_to_cylance": "", 
             "sha256": "", 
             "safelisted": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Zones

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.   

Parameter Description
Page Number (e.g 1-10) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves information about your organization's zones from CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "criticality": "", 
             "date_created": "", 
             "policy_id": "", 
             "update_type": "", 
             "id": "", 
             "zone_rule_id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Device Zone

Input parameters

Parameter Description
Device ID Unique ID of the device for which you want to retrieve zone information from CylancePROTECT.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of zones that are assigned to the device you have specified using device ID.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "criticality": "", 
             "date_created": "", 
             "policy_id": "", 
             "update_type": "", 
             "id": "", 
             "zone_rule_id": "", 
             "name": "", 
             "date_modified": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Get Global List

Input parameters

Parameter Description
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.
Page Number (e.g 1-10) (Optional) Page number from which you want to request for data.
This is optional query string parameter and if you do not specify any value, then this defaults to 1.
Record Per Page (e.g 1-200) (Optional) Number of records that you want to retrieve per page.
This is optional query string parameter and if you do not specify any value, then this defaults to 100.

Output

The JSON output retrieves a list of file hashes from the Global Quarantine List or the Global Safe List in CylancePROTECT.

The output contains the following populated JSON schema:

     "page_number": "", 
     "total_number_of_items": "", 
     "page_items": [ 
         { 
             "added_by": "", 
             "added": "", 
             "classification": "", 
             "av_industry": "", 
             "category": "", 
             "name": "", 
             "md5": "", 
             "sub_classification": "", 
             "cylance_score": "", 
             "sha256": "", 
             "reason": "", 
             "list_type": "" 
         } 
     ], 
     "page_size": "", 
     "total_pages": "" 
}

operation: Block Hash

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat that you want to add to the Global Quarantine List or the Global Safe List in CylancePROTECT.
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.
Category Required only if the list type is the Global Safe List. Choose one of the following categories:
Drivers
None
Important: There are other categories, such as Admin Tool, Internal Application, etc, present in the Global Safe List, which are currently not supported.
Reason Reason why you want to add this file to the Global Quarantine List or the Global Safe List.
File Name (Optional) Name of the file that you want to add to the Global Quarantine List or the Global Safe List.

Output

The JSON output returns a Success message if the filehash you have specified is successfully added to the Global Quarantine List or the Global Safe List in CylancePROTECT or an Errormessage containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

operation: Unblock Hash

Input parameters

Parameter Description
Filehash (Only SHA256) Filehash of the threat that you want to remove from the Global Quarantine List or Global Safe List in CylancePROTECT.
List Type The list type to which the threat belongs. Choose between Global Quarantine List or Global Safe List.

Output

The JSON output returns a Success message if the filehash you have specified is successfully removed from the Global Quarantine List or the Global Safe List in CylancePROTECT or an Errormessage containing the reason for failure.

The output contains the following populated JSON schema:

     "status": "" 
}

Included playbooks

The Sample-CylancePROTECT-1.1.0 playbook collection comes bundled with the CylancePROTECT connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the CylancePROTECT connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.