Cylance Protect v2

Overview

Use the Cylance Protect v2 integration to manage endpoints, streamline remediation, and response from Cortex XSOAR.

This integration was integrated and tested with version 2.0.5 rev6 of Cylance Protect and Optics.

Prerequisites

Before you integrate Cylance Protect on Cortex XSOAR, you need to obtain a Cylance token.

1. In Cylance, navigate to Settings > Integrations.
2. Click Add Application.
3. Enter an Application Name, and select the necessary privileges.
4. Click Save.
5. Record the Application ID and Application Secret for later use. You will not be able to access these later.
6. Locate the Tenant ID at the top right side of the Integrations page and record it for later use. 

Configure the Cylance Protect v2 Integration on Cortex XSOAR

1. Navigate to Settings > Integrations > Servers & Services.
2. Search for Cylance Protect v2.
3. Click Add instance to create and configure a new integration instance.
   
   • Name: A textual name for the integration instance.
   • Server URL: URL of Cylance server.
   • Application ID
   • Application Secret
   • Tenant API Key
   • Use system proxy settings
   • File Threshold: Default is -59
   • Fetch Incidents
   • Trust any certificate (not secure)
4. Click Test to validate the URLs and connection.

Understanding the Cylance Score

The Cylance score ranges from -100 to 100, and is translated as follows.

Score translation

Use Cases

• Retrieve and update threats and devices.
• Produce threat data report of indicators.
• Retrieve and create policies and zones.

 Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

1. List console device resources for a tenant: cylance-protect-get-devices
2. Get a console device resource for a tenant: cylance-protect-get-device
3. Update a device: cylance-protect-update-device
4. Get information for device threats: cylance-protect-get-device-threats
5. Get information for console policy resources: cylance-protect-get-policies
6. Create a zone: cylance-protect-create-zone
7. Get information for multiple zones: cylance-protect-get-zones
8. Get information for a single zone: cylance-protect-get-zone
9. Update a zone: cylance-protect-update-zone
10. Get information for a threat: cylance-protect-get-threat
11. Get information for a threat device: cylance-protect-get-threat-devices
12. Generate a report for indicators: cylance-protect-get-indicators-report
13. Get information for threats: cylance-protect-get-threats
14. Update device threats: cylance-protect-update-device-threats
15. Get a list for hashes: cylance-protect-get-list
16. Download a threat: cylance-protect-download-threat
17. Add a hash to a list: cylance-protect-add-hash-to-list
18. Delete a hash from a list: cylance-protect-delete-hash-from-lists
19. Get details of a policy: cylance-protect-get-policy-details
20. Delete devices: cylance-protect-delete-devices
21. Create a new Instaquery: cylance-optics-create-instaquery
22. Get Instaquery result: cylance-optics-get-instaquery-result
23. List current Instaquery: cylance-optics-list-instaquery

1. List console device resources for a tenant

Returns a list of console device resources that belong to a tenant. The list is sorted by registration created date, with the most recent at the top of the list.

Base Command

cylance-protect-get-devices

Input

Context Output

Command Example

!cylance-protect-get-devices pageNumber=2 pageSize=75

Raw Output

{  
   "agent_version":"2.0.1440",
   "date_first_registered":"2018-01-21T15:45:42",
   "id":"652bbfa9-cf74-4e24-90f7-d01b16429701",
   "ip_addresses":[  
      "172.31.31.110"
   ],
   "mac_addresses":[  
      "06-F8-13-8B-16-C9"
   ],
   "name":"WIN-0VJ9RO3P33Q",
   "policy":{  
      "id":null,
      "name":"Default"
   },
   "state":"Online"
}

2. Get a console device resource for a tenant

Returns a single device resource that belongs to a tenant.

Base Command

cylance-protect-get-device

Input

Context Output

Command Example

!cylance-protect-get-devices pageNumber=2 pageSize=75

Raw Output

{  
   "agent_version":"2.0.1440",
   "date_first_registered":"2018-01-21T15:45:42",
   "id":"652bbfa9-cf74-4e24-90f7-d01b16429701",
   "ip_addresses":[  
      "172.31.31.110"
   ],
   "mac_addresses":[  
      "06-F8-13-8B-16-C9"
   ],
   "name":"WIN-0VJ9RO3P33Q",
   "policy":{  
      "id":null,
      "name":"Default"
   },
   "state":"Online"
}

3. Update a device

Updates a specified device.

Base Command

cylance-protect-update-device

Input

Context Output

There is no context output for this command.

Command Example

!cylance-protect-update-device id=652bbfa9-cf74-4e24-90f7-d01b16429701

