BlackBerry CylancePROTECT, CylanceOPTICS User Manual

Download

Cylance® API

User API v2.0 Guide

Product:CylancePROTECT® and CylanceOPTICS

Document:Cylance APIGuide. This guide is a succinct

resource for analysts, administrators, and customers who are reviewing or evaluating the product.

Document Release Date:v2.0 rev34, December 2020

About BlackBerry Cylance®: BlackBerry Cylance

develops artificial intelligence to deliver prevention-first, predictive security products and smart, simple, secure solutions that change how organizations approach endpoint security. BlackBerry Cylance provides fullspectrum predictive threat prevention and visibility across the enterprise to combat the most notorious and advanced cybersecurity attacks, fortifying endpoints to promote security hygiene in the security operations center, throughout global networks, and even on employees’ home networks. With AI-based malware prevention, threat hunting, automated detection and response, and expert security services, BlackBerry Cylance protects the endpoint without increasing staff workload or costs.

Reserved.

- 3 -

Contents

Table of Contents

Application Management

Application Management 10

To Add an Application 10

To Edit an Application 13

To Delete an Application 14

To Regenerate an Application Control 15

Copy Tenant ID 16

API in Audit Logs 16

RESTful API

Authentication and Authorization 19

Application 19

Service Endpoint 19

Authentication 20

Authentication Token 20

Generating the Authentication and Access Tokens 21

Token Lifecycle 23

Request / Response Model 23

Authorization 24

Access Token 24

Response Status Codes 24

API Rate Limit 25

About Device ID 25

About Zone ID 26

User API

Create User 28

Get Users 31

Get User 34

Update User 36

Delete User 38

Send Invite Email 39

Send Request Password Email 41

Device API

Cylance User APIGuide, v2.0 rev34, December 2020 | 4

Get Devices 43

Get Devices Extended 46

Get Device Count 49

Get Device 51

Get Device by MAC Address 53

Get Device by Hostname 56

Update Device 59

Get Device Threat 60

Update Device Threat 62

Get Zone Devices 64

Get Agent Installer Link 65

Delete Devices 68

Global List API

Get Global List 72

Add to Global List 74

Delete From Global List 76

Policy API

Get Policies 79

Get Policy 81

Create Policy 98

Update Policy 121

Delete Policy 140

Delete Policies 141

Zone API

Create Zone 143

Get Zones 144

Get Zone 146

Get Device Zones 148

Update Zone 149

142

Delete Zone 151

Threat API

Get Threats 153

Get Threat 156

Get Threat Devices 158

Cylance User APIGuide, v2.0 rev34, December 2020 | 5

152

Get Threat Download URL 161

Memory Protection API

Get Memory Protection Events 164

Get Memory Protection Event 166

Memory Violation Types 168

Detection API

Get Detections 172

Get Detection 175

Get Recent Detections 182

Get Detections CSV 183

Get Detections By Severity 186

Update Detection 188

Delete Detection 190

Delete Detections 191

Package Deployment API

Create Package 193

Get Packages 195

Get Package 199

163

171

192

Delete Package 201

Create Package Execution 202

Get Package Executions 206

Get Package Execution 210

Delete Package Execution 212

Detection Rule API

Get Detection Rule List 216

Get Detection Rule CSV List 219

Get Detection Rule 220

Validate Detection Rule 224

Create Detection Rule 227

Update Detection Rule 232

Deactivate or Delete Detection Rule 237

Get Detection Rule Natural Language Representation 238

Get Detection Rule Counts 239

Detection Rule Sets

215

241

Cylance User APIGuide, v2.0 rev34, December 2020 | 6

Get Detection Rule Set List 242

Get Detection Rule Set CSV List 245

Get Detection Rule Set 246

Create Detection Rule Set 250

Retrieve Default Detection Rule Set 255

Update Detection Rule Set 258

Delete Detection Rule Set 262

Delete Multiple Detection Rule Sets 263

Detection Exceptions

Get Detection Exceptions List 266

Get Detection Exception CSV List 268

Get Detection Exception Content 269

Create Detection Exception 271

Update Detection Exception 275

Deactivate / Delete Detection Exception 278

Device Commands

Device Commands 281

Lockdown Device Command 281

Get Device Lockdown History 283

Get Retrieved File Results 284

Request File Retrieval From Device 287

Check File Retrieval Status From Device 289

Focus View

Focus View 293

Get Focus View List 293

265

280

292

Search for Focus View Results 296

Request a Focus View 298

Get a Focus View Summary 301

Get Focus View Results 304

InstaQuery

InstaQuery 307

Get InstaQueries 307

Create InstaQuery 310

Get InstaQuery 314

Cylance User APIGuide, v2.0 rev34, December 2020 | 7

306

Get InstaQuery Results 318

Archive InstaQuery 321

CylanceOPTICS Policy

CylanceOPTICS Policy 324

Get Detection Rule Sets to Policy Mapping 324

Get Detection Rule Set for a Policy 326

Update a Detection Rule Set in a Policy 327

API Tools

REST Clients 331

JSON Validators 331

Appendix

Find File Checksum 333

Windows 333

macOS 333

Linux 333

Threat Classifications 333

File Unavailable 334

Trusted - Local 334

PUP 334

323

330

332

Dual Use 335

Malware 336

Scope Values for Authentication Token 337

Legal Notice

Legal Notice 341

340

Cylance User APIGuide, v2.0 rev34, December 2020 | 8

Application Management

- 9 -

Application Management

Cylance Console administrators can manage multiple API applications, including the access

privileges to your Cylance Console data, CylancePROTECT and CylanceOPTICS.

To Add an Application

IMPORTANT: A tenant can have up to 10 Custom Applications.

application integration.

2. Select Settings >Integrations.

3. Click Add Application.

Type an Application Name. This must be unique within your organization.

Select the access privileges for a Console data type. Not selecting any checkboxes for a

data type means the application does not have access to that data type.

Cylance User APIGuide, v2.0 rev34, December 2020 | 10

Figure 1: Configure Custom Application Settings

6. Click Save. The credentials to use for the application displays.

Copy and paste the Application ID and Application Secret to your API application. Or you

can click OK to close the dialog box. You can view the Application ID and Application

Secret from the Integrations page.

Note: There are some API operations listed in the Add Application matrix that can be enabled

(Global List - Read and Modify; Policy - Write, Modify, and Delete) but are not available with

the initial release. These API operations are currently under development and will be available

in a future release.

Cylance User APIGuide, v2.0 rev34, December 2020 | 11

Figure 2: View or Hide Cust om Application Settings

Data Type Description

CylanceOPTICS Commands

CylanceOPTICS Detections

CylanceOPTICS Exceptions

CylanceOPTICSFocus Views

CylanceOPTICS InstaQueries

CylanceOPTICS Policies

CylanceOPTICS RuleSets

The CylanceOPTICS Device Commands. Includes Device Lockdown (locking a device, retrieving history) and File Retrieval (requesting, checking, and getting results).

The CylanceOPTICS Detection Events triggered by the Context Analysis Engine (CAE). Enables further automation of analyzing, triaging, and responding to malicious or suspicious activity prevented or detected by CylanceOPTICS.

The CylanceOPTICS DetectionExceptions that adds exceptions to Detection Rules.

The CylanceOPTICS Focus Views retrieves an information trail starting with the first event related to an artifact from an InstaQuery result or CylancePROTECT event.

The CylanceOPTICS InstaQuery allows searching for system artifacts stored locally by CylanceOPTICS - files, registry key persistence points, processes, etc.

The CylanceOPTICS settings in a Policy. This requires the Policy settings to also be enabled.

The CylanceOPTICS set of rules that is then applied to a Policy.

CylanceOPTICS Rules The CylanceOPTICSDetection Rules that help monitor an organization for

security threats or anomalous behavior.

Devices Devices are systems with a Cylance Agent installed. You can get information

about devices in your organization. You can also update (Modify) or remove (Delete) devices from your organization.

GlobalList Global Lists include the Safe List and the Global Quarantine List. Each Global

List operation has its own set of required and optional request fields.

Cylance User APIGuide, v2.0 rev34, December 2020 | 12

Data Type Description

Packages Configuration

Packages Deployment The CylanceOPTICS packages to execute on devices.

Policies Policies contain the protection settings applied to devices. Policies allow

Threats Threat Details provide information about a file as well as reference

Users Users have access to the data in the Console, based on the role assigned to

Zones Each device belongs to at least one Zone.Zones are similar to tags and

The CylanceOPTICS packages to be sent and stored on devices.

Note: CylanceOPTICS packages are not sent to devices by default. Devices must receive a command to download a package.

adding and removing devices instead of needing to manually update each device when you want to change the protection settings.

information about why a file is considered Safe or a Threat. Use the Threats request to get this information.

the User. For example, an Administrator can see everything in the Console, while a User is limited to the zones to which the User is assigned.

assist in organizing your devices.

Privilege Description

Delete Ability to delete the data.

Modify Ability to modify existing data. Also known as update.

Read Ability to read data but cannot create, modify, or delete the data. Also known as list.

Write Ability to add data to the Console. Also known as create.

To Edit an Application

application integration.

2. Select Settings >Integrations.

Click the Edit icon for the application you want to change.

Cylance User APIGuide, v2.0 rev34, December 2020 | 13

Figure 3: Edit Custom Applicat ion

4. Edit the privileges, then click Save Changes.

Figure 4: Save Cust om Application

To Delete an Application

application integration.

2. Select Settings >Integrations.

Click the Remove icon for the application you want to remove.

Figure 5: Remove Custom Application

4. Click Remove Application to confirm the deletion.

Cylance User APIGuide, v2.0 rev34, December 2020 | 14

Figure 6: Remove Custom Application Confirmation Message

To Regenerate an Application Control

There may be times when it is necessary to regenerate the credentials for an Integration, like

when credentials are compromised or stolen. For Cylance Integrations, regenerating credentials

creates a new Application Secret; the Application ID remains unchanged.

Note: After regenerating credentials, you must update this information in the application used to

generate the APIaccess token.

an application credential.

2. Select Settings >Integrations.

Click the down arrow to expand the information for the application for which you want to

regenerate credentials.

Table 1: Regenerate Custom Application Credentials

4. Click Regenerate Credentials. A confirmation message appears.

5. Click Yes, Regenerate to confirm regenerating the credentials.

Cylance User APIGuide, v2.0 rev34, December 2020 | 15

Figure 7: Regenerate Custom Application Credentials Confirmation Message

Copy Tenant ID

The Tenant ID is required for authorization. You can copy your Tenant ID from the Integrations

page.

Figure 8: Copy Tenant ID

API in Audit Logs

The API calls listed below are included in the Console Audit Log (My Account >Audit Log) when

something is created or updated. In the Audit Log, the "Who" field displays the Application

Name, not the username.

Policy:Create, Update, or Delete

Global List:Add or Delete

Zone:Create, Update, or Delete

Cylance User APIGuide, v2.0 rev34, December 2020 | 16

Tenant User:Create, Update, or Delete

Device:Update Device, Update Device Threat, or Delete Device

Cylance User APIGuide, v2.0 rev34, December 2020 | 17

RESTful API

- 18 -

Cylance provides RESTful APIs for registered organizations to manage their resources. To

access the CylanceAPI resources, the client will need to follow the authentication and

authorization flow as defined below. This requires the client to send a request to the Auth

endpoint, which will return an access token that the client will use for calling all other endpoints.

Note: Cylance supports CylanceAPIresources, including helping users troubleshoot Cylance

APIrequests. Cylance does not write or train users on how to create scripts or code (like using

Python).

Authentication and Authorization

Application

An Application acts as an integration point between the client system and the Cylance API.

Through the Application, the client system is granted temporary access to act upon resources.

Actions will be limited by the scopes associated to the Application itself, as defined in the

"Application Management" on page10 section.

Service Endpoint

The service endpoint address can contain a region code to identify the set of servers to which

your organization belongs.

Example for Europe - Central:http://protectapi-euc1.cylance.com/devices/v2

Note: North America and USGovernment have a different format. See Service Endpoint column

below for examples.

Region Code Service Endpoint with Region Code

Asia-Pacific - North apne1

Asia-Pacific - Southeast au

Europe - Central euc1

North America

South America sae1

USGovernment us

https://protectapi-apne1.cylance.com/

https://protectapi-au.cylance.com/

