Cylance Protect v1.0.0

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

Compatibility with FortiSOAR™ Versions: 4.10.0 and later

Compatibility with CylancePROTECT Versions: v2 and later

Installing the connector

For the procedure to install a connector, click here.

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 the how to work with the Field Value parameter, which is explained in the Working with the Field Value parameter section.

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, select the CylancePROTECT connector and click Configureto configure the following parameters:

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.	get_endpoint_info Investigation
Get Device Threats	Retrieves a list of threats associated with a device that you have specified using the device ID.	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.	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.	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.	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.
Get Global List	Retrieves a list of 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

Parameter	Description
Page Number	(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	(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 containing the information of all the devices connected to CylancePROTECT.

Following image displays a sample output:

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.

Following image displays a sample output:

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

Following image displays a sample output:

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.

Following image displays a sample output:

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.

Following image displays a sample output:

operation: Get Policies

Input parameters

Parameter	Description
Page Number	(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	(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 policies associated with devices connected to CylancePROTECT.

Following image displays a sample output:

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.

Following image displays a sample output:

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

Following image displays a sample output:

operation: Get Threats

Input parameters

Parameter	Description
Page Number	(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	(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 threats detected on your organization's tenant(s) from CylancePROTECT.

Following image displays a sample output:

operation: Get Zones

Input parameters

Parameter	Description
Page Number	(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	(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 information about your organization's zones from CylancePROTECT.

Following image displays a sample output:

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

Following image displays a sample output:

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

Following image displays a sample output:

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.

Following image displays a sample output:

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.

Following image displays a sample output:

Included playbooks

The Sample-CylancePROTECT-1.0.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.