Raw Output

{  
   "Name":"TestName",
   "PolicyID":"7bcb0817-e9c9-444d-96e2-be9b59f429cb",
   "id":"6033f7a1-e66c-4aef-9c7d-ed454457d071"
}

4. Get information for device threats

Returns information about threats to devices, including classification, threat score, and more.

Base Command

cylance-protect-get-device-threats

Input

Context Output

Command Example

!cylance-protect-get-device-threats id=6033f7a1-e66c-4aef-9c7d-ed454457d071 pageNumber=2 pageSize=75

Raw Output

{  
   "classification":"Malware",
   "cylance_score":-1,
   "date_found":"2017-11-21T17:34:51",
   "file_path":"C:\\$Recycle.Bin\\S-1-5-21-3378384064-522475393-1698893855-1001\\$RPJNCM8\\artifacts\\2017-08-12-Trickbot-binary-from-usdata.estoreseller.com.exe",
   "file_status":"Default",
   "name":"2017-08-12-Trickbot-binary-from-usdata.estoreseller.com.exe",
   "sha256":"5DA547E87D6EF12349FB4DBBA9CF3146A358E284F72361DD07BBABFC95B0BAC3",
   "sub_classification":"Trojan"
}

5. Get information for console policy resources

Returns information for console policy resources.

Base Command

cylance-protect-get-policies

Input

Context Output

Command Example

!cylance-protect-get-policies id=6033f7a1-e66c-4aef-9c7d-ed454457d071 pageNumber=2 pageSize=75

Raw Output

{  
   "date_added":"2018-03-05T12:29:02",
   "date_modified":"2018-03-05T12:29:02",
   "device_count":0,
   "id":"7bcb0817-e9c9-444d-96e2-be9b59f429cb",
   "name":"Test_Policy",
   "zone_count":4
}

6. Create a zone

Creates a zone with a policy ID and criticality level.

Base Command

cylance-protect-create-zone

Input

Context Output

There is no context output for this command.

Command Example

!cylance-protect-create-zone name=TestingZone3 criticality=High

Raw Output

{  
   "criticality":"High",
   "date_created":"2018-03-13T11:38:52.2065082Z",
   "id":"f15b2f79-c100-4146-b056-a8005c13b2de",
   "name":"TestingZone3",
   "policy_id":"7bcb0817-e9c9-444d-96e2-be9b59f429cb"
}

7. Get information for multiple zones

Returns information for multiple zones.

Base Command

cylance-protect-get-zones

Input

Context Output

Command Example

!cylance-protect-get-zones pageNumber=2 pageItems=10

Raw Output

{  
   "criticality":"High",
   "date_created":"2018-03-13T11:38:52",
   "date_modified":"2018-03-13T11:38:52",
   "id":"f15b2f79-c100-4146-b056-a8005c13b2de",
   "name":"TestingZone3",
   "policy_id":"7bcb0817-e9c9-444d-96e2-be9b59f429cb",
   "update_type":"Production",
   "zone_rule_id":null
}

8. Get information for a single zone

Returns information for a single zone.

Base Command

cylance-protect-get-zone

Input

Context Output

Command Example

!cylance-protect-get-zone id=f15b2f79-c100-4146-b056-a8005c13b2de

Raw Output

{  
   "criticality":"High",
   "date_created":"2018-03-13T11:38:52",
   "date_modified":"2018-03-13T11:38:52",
   "id":"f15b2f79-c100-4146-b056-a8005c13b2de",
   "name":"TestingZone3",
   "policy_id":"7bcb0817-e9c9-444d-96e2-be9b59f429cb",
   "update_type":"Production",
   "zone_rule_id":null
}

9. Update a zone

Updates a specified zone.

Base Command

cylance-protect-update-zone

Input

Context Output

There is no context output for this command.

Command Example

!cylance-protect-update-zone id=f15b2f79-c100-4146-b056-a8005c13b2de

Raw Output

true

10. Get information for a threat

Returns information for a threat.

Base Command

cylance-protect-get-threat

Input

Context Output

Command Example

!cylance-protect-get-threat sha256=ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA

Raw Output

{  
   "auto_run":false,
   "av_industry":null,
   "cert_issuer":"",
   "cert_publisher":"",
   "cert_timestamp":"0001-01-01T00:00:00",
   "classification":"Malware",
   "cylance_score":-1,
   "detected_by":"File Watcher",
   "file_size":3514368,
   "global_quarantined":true,
   "md5":"84C82835A5D21BBCF75A61706D8AB549",
   "name":"wanncry.exe",
   "running":false,
   "safelisted":false,
  "sha256":"ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA",
   "signed":false,
   "sub_classification":"Ransom",
   "unique_to_cylance":false
}