https://protectapi-euc1.cylance.com/

https://protectapi.cylance.com/

https://protectapi-sae1.cylance.com/

https://protectapi.us.cylance.com/

Cylance User APIGuide, v2.0 rev34, December 2020 | 19

Authentication

During the step which a client system requests access prior to using Cylance Resources, there

is an independent Web API that will handle the Authentication process and grant access to the

client system. A token based authentication approach is being taken as a means of data

transportation between the parties. Cylance has adopted JWT(RFC 7519) as the token format

for its simplicity as well as its capabilities for digital signature.

The following actors exist in the Authentication workflow:

Authentication Token:Created and signed by the client system to perform an

Authentication request, it is in this request where the Application is indicated.

Authentication Endpoint: Part of the Cylance Auth Web API which will handle the

authentication requests coming from client systems, there will be a particular endpoint to

handle JWT tokens.

Access Token:If authentication is successful and the client system is granted access to

the requested application, a token representing this identity and some key attributes will

be returned as a JWT token.

Authentication Token

The Authentication Token contains the ID of the Application to which a client system is

requesting access. The Application contains two attributes: Application ID and Application

Secret, the latter is cryptographic nonce used to sign the token, thus ensuring the authenticity

of the caller and therefore, it must be shared between client and server. The Authentication

endpoint has a mechanism to verify the signature and eventually proceed to grant access to the

Application, if the client request is indeed allowed.

The client will create the Authentication token by indicating the Application ID as a claim and

sign it using the Application Secret.

The Authentication Token must have the following claims. All are registered and conform to the

JWTstandard.

Claim Type Description

Registered Claims

exp NumericDate

Date and time when the Token expires and is no longer valid for processing. This is Unix epoch time in seconds.

Note: The longest time-span honored by the service is 30 minutes from the value specified in the iat claim. Specifying a longer time-span will result in an HTTP 400 (Bad Request) response from the server.

Cylance User APIGuide, v2.0 rev34, December 2020 | 20

Claim Type Description

iat NumericDate

iss StringOrUri

jti String

sub StringOrUri

Time when the token was issued. This is Unix epoch time in seconds.

Represents the principal issuing the token, which is

Unique ID for the token, which can be used to prevent reply attacks.

Principal subject to the claim. In our case, this would hold our Application ID.

http://cylance.com

Custom Claims

scp String

tid String

Comma delimited scopes requested. This claim is optional.

Tenant ID (available on the Integrations page in the Console).

Example:

Authentication Token - Adding Required Token Claims

DateTime now = DateTime.UtcNow; long unixTimestamp = now.ToUnixTimestamp();