11. Get information for a threat device

Returns information for a threat device.

Base Command

cylance-protect-get-threat-devices

Input

Context Output

Command Example

!cylance-protect-get-threat-devices sha256=ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA

Raw Output

{  
   "agent_version":"2.0.1440",
   "date_found":"2018-01-21T15:45:46",
   "file_status":"Whitelisted",
   "id":"652bbfa9-cf74-4e24-90f7-d01b16429701",
   "ip_addresses":"172.31.31.110",
   "mac_addresses":"06-F8-13-8B-16-C9",
   "name":"WIN-0VJ9RO3P33Q",
   "policy_id":null,
   "state":"Online"
}

12. Generate a report for indicators

Generates a report for indicators.

Base Command

cylance-protect-get-indicators-report

Input

Context Output

There is not context output for this command.

Command Example

cylance-protect-get-indicators-report token=As3424$%

Raw Output

There is no raw output for this command.

13. Get information for threats

Returns information for threats.

Base Command

cylance-protect-get-threats

Input

Context Output

Command Example

!cylance-protect-get-threats page_size=4

Raw Output

{  
   "av_industry":null,
   "classification":"Malware",
   "cylance_score":-1,
   "file_size":3514368,
   "global_quarantined":true,
   "last_found":"2018-01-21T15:45:46",
   "md5":"84C82835A5D21BBCF75A61706D8AB549",
   "name":"wanncry.exe",
   "safelisted":false,
   "sha256":"ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA",
   "sub_classification":"Ransom",
   "unique_to_cylance":false
}

14. Update device threats

Updates multiple device threats.

Base Command

cylance-protect-update-device-threats

Input

Context Output

There is no context output for this command.

Command Example

!cylance-protect-update-device-threats threat_id=ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA

Raw Output

true

15. Get a list for hashes

Returns a list for hashes.

Base Command

cylance-protect-get-list

Input

Context Output

Command Example

!cylance-protect-get-list listTypeId=0 page_size=4

Raw Output

{  
   "added":"2017-11-07T04:30:04",
   "added_by":"3ff9b11e-b64e-4350-97ba-aeb0a099b8ee",
   "av_industry":null,
   "category":"",
   "classification":"Malware",
   "cylance_score":-1,
   "list_type":"GlobalQuarantine",
   "md5":"84C82835A5D21BBCF75A61706D8AB549",
   "name":"wanncry.exe",
   "reason":"Malicious File Found",
   "sha256":"ED01EBFBC9EB5BBEA545AF4D01BF5F1071661840480439C6E5BABE8E080E41AA",
   "sub_classification":"Ransom"
}

16. Download a threat

Downloads a threat attached to a specific SHA-256 hash.

Base Command

cylance-protect-download-threat

Input

Context Output

Command Example

!cylance-protect-download-threat sha256="0f427b33b824110427b2ba7be20740b45ea4da41bc1416dd55771edfb0c18f09" unzip="yes"

Context Example

DBotScore
{
  "Indicator": "AutoitLocker.exe",
  "Score": 3,
  "Type": "file",
  "Vendor": "Cylance Protect"
}
File
{
  "DownloadURL":       "https://cylanceephemeralfilestore.s3.amazonaws.com/0F/42/7B/33/0F427B33B824110427B2BA7BE20740B45EA4DA41BC1416DD55771EDFB0C18F09.zip? Signature=98kI7a19I2q%2BeE7Ef1un4BjSolQ%3D&Expires=1541875473&AWSAccessKeyId=AKIAIAD6JC2YTYVBFRFA",
  "MD5": "2FC103D0D52466B63D44444CE12A5901",
  "Malicious": {
  "Description": "Score determined by get threat command",
  "Vendor": "Cylance Protect"
},
  "Name": "AutoitLocker.exe",
  "SHA256": "0F427B33B824110427B2BA7BE20740B45EA4DA41BC1416DD55771EDFB0C18F09",
  "Safelisted": false,
  "Size": 405345,
  "Timestamp": "0001-01-01T00:00:00"
}

Human Readable Output

17. Add a hash to a list

Adds an identified threat to either the Global Quarantine list or the Global Safe list for a particular Tenant.

Base Command

cylance-protect-add-hash-to-list

Input

Context Output

Command Example

!cylance-protect-add-hash-to-list sha256="9ACD45F5F3F2C7629E51FE3123D31296EF763F6ABC1F895CDD1BF1AFB9A7453B" listType="GlobalQuarantine"

Human Readable Output