token.Claims.Add("iss", "http://cylance.com"); token.Claims.Add("iat", now.ToUnixTimestamp();); token.Claims.Add("exp", now.AddMinutes(1).ToUnixTimestamp()); token.Claims.Add("sub", "k45f6798092hjdhs836h"); token.Claims.Add("jti", "k45f6798092hjdhs836h+d82c7976-ef46-47b680ce-4dda3c91bba3"); token.Claims.Add("tid", "f00e9987-ee61-57b7-80cf-5eeb3d02ccb4”); token.claims.Add(“scp”, “policy:create, policy:list, policy:read, policy:update”)

Generating the Authentication and Access Tokens

The Authentication Token can be generated using Python. You can use the Python example

below, adding the required token claims that you need.

Note: Cylance Support does not provide assistance with installing non-Cylance programs (like

Python) or security (lke PyJWT). Cylance does have a knowledge base article with an example

for installing Python and PyJWT on Windows; this example is provided AS-IS and there is no

guarantee the example will work in your environment.

Software Requirements:

n Python 3.7 (latest version recommended)

n PyJWT package (pip install PyJWT)

Cylance User APIGuide, v2.0 rev34, December 2020 | 21

n Requests package (pip install requests)

Notes:

n Copying the Python Example from the PDF requires proper formatting in Python due to

the extra line breaks that can cause an error. Use the Python and PyJWT on Windows

knowledge base article to copy the example.

n Example using C# are available upon request.

PythonExample

# WARNING:Copying this example from the PDF requires proper # formatting in Python due to the extra lines breaks that # can cause an error. # RECOMMENDED:Use the Python and PyJWT on Windows knowledge base # article to copy the example.

import jwt # PyJWT version 1.7.1 as of the time of authoring. import uuid import requests # requests version 2.22.0 as of the time of authoring import json from datetime import datetime, timedelta

# 30 minutes from now timeout = 1800 now = datetime.utcnow() timeout_datetime = now + timedelta(seconds=timeout) epoch_time = int((now - datetime(1970, 1, 1)).total_seconds()) epoch_timeout = int((timeout_datetime - datetime(1970, 1, 1)).total_ seconds())

jti_val = str(uuid.uuid4()) tid_val = "" # The tenant's unique identifier. app_id = "" # The application's unique identifier. app_secret = "" # The application's secret to sign the auth token with.

AUTH_URL = "https://protectapi.cylance.com/auth/v2/token"

claims = {

"exp": epoch_timeout, "iat": epoch_time, "iss": "http://cylance.com", "sub": app_id, "tid": tid_val, "jti": jti_val # The following is optional and is being noted here as an example

on how one can restrict

# the list of scopes being requested # "scp":

Cylance User APIGuide, v2.0 rev34, December 2020 | 22

PythonExample

["policy:create","policy:list","policy:read","policy:update"] }

encoded = jwt.encode(claims, app_secret, algorithm='HS256').decode ('utf-8') print ('auth_token:\n' + encoded + "\n")

payload = {"auth_token": encoded} headers = {"Content-Type": "application/json; charset=utf-8"} resp = requests.post(AUTH_URL, headers=headers, data=json.dumps (payload))

print("http_status_code: " + str(resp.status_code)) print("access_token:\n" + json.loads(resp.text)['access_token'] + "\n")

Token Lifecycle

An Authentication token should be used only once per request. This means the same token

should not be usable for more than one request to prevent impersonation attempts. The jti

attribute uniquely identifies the token. It can be used to keep track of all the tokens and prevent

them from being reused. To ensure that the authentication token can be used only once, an

expiration is enforced on the token. This means the token is usable within a few minutes or

less.

Request / Response Model

HTTPMethod POST

Endpoint /auth/v2/token

Example:https://protectapi.cylance.com/auth/v2/token

Request Headers

Request

Accept: application/json

Content-Type: application/json

Authorization:Bearer <JWTToken returned by AuthAPI>with the user:create scope encoded.

{

"title":"Authoriztion Request", "type": "object" "properties": {

"auth_token": {

"type": "" "description": "token representing authorization request"

}

Cylance User APIGuide, v2.0 rev34, December 2020 | 23

}, "request": ["auth_token"]

}

Authorization

In response to the Authentication request, the client will receive a response that contains at

least the Access Token. The access token will contain the Scopes that will dictate what can or

cannot be done. This token is signed by the server and the client will merely echo it on every

request as it tries to access Resources.

The access token represents the identity of the requester as well as some attributes like

Scopes. This token will have an expiration and should be sent on every request in the

Authorization Request Header. Failing to do so will result in an HTTP/1.1 401 Unauthorized

response. Should the token be provided and prove to be legitimate but the server finds the

action the caller is trying to attempt is not allowed (found in the scopes granted), an HTTP/1.1

403 Forbidden will be returned.

Access Token

The Access token represents a grant to access Cylance Resources. It contains information about

the identity of the caller (Application) as well as control information form the Token itself, for

instance, date it was issued and expiration. This token is also responsible for holding all Scopes

that would be used by our system to validate actions attempted to be taken against Cylance

Resources.

There is an expiration associated to this Token. The expiration time will be set during token

creation on the server side. After the token expires, the server will respond with HTTP/1.1 401

Unauthorized indicating to the caller to authenticate again with a new access token.

Response Status Codes

Each APIrequest will receive a response with a JSON payload and a standard HTTPstatus

code.

Note: Some API request sections include additional response status descriptions (specific to that

request) to help you troubleshoot issues.

Status

Code

Description

200 - OK A successful call and operation. The response payload will be JSON, structured

according to the nature of the request.

Cylance User APIGuide, v2.0 rev34, December 2020 | 24

Status

Code

Description

400 - Bad Request

401 Unauthorized

403 Forbidden

404 - Not Found

409 - Conflict A request was made to create or update an aspect of the resource that conflicts with

500 - Internal Server Error

501 - Not Implemented

Other Contact Cylance Support if you encounter any status codes that are not on this list.

There was a problem with the structure of the request or the payload. If determinable, the response payload will identify the failure in the request. A common case of this type of error is malformed JSON in the request body. A JSON validator can be used to troubleshoot these issues.

Invalid credentials were passed or some other failure in authentication.

Request has been successfully authenticated, but authorization to access the requested resource was not granted.

A request was made for a resource that doesn't exist. Common causes are either an improperly formed URL or an invalid APIkey.

another. The most common reason for this code is a Tenant name or User email that is already in use.

A catch-all code response for any unhandled error that has occurred on the server. Contact Cylance Support for help with this issue.

A request was made against a resource with an operation that has yet to be implemented. Such operations should be identified accordinly in documentation.

API Rate Limit

The rate limiting for APIendpoints is 100,000 requests per day, or about 70 requests per

minute. If a tenant exceeds these limits, they will receive a 429 error - Too Many Requests. If

you encounter a 429 error, wait 60 seconds before retrying the API request.

The purpose of a rate limit is to maintain a good user experience for all APIusers. Without a

rate limit, APIendpoints can flood the server with requests that overwhelm the system and

negatively impact all users.

About Device ID

When attempting to query a CylanceOPTICS APIcall that utilizes a device ID value, be aware

of the following:

The format for the CylanceOPTICS APIdevice ID value should be:

CylanceOPTICS Example:

n 45E07F34E76B4A9EB167D6D0C510D6BA (upper case without dashes)

Cylance User APIGuide, v2.0 rev34, December 2020 | 25

Passing the device ID value as the CylancePROTECT format will return an HTTP200 status, as

if the call was successful, but you will receive an incorrect response.

CylancePROTECT Example:

n 45e07f34-e76b-4a9e-b167-d6d0c510d6ba (lower case with dashes)

To obtain the device ID, you must query the CylancePROTECT API, then format the device ID

to match the CylanceOPTICS format (see example above).

This query can be found in the Device API section of this document. Use the Get Devices and

Get Device requests from the guide. The device ID value is the field titled "id".

About Zone ID

When attempting to query a CylanceOPTICS APIcall that utilizes a zone ID value, be aware of

the following:

The format for the CylanceOPTICS APIzone ID value should be:

CylanceOPTICS Example:

n D27FF5C45C0D4F56A00DA1FB297E440E (upper case without dashes)

Passing the zone ID value as the CylancePROTECT format will return an HTTP200 status, as if

the call was successful, but you will receive an incorrect response.

CylancePROTECT Example:

n d27ff5c4-5c0d-4f56-a00d-a1fb297e440e (lower case with dashes)

To obtain the zone ID, you must query the CylancePROTECT API, then format the zone ID to

match the CylanceOPTICS format (see example above).

This query can be found in the Zone API section of this document. Use the Get Zones and Get

Zone requests from the guide.

Cylance User APIGuide, v2.0 rev34, December 2020 | 26

User API

- 27 -

Create User

Create (add) a new Console user. This requires a unique email address for the user being

created.

Service Endpoint:

n /users/v2

Example:https://protectapi.cylance.com/users/v2

Method:

n HTTP/1.1 POST

Request Header:

n Accept:application/json

n Content-Type:application/json

n Authorization:Bearer <JWTToken returned by AuthAPI> with the user:create scope

encoded.

Request:

{

"email": "testuser@email.com", "user_role": "00000000-0000-0000-0000-000000000001", "first_name": "Test", "last_name": "User", "zones":[

{ "id":"d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002" }

]

}

Response:

201 Created

{

"id":"a2c0ac7a-a63d-4583-b646-ae10db9c9768", "tenant_id": "4b1640d2-d563-41cf-94a7-0da1dca6aa98", "first_name": "Test", "last_name": "User", "email": "testuser@email.com", "has_logged_in": false, "role_type": "00000000-0000-0000-0000-000000000001", "role_name": "User",

Cylance User APIGuide, v2.0 rev34, December 2020 | 28

"default_zone_role_type": "00000000-0000-0000-0000-000000000000", "default_zone_role_name": "None", "zones": [

{ "id":"d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002" }

] "date_last_login": null, "date_email_confirmed": null, "date_created": "2019-09-13T22:33:26.098Z", "date_modified":"2019-09-13T22:33:26.098Z"

}

400 Bad Request - Returned for the following reasons:

n The User create request was empty.

n The Tenant ID cannot be retrieved from the JWTToken.

n The User's email address specified is not a proper email address.

n The User application role specified is not one of the accepted values.

n The zones array is empty when the User application role is not Administrator.

n The email provided is already in use.

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

500 Internal Server Error - An unforeseeable error has occurred.

Request JSONSchema Descriptions

Field Name Description

email The user's email address. This must be unique.

first_name The user's first name. Maximum of 64 characters.

last_name The user's last name.Maximum of 64 characters.

user_role The user's role in the Console.

n User: 00000000-0000-0000-0000-000000000001

n Administrator: 00000000-0000-0000-0000-000000000002

n Read-Only: 00000000-0000-0000-0000-000000000003

zones The zones to which the user has access. This is an array of

elements.

n id: The unique identifier for the zone.

n role_type:The user's role for this particular zone.

Cylance User APIGuide, v2.0 rev34, December 2020 | 29

Field Name Description

l Zone Manager: 00000000-0000-0000-0000-

000000000001

l User: 00000000-0000-0000-0000-000000000002

Note: If the user is an Administrator, the zones array is not required.

Note: To create a Zone Manager, set the user_role to User and assign a zone or zones to the

User via the Zones parameter. Setting the user_role to Read-Only and using the Zones

parameter will result in a bad request error.

Response JSONSchema Descriptions

Field

Name

date_ created

date_ email_ confirmed

date_ last_login

date_ modified

default_ zone_ role_ name

default_ zone_ role_type

Description

The date and time (in UTC) the Console user was created.

The date and time (inUTC) when the user confirmed the email provided. This should be null because the user account was recently created.

The date and time (in UTC)the user last logged in to the Console. This should be null because the user account was recently created.

The date and time (in UTC) the Console user information was last updated.

The name of the role for the user in the zone.

The unique identifier for the user's default role when assigned to a zone.

n None: 00000000-0000-0000-0000-000000000000

n Zone Manager:00000000-0000-0000-0000-000000000001

n User:00000000-0000-0000-0000-000000000002

email The user's email address.

first_

The user's first name.

name

has_

This should be false because the user account was recently created. logged_ in

id The user's unique identifier for the Console.

last_ The user's last name.

Cylance User APIGuide, v2.0 rev34, December 2020 | 30

Field

Name

name

Description

role_

The name of the user's role in the Console. name

role_type The unique identifier defining the user's role in the Cosole.

n User: 00000000-0000-0000-0000-000000000001

n Administrator: 00000000-0000-0000-0000-000000000002

n Read-Only: 00000000-0000-0000-0000-000000000003

n Zone Manager:00000000-0000-0000-0000-000000000004

Note: To create a Zone Manager, set the user_role to User and assign a zone or

zones to the User via the Zones parameter. Setting the user_role to Read-Only and

using the Zones parameter will result in a bad request error.

zones The zones to which the user has access. This is an array of elements.

n id: The unique identifier for the zone.

n role_type: The user's role for this particular zone.

l None:00000000-0000-0000-0000-000000000000

l Zone Manager: 00000000-0000-0000-0000-000000000001

l User: 00000000-0000-0000-0000-000000000002

n role_name:The name of the user's role in the zone.

Note: If the user is an Administrator, the zones array will display empty brackets [ ].

Get Users

Request a page with a list of Console user resources belonging to a tenant, sorted by the

created date, in descending order (most recent user registered listed first). The page number

and page size parameters are optional. When the values are not specified, the default values

are 1 and 10 respectively. The maximum page size that can be specified is 200 entries per

page.

Service Endpoint:

n /users/v2?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

For example, to return the first page with up to 100 users:

https://protectapi.cylance.com/users/v2?page=1&page_size=100

Cylance User APIGuide, v2.0 rev34, December 2020 | 31

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the user:list scope encoded

Request:

None

Response:

200 OK

{

"page_number":"1", "page_size": "10", "total_pages": "1", "total_number_of_items": "1", "page_items": [ {

"id": "a2c0ac7a-a63d-4583-b646-ae10db9c9768", "tenant_id": "4b1640d2-d563-41cf-94a7-0da1dca6aa98", "first_name": "Test", "last_name": "User", "email": "testuser@email.com", "has_logged_in": "true", "role_type": "00000000-0000-0000-0000-000000000001", "role_name":"User", "default_zone_role_type": "00000000-0000-0000-0000-

000000000000",

"default_zone_role_name": "None", "zones": [ {

"id": "d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002",

"role_name":"User" } ], "date_last_login": "2019-09-13T22:33:26.098Z", "date_email_confirmed": "2019-09-13T22:33:26.098Z", "date_created": "2019-09-13T22:33:26.098Z", "date_modified": "2019-09-13T22:33:26.098Z" }

]

}

400 Bad Request - Returned for the following reasons:

Cylance User APIGuide, v2.0 rev34, December 2020 | 32

n The Tenant ID cannot be retrieved from the JWTtoken

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 200

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

date_created The date and time (in UTC) the Console user was created.

date_email_

The date and time (in UTC) when the user confirmed the email provided.

confirmed

date_last_login The date and time (in UTC) the user last logged in to the Console.

date_modified The date and time (inUTC) the Console user information was last

updated.

default_zone_role_

The name of the role for the user in the zone.

name

default_zone_role_ type

The unique identifier for the user's default role when assigned to a zone.

n None: 00000000-0000-0000-0000-000000000000

n Zone Manager: 00000000-0000-0000-0000-000000000001

n User:00000000-0000-0000-0000-000000000002

email The user's email address.

first_name The user's first name.

has_logged_in True if the user has successfully logged in to the Console.

last_name The user's last name.

page_number The page number requested.

page_size The page size requested.

role_type The unique identifier defining the user's role in the Console.

n User: 00000000-0000-0000-0000-000000000001

n Administrator: 00000000-0000-0000-0000-000000000002

n Read-Only:00000000-0000-0000-0000-000000000003

n Zone Manager:00000000-0000-0000-0000-000000000004

tenant_id The organization's unique identifier for the Console.

total_number_of_ The total number of resources.

Cylance User APIGuide, v2.0 rev34, December 2020 | 33

Field Name Description

items

total_pages The total number of pages that can be retrieved, based on the page size

specified.

user_id The user's unique identifier for the Console.

zones The zones to which the user has access. This is an array of elements.

n id:The unique identifier for the zone.

n role_type:The user's role for this particular zone.

l None: 00000000-0000-0000-0000-000000000000

l Zone Manager: 00000000-0000-0000-0000-000000000001

l User:00000000-0000-0000-0000-000000000002

n role_name:The name of the user's role in this zone.

Get User

Request information for a specific Console user resource belonging to a tenant.

Service Endpoint:

n /users/v2/{user_id |user_email_address}

Example with user_id: https://protectapi.cylance.com/users/v2/a2c0ac7a-

a63d-4583-b646-ae10db9c9768

Examplewith a user_email:

https://protectapi.cylance.com/users/v2/username@email.com

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the user:read scope

encoded

Request:

n None

Response:

200 OK

Cylance User APIGuide, v2.0 rev34, December 2020 | 34

{

"id": "a2c0ac7a-a63d-4583-b646-ae10db9c9768", "tenant_id": "4b1640d2-d563-41cf-94a7-0da1dca6aa98", "first_name": "Test", "last_name": "User", "email": "testuser@email.com", "has_logged_in": true, "role_type":"00000000-0000-0000-0000-000000000001", "role_name":"User", "default_zone_role_type": "00000000-0000-0000-0000-000000000000", "default_zone_role_name": "User", "zones": [ {

"id": "d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002", "role_name":"User"

} ], "date_last_login": "2019-09-13T22:33:26.098Z", "date_email_confirmed": "2019-09-13T22:33:26.098Z", "date_created": "2019-09-13T22:33:26.098Z", "date_modified": "2019-09-13T22:33:26.098Z"

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The user's unique identifier is not valid (when using a unique user ID)

n The user's email address specified is not a proper email address (when using the user's

email address)

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The user resource cannot be found by the unique user ID or email address

specified in the URL.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

date_created The date and time (in UTC) the Console user was created.

date_email_ confirmed

date_last_login The date and time (in UTC) the user last logged in to the Console.

The date and time (in UTC) when the user confirmed the email provided.

Cylance User APIGuide, v2.0 rev34, December 2020 | 35

Field Name Description

date_modified The date and time (inUTC) the Console user information was last

updated.

default_zone_role_

The name of the role for the user in the zone.

name

default_zone_role_ type

The unique identifier for the user's default role when assigned to a zone.

n None: 00000000-0000-0000-0000-000000000000

n Zone Manager: 00000000-0000-0000-0000-000000000001

n User:00000000-0000-0000-0000-000000000002

email The user's email address.

first_name The user's first name.

has_logged_in True if the user has successfully logged in to the Console.

id The user's unique identifier for the Console.

last_name The user's last name.

role_name The name of the role.

role_type The unique identifier defining the user's role in the Console.

n User: 00000000-0000-0000-0000-000000000001

n Administrator: 00000000-0000-0000-0000-000000000002

n Read-Only:00000000-0000-0000-0000-000000000003

n Zone Manager:00000000-0000-0000-0000-000000000004

tenant_id The organization's unique identifier for the Console.

total_pages The total number of pages that can be retrieved, based on the page size

specified.

zones The zones to which the user has access. This is an array of elements.

n id:The unique identifier for the zone.

n role_type:The user's role for this particular zone.

l None: 00000000-0000-0000-0000-000000000000

l Zone Manager: 00000000-0000-0000-0000-000000000001

l User:00000000-0000-0000-0000-000000000002

n role_name:The name of the user's role in this zone.

Update User

Update an existing Console user resource.

Service Endpoint:

Cylance User APIGuide, v2.0 rev34, December 2020 | 36

n /users/v2/{user_id}

Example with user_id: https://protectapi.cylance.com/users/v2/a2c0ac7a-

a63d-4583-b646-ae10db9c9768

Method:

n HTTP/1.1 PUT

Request Headers:

n Accept: application/json

n Content-Type: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the user:update scope

encoded

Request:

{

"email": "testuser@email.com", "user_role": "00000000-0000-0000-0000-000000000001", "first_name": "Test", "last_name": "User", "zones":[

{ "id":"d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002" }

]

}

Response:

200 OK

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The user's unique identifier is not valid (when using a unique user ID)

n The user application role specified is not one of the accepted values

n The zones array is empty when the user application role is not Administrator

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The user resource cannot be found by the unique user ID or email address

specified in the URL.

500 Internal Server Error - An unforeseeable error has occurred.

Cylance User APIGuide, v2.0 rev34, December 2020 | 37

Request JSONSchema Descriptions

Field Name Description

email The user's email address.

first_name The user's first name.

last_name The user's last name.

user_role The unique identifier defining the user's role in the Console.

n User: 00000000-0000-0000-0000-000000000001

n Administrator: 00000000-0000-0000-0000-000000000002

n Read-Only:00000000-0000-0000-0000-000000000003

zones The zones to which the user has access. This is an array of

elements.

n id:The unique identifier for the zone.

n role_type:The user's role for this particular zone.

l None: 00000000-0000-0000-0000-000000000000

l Zone Manager: 00000000-0000-0000-0000-

000000000001

l User:00000000-0000-0000-0000-000000000002

Note: If the user is an Administrator, the zones array is not required.

Note: To update a Zone Manager or change a user to a Zone Manager, set the user_role to

User and set the Zones role_type to Zone Manager.

Delete User

Delete an existing Console user resource.

Service Endpoint:

n /users/v2/{user_id}

Example with user_id: https://protectapi.cylance.com/users/v2/a2c0ac7a-

a63d-4583-b646-ae10db9c9768

Method:

n HTTP/1.1 DELETE

Request Headers:

n Authorization:Bearer <JWTToken returned by Auth API> with the user:delete scope

encoded

Request:

Cylance User APIGuide, v2.0 rev34, December 2020 | 38

None

Response:

200 OK

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The user's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The user resource cannot be found by the unique user ID specified in the

URL.

500 Internal Server Error - An unforeseeable error has occurred.

Send Invite Email

Request the Console login invitation email to be resent to a user who has not logged into the

Console yet. The user must already be created, either using the Create User APIor using the

Console.

Service Endpoint:

n /users/v2/{user_email_address}/invite

Example:

https://protectapi.cylance.com/users/v2/username@email.com/invite

Method:

n HTTP/1.1 POST

Request Headers:

n Authorization:Bearer <JWTToken returned by Auth API> with the user:read scope

encoded

Request:

None

Response:

200 OK - The email was successfully sent.

400 Bad Request - Returned for the following reasons:

Cylance User APIGuide, v2.0 rev34, December 2020 | 39

n The Tenant ID cannot be retrieved from the JWTtoken

n The user's email address specified is not a proper email address

n The unique ID of the user triggering the invitation email to be sent cannot be retrieved

from the JWTtoken

n The user to whom the invite email is to be sent has already logged in to the Console

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The user resource to send or resend the invitation email to is not found.

Cylance User APIGuide, v2.0 rev34, December 2020 | 40

Send Request Password Email

Request for the Console reset password email to be sent or resent to an existing Console user.

Service Endpoint:

n /users/v2/{user_email_address}/resetpassword

Example:

https://protectapi.cylance.com/users/v2/username@email.com/resetpassw

ord

Method:

n HTTP/1.1 POST

Request Headers:

n Authorization:Bearer <JWTToken returned by Auth API> with the user:read scope

encoded

Request:

None

Response:

200 OK - The email was successfully sent.

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The user's email address specified is not a proper email address

n The user to whom the reset password email is to be sent has not confirmed the email

provided

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The user resource to send or resend the reset password email to is not found.

500 Internal Server Error - An unforeseeable error has occurred.

Cylance User APIGuide, v2.0 rev34, December 2020 | 41

Device API

- 42 -

Get Devices

Request a page with a list of Console device resources belonging to a tenant, sorted by

registration (created) date, in descending order (most recent device registered listed first). The

page number and page size parameters are optional. When the values are not specified, these

default to 1 and 10 respectively. The maximum page size that can be specified is 10000 entries

per page.

Note: When adding a new device to the Console, the new device will be seen at the top of the

Device list when utilizing the Get DevicesAPIcall. When this occurs, all old devices will be

moved down the list by one space. This causes the last device on the Device list to be move to

the next page.

Potential Issue:Due to the above functionality, a race condition can occur where if a user is

querying the Get Device API call for all devices in their Console and a new device is added to

the Console during this time, the user may see "duplicate" devices appear in the APIcall.This

occurs because of the above functionality, where a new device causes the last device on the

Device list to be moved to the next page.

Example:

Device Name:TESTDEVICE is the last device on page 1 of the Device list page (using the Get

Devices APIcall).

A new device is added to the Console.

If the Get Devices APIcall is querying all devices during this time frame, the returned query

would show TESTDEVICEas being present on both page 1 and 2. This would appear to the

user as if a "duplicate" device was present, but this is not the case and is simply due to the

timing of the API call and the new device addition causing the same device to appear at the

bottom of one page and at the top of the next.

A duplicate device would have the same device name, but a different device_ID. If a user spots

a "duplicate" device in the Get Devices APIcall, it is recommended to compare the device_ID to

confirm if it is truly a duplicate. If the two devices have the same device_ID, it is not an actual

duplicate device respective to the Console.

For more information about Duplicate Devices, read this knowledge base article.

Recommendation:If a user is utilizing the Get Devices API call to iterate through all devices,

it is suggested to query the first page of the device list again to catch any new devices that

were potentially added during the iteration.

Cylance User APIGuide, v2.0 rev34, December 2020 | 43

Service Endpoint:

n /devices/v2?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

For example, to return the first page with 100 devices:

https://protectapi.cylance.com/devices/v2?page=1&page_size=100

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:list scope

encoded

Request:

None

Response:

200 OK

{

"page_number":"1", "page_size": "10", "total_pages": "1", "total_number_of_items": "1", "page_items": [

{

"id": "e378dacb-9324-453a-b8c6-5a8406952195", "name": "User-Laptop-A123", "state": "Online", "agent_version": "2.0.1570", "os_kernel_version": "10.0.0", "products": [

{

"name": "protect", "version": "2.1.1570",

"status": "Online" }, {

"name": "optics",

"version": "",

"status": null

Cylance User APIGuide, v2.0 rev34, December 2020 | 44

}

], "policy": {

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "name":"Test Policy"

}, "date_first_registered": "2019-04-26T19:55:33", "ip_addresses": [

"123.45.67.89"

], "mac_addresses": [

"00-00-00-00-00-00" ], "date_offline": null

}

]

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 200

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resources page requested doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

agent_version The CylancePROTECT Agent version installed on

the device.

date_first_registered The date and time (in UTC) when the device

record was created.

date_offline The date and time (in UTC) when the device last

communicated with the Console.

id The endpoint's unique identifier.

ip_addresses The list of IP addresses for the device.

mac_addresses The list of MAC addresses for the device.

name The name of the device.

Cylance User APIGuide, v2.0 rev34, December 2020 | 45

Field Name Description

os_kernel_version The kernel version for the operating system on the

device.

page_number The page number requested.

page_size The page size requested.

policy The policy ID and name.

products The name of the product installed on the device,

the version number, and status.

state Signals whether the device is online or offline.

total_number_of_ items

total_pages The total number of pages that can be retrieved,

The total number of resources.

based on the page size specified.

Get Devices Extended

Request a page with a list of Console devices with extended information, belonging to a tenant,

sorted by registration (created) date, in descending order (most recent device registered listed

first). The page number and page size parameters are optional. When the values are not

specified, these default to 1 and 100 respectively. The maximum page size that can be

specified is 200 entries per page.

Service Endpoint:

n /devices/v2/extended?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

For example, to return the first page with 100 devices:

https://protectapi.cylance.com/devices/v2/extended?page=1&page_

size=100

Method:

n HTTP/1.1 GET

Request Headers:

Cylance User APIGuide, v2.0 rev34, December 2020 | 46

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:list scope

encoded

Request:

None

Response:

200 OK

{

"page_number":"1", "page_size": "10", "total_pages": "1", "total_number_of_items": "1", "page_items": [

{

"id": "e378dacb-9324-453a-b8c6-5a8406952195", "name": "User-Laptop-A123", "host_name": "User-Laptop-A123", "os_version": "Microsoft Windows 10 Pro", "os_kernel_version": "10.0.0", "background_detection": "false", "is_safe": "true", "state": "Online", "agent_version": "2.0.1570", "products": [

{

"name": "protect", "version": "2.1.1570",

"status": "Online" }, {

"name": "optics",

"version": "",

"status": null }

], "policy": {

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "name":"Test Policy"

}, "date_first_registered": "2019-04-26T19:55:33", "ip_addresses": [

"123.45.67.89"

], "mac_addresses": [

"00-00-00-00-00-00" ], "date_offline": null

Cylance User APIGuide, v2.0 rev34, December 2020 | 47

}

]

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 200

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resources page requested doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

agent_version The CylancePROTECT Agent version installed on

the device.

background_ detection

date_first_registered The date and time (in UTC) when the device

date_offline The date and time (in UTC) when the device last

hostname The hostname for the device.

id The endpoint's unique identifier.

ip_addresses The list of IP addresses for the device.

is_safe If true, there are no outstanding threats.

mac_addresses The list of MAC addresses for the device.

name The name of the device.

os_kernel_version The kernel version for the operating system on the

os_version The operating system and version.

page_number The page number requested.

If true, the Agent is currently running a Background Threat Detection scan.

record was created.

communicated with the Console.

device.

page_size The page size requested.

Cylance User APIGuide, v2.0 rev34, December 2020 | 48

Field Name Description

policy The policy ID and name.

products The name of the product installed on the device,

the version number, and status.

state Signals whether the device is online or offline.

total_number_of_ items

total_pages The total number of pages that can be retrieved,

The total number of resources.

based on the page size specified.

Get Device Count

Request a list of products, product versions, and number of devices using a product and product

version in a tenant.

Service Endpoint:

n /devices/v2/products

Example: https://protectapi.cylance.com/devices/v2/products

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:list scope

encoded

Request:

None

Response:

200 OK

{

"products": [

{

"name": "protect", "versions": [

{

"version": "2.1.1570",

Cylance User APIGuide, v2.0 rev34, December 2020 | 49

"count": 5000 }, {

"version": "2.1.1564",

"count": 5000 }

] }, {

"name": "optics",

"versions: [] }

]

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resources page does not exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

count The total number of devices for a product

version

name The product name

version The product version

Cylance User APIGuide, v2.0 rev34, December 2020 | 50

Get Device

Request a specific device resource belonging to a tenant.

Service Endpoint:

n /devices/v2/{unique_device_id}

Example: https://protectapi.cylance.com/devices/v2/e378dacb-9324-453a-

b8c6-5a8406952195

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:read scope

encoded

Request:

None

Response:

200 OK

{

"id":"e378dacb-9324-453a-b8c6-5a8406952195", "name": "User-Laptop-A123", "host_name": "User-Laptop-A123", "os_version": "Microsoft Windows 10 Pro", "os_kernel_version": "10.0.0", "state": "Online", "agent_version": "2.0.1570", "products": [

{

"name": "protect", "version": "2.1.1570",

"status": "Online" }, {

"name": "optics",

"version": "",

"status": null }

], "policy": {

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "name": "Test Policy"

Cylance User APIGuide, v2.0 rev34, December 2020 | 51

"last_logged_in_user": "User-Laptop-A123\\TestUser", "update_type": null, "update_available": false, "background_detection": false, "is_safe": true, "date_first_registered": "2019-04-04T16:45:04", "date_offline": null, "date_last_modified": "2019-04-04T16:45:04", "ip_addresses":[

"123.45.67.89"

], "mac_addresses": [

"00-00-00-00-00-00"

"distinguished_ name":"CN=DEVICENAME,OU=Computers,DC=TEST,DC=LABS,DC=NET" }

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

agent_version The CylancePROTECT Agent version installed on the device.

background_ detection

date_first_ registered

date_last_ modified

date_offline The date and time (in UTC) when the device last communicated with the

distinguished_ name

If true, the Agent is currently running a Background Threat Detection scan.

The date and time (in UTC) when the device record was created.

The date and time (in UTC) when the device record was last modified.

Console.

The unique identifier for the device in the Lightweight Directory Access Protocol (LDAP).

host_name The hostname for the device.

Cylance User APIGuide, v2.0 rev34, December 2020 | 52

Field Name Description

id The unique identifier for the device.

ip_addresses The list of IP addresses for the device.

is_safe If true, there are no outstanding threats.

last_logged_in_ user

mac_addresses The list of MAC addresses for the device.

name The name of the device.

os_kernel_version The kernel version for the operating system on the device.

os_version The operating system and version.

policy The name of the policy assigned to the device.

products The name of the product installed on the device, the version number, and

state The device is online or offline.

update_available If true, an Agent update is available for the device based on the update

update_type The update phase on which the device is scheduled.

The ID of the user who logged in last on to the device.

status.

type (Phase).

Get Device by MAC Address

Request a specific device resource belonging to a tenant by using the MAC address of the

device.

Service Endpoint:

n /devices/v2/macaddress/{mac_address}

Example: https://protectapi.cylance.com/devices/v2/macaddress/28-F1-0E-

45-AB-54

Example:

https://protectapi.cylance.com/devices/v2/macaddress/28:F1:0E:45:AB:54

Method:

n HTTP/1.1 GET

Request Headers:

Cylance User APIGuide, v2.0 rev34, December 2020 | 53

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:read scope

encoded

Request:

None

Response:

200 OK

{

"id":"e378dacb-9324-453a-b8c6-5a8406952195",

"name": "User-Laptop-A123",

"host_name": "User-Laptop-A123",

"os_version": "Microsoft Windows 10 Pro",

"os_kernel_version": "10.0.0",

"state": "Online",

"agent_version": "2.0.1570",

"products": [

{

"name": "protect", "version": "2.1.1570",

"status": "Online" }, {

"name": "optics",

"version": "",

"status": null }

], "policy": {

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "name": "Test Policy" },

"123.45.67.89"

], "mac_addresses": [

"00-00-00-00-00-00"

], "distinguished_

name":"CN=DEVICENAME,OU=Computers,DC=TEST,DC=LABS,DC=NET"

Cylance User APIGuide, v2.0 rev34, December 2020 | 54

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

agent_version The CylancePROTECT Agent version installed on the device.

background_ detection

date_first_ registered

date_last_ modified

date_offline The date and time (in UTC) when the device last communicated with the

distinguished_ name

host_name The hostname for the device.

id The unique identifier for the device.

ip_addresses The list of IP addresses for the device.

is_safe If true, there are no outstanding threats.

last_logged_in_ user

mac_addresses The list of MAC addresses for the device.

If true, the Agent is currently running a Background Threat Detection scan.

The date and time (in UTC) when the device record was created.

The date and time (in UTC) when the device record was last modified.

Console.

The unique identifier for the device in the Lightweight Directory Access Protocol (LDAP).

The ID of the user who logged in last on to the device.

name The name of the device.

os_kernel_version The kernel version for the operating system on the device.

os_version The operating system and version.

policy The name of the policy assigned to the device.

products The name of the product installed on the device, the version number, and

Cylance User APIGuide, v2.0 rev34, December 2020 | 55

Field Name Description

status.

state The device is online or offline.

update_available If true, an Agent update is available for the device based on the update

type (Phase).

update_type The update phase on which the device is scheduled.

Get Device by Hostname

Request a specific device resource belonging to a tenant by using the hostname of the device

(DNSname).

Note: The hostname ("host_name") may not be the same as the name ("name") displayed by

Cylance. The hostname is created by the operating system, while the name can be changed in

the Cylance Console or API. For domain-joined computers, the "host_name" would be

"hostname.domain.com". For computers not joined to a domain, it would just be "hostname".

Service Endpoint:

n /devices/v2/hostname/{host_name}

Example: https://protectapi.cylance.com/devices/v2/hostname/User-

Laptop-A123

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:read scope

encoded

Request:

None

Response:

200 OK

{

"id":"e378dacb-9324-453a-b8c6-5a8406952195", "name": "Executive Laptop", "host_name": "User-Laptop-A123",

Cylance User APIGuide, v2.0 rev34, December 2020 | 56

"os_version": "Microsoft Windows 10 Pro", "os_kernel_version": "10.0.0", "state": "Online", "agent_version": "2.0.1570", "products": [

{

"name": "protect",

"version": "2.1.1570",

"status": "Online" }, {

"name": "optics",

"version": "",

"status": null }

], "policy": {

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "name": "Test Policy" },

"123.45.67.89"

], "mac_addresses": [

"00-00-00-00-00-00"

"distinguished_ name":"CN=DEVICENAME,OU=Computers,DC=TEST,DC=LABS,DC=NET" }

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Cylance User APIGuide, v2.0 rev34, December 2020 | 57

Field Name Description

agent_version The CylancePROTECT Agent version installed on the device.

background_ detection

date_first_ registered

date_last_ modified

date_offline The date and time (in UTC) when the device last communicated with the

distinguished_ name

host_name The hostname for the device.

id The unique identifier for the device.

ip_addresses The list of IP addresses for the device.

is_safe If true, there are no outstanding threats.

last_logged_in_ user

mac_addresses The list of MAC addresses for the device.

If true, the Agent is currently running a Background Threat Detection scan.

The date and time (in UTC) when the device record was created.

The date and time (in UTC) when the device record was last modified.

Console.

The unique identifier for the device in the Lightweight Directory Access Protocol (LDAP).

The ID of the user who logged in last on to the device.

name The name of the device.

os_kernel_ version

os_version The operating system and version.

policy The name of the policy assigned to the device.

products The name of the product installed on the device, the version number, and

The kernel version for the operating system on the device.

status

Notes:

n The version number is major, minor, and build number to match the

data displayed in the console.

state The device is online or offline.

update_ available

update_type The update phase on which the device is scheduled.

If true, an Agent update is available for the device based on the update type (Phase).

Cylance User APIGuide, v2.0 rev34, December 2020 | 58

Update Device

Update a specific device resource belonging to a tenant.

Service Endpoint:

n /devices/v2/{unique_device_id}

Example: https://protectapi.cylance.com/devices/v2/e378dacb-9324-453a-

b8c6-5a8406952195

Method:

n HTTP/1.1 PUT

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:update scope

encoded

n Content-Type:application/json

Request:

{

"name": "User-Laptop-A123",

"policy_id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea",

"add_zone_ids": [

"d27ff5c4-5c0d-4f56-a00d-a1fb297e440e" ],

"remove_zone_ids": [

"639db7f7-c7f9-488d-b834-41c4522b32b6"

] }

Response:

200 OK

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resource to update doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Cylance User APIGuide, v2.0 rev34, December 2020 | 59

Request JSONSchema Descriptions

Field

Description

Name

add_ zone_ids

name The name of the device.

policy_id The unique identifier for the policy to assign to the device. Specify null or leave the

remove_ zone_ids

The list of zone identifiers which the device is to be assigned.

string empty to remove the current policy from the device.

The list of zone identifiers from which the device is to be removed.

Get Device Threat

Request a page with a list of threats found on a specific device. The page number and page

size parameters are optional. When the values are not specified, these default to 1 and 10

respectively. The maximum page size that can be specified is 200 entries per page.

Service Endpoint:

n /devices/v2/{unique_device_id}/threats?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

Example: https://protectapi.cylance.com/devices/v2/e378dacb-9324-453a-

b8c6-5a8406952195/threats?page=1&page_size=100

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:threatlist scope

encoded

Request:

None

Response:

Cylance User APIGuide, v2.0 rev34, December 2020 | 60

200 OK

{

"page_number":"1",

"page_size": "10",

"total_pages": "1",

"total_number_of_items": "1",

"page_items": [

{ "name": "threat.exe", "sha256":

"bf17366ee3bb8068a9ad70fc9e68496e7e311a055bf4ffeeff53cc5d29ccce52",

"file_status": "Suspicious", "file_path": "C:\\Some\File\Path\threat.exe", "cylance_score": "-0.900", "classification": "Malware", "sub_classification": "Backdoor", "date_found": "2019-05-08T20:55:27" }

] }

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 200

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The identifier specified doesn't belong to a device resource in the system.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field

Description

Name

classification The threat classification assigned by Cylance.

cylance_ score

The Cylance score assigned to the threat.

The Cylance APIreturns a raw score of -1 to 1. Threats have a negative raw score, while safe files have a positive raw score. The CylanceConsole only displays threats and uses a score of 1 to 100. A raw score of -1 equals a Console score of 100.

Cylance User APIGuide, v2.0 rev34, December 2020 | 61

Field

Description

Name

date_found The date and time (inUTC) when the threat was found on the device.

file_path The file path to the threat, includes the file name.

file_status The current status of the file on the device. This can be one of the following:

n Default (0) (Unsafe)

n Quarantined (1)

n Whitelisted (2)

n Suspicious (3) (Abnormal)

n FileRemoved (4) (Delete) - The file was removed from the Console.

n Corrupt (5) - The file could not be scanned. The file could be corrupt or

malformed.

name The name of the threat.

page_ number

page_size The page size requested.

sha256 The SHA256 hash for the threat.

sub_ classification

total_pages The total number of pages that can be retrieved, based on the page size

total_ number_of_ items

The page number requested.

The threat sub-classification assigned by Cylance.

specified.

The total number of resources.

Update Device Threat

Update the status (waive or quarantine) of a convicted threat.

Note: To update a threat on a device requires the Modify permission for the Threats privilege in

an Integration. See Authorization below.

Service Endpoint:

n /devices/v2/{unique_device_id}/threats

Example: https://protectapi.cylance.com/devices/v2/e378dacb-9324-453a-

b8c6-5a8406952195/threats

Method:

Cylance User APIGuide, v2.0 rev34, December 2020 | 62

n HTTP/1.1 POST

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the threat:update scope

encoded

n Content-Type:application/json

Request:

{

"threat_id": "bf17366ee3bb8068a9ad70fc9e68496e7e311a055bf4ffeeff53cc5d29ccce52",

"event": "Quarantine" }

Response:

200 OK

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resource to update doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

event The requested status update for the convicted

threat.

n Quarantine

n Waive

threat_id The SHA256 hash of the convicted threat.

Cylance User APIGuide, v2.0 rev34, December 2020 | 63

Get Zone Devices

Request a page with a list of Console device resources belonging to a zone, sorted by

registration (created) date, in descending order (most recent registered listed first). The page

number and page size parameters are optional. When the values are not specified, these

default to 1 and 10 respectively. The maximum page size that can be specified is 200 entries

per page.

Service Endpoint:

n /devices/v2/{unique_zone_id}/devices?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

Example: https://protectapi.cylance.com/devices/v2/d27ff5c4-5c0d-4f56-

a00d-a1fb297e440e/devices?page=1&page_size=100

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:list scope

encoded

Request:

None

Response:

200 OK

{

"page_number":"1",

"page_size": "10",

"total_pages": "1",

"total_number_of_items": "1",

"page_items": [

{ "id": "e378dacb-9324-453a-b8c6-5a8406952195", "name": "User-Laptop-A123", "policy_id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea" }

]

Cylance User APIGuide, v2.0 rev34, December 2020 | 64

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The device's unique identifier is not valid

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 200

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The zone resource requested is not a valid ID.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

id The unique identifier for the device.

name The name of the device.

page_number The page number requested.

page_size The page size requested.

policy_id The unique identifier for the policy to which the policy is currently assigned.

This can be null.

total_number_of_ items

total_pages The total number of pages that can be retrieved, based on the page size

The total number of resources.

specified

Get Agent Installer Link

Request a secured link to download the Agent installer.

Service Endpoint:

n /devices/v2/installer?product=p&os=o&package=k&architecture=a&build=v

Example:

https://protectapi.cylance.com/devices/v2/installer?product=Protect&o

s=Windows&package=Msi&architecture=X64&build=1510

Method:

Cylance User APIGuide, v2.0 rev34, December 2020 | 65

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the device:read scope

encoded

Request:

Append the following optional query string parameters:

n product (required for all operating systems):Specify the Cylance product installer to

download. The allowed values are:

l Protect

l Optics

l Protect+Optics

Note: To download the CylancePROTECT+CylanceOPTICS installer, use the

following example (Windows only). This downloads the latest

CylancePROTECT+CylanceOPTICS installer available to the tenant. Other versions

of the CylancePROTECT+CylanceOPTICS installer must be downloaded from the

Console.

EXEExample:

https://protectapi.cylance.com/devices/v2/installer?product=Protect+Optics&os=

Windows&package=Exe&architecture=

32-bit MSIExample:

https://protectapi.cylance.com/devices/v2/installer?product=Protect+Optics&os=

Windows&package=Msi&architecture=x86

64-bit MSIExample:

https://protectapi.cylance.com/devices/v2/installer?product=Protect+Optics&os=

Windows&package=Msi&architecture=x64

n os (required for all operating systems):Specify the operating system (OS)family. The

allowed values are:

l AmazonLinux1

l AmazonLinux2

l CentOS7

l Linux

Cylance User APIGuide, v2.0 rev34, December 2020 | 66

Note: Use Linux as the OS family for CentOS6.

l Mac

l Rhel8

l Suse11

l Suse12

l Ubuntu1404

l Ubuntu1604

l Ubuntu1804

l Windows

n architecture (required for Linux and Windows):Specify the target architecture. The

allowed values are:

l X86

l X64

l AmazonLinux1

l AmazonLinux2

l CentOS6

l CentOS6UI

l CentOS7

l CentOS7UI

l RedHatEnterprise8

l RedHatEnterprise8UI

l Suse11

l Suse11UI

l Suse12

l Suse12UI

l Ubuntu1404

l Ubuntu1404UI

l Ubuntu1604

l Ubuntu1604UI

Cylance User APIGuide, v2.0 rev34, December 2020 | 67

l Ubuntu1804

l Ubuntu1804UI

n package (required for macOS and Windows):Specify the installer format.The allowed

values are:

l Exe (Windows only)

l Msi (Windows only)

l Dmg (macOSonly)

l Pkg (macOSonly)

n build(optional): The Agent version.CylancePROTECTexample 1540. CylanceOPTICS

example:2061.

Response:

200 OK

{

"url":"https://cylance/download/url" }

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The requested payload failed validation

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The requested link resource does not exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field

Description

Name

url The URLyou can use to download the requested Agent installer. The APIcall only

provides the URL, it does not download the installer for you.

Delete Devices

Delete one or more devices from a tenant.

Cylance User APIGuide, v2.0 rev34, December 2020 | 68

Note: This is an asynchronous operation and could take up to two hours to delete the devices.

If a callback URL is provided, the callback will occur when deletion is complete.

Service Endpoint:

n /devices/v2

Example:https://protectapi.cylance.com/devices/v2

Method:

n HTTP/1.1 DELETE

Note: For clients who do not support DELETE, see the note below.

Request Header:

n Accept:application/json

n Authorization:Bearer <JWTToken returned by AuthAPI> with the device:delete scope

encoded.

n Content-Type:application/json

Request:

{

"device_ids":

[

"e378dacb-9324-453a-b8c6-5a8406952195" ], "callback_url": ""

}

Response:

202 Accepted

{

"request_id":""

}

400 Bad Request - Returned for the following reasons:

n The tenant ID could not be retrieved from the JWTtoken

n The device IDs are not valid

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The devices do not exist.

413 Payload Too Large - The number of resources specified in the request is too large.

Cylance User APIGuide, v2.0 rev34, December 2020 | 69

500 Internal Server Error - An unforeseeable error has occurred.

Request JSONSchema Descriptions

Field

Description

Name

callback_ url

device_ ids

Response JSONSchema Descriptions

The URLof the callback upon completion. This is optional.

The unique identifiers for the devices to be deleted.

n All device IDs should be well formed GUIDs. Non-conforming values will be

removed from the request.

n The maximum number of device IDs per request is 20.

Field Name Description

request_id The unique identifier for the deletion request.

Note: Not all clients support sending a DELETErequest. For this instance, use the following

POST instead.

Service Endpoint:/devices/v2/delete

Example:https://protectapi.cylance.com/devices/v2/delete

Method:HTTP/1.1 POST

Delete this text and replace it with your own content.

Cylance User APIGuide, v2.0 rev34, December 2020 | 70

Global List API

- 71 -

Get Global List

Request a page with a list of global list resources for a tenant, sorted by the date when the

hash was added to the global list, in descending order (most recent policy listed first). The page

number and page size parameters are optional. When the values are not specified, these

default to 1 and 10 respectively. The maximum page size that can be specified is 200 entries

per page. The listTypeId parameter is required and can be 0 (GlobalQuarantined) or 1 (Global

Safe).

Service Endpoint:

n /globallists/v2?listTypeId={0|1}&page-m&page_size=n

Append the following optional query string parameters:

n listTypeId:The type of list to retrieve.

l 0 = Global Quarantine list

l 1 = Global Safe list

n page: The page number to request

n page_size: The number of device records to retrieve per page

For example, to return the first page with up to 100 list items:

https://protectapi.cylance.com/globallists/v2?listTypeId=0&page=1&pag

e_size=100

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the globallist:list scope

encoded

Request:

None

Response:

200 OK

{

"page_number":"1", "page_size": "10", "total_pages": "1",

Cylance User APIGuide, v2.0 rev34, December 2020 | 72

"total_number_of_items": "1", "page_items": [

{

"name": "threat.exe",

"sha256":

"bf17366ee3bb8068a9ad70fc9e68496e7e311a055bf4ffeeff53cc5d29ccce52",

"md5": "d41d8cd98f00b204e9800998ecf8427e",

"cylance_score": "-1",

"av_industry": null,

"classification": "Malware",

"sub_classification": "Trojan",

"list_type": "GlobalQuarantine",

"category": "None",

"added": "2019-05-07T16:41:5",

"added_by": "a2c0ac7a-a63d-4583-b646-ae10db9c9768",

"reason": "Test"

} ]

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The page number or page size specified is less than or equal to zero

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The global list page requested doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field

Description

Name

added The timestamp when the file was added to the list.

added_by The tenant user ID who added the file to the list.

av_industry The score provided by the antivirus industry.

category The category for the list specified (for the Global Safe list only).

n Admin Tool

n Commercial Software

n Drivers

n Internal Application

n None

n Operating System

Cylance User APIGuide, v2.0 rev34, December 2020 | 73

Field

Description

Name

n Security Software

When using Add to Global List, the category does not include the space. For example, AdminTool.

classification The threat classification assigned by Cylance.

cylance_ score

list_type The list type to which the threat belongs (Global Quarantine or Global Safe).

md5 The MD5 hash for the threat.

name The name of the threat.

page_ number

page_size The page size requested.

reason The reason why the file was added to the list.

sha256 The SHA256 hash for the threat.

sub_ classification

total_pages The total number of pages that can be retrieved, based on the page size

The Cylance score assigned to the threat.

The Cylance APIreturns a raw score of -1 to 1. Threats have a negative raw score, while safe files have a positive raw score. The Cylance Console only displays threats and uses a score of 1 to 100. A raw score of -1 equals a Console score of 100.

The page number requested.

The threat sub-classification assigned by Cylance.

specified.

total_ number_of_ items

The total number of resources.

Add to Global List

Add a convicted threat to either the Global Quarantine or the Global safe list for a particular

tenant.

Service Endpoint:

n /globallists/v2

Example: https://protectapi.cylance.com/globallists/v2

Cylance User APIGuide, v2.0 rev34, December 2020 | 74

Method:

n HTTP/1.1 POST

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the globallist:create scope

encoded

Request:

{

"sha256":"bf17366ee3bb8068a9ad70fc9e68496e7e311a055bf4ffeeff53cc5d2 9ccce52",

"list_type": "GlobalSafe", "category": "CommercialSoftware", "reason": "Test"

}

Response:

200 OK

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The requested payload failed validation

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

409 Conflict - The threat specified already exists in the intended list.

500 Internal Server Error - An unforeseeable error has occurred.

Request JSONSchema Descriptions

Field

Description

Name

category This field is required only if the list_type value is GlobalSafe. The value can be

one of the following:

n AdminTool

n CommercialSoftware

n Drivers

n InternalApplication

n OperatingSystem

Cylance User APIGuide, v2.0 rev34, December 2020 | 75

Field

Description

Name

n SecuritySoftware

n None

There are no spaces in the Category name when adding to a Global List.

list_type The list type to which the threat belongs(GlobalQuarantine or GlobalSafe).

reason The reason why the file was added to the list.

sha256 The SHA256 hash for the threat.

Delete From Global List

Remove a convicted threat from either the Global Quarantine or the Global Safe list for a

particular tenant.

Service Endpoint:

n /globallists/v2

Example: https://protectapi.cylance.com/globallists/v2

Method:

n HTTP/1.1 DELETE

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the globallist:delete scope

encoded

Request:

{

"sha256":"bf17366ee3bb8068a9ad70fc9e68496e7e311a055bf4ffeeff53cc5d2 9ccce52",

"list_type": "GlobalSafe"

}

Response:

200 OK

400 Bad Request - Returned for the following reasons:

Cylance User APIGuide, v2.0 rev34, December 2020 | 76

n The Tenant ID cannot be retrieved from the JWTtoken

n The provided SHA256 is invalid

n The provided list type is not supported

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The threat specified does not exist in the intended list.

500 Internal Server Error - An unforeseeable error has occurred.

Request JSONSchema Descriptions

Field Name Description

list_type The list type to which the threat belongs (GlobalQuarantine or GlobalSafe).

sha256 The SHA256 hash for the threat.

Cylance User APIGuide, v2.0 rev34, December 2020 | 77

Policy API

- 78 -

Get Policies

Request a page with a list of Console policies belonging to a tenant, sorted by modified date,

in descending order (most recently modified policy listed first). The page number and page size

parameters are optional. When the values are not specified, these default to 1 and 10

respectively.

Note: When a policy is created, the modified date is the same as the created date, until the

policy is modified.

Service Endpoint:

n /policies/v2?page=m&page_size=n

Append the following optional query string parameters:

n page: The page number to request

n page_size: The number of device records to retrieve per page

For example, to return the first page with up to 100 policies:

https://protectapi.cylance.com/policies/v2?page=1&page_size=100

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the policy:list scope

encoded

Request:

None

Response:

200 OK

{

"page_number":"1", "page_size": "10", "total_pages": "1", "total_number_of_items": "1", "page_items": [

{

"id": "d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea",

"name": "Test Policy",

"device_count": "1",

Cylance User APIGuide, v2.0 rev34, December 2020 | 79

"zone_count": "1",

"date_added": "2019-05-08T21:32:46.9860259",

"date_modified": "2019-05-08T21:32:46.9860259"

} ]

}

400 Bad Request - Returned for the following reasons:

n The Tenant ID cannot be retrieved from the JWTtoken

n The page number or page size specified is less than or equal to zero, or the page size is

greater than 100

401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.

403 Forbidden - The JWTToken did not contain the proper scope to perform this action.

404 Not Found - The device resources page requested doesn't exist.

500 Internal Server Error - An unforeseeable error has occurred.

Response JSONSchema Descriptions

Field Name Description

date_added The date and time (in UTC) when the Console policy resource was first

created.

date_modified The date and time (in UTC) when the Console policy resource was last

modified.

device_count The number of devices assigned to this policy.

id The unique ID for the policy resource.

name The name of the policy.

page_number The page number requested.

page_size The page size requested.

total_number_of_ items

total_pages The total number of pages that can be retrieved based on the page size

zone_count The number of zones assigned to this policy.

The total number of resources.

specified.

Cylance User APIGuide, v2.0 rev34, December 2020 | 80

Get Policy

Get details for a policy, using the policy ID.

Service Endpoint:

n /policies/v2/{policy_id}

Example: https://protectapi.cylance.com/policies/v2/d5c6d6a3-0599-4fb5-

96bc-0fdc7eacb6ea

Method:

n HTTP/1.1 GET

Request Headers:

n Accept: application/json

n Authorization:Bearer <JWTToken returned by Auth API> with the policy:read scope

encoded

Request:

None

Response:

200 OK

{

"policy": [

{

"value":"1",

"name":"auto_blocking"

}, {

"value":"1",

"name": "auto_uploading"

}, {

"value": "500",

"name":"threat_report_limit"

}, {

"name":"low_confidence_threshold",

"value":"-600"

}, {

"value":"2",

"name":"full_disc_scan"

}, {

Cylance User APIGuide, v2.0 rev34, December 2020 | 81

"name":"watch_for_new_files",

"value":"1"

}, {

"value":"1",

"name":"memory_exploit_detection"

}, {

"value":"1",

"name":trust_files_in_scan_exception_list"

}, {

"name":"logpolicy",

"value":"0"

}, {

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

}, {

Cylance User APIGuide, v2.0 rev34, December 2020 | 82

"value":"0",

"name":"optics_script_control_auto_upload"

}, {

"value":"0",

"name":"optics_application_control_auto_upload"

}, {

"name":"device_control",

"value":"1"

}, {

"name": "optics_sensors_dns_visibility",

"value": "0"

}, {

"value": "0",

"name": "optics_sensors_private_network_address_visibility"

}, {

"name": "optics_sensors_windows_event_log_visibility",

"value": "0"

}, {

"name": "optics_sensors_advanced_powershell_visibility",

"value": "0"

}, {

"name": "optics_sensors_advanced_wmi_visibility",

"value": "0"

}, {

"name": "optics_sensors_advanced_executable_parsing",

"value": "0"

}, {

"name": "optics_sensors_enhanced_process_hooking_visibility",

"value": "0"

}, {

"value": "1",

"name": "optics"

}, {

"name": "auto_delete",

"value": "1"

}, {

"name": "days_until_deleted",

"value": "14"

}, {

Cylance User APIGuide, v2.0 rev34, December 2020 | 83

"name": "pdf_auto_uploading",

"value": "0"

}, {

"name": "ole_auto_uploading",

"value": "0"

}, {

"name": "docx_auto_uploading",

"value": "0"

}, {

"value": "0",

"name": "python_auto_uploading"

}, {

"value": "0",

"name": "autoit_auto_uploading"

}, {

"name": "powershell_auto_uploading",

"value": "0"

}, {

"name": "custom_thumbprint",

"value": null

}, {

"value": [

"c:\\temp" ], "name": "scan_exception_list"

}, {

"name": "optics_show_notifications", "value": "1"

} ], "device_control": {

"configurations": [

{

"device_class": "AndroidUSB",

"control_mode": "FullAccess" }, {

"control_mode": "FullAccess",

"device_class": "iOS" }, {

"control_mode": "FullAccess",

"device_class": "StillImage" },

Cylance User APIGuide, v2.0 rev34, December 2020 | 84

{

"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 device control exclusion",

"serial_number""987654321",

"product_id":"5678",

"control_mode":"FullAccess",

"date_added":"2019-03-07T17:58:36.484Z" }

] }, "memoryviolation_actions":{

"memory_violations":[

{

"violation_type":"lsassread",

"action":"Terminate" }, {

"violation_type":"outofprocessunmapmemory",

"action":"Terminate" }, {

"violation_type":"stackpivot",

"action":"Terminate" }, {

"violation_type":"stackprotect",

"action":"Terminate" }, {

"violation_type":"outofprocessoverwritecode",

"action":"Terminate" }, {

"action":"Terminate",

"violation_type":"outofprocesscreatethread"

Cylance User APIGuide, v2.0 rev34, December 2020 | 85

}, {

"violation_type":"overwritecode",

"action":"Terminate" }, {

"action":"Terminate",

"violation_type":"outofprocesswritepe" }, {

"violation_type":"outofprocessallocation",

"action":"Terminate" }, {

"violation_type":"outofprocessmap",

"action":"Terminate" }, {

"violation_type":"outofprocesswrite",

"action":"Terminate" }, {

"action":"Terminate",

"violation_type":"outofprocessapc" }

], "memory_violations_ext":[

{

"violation_type":"dyldinjection",

"action":"Terminate" }, {

"violation_type":"trackdataread",

"action":"Terminate" }, {

"action":"Terminate",

"violation_type":"zeroallocate" }, {

"action":"Terminate",

"violation_type":"maliciouspayload" }

], "memory_exclusion_list":[

"\\temp"

] }, "script_control":{

"powershell_settings": {

"control_mode":"Block", "console_mode":"Block"

Cylance User APIGuide, v2.0 rev34, December 2020 | 86

"global_settings":{

"control_mode":"Alert", "allowed_folders":[

"\\temp_scriptcontrol"

] }, "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":null, "maxlogsize":"100"

}, "checksum":"" "file_exclusions":[], "policy_name":"Test Policy", "appcontrol":{

"lockdown":[

{

"action":"deny",

"lockdown_type":"executionfromexternaldrives" }, {

"lockdown_type":"pechange",

"action":"deny" }

], "allowed_folders":[

"c:\\temp_appcontrol"

"changewindow_enabled":"1" }, "policy_id":"d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea", "policy_utctimestamp":"/Date(1557768200200+0000)/"

}

Cylance User APIGuide, v2.0 rev34, December 2020 | 87

404 Not Found - The tenant policy ID specified is valid, but no such record exists.

Response JSONSchema Descriptions

Field Name Description

appcontrol Application Control allows restricting any changes to applications on a

device. Only the applications that exist on a device before enabling ApplicationControl are allowed to execute on that device. Any new applications, as well as changes to the executables of existing applications, will be denied.

The Agent Updater will also be disabled when Application Control is enabled.

n allowed_folders: Allows applications and additions to the specified

folders. Must be an absolute path. Example:c:\temp_appcontrol.

n changewindow_enabled:

l 0 - Closed:No changes can be made to any applications on

the device.

l 1 - Open:Allow, edit, and run new applications on the device.

This includes updating applications.

n lockdown:

l action:

l deny:Blocks (denies) the lockdown_type.

l lockdown_type:

l executionfromexternaldrives:Executing a file from an

external drive, like a USB hard drive or USBflash drive.

l pechange:Making changes to existing applications on

the device.

checksum Used for detecting errors that may have occurred during transmission or

storage of data.

device_control Device Control

n control_mode:

l Block:Does not allow the selected device_class to connect to

the device.

l FullAccess:Allows the selected device_class to connect to the

device.

n device_class:

l AndroidUSB:A portable device running Android OS, like a

smartphone or tablet.

Note: An Android device could connect and be identified as Android, Still Image, or Windows Portable Device (WPD). When blocking Android devices, consider also blocking Still Image and Windows Portable Devices.

iOS:An Apple portable device running iOS, like an iPhone or

iPad.

Cylance User APIGuide, v2.0 rev34, December 2020 | 88

Field Name Description

Note: iOSdevices will not charge when Device Control is

enabled and set to Block, unless the iOS device is powered off. Apple includes their charging capability within functions of the device that are required for our iOSdevice blocking capability.

l StillImage:The device class that includes scanners, digital

cameras, multi-mode video cameras with frame capture, and frame grabbers.

l USBCDDVDRW:A USBoptical drive.

l USBDrive:A USBhard drive or USBflash drive.

l VMWareMount:The VMware USBPassthrough that allows a

VMware virtual machine client to access USB devices connected to the host.

l WPD - A portable device that uses the Microsoft Windows

Portable Device (WPD)driver technology, such as a mobile phone, digital camera, and portable media players.

n exclusion_list:DeviceControl exclusions that allow full access or block

connecting a USB device. The vendor_id is required.

l comment: Optional information about why the exclusion was

added.

l control_mode:

l Block:Blocks the specified vendor_id from connecting to

the device.

l FullAccess:Allows the specified vendor_id to connect to

the device.

l date_added: The date and time the Device Control exclusion

was added to the policy.

l product_id: Some manufacturers provide a unique identifier for

each USBproduct they make.This information is optional.

l serial_number: Some manufacturers provide a unique serial

number for each USBdevice they make.This information is optional.

l vendor_id:The unique identifier for the manufacturer of the USB

device.

file_exclusions The Policy Safe List identifies file exclusions specific to the policy, and any

devices assigned to the policy will allow the excluded files to run.

n av_industry:

l false:The file hash has not been identified by the anti-virus

industry.

l true:The file hash has been identified by the anti-virus industry.

n category_id:The Category selected when adding the file to the policy

Safe List.

l 1 = None

l 2 = AdminTool

Cylance User APIGuide, v2.0 rev34, December 2020 | 89

Field Name Description

l 3 = Internal Application

l 4 = Commercial Software

l 5 = Operating System

l 6 = Drivers

l 7 = Security Software

n cloud_score: The Cylance Score displayed in the Console. The score

can go up to 100.

n file_hash:The SHA256 has for the file.This information is required.

n file_name:The name of the file. This is "null" if the filename is not

available.

n file_type:The file scanner type. Should always return 1 for executable.

n infinity: The Cylance Cloud score. This is "null" if no score is available.

n md5: The MD5 hash for the file. This information is optional.

n reason: The reason for adding the file to the policy Safe List.The

reason must be added when creating the file exclusion.

n research_class_id: The Cylance threat classification. If "infinity" is null,

then the research_class_id is not available.

l 1 = Trusted

l 2 = PUP

l 3 = Malware

l 4 = File Unavailable

l 5 = Possible PUP

l 6 = Dual Use

n research_subclass_id:Some threat classification have sub-classes to

help administrators determine if a file should be blocked or allowed to run. See "Threat Classifications" on page333 for more information.

filetype_actions The Auto Quarantine of Unsafe (threat_files) and Abnormal (suspcisious_

files). (Policy >File Actions)

n actions - The setting to enable or disable Auto Quarantine and Auto

Upload.

l 0 - AutoQuarantine OFF and AutoUpload OFF

l 1 - AutoQuarantine ON and AutoUpload OFF

l 2 - AutoQuarantine OFF and AutoUpload ON

l 3 - AutoQuarantine ON and AutoUpload ON

n file_type - The only option is "executable".

n suspicious_files - Abnormal files

n threat_files - Unsafe files

logpolicy The Agent log file settings.

n log_upload - The setting to enable or disable uploading log files.

l null - Disabled

l 1 - Enabled

Cylance User APIGuide, v2.0 rev34, December 2020 | 90

Field Name Description

n maxlogsize - The maximum file size (in MB) for a single log file.

n retentiondays - The number of days to save log files.Log files older

than the set number of days will be deleted.

memoryviolation_ actions

The Violation Types for MemoryProtection.

All Violation Types must be included in the Request.

n memory_violations:

l lsassread (LSASSRead) - Memory belonging to the Windows

Local Security Authority process has been accessed in a manner that indicates an attempt to obtain users' passwords.

l outofprocessallocation (Remote Allocation of Memory) - A

process has allocated memory in another process. Most allocations will only occur within the same process. This generally indicates an attempt to inject code or data into another process, which may be a first step in reinforcing a malicious presence on a system.

l outofprocessapc (Remote APC Scheduled) - A process has

diverted the execution of another process’s thread. This is generally used by an attacker to activate a malicious presence that has been injected into another process.

l outofprocesscreatethread (Remote Thread Creation) - A process

has created a new thread in another process. A process’s threads are usually only created by that same process. This is generally used by an attacker to activate a malicious presence that has been injected into another process.

l outofprocessmap (Remote Mapping of Memory) - A process has

introduced code and/or data into another process. This may indicate an attempt to begin executing code in another process and thereby reinforce a malicious presence.

l outofprocessoverwritecode (Remote Overwrite Code) - A

process has modified executable memory in another process. Under normal conditions, executable memory will not be modified, especially by another process. This usually indicates an attempt to divert execution in another process.

l outofprocessunmapmemory (Remote Unmap of Memory) - A

process has removed a Windows executable from the memory of another process. This may indicate an intent to replace the executable image with a modified copy for the purpose of diverting execution.

l outofprocesswrite (Remote Write to Memory) - A process has

modified memory in another process. This is usually an attempt to store code or data in previously allocated memory (see OutOfProcessAllocation), but it is possible that an attacker is trying to overwrite existing memory in order to divert execution for a malicious purpose.

l outofprocesswritepe (Remote Write PEto Memory) - A process

has modified memory in another process to contain an

Cylance User APIGuide, v2.0 rev34, December 2020 | 91

Field Name Description

executable image. Generally, this indicates that an attacker is attempting to execute code without first writing that code to disk.

l overwritecode (Overwrite Code) - The code residing in a

process’s memory has been modified using a technique that may indicate an attempt to bypass Data Execution Prevention (DEP).

l stackpivot (Stack Pivot) - The stack for a thread has been

replaced with a different stack. Generally, the system will only allocate a single stack for a thread. An attacker would use a different stack to control execution in a way that is not blocked by Data Execution Prevention (DEP).

l stackprotect (Stack Protect) - The memory protection of a

thread’s stack has been modified to enable execution permission. Stack memory should not be executable, so usually this means that an attacker is preparing to run malicious code stored in stack memory as part of an exploit, an attempt which would otherwise be blocked by Data Execution Prevention (DEP).

n memory_violation_ext:

l dyldinjection (DYLDInjections) - An environment variable has

been set that will cause a shared library to be injected into a launched process. Attacks can modify the plist of applications like Safari or replace applications with bash scripts, causing their modules to be loaded automatically when an application starts.

l maliciouspayload (Malicious Payload) - A generic shellcode and

payload detection associated with exploitation has been detected.

l trackdataread (RAMScraping) - A process is trying to read valid

magnetic stripe track data from another process. Typically related to point of sale systems (POS).

l zeroallocate (Zero Allocate) - A null page has been allocated.

The memory region is typically reserved, but in certain circumstances, it can be allocated. Attacks can use this to setup privilege escalation by taking advantage of some known null de-reference exploit, typically in the kernel.

n memory_exclusion_list:The executable files to exclude from Memory

Protection. This must be a relative path to the excluded executable file. Example: \\temp

policy Various policy settings are contained within this section.

All policy settings must be included in the Request.

n auto_blocking - Setting to Auto Quarantine Unsafe threats.

l 0 - Disabled

l 1 - Enabled

n auto_delete - Setting to automatically delete quarantined files after a

set number of days. If this feature is enabled, set "days_until_deleted"

Cylance User APIGuide, v2.0 rev34, December 2020 | 92

Field Name Description

for the number of days to retain a quarantined file.

l 0 - Disabled

l 1 - Enabled

n auto_uploading - Setting to automatically upload files that Cylance has

not seen before. Cylance will perfrom an analysis on the file and provide details to assist in manual analysis and triage.

l 0 - Disabled

l 1 - Enabled

n autoit_auto_uploading: Currently not in use.

n days_until_deleted - Setting for the number of days to retain a

quarantined file. Quarantined files older than the set number of days will be automatically deleted. The minimum number of days is 14, the maximum number of days is 365. The "auto-delete" setting must be enabled.

n device_control - Setting to enable or disable the Device Control

feature.

l 0 - Disabled

l 1 - Enabled

n docx_auto_uploading:Currently not in use.

n full_disc_scan - Setting to have Cylance analyze all executable files

on disk to detect any dormant threats. This is the Background Threat Detection setting.

l 0 - Disabled

l 1 - Run Recurring (performs a scan every nine days)

l 2 - Run Once (runs a full disk scan upon installation only)

n kill_running_threats - Setting to kill processes and children processes

regardless of the state when a threat is detected (EXE or DLL).

l 0 - Disabled

l 1 - Enabled

n logpolicy - This setting is not used.

n low_confidence_threshold - Setting to adjust the Cylance Score

threshold between Unsafe and Abnormal threats. The default is -600, therefore:

l A Cylance Score of -600 to -1000 is Unsafe

l A Cylance Score of 0 to -599 is Abnormal

l A Cylance Score greater than 0 is Safe

n memory_exploit_detection - Setting to enable or disable the Memory

Protection feature. This affects "memory_violation_actions" ("memory_ violations" and "memory_violations_ext").

n ole_auto_uploading:Currently not in use.

n optics - Setting to enable or disable CylanceOPTICS.

l 0 - Disabled

l 1 - Enabled

n optics_application_control_auto_upload - Setting to allow the automatic

Cylance User APIGuide, v2.0 rev34, December 2020 | 93

Field Name Description

uploading of Application Control related Focus Data.

l 0 - Disabled

l 1 - Enabled

n optics_malware_auto_upload - Setting to allow the automatic uploading

of Threat related Focus Data.

l 0 - Disabled

l 1 - Enabled

n optics_memory_defense_auto_upload - Setting to allow the automatic

uploading of Memory Protection related Focus Data.

l 0 - Disabled

l 1 - Enabled

n optics_script_control_auto_upload - Setting to allow the automatic

uploading of Script Control related Focus Data.

l 0 - Disabled

l 1 - Enabled

n optics_sensors_advanced_executable_parsing:Setting to enable

recording data fields associated with Portable Executable (PE)files, such as File version, Import functions, and Packer types. This is Enhanced Portable Executable Parsing in the policy settings.

l 0 - Disabled

l 1 - Enabled

n optics_sensors_advanced_powershell_visibility: Setting to enable

recording commands, arguments, scripts, and content entered directly into the Powershell Console and the Powershell Integrated Scripting Environment (ISE).

l 0 - Disabled

l 1 - Enabled

n optics_sensors_advanced_wmi_visibility: Setting to enable recording

additional Windows Management Instrumentation (WMI) attributes and parameters.

l 0 - Disabled

l 1 - Disabled

n optics_sensors_dns_visibility:Setting to enable recording commands

and arguments of commands issued directly or indirectly to the Windows Management Instrumentation (WMI)interpreter.

l 0 - Disabled

l 1 - Enabled

n optics_sensors_enhanced_process_hooking_visibility:Setting to enable

recording process information from the Win32 API and Kernel Audit messages to detect forms of process hooking and injection.

l 0 - Disabled

l 1 - Enabled

n optics_sensors_private_network_address_visibility: Setting to enable

recording network connections within the RFC 1918 and RFC 3419

Cylance User APIGuide, v2.0 rev34, December 2020 | 94

Field Name Description

address spaces.

l 0 - Disabled

l 1 - Enabled

n optics_sensors_windows_event_log_visibility:Setting to enable

recording Windows Security Events and their associated attributes.

l 0 - Disabled

l 1 - Enabled

n optics_set_disk_usage_maximum_fixed:Setting the maximum amount of

device storage reserved for use by CylanceOPTICS, in MB. The minimum value is 500 and the maximum value is 1000.

Example:

{

"name":"optics_set_disk_usage_maximum_fixed",

"value":"1000"

}

n optics_show_notifications: Setting to enable or disable Desktop

Notifications on the endpoint for CylanceOPTICS events.

l 0 - Disabled

l 1 - Enabled

n pdf_auto_uploading:

n powershell_auto_uploading:

n prevent_service_shutdown:Setting that protects the Cylance service

from being shutdown, either manually or by another process.

l 0 - Disabled

l 1 - Enabled

n python_auto_uploading:

nn sample_copy_path:Setting to copy all file samples to a network share

(CIFS/SMB).

Example:

{

"name":"sample_copy_path", "value":"\\\\server_name\\shared_folder"

}

n scan_exception_list:Setting to exclude specific folders and subfolders

from being scanned by full_disc_scan and watch_for_new_files. Set the value to the absolute path for the excluded files.

Example:

{

"name":"scan_exception_list", "value":[

"c:\\temp"

]

}

n scan_max_archive_size:Setting for the maximum archive file size (in

Cylance User APIGuide, v2.0 rev34, December 2020 | 95

Field Name Description

MB) to be scanned. The value can be 0 to 150. If set to 0, then archive files will not be scanned.

Example:

{

"name":"scan_max_archive_size", "value":"0"

}

n script_control:Setting to enable or disable the Script Control feature.

Note: Also set the script_control settings (see below in this table).

l 0 - Disabled

l 1 - Enabled

n show_notifications:Setting to enable or disable Desktop Notifications

on the endpoint for CylancePROTECT events.

l 0 - Disabled

l 1 - Enabled

n threat_report_limit:The number of threats to upload to the Console.

Example:

{

"name":"threat_report_limit",

"value":"500"

}

n trust_files_in_scan_exception_list:Setting to Allow Execution of files in

the excluded folders.This is related to the scan_exception_list.

0 - Disabled

1 - Enabled (Allows execution of files in the excluded folders)

watch_for_new_files:Setting to analyze new or modified executable files for threats.

l 0 - Disabled

l 1 - Enabled

n optics_set_disk_usage_maximum_fixed - Setting the maximum amount

of device storage reserved for use by CylanceOPTICS, in MB. The minimum amount is 500MB and the maximum is 1000MB.

n optics_show_notification:Setting to enable or disable CylanceOPTICS

Desktop Notifications on the device.

l 0 - Disabled

l 1 - Enabled

n pdf_auto_uploading:Currently not in use.

n powershell_auto_uploading: Currently not in use.

n prevent_service_shutdown - Setting that protects the Cylance service

from being shutdown, either manually or by another process.

n python_auto_uploading:Currently not in use.

n sample_copy_path - Setting to copy all file samples to a network share

Cylance User APIGuide, v2.0 rev34, December 2020 | 96

Field Name Description

(CIFS/SMB). Use the fully qualified path.

n Example:\\server_name\shared_folder.

n scan_exception_list - Setting to exclude specific folders and subfolders

from being scanned by "full_disc_scan" and "watch_for_new_files". Set the value to the absolute path for the excluded files.

n scan_max_archive_size - Setting for the maximum archive file size (in

MB) to be scanned. The value can be 0 to 150. If set to 0, then archive files will not be scanned.

n script_control - Setting to enable or disable the Script Control feature.

l 0 - Disabled

l 1 - Enabled

n show_notifications - Setting to enable or disable Desktop Notifications

on the device.

l 0 - Disabled

l 1 - Enabled

n threat_report_limit - The number of threats to upload to the Console.

n trust_files_in_scan_exception_list - Setting to Allow Execution of files in

the excluded folders.This is related to the scan_exception_list.

l 0 - Disabled

l 1 - Enabled (Allows execution of files in the excluded folders)

n watch_for_new_files - Setting to analyze new or modified executable

files for threats.

policy_id The unique identifier for the policy.

policy_name The name of the policy.

policy_

The date and time the policy was created (in UTC).

utctimestamp

script_control Script Control settings in a policy.

n activescript_settings:

l control_mode:Allows or blocks ActiveScript usage.

l Allow

l Block

n global_settings:

l allowed_folders:Specifies folder exclusions, including

subfolders, for Script Control. Specifies a relative path.

l control_mode:Allows or blocks ActiveScript and PowerShell

usage with Agent 1370 or lower.

l Allow

l Block

n macro_settings:

l control_mode: Allows or blocks Macro usage. Microsoft Office

macros use Visual Basic for Applications (VBA).

Cylance User APIGuide, v2.0 rev34, December 2020 | 97

Field Name Description

l Allow

l Block

n powershell_settings:

l console_mode:Allows or blocks the PowerShell console. This

affects PowerShell command usage, including PowerShell oneliners.

l Allow

l Block

l control_mode: Allows or blocks PowerShell usage.

l Allow

l Block

Create Policy

Create a policy.

Service Endpoint:

n /policies/v2

Example:https://protectapi.cylance.com/policies/v2

Method:

n HTTP/1.1 POST

Request Header:

n Content-Type:application/json

n Authorization:Bearer <JWTToken returned by AuthAPI> with the policy:create scope

encoded.

Request:

Note: The following example creates a policy with all features disabled (blank policy), except for

Execution Control (which is always enabled).

{

"user_id": "a2c0ac7a-a63d-4583-b646-ae10db9c9769", "policy": {

"policy": [

{

"name": "auto_blocking",

"value": "0" }, {

Cylance User APIGuide, v2.0 rev34, December 2020 | 98

"name": "auto_uploading",

"value": "0" }, {

"name": "threat_report_limit",

"value": "500" }, {

"name": "low_confidence_threshold",

"value": "-600" }, {

"name": "full_disc_scan",

"value": "0" }, {

"name": "watch_for_new_files",

"value": "0" }, {

"name": "memory_exploit_detection",

"value": "0" }, {

"name": "trust_files_in_scan_exception_list",

"value": "0" }, {

"name": "logpolicy",

"value": "0" }, {

"name": "script_control",

"value": "0" }, {

"name": "prevent_service_shutdown",

"value": "0" }, {

"name": "scan_max_archive_size",

"value": "0" }, {

"name": "sample_copy_path",

"value": null }, {

"name": "kill_running_threats",

"value": "0" }, {

Cylance User APIGuide, v2.0 rev34, December 2020 | 99

"name": "show_notifications",

"value": "0" }, {

"name": "optics_set_disk_usage_maximum_fixed",

"value": "1000" }, {

"name": "optics_malware_auto_upload",

"value": "0" }, {

"name": "optics_memory_defense_auto_upload",

"value": "0" }, {

"name": "optics_script_control_auto_upload",

"value": "0" }, {

"name": "optics_application_control_auto_upload",

"value": "0" }, {

"name": "optics_sensors_dns_visibility",

"value": "0" }, {

"value": "0",

"name": "optics_sensors_private_network_address_visibility" }, {

"name": "optics_sensors_windows_event_log_visibility",

"value": "0" }, {

"name": "optics_sensors_advanced_powershell_visibility",

"value": "0" }, {

"name": "optics_sensors_advanced_wmi_visibility",

"value": "0" }, {

"name": "optics_sensors_advanced_executable_parsing",

"value": "0" }, {

"name": "optics_sensors_enhanced_process_hooking_visibility",

"value": "0" {

"name": "device_control",

Cylance User APIGuide, v2.0 rev34, December 2020 | 100

BlackBerry CylancePROTECT, CylanceOPTICS User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

Application Management

Application Management

To Add an Application

To Edit an Application

To Delete an Application

To Regenerate an Application Control

Copy Tenant ID

API in Audit Logs

RESTful API

Authentication and Authorization

Application

Service Endpoint

Authentication

Authentication Token

Generating the Authentication and Access Tokens

Token Lifecycle

Request / Response Model

Authorization

Access Token

Response Status Codes

API Rate Limit

About Device ID

About Zone ID

User API

Create User

Get Users

Get User

Update User

Delete User

Send Invite Email

Send Request Password Email

Device API

Get Devices

Get Devices Extended

Get Device Count

Get Device

Get Device by MAC Address

Get Device by Hostname

Update Device

Get Device Threat

Update Device Threat

Get Zone Devices

Get Agent Installer Link

Delete Devices

Global List API

Get Global List

Add to Global List

Delete From Global List

Policy API

Get Policies

Get Policy

Create Policy