18. Remove a threat from a list

Removes an identified threat from either the Global Quarantine list or the Global Safe list for a particular Tenant.

Base Command

cylance-protect-delete-hash-from-lists

Input

Context Output

Command Example

!cylance-protect-delete-hash-from-lists sha256="9ACD45F5F3F2C7629E51FE3123D31296EF763F6ABC1F895CDD1BF1AFB9A7453B" listType="GlobalQuarantine"

Human Readable Output

19. Get details for a policy

Gets details for a single policy.

Base Command

cylance-protect-get-policy-details

Input

Context Output

20. Delete devices

Deletes one or more devices from an organization.

Base Command

cylance-protect-delete-devices

Input

Context Output

Command Example

!cylance-protect-get-policy-details policyID="7bcb0817-e9c9-444d-96e2-be9b59f429cb"

Context Example

Cylance
{
  "Policy": {
  "ID": "7bcb0817-e9c9-444d-96e2-be9b59f429cb",
  "Name": "Test_Policy",
  "Timestamp": "2018-03-05T12:29:03.000000+00:00"
               }
}

Human Readable Output

cylance-protect-get-device-by-hostname

Allows a caller to request a specific device resource belonging to a Tenant by hostname

Base Command

cylance-protect-get-device-by-hostname

Input

Context Output

Command Example

!cylance-protect-get-device-by-hostname hostname=WIN-5HMOGIEG6M5

Context Example

{
    "CylanceProtect": {
        "Device": {
            "AgentVersion": "1.2.1418",
            "BackgroundDetection": false,
            "DateFirstRegistered": "2017-12-29T04:07:56",
            "DateLastModified": null,
            "DateOffline": "2020-02-07T02:25:34.151",
            "Hostname": "WIN-5HMOGIEG6M5",
            "ID": "b4eceeb0-8699-4d42-b853-155513042d6e",
            "IPAddress": [
                "127.0.0.1"
            ],
            "IsSafe": true,
            "LastLoggedInUser": "",
            "MACAdress": [
                "02-76-91-6B-0A-BB"
            ],
            "Name": "WIN-5HMOGIEG6M5",
            "OSVersion": "Microsoft Windows Server 2012 R2 Standard",
            "Policy": {
                "ID": "32e4aacd-7698-4ef0-93e8-3e6f1f5c6857",
                "Name": "Default"
            },
            "State": "Offline",
            "UpdateAvailable": false
        }
    },
    "Endpoint": {
        "Hostname": "WIN-5HMOGIEG6M5",
        "IPAddress": [
            "127.0.0.1"
        ],
        "MACAdress": [
            "02-76-91-6B-0A-BB"
        ],
        "OSVersion": "Microsoft Windows Server 2012 R2 Standard"
    }
}

Human Readable Output

Cylance Protect Device WIN-5HMOGIEG6M5

AgentVersion	BackgroundDetection	DateFirstRegistered	DateOffline	DlcmStatus	HostName	Id	IpAddresses	IsSafe	MacAddresses	Name	OsKernelVersion	OsVersion	Policy	Products	State	UpdateAvailable
1.2.1418	false	2017-12-29T04:07:56	2020-02-07T02:25:34.151	Unknown	WIN-5HMOGIEG6M5	b4eceeb0-8699-4d42-b853-155513042d6e	127.0.0.1	true	02-76-91-6B-0A-BB	WIN-5HMOGIEG6M5	6.3.0	Microsoft Windows Server 2012 R2 Standard	Default	{u’status’: u’Offline’, u’version’: u’1.2.1418’, u’name’: u’protect’}	Offline	false

21. Create a new Instaquery

cylance-optics-create-instaquery

Create a cylance InstaQuery

Base Command

cylance-optics-create-instaquery

Input

Context Output

Command Example

!cylance-optics-create-instaquery name="Test Insta continue" description="Test only" artifact="File" match_value_type="File.Path" match_values="exe" zone="6608ca0e-88c6-4647-b276-271cc5ea4295" match_type="Fuzzy"

Human Readable Output

22. Get Instaquery result

cylance-optics-get-instaquery-result

Get a cylance InstaQuery search result

Base Command

cylance-optics-get-instaquery-result

Input

Context Output

Command Example

!cylance-optics-get-instaquery-result query_id=9E2CCDA5A93918C588E6865ED6FEEA70

Human Readable Output

23. List current Instaqueries

cylance-optics-list-instaquery

Get a list of InstaQuery

Base Command

cylance-optics-list-instaquery

Input

Context Output

Command Example

!cylance-optics-list-instaquery page_size="10"

Human Readable Output