Cylance PROTECT API Guide V2.0 Rev10

User Manual:

Open the PDF directly: View PDF .
Page Count: 97

Download
Open PDF In Browser	View PDF

CylancePROTECT®
User API Guide

Product: CylancePROTECT

Global Headquarters

Document: CylancePROTECT Console API Guide. This guide is a
succinct resource for analysts, Administrators, and customers
who are reviewing or evaluating the product.

400 Spectrum Drive, Irvine, CA 92618

Document Release Date: v2.0 rev10, March 2018

+1-877-97DEFEND • +1-877-973-3336

About Cylance®: Cylance uses artificial intelligence to deliver
prevention-first, predictive security products and specialized
security services that change how organizations approach
endpoint security. Cylance’s security solutions provide full
spectrum predictive threat prevention and visibility across the
enterprise, combatting threats such as malware, ransomware,
fileless malware, malicious scripts, weaponized docs, and
other attack vectors. With AI based malware prevention,
application and script control, memory protection, device
policy enforcement, root cause analysis, threat hunting,
automated threat detection and response, coupled with expert
security services, Cylance can protect endpoints without
increasing staff workload or costs. Visit cylance.com.

Professional Services Hotline

Corporate Contact
+1-914-CYLANCE • +1-914-295-2623
Email
sales@cylance.com
Website
https://www.cylance.com
To Open a Support Ticket
https://support.cylance.com — Click on Submit a Ticket
To View Knowledge Base and Announcements
Login to https://support.cylance.com
To Request a Callback from Cylance Support
+1-866-699-9689

CylancePROTECT User API Guide — v2.0 rev10

Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Update Device Threat . . . . . . . . . . . . . . . . . . . . 39
Get Zone Devices . . . . . . . . . . . . . . . . . . . . . . . 40

Application Management . . . . . . . . . . . . . . . . . . . .7

Get Agent Installer Link . . . . . . . . . . . . . . . . . . . 41

To Add an Application . . . . . . . . . . . . . . . . . . . 7

Delete Devices . . . . . . . . . . . . . . . . . . . . . . . . 43

To Edit an Application . . . . . . . . . . . . . . . . . . . 9

Get Device by MAC Address . . . . . . . . . . . . . . . . 44

To Delete an Application . . . . . . . . . . . . . . . . 10

Global List API . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Copy Tenant ID . . . . . . . . . . . . . . . . . . . . . . 12
RESTful API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Authentication and Authorization . . . . . . . . . . . . . . 14
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Service Endpoint . . . . . . . . . . . . . . . . . . . . . . . 14
Authentication . . . . . . . . . . . . . . . . . . . . . . . . 14
Authentication Token . . . . . . . . . . . . . . . . . . 15
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Generating the Authentication and
Access Tokens . . . . . . . . . . . . . . . . . . . . . 16
Software Requirements . . . . . . . . . . . . . . . . 16
Token Lifecycle . . . . . . . . . . . . . . . . . . . . . . 17
Request/Response Model . . . . . . . . . . . . . . . 17
Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 18
Access Token . . . . . . . . . . . . . . . . . . . . . . . 18
Response Status Codes . . . . . . . . . . . . . . . . . . . . 18
Region Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
User API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Create User . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Get Users . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Get User . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Update User . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Delete User . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Send Invite Email . . . . . . . . . . . . . . . . . . . . . . . 30
Send Reset Password Email . . . . . . . . . . . . . . . . 30
Device API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Get Global List . . . . . . . . . . . . . . . . . . . . . . . . 47
Add To Global List . . . . . . . . . . . . . . . . . . . . . . 49
Delete From Global List . . . . . . . . . . . . . . . . . . . 51
Policy API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Get Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Get Policies . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Create Policy . . . . . . . . . . . . . . . . . . . . . . . . . 59
Update Policy . . . . . . . . . . . . . . . . . . . . . . . . . 70
Delete Policy . . . . . . . . . . . . . . . . . . . . . . . . . 79
Delete Policies . . . . . . . . . . . . . . . . . . . . . . . . 79
Zone API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Create Zone . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Get Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Get Device Zones . . . . . . . . . . . . . . . . . . . . . . . 83
Get Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Update Zone . . . . . . . . . . . . . . . . . . . . . . . . . 86
Delete Zone . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Threat API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Get Threat . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Get Threats . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Get Threat Devices . . . . . . . . . . . . . . . . . . . . . . 91
Get Threat Download URL . . . . . . . . . . . . . . . . . 94
API Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
REST Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
JSON Validators . . . . . . . . . . . . . . . . . . . . . . . . . 96

Get Devices . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Get Device . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Update Device . . . . . . . . . . . . . . . . . . . . . . . . 36
Get Device Threats . . . . . . . . . . . . . . . . . . . . . . 37

CylancePROTECT User API Guide — v2.0 rev10

Overview

Overview
Cylance’s award winning next-generation anti-malware product, CylancePROTECT, offers APIs as an alternative way of interacting
with the system.
The latest version of Cylance’s API allows you to create multiple applications to control access to your Cylance Console data. You
can provide Read, Write, Modify, and Delete privileges to each of the API calls. Each API application has unique credentials (ID and
Secret) that are used to create a token.

CylancePROTECT User API Guide — v2.0 rev10

Application Management

Application Management
CylancePROTECT Administrators can manage multiple API applications, including the access privileges to your CylancePROTECT
Console data.
To Add an Application:
1.

Log in to the CylancePROTECT Console (https://login.cylance.com/Login) as an Administrator. Only Administrators can create
an application integration.

Select Settings > Integrations.

Click Add Application.

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

Select the access privilege for a Console data type. Not selecting any checkboxes for a data type means the application does
not have access to that data type.

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.

CylancePROTECT User API Guide — v2.0 rev10

Data Type

Description

Devices

Devices are systems with a CylancePROTECT Agent installed. You can get information
about devices in your organization. You can also add (Write) 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.

Policy

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

Threat

Threat Details provide information about a file as well as reference information
about why a file is considered Safe or a Threat. Use the Threats request to get this
information.

User

Users have access to the data in the Console, based on the role assigned to 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.

Zone

Each device belongs to at least one Zone. Zones are similar to tags and assist in
organizing your devices.

Privilege

Description

Read

Ability to read data but cannot create, modify, or delete the data.

Write

Ability to add data to the Console.

Modify

Ability to modify existing data.

Delete

Ability to delete the data.

CylancePROTECT User API Guide — v2.0 rev10

To Edit an Application:
1.

Log in to the CylancePROTECT Console (https://login.cylance.com/Login) as an Administrator. Only Administrators can create
an application integration.

Select Settings > Integrations.

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

Edit the privileges, then click Save Changes.

CylancePROTECT User API Guide — v2.0 rev10

To Delete an Application:
1.

Log in to the CylancePROTECT Console (https://login.cylance.com/Login) as an Administrator. Only Administrators can create
an application integration.

Select Settings > Integrations.

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

Click Remove Application to confirm the deletion.

CylancePROTECT User API Guide — v2.0 rev10

To Regenerate an Application Credential:
1.

Log in to the CylancePROTECT Console (https://login.cylance.com/Login) as an Administrator. Only Administrators can
regenerate an application credential.

Select Settings > Integrations.

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

Click Regenerate Credentials. A confirmation message appears.

Click Yes, Regenerate to confirm regenerating the credentials.

CylancePROTECT User API Guide — v2.0 rev10

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

CylancePROTECT User API Guide — v2.0 rev10

RESTful API

RESTful API
Cylance provides RESTful APIs for registered organizations to manage their resources. To access the CylancePROTECT 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 CylancePROTECT 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 CylancePROTECT Web 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 section.

Service Endpoint
The Auth API will be accessed via the following base endpoint:
North America: https://protectapi.cylance.com/auth/v2
US Government: https://protectapi.us.cylance.com/auth/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/auth/v2

Authentication
During the step which a client system requests access prior to using CylancePROTECT 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 flow:
• 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 CylancePROTECT 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.

CylancePROTECT User API Guide — v2.0 rev10

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
Date and time when the Token expires and is no longer valid for processing. This is
Unix epoch time in seconds.

exp

NumericDate

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.

iat

NumericDate

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

iss

StringOrUri

Represents the principal issuing the token, which is “http://cylance.com”

jti

String

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

sub

StringOrUri

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

Custom Claims
scp

String

Comma delimited scopes requested. This claim is Optional.

tid

String

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-47b6-80ce-4dda3c91bba3”);
token.Claims.Add(“tid”, “f00e9987-ee61-57b7-80cf-5eeb3d02ccb4”);
o token.claims.Add(“scp”, “policy:create, policy:list, policy:read,
policy:update”)

CylancePROTECT User API Guide — v2.0 rev10

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.
Software Requirements:
• Python 2.7 (latest version is recommended)
• PyJWT package (pip install PyJWT)
• Requests package (pip install requests)
Examples using C# are available upon request.
Python Examples
import jwt # PyJWT version 1.5.3 as of the time of authoring.
import uuid
import requests # requests version 2.18.4 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": "policy:create, policy:list, policy:read, policy:update"
}
encoded = jwt.encode(claims, app_secret, algorithm='HS256')
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"

CylancePROTECT User API Guide — v2.0 rev10

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

North America: https://protectapi.cylance.com/auth/v2/token
US Government: https://protectapi.us.cylance.com/auth/v2/token
All Other Regions: https://protectapi-{region-code}.cylance.com/auth/v2/token

Method

HTTP/1.1 POST

Request Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer with the user:create scope encoded.
Authentication Request Schema
{
"title":"Authentication Request",
"type":"object",
"properties": {
"auth_token":{
"type":"string",
"description":"Token representing authentication request"
}
},
"required":["auth_token"]

Request

COPY
CODE

}

Authentication Response Schema
{
"title":"Authentication Response",
"type":"object",
"properties": {
"access_token":{
"type":"string",
"description":"Access token granted by the Server"
}
},
"required":["access_token"]

Response

COPY
CODE

}
401 Unauthorized – Returned for the following reasons:
• The authentication token provided failed to authorize.
• The application ID supplied in the “sub” claim could not be found in the system.
403 Forbidden – The authentication token provided is requesting invalid or unavailable scopes.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

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 CylancePROTECT Resources. It contains information about the identity of the
caller (Application) as well as control information for 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
CylancePROTECT 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.

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.

400 – Bad Request

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 cause of this
type of error is malformed JSON in the request body. A JSON validator can be used to
troubleshoot these issues.

401 - Unauthorized

Invalid credentials were passed or some other failure in authentication.

403 – Forbidden

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

404 – Not Found

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

409 – Conflict

A request was made to create or update an aspect of the resource that conflicts with
another. The most common reason for this code is a Tenant name or User email that is
already in use.

500 – Internal Server
Error

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

501 – Not Implemented

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

Other

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

CylancePROTECT User API Guide — v2.0 rev10

Region Codes
The service endpoint address includes a region code to identify the set of servers to which your organization belongs.
Example: http://protectapi-euc1.cylance.com/devices/v2
NOTE: North America and US Government have a different format. See Service Endpoint for more information.

Region Code

Description

Asia-Pacific – North

apne1

Asia-Pacific – Southeast

Europe – Central

euc1

South America

sae1

Notes

User API
Create User
Create (add) a new Console User. This requires a unique email address for the User being created.
Service
Endpoint

North America: https://protectapi.cylance.com/users/v2
US Government: https://protectapi.us.cylance.com/users/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2

Method

HTTP/1.1 POST

Request
Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer with the user:create scope encoded.
Post User Request Schema
{
"email": "string",
"user_role": "string",
"first_name": "string",
"last_name": "string",
"zones": [
{
"id": "string",
"role_type": "string"
}
]

Request

COPY
CODE

}

CylancePROTECT User API Guide — v2.0 rev10

201 Created
Post User Response Schema
{
"id": "string",
"tenant_id": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"has_logged_in": true,
"role_type": "string",
"role_name": "string",
"default_zone_role_type": "string",
"default_zone_role_name": "string",
"zones": [
{
"id": "string",
"role_type": "string",
"role_name": "string"
}
],
"date_last_login": "2017-09-13T22:33:26.098Z",
"date_email_confirmed": "2017-09-13T22:33:26.098Z",
"date_created": "2017-09-13T22:33:26.098Z",
"date_modified": "2017-09-13T22:33:26.098Z"

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The User create request was empty.
• The Tenant ID cannot be retrieved from the JWT token.
• The User’s email address specified is not a proper email address.
• The User application role specified is not one of the accepted values.
• The zones array is empty when the User application role is not Administrator.
• 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 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The request JSON schema contains the following fields:

Field Name

Description

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 your Console.
• User: 00000000-0000-0000-0000-000000000001
• Administrator: 00000000-0000-0000-0000-000000000002
• Zone Manager: 00000000-0000-0000-0000-000000000003

zones

The zones to which the User has access. This is an array of elements.
• id: The unique identifier for the zone.
• role_type: The User’s role for this particular zone.
••Zone Manager: 00000000-0000-0000-0000-000000000001
••User: 00000000-0000-0000-0000-000000000002
• role_name: The name of the User’s role in this zone.
NOTE: If the User is an Administrator, this array is not required
and the elements specified will be ignored.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

date_created

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

date_email_confirmed

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

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

The unique identifier for the User’s default role when assigned to a zone.
• None: 00000000-0000-0000-0000-000000000000
• Zone Manager: 00000000-0000-0000-0000-000000000001
• User: 00000000-0000-0000-0000-000000000002

default_zone_role_
name

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

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.

The User’s unique identifier for the Console.

last_name

The User’s last name.

tenant_id

The organization’s unique identifier for the Console.

role_type

The unique identifier defining the User’s role in the Console.
• User: 00000000-0000-0000-0000-000000000001
• Administrator: 00000000-0000-0000-0000-000000000002
• Zone Manager: 00000000-0000-0000-0000-000000000003

role_name

The name of the User’s role in the Console.

zones

The zones to which the User has access. This is an array of elements.
• id: The unique identifier for the zone.
• role_type: The User’s role for this particular zone.
••None: 00000000-0000-0000-0000-000000000000
••Zone Manager: 00000000-0000-0000-0000-000000000001
••User: 00000000-0000-0000-0000-000000000002
• role_name: The name of the User’s role in this zone.
NOTE: If the User is an Administrator, this array is not required
and the elements specified will be ignored.

CylancePROTECT User API Guide — v2.0 rev10

Get Users
Allows a caller to 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

North America: https://protectapi.cylance.com/users/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/users/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the user:list scope encoded.

Request

Append the following optional query string parameters:
• page: The page number to request.
• page_size: The number of device records to retrieve per page.

CylancePROTECT User API Guide — v2.0 rev10

200 OK
Get Users Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"tenant_id": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"has_logged_in": true,
"role_type": "string",
"role_name": "string",
"default_zone_role_type": "string",
"default_zone_role_name": "string",
"zones": [
{
"id": "string",
"role_type": "string",
"role_name": "string"
}
],
"date_last_login": "2017-09-26T05:21:01.943Z",
"date_email_confirmed": "2017-09-26T05:21:01.943Z",
"date_created": "2017-09-26T05:21:01.943Z",
"date_modified": "2017-09-26T05:21:01.943Z"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

date_created

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

date_email_
confirmed

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

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

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.

user_id

The User’s unique identifier for the Console.

user_role

zones

CylancePROTECT User API Guide — v2.0 rev10

Get User
Allows a caller to request a specific Console User resource belonging to a Tenant.

Service
Endpoint

North America: https://protectapi.cylance.com/users/v2/{user_id | user_email_address}
US Government: https://protectapi.us.cylance.com/users/v2/{user_id | user_email_address}
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2/{user_id | user_email_
address}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the user:read scope encoded.

Request

None
200 OK
Get User Response Schema
{
"user_id": "string",
"tenant_id": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"has_logged_in": true,
"user_role": "string",
"default_zone_role": "string",
"zones": [
{
"id": "string",
"role_type": "string",
"role_name: "string"
}
],
"date_last_login": "2017-05-22T23:35:56.705Z",
"date_email_confirmed": "2017-05-22T23:35:56.705Z",
"date_created": "2017-05-22T23:35:56.705Z",
"date_modified": "2017-05-22T23:35:56.705Z"

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The User’s unique identifier is not valid (when using a unique User ID).
• The User’s email address specified is not a proper email address (when using User’s email address).
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The User resource cannot be found by the unique User ID or email address specified in
the URL.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

date_created

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

date_email_
confirmed

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

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

tenant_id

The organization’s unique identifier for the Console.

user_id

The User’s unique identifier for the Console.

user_role

zones

CylancePROTECT User API Guide — v2.0 rev10

Update User
Allows a caller to update an existing Console User resource.

Service
Endpoint

Method

HTTP/1.1 PUT

Request
Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer with the user:update scope encoded.
Put User Request Schema
{
"email": "string",
"user_role": "string",
"first_name": "string",
"last_name": "string",
"zones": [
{
"id": "string",
"role_type": "string"
}
]

Request

COPY
CODE

}

Response

200 OK
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The User ID is invalid or not specified.
• The User’s email address specified is not a proper email address.
• The User application role specified is not one of the accepted values.
• The zones array is empty when the User application role is not Administrator.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The User ID does not exist.
500 Server Error – The server encountered something it did not expect and was unable to complete the
request.

CylancePROTECT User API Guide — v2.0 rev10

The request JSON schema contains the following fields:

Field Name

Description

The User’s email address.

first_name

The User’s first name.

last_name

The User’s last name.

user_role

zones

Delete User
Allows a caller to delete an existing Console User resource.
Service
Endpoint

North America: https://protectapi.cylance.com/users/v2/{user_id}
US Government: https://protectapi.us.cylance.com/users/v2/{user_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2/{user_id}

Method

HTTP/1.1 DELETE

Request
Headers

Authorization: Bearer with the user:delete scope encoded.

Request

None

Response

200 OK - The User was deleted successfully.
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The User ID is invalid or not specified.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound– The User specified by unique User ID was not found.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

Send Invite Email
Allows a caller to request for the Console login invitation email to be sent or resent to an existing User.
Service
Endpoint

North America: https://protectapi.cylance.com/users/v2/{user_email_address}/invite
US Government: https://protectapi.us.cylance.com/users/v2/{user_email_address}/invite
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2/{user_email_address}/invite

Method

HTTP/1.1 POST

Request
Headers

Authorization: Bearer with the user:read scope encoded.

Request

None

Response

200 OK– The email was successfully sent.
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The unique ID of the User triggering the invitation email to be sent cannot be retrieved from the
JWT token.
• The User’s email address specified is not a proper email address.
• The User to whom the invite email is to be sent has already logged in to the Console.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound– The User resource to send or resend the invitation email to is not found.

Send Reset Password Email
Allows a caller to request for the Console reset password email to be sent or resent to an existing User.

Service
Endpoint

North America: https://protectapi.cylance.com/users/v2/{user_email_address}/resetpassword
US Government: https://protectapi.us.cylance.com/users/v2/{user_email_address}/resetpassword
All Other Regions: https://protectapi-{region-code}.cylance.com/users/v2/{user_email_address}/
resetpassword

Method

HTTP/1.1 POST

Request
Headers

Authorization: Bearer with the user:read scope encoded.

Request

None

Response

200 OK – The email was successfully sent.
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The User’s email address specified is not a proper email address.
• The User to whom the reset password email is to be sent has not confirmed the email provided.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound– The User resource to send or resend the invitation email to is not found.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

Device API
Get Devices
Allows a caller to 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.
Service
Endpoint

North America: https://protectapi.cylance.com/devices/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/devices/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the device:list scope encoded.

Request

Append the following optional query string parameters:
• page: The page number to request.
• page_size: The page number of device records to retrieve per page.

CylancePROTECT User API Guide — v2.0 rev10

200 OK
Get Devices Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"state": "string",
"agent_version": "string",
"policy": {
"id": "string",
"name": "string"
},
"date_first_registered": "2017-07-28T16:35:46.081Z",
"ip_addresses": [
"string1",
"string2" ],
"mac_addresses": [
"string1",
"string2" ]
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The page number or page size specified is less than or equal to zero.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The device resources page requested doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

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.

The device’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 device’s name.

page_number

The page number requested.

page_size

The page size requested.

policy

The policy ID and name.

state

Signals whether the device is online or offline.

total_number_of_items

Total number of resources.

total_pages

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

CylancePROTECT User API Guide — v2.0 rev10

Get Device
Allows a caller to request a specific device resource belonging to a Tenant.
Service
Endpoint

North America: https://protectapi.cylance.com/devices/v2/{unique_device_id}
US Government: https://protectapi.us.cylance.com/devices/v2/{unique_device_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/{unique_device_id}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the device:read scope encoded.

Request

None
200 OK
Get Device Response Schema
{
"id": "string",
"name": "string",
"host_name": "string",
"os_version": "string",
"state": "string",
"agent_version": "string",
"policy": {
"id": "string",
"name": "string"
},
"last_logged_in_user": "string",
"update_type": "string",
"update_available": true,
"background_detection": true,
"is_safe": true,
"date_first_registered": "2017-06-15T18:02:45.714Z",
"date_offline": "2017-06-15T18:02:45.714Z",
"date_last_modified": "2017-06-15T18:02:45.714Z",
"ip_addresses": [
"string1",
"string2" ],
"mac_addresses": [
"string1",
"string2" ]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The device’s unique identifier is not valid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The device resources page requested doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.
CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description

agent_version

The CylancePROTECT Agent version installed on the device.

background_detection

If true, the Agent is currently running.

date_first_registered

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

date_last_modified

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

date_offline

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

host_name

The hostname for the device.

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

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

mac_addresses

The list of MAC addresses for the device.

name

The name of the device.

os_version

The operating system and version.

policy

The name of the policy assigned to the device.

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.

CylancePROTECT User API Guide — v2.0 rev10

Update Device
Allows a caller to update a specific Console device resource belonging to a Tenant.
Service
Endpoint

Method

HTTP/1.1 PUT

Request
Headers

Accept: application/json
Authorization: Bearer with the device:update scope encoded.
Content-Type: application/json
Put Device Response Schema
{
"name": "string",
"policy_id": "string",
"add_zone_ids": [
"string"
],
"remove_zone_ids": [
"string"
]

Request

COPY
CODE

}

Response

200 OK
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT.
• The device’s unique identifier is not valid.
• The device update data failed validation.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – Returned if the device resource to update doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.

The request JSON schema contains the following fields:

Field Name

Description

add_zone_ids

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

name

The name of the device.

policy_id

The unique identifier for the policy to assign to the device. Specify null or leave the string
empty to remove the current policy from the device.

remove_zone_ids

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

CylancePROTECT User API Guide — v2.0 rev10

Get Device Threats
Allows a caller to 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

North America: https://protectapi.cylance.com/devices/v2/{unique_device_id}/
threats?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/devices/v2/{unique_device_id}/
threats?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/{unique_device_id}/
threats?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the device:threatlist scope encoded.

Request

COPY
CODE

"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"name": "string",
"sha256": "string",
"file_status": 0,
"file_path": "string",
"cylance_score": 0,
"classification": "string",
"sub_classification": "string",
"date_found": "2017-06-15T18:02:45.714Z"
}
]

Response

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The device’s unique identifier is not valid.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The identifier specified doesn’t belong to a device resource in the system.
500 InternalServerError – An unforeseeable error has occurred.
CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

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.

date_found

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

file_path

The file path where the threat was found on the device.

file_status

The current status of the file on the device. This can be one of the following:
• Default (0)
• Quarantined (1)
• Whitelisted (2)
• Suspicious (3)
• FileRemoved (4)
• Corrupt (5)

name

The name of the threat.

page_number

The page number requested.

page_size

The page size requested.

sha256

The SHA256 hash for the threat.

sub_classification

The threat sub-classification assigned by Cylance.

total_pages

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

total_number_of_items

Total number of resources.

CylancePROTECT User API Guide — v2.0 rev10

Update Device Threat
Allows a caller to update the status (waive or quarantine) of a convicted threat.
Service
Endpoint

North America: https://protectapi.cylance.com/devices/v2/{unique_device_id}/threats
US Government: https://protectapi.us.cylance.com/devices/v2/{unique_device_id}/threats
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/{unique_device_id}/threats

Method

HTTP/1.1 POST

Request
Headers

Accept: application/json
Authorization: Bearer with the threat:update scope encoded.
Content-Type: application/json
{
"threat_id": "string",
"event": "string"

Request

COPY
CODE

}

Response

200 OK
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The device’s unique identifier is not valid.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The identifier specified doesn’t belong to a device resource in the system.
500 InternalServerError – An unforeseeable error has occurred.

The response JSON schema contains the following fields:

Field Name

Description

event

The requested status update for the convicted threat.
• Quarantine
• Waive

threat_id

The SHA256 hash of the convicted threat.

CylancePROTECT User API Guide — v2.0 rev10

Get Zone Devices
Allows a caller to 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

North America: https://protectapi.cylance.com/devices/v2/{unique_zone_id}/devices?page=m&page_
size=n
US Government: https://protectapi.us.cylance.com/devices/v2/{unique_zone_id}/
devices?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/{unique_zone_id}/
devices?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the device:threatlist scope encoded.

Request

Append the following optional query string parameters:
• page: The page number to request.
• page_size: The page number of device records to retrieve per page.
200 OK
Get Device Threat Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"policy_id": "string"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The device’s unique identifier is not valid.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The zone resource requested is not a valid ID.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

The unique identifier for the device.

name

The name of the device.

policy_id

The unique identifier for the policy to which the policy is currently assigned. Can be null.

Get Agent Installer Link
Allows a caller to request a secured link to download the Agent installer.

Service
Endpoint

North America: https://protectapi.cylance.com/devices/v2/
installer?product=p&os=o&package=k&architecture=a&build=v
US Government: https://protectapi.us.cylance.com/devices/v2/
installer?product=p&os=o&package=k&architecture=a&build=v
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/
installer?product=p&os=o&package=k&architecture=a&build=v

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer with the device:read scope encoded.

CylancePROTECT User API Guide — v2.0 rev10

Request

Append the following optional query string parameters:
• product: Specify the Cylance product installer to download. The allowed values are:
••Protect
••Optics
• os: Specify the operating system (OS) family. The allowed values are:
••CentOS7
••Linux
••Mac
••Ubuntu1404
••Ubuntu1604
••Windows
• architecture (required for Windows and macOS): Specify the target architecture. The allowed
values are:
••X86
••X64
••CentOS6
••CentOS6UI
••CentOS7
••CentOS7UI
••Ubuntu1404
••Ubuntu1404UI
••Ubuntu1604
••Ubuntu1604UI
• package (required for Windows and macOS): Specify the installer format. The allowed values are:
••Exe (Windows only)
••Msi (Windows only)
••Dmg (macOS only)
••Pkg (macOS only)
• build (optional): The Agent version. Example: 1480.
200 OK
Get Agent Installer Link Response Schema
{

COPY
CODE

"url": "string"
}
Response

400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The requested payload failed validation.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The requested link resource does not exist.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

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

url

Delete Devices
Allows a caller to delete one or more devices from an organization.
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

Method

Request
Headers

North America: https://protectapi.cylance.com/devices/v2/
US Government: https://protectapi.us.cylance.com/devices/v2/
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/
HTTP/1.1 DELETE
NOTE: For clients who do not support DELETE, see the not below.
Accept: application/json
Authorization: Bearer with the device:read scope encoded.
Content-Type: application/json
Delete Device Request Schema
{
"device_ids":
[
"string"
],
"callback_url": "string"

Request

COPY
CODE

}
202 Accepted
Delete Device Response Schema
{
"request_id": "string"
}
Response

COPY
CODE

400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The device IDs are not valid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The devices do not exist.
413 PayloadTooLarge – The number of resources specified in the request is too large.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

NOTE: Not all clients support sending a DELETE request. For this instance, use the following POST instead.
• Service Endpoint: https://protectapi-{region-code}.cylance.com/devices/v2/delete
• Method: HTTP/1.1 POST
The request JSON schema contains the following fields:

Field Name

Description

device_ids

The unique identifiers for the devices to be deleted.
• All device IDs should be well formed GUIDs. Non-conforming values will be removed from
the request.
• The maximum number of Device IDs per request is 20.

callback_url
(Optional)

The URL of the callback upon completion.

The response JSON schema contains the following fields:

Field Name
request_id

Description
The unique identifier of the deletion request.

Get Device by MAC Address
Allows a caller to request a specific device resource belonging to a Tenant, by using the MAC address of the device.

Service Endpoint

North America: https://protectapi.cylance.com/devices/v2/macaddress/{mac_address}
US Government: https://protectapi.us.cylance.com/devices/v2/macaddress/{mac_address}
All Other Regions: https://protectapi-{region-code}.cylance.com/devices/v2/macaddress/{mac_
address}

Method

HTTP/1.1 GET

Request Headers

Accept: application/json
Authorization: Bearer with the device:read scope encoded.

Request

From URI:
• mac_address: The MAC address of the device. Acceptable MAC address formats are:
•• 00-00-00-00-00-00
•• 00:00:00:00:00:00

CylancePROTECT User API Guide — v2.0 rev10

200 OK
Get Device By MAC Address Response Schema
[
{
"id": "string",
"name": "string",
"host_name": "string",
"os_version": "string",
"state": "string",
"agent_version": "string",
"policy": {
"id": "string",
"name": "string"
},
"last_logged_in_user": "string",
"update_type": "string",
"update_available": "string",
"background_detection": "string",
"is_safe": "string",
"date_first_registered": "2017-06-15T18:02:45.714Z",
"date_offline": "2017-06-15T18:02:45.714Z",
"date_last_modified": "2017-06-15T18:02:45.714Z",
"ip_addresses": [
"strings1",
"string2" ],
"mac_addresses": [
"strings1",
"string2" ]

Response

COPY
CODE

}
]
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The MAC address is not valid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

agent_version

The CylancePROTECT Agent version installed on the device.

background_
detection

The response is True if the CylancePROTECT Agent is running.

date_first_registered

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

date_last_modified

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

date_offline

The date and time (in UTC) when the device last communicated with the Cylance Console.

host_name

The host name for the device.

The unique identifier for the device.

ip_addresses

The list of IP addresses for the device.

is_safe

The response is True if there are not outstanding threats on the device. An outstanding
threat is a threat that is not waived, safelisted, or quarantined.

last_logged_in_user

The ID of the User who last logged in to the device.

mac_addresses

The list of MAC addresses for the device.

name

The name for the device.

os_version

The operating system running on the device.

policy

The policy name and policy ID assigned to the device.

state

The current status of the device, which is either online or offline.

update_available

The response is True if there is an Agent update available for the device, according to the
update type (phase).

update_type

The update phase on which the device is scheduled.

CylancePROTECT User API Guide — v2.0 rev10

Global List API
Get Global List
Allows a caller to 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 either 0 (GlobalQuarantine) or 1 (GlobalSafe).

Service
Endpoint

North America: https://protectapi.cylance.com/globallists/v2?listTypeId=[0|1]&page=m&page_size=n
US Government: https://protectapi.us.cylance.com/globallists/v2?listTypeId=[0|1]&page=m&page_
size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/globallists/
v2?listTypeId=[0|1]&page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the globallist:list scope encoded.

Request

Append the following optional query string parameters:
• listTypeId: The type of the list to retrieve the hashes for.
• page: The page number to request.
• page_size: The number of policy records to retrieve per page.

CylancePROTECT User API Guide — v2.0 rev10

200 OK
Get Threats Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"name": "string",
"sha256": "string",
"md5": "string",
"cylance_score": 0,
"av_industry": 0,
"classification": "string",
"sub_classification": "string",
"list_type": "string",
"category": "string",
"added": "2017-05-22T23:35:56.705Z",
"added_by": "string",
"reason": "string"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The page number or page size specified is less than or equal to zero.
401 Unauthorized – The JWT token was 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 – Generic server error.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

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

This field is required only if the list_type value is Global Safe. The value can be one of
the following:
• Admin Tool
• Commercial Software
• Drivers
• Internal Application
• Operating System
• Security Software
• None

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.

CylancePROTECT User API Guide — v2.0 rev10

Delete From Global List
Allows a caller to remove a convicted threat from either the Global Quarantine or the Global Safe list for a particular Tenant.
Service
Endpoint

Method

HTTP/1.1 DELETE

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the globallist:delete scope encoded.
Content-Type: application/json
Post Global List Entry Request Schema
{

Request

"sha256": "string",
"list_type": "string"

COPY
CODE

}

Response

200 OK
400 BadRequest – Returned for the following reasons:
The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The provided SHA256 is invalid.
• The provided list type is not supported.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The threat specified does not exist in the intended list.
500 Internal Server Error – An unforeseeable error has occurred.

The response JSON schema contains the following fields:

Field Name

Description

list_type

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

sha256

The SHA256 hash for the threat.

CylancePROTECT User API Guide — v2.0 rev10

Policy API
Get Policy
Allows the caller to get details for a single policy.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2/{policy_id}
US Government: https://protectapi.us.cylance.com/policies/v2/{policy_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2/{policy_id}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the policy:read scope encoded.

Request

Append the Tenant policy ID to the service endpoint.
Requires policy:read scope.
200 OK
Get Policy Response Schema
{

Response

"file_exclusions": {
"checksum": "",
"error_rate": "0",
"exclusionlisthash": "",
"exclusionlisthash_secondary": "size": "0"
},
"filetype_actions": {
"suspicious_files": [
{
"actions": "string",
"file_type": "executable"
}
],
"threat_files": [
{
"actions": "string",
"file_type": "executable"
}
]
},
"memoryviolation_actions": {
"memory_exclusion_list": [],
"memory_violations": [
{

COPY
CODE

CylancePROTECT User API Guide — v2.0 rev10

"actions": "string",
"violation_type": "string"
}
],
"memory_violations_ext": [
{
"actions": "string",
"violation_type": "string"
}
]
},
"policy": [
{
"name": "string",
"value": "string"
}
{
"name": "scan_exception_list",
"value": [
""
]
}
],
"policy_id": "string",
"policy_name": "string",
"policy_utctimestamp": "9/15/2017 8:41:15 PM"

Response

}
404 Not Found – The Tenant policy ID specified is valid, but no such record exists.

CylancePROTECT User API Guide — v2.0 rev10

The request JSON schema contains the following fields:

Field Name

file_exclusions

filetype_actions

Description
Policy Safe List are file exclusions specific to the policy, and any endpoints assigned to the
policy will allow the excluded files to run.
• checksum
• error_rate
• exclusionlisthash
• exclusionlisthash_secondary
• size
The Auto-Quarantine of Unsafe (threat_files) and Abnormal (suspicious_files).
• actions – Set Auto-Quarantine to Enable or Disable.
••0 – Disabled
••1 – Enabled
• file_type – The only option is “executable”.
• suspicious_files – Abnormal files
• threat_files – Unsafe files

logpolicy

The Agent log file settings.
• log_upload – The setting to enable or disable uploading log files.
••0 – Disabled
••1 – Enabled
• maxlogsize – The maximum file size (in MB) for a single log file.
• retentiondays – The number of days to save log files. Log files older than the set
number of days will be deleted.

memory_exclusion_list

The executable files to exclude from Memory Protection. This must be a relative path to
the excluded executable file.
The Violation Types for Memory Protection.
NOTE: All Violation Types must be included in the Request.
• dyldinjection (DYLD Injection) – 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.

memoryviolation_
actions

• 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.
• maliciouspayload (Malicious Payload) – A generic shellcode and payload detection
associated with exploitation has been detected.
• 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.
• 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.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
• outofprocesscreatethread (Remote Threat 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.
• 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.
• 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.
• 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.
• 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.

memoryviolation_
actions

• outofprocesswritepe (Remote Write PE to Memory) – A process has modified memory
in another process to contain an executable image. Generally, this indicates that an
attacker is attempting to execute code without first writing that code to disk.
• 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).
• 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).
• 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).
• 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).
• 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.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
Various policy settings are contained within this section.
NOTE: All policy settings must be included in the Request.
• auto_blocking – Setting to Auto Quarantine Unsafe threats.
••0 – Disabled
••1 – Enabled
• auto_delete – Setting to automatically delete quarantined files after a set number
of days. If this feature is enabled, set “days_until_deleted” for the number of days to
retain a quarantined file.
••0 – Disabled
••1 – Enabled
• auto_uploading – Setting to automatically upload files that Cylance has not seen
before. Cylance will perform an analysis on the file and provide details to assist in
manual analysis and triage.
••0 – Disabled
••1 – Enabled
• 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.
• device_control – Setting to enable or disable the Device Control feature.
••0 – Disabled
••1 – Enabled

policy

• 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.
••0 – Disabled
••1 – Run Recurring (performs a scan every nine days)
••2 – Run Once (runs a full disk scan upon installation only)
• kill_running_threats – Setting to kill processes and children processes regardless of the
state when a threat is detected (EXE or DLL).
••0 – Disabled
••1 – Enabled
• logpolicy – Setting to enable or disable the Agent logging feature.
• low_confidence_threshold – Setting to adjust the Cylance Score threshold between
Unsafe and Abnormal threats. The default is -600, therefore:
••A Cylance Score of -600 to -1000 is Unsafe.
••A Cylance Score of 0 to -599 is Abnormal.
••A Cyalnce Score greater than 0 is Safe.
• memory_exploit_detection – Setting to enable or disable the Memory Protection
feature. This affects “memory_violation_actions” (“memory_violations” and “memory_
violations_ext”).
• optics – Setting to enable or disable CylanceOPTICS™.
••0 – Disabled
••1 – Enabled
• optics_application_control_auto_upload – Setting to allow the automatic uploading of
Application Control related Focus Data.
••0 – Disabled
••1 – Enabled

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
• optics_malware_auto_upload – Setting to allow the automatic uploading of Threat
related Focus data.
••0 – Disabled
••1 – Enabled
• optics_memory_defense_auto_upload – Setting to allow the automatic uploading of
Memory Protection related Focus data.
••0 – Disabled
••1 – Enabled
• optics_script_control_auto_upload – Setting to allow the automatic uploading of Script
Control related Focus data.
••0 – Disabled
••1 – Enabled

policy

• 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.
• prevent_service_shutdown – Setting that protects the Cylance service from being
shutdown, either manually or by another process.
• sample_copy_path – Setting to copy all file samples to a network share (CIFS/SMB).
Use the fully qualified path.
Example: \\server_name\shared_folder.
• 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.
• 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.
• script_control – Setting to enable or disable the Script Control feature.
••0 – Disabled
••1 – Enabled
• show_notifications – Setting to enable or disable Desktop Notifications on
the endpoint.
••0 – Disabled
••1 – Enabled
• threat_report_limit – The number of threats to upload to the Console.
• trust_files_in_scan_exception_list – Setting to exclude executable files from Memory
Protection actions. The value is the relative path to the excluded executable files.
• watch_for_new_files – Setting to analyze new or modified executable files for threats.

policy_name

The name of the policy.

policy_id

The unique identifier for the policy.

policy_utctimestamp

The date and time the policy was created, in UTC.

CylancePROTECT User API Guide — v2.0 rev10

Get Policies
Allows the caller to get a list of Tenant policies where the Tenant ID is retrieved from the JWT token provided in the request.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/policies/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the policy:list scope encoded.

Request

Append the following optional query string parameters:
• page: The page number to request.
• page_size: The number of policy records to retrieve per page.
200 OK
Get Policies Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"device_count": "string",
"zone_count": "string",
"date_added": "2017-05-22T23:35:56.705Z",
"date_modified": "2017-05-22T23:35:56.705Z"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The page number or page size specified is less than or equal to zero.
401 Unauthorized – The JWT token was 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 – No policy resources available.
500 Internal Server Error – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

page_items

The list of policies belonging to the requested page, each displaying the following
information:
• 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.
• zone_count: The number of zones assigned to this policy.

page_number

The page number requested.

page_size

The page size requested.

total_number_of_
items

The total number of resources.

total_pages

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

Create Policy
Allows the caller to create a policy.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2
US Government: https://protectapi.us.cylance.com/policies/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2

Method

HTTP/1.1 POST

Request
Headers

Authorization: Bearer < JWT Token returned by Auth API> with the policy:create scope encoded.
Content-Type: application/json

CylancePROTECT User API Guide — v2.0 rev10

Create Policy Request Schema
{

Request

"user_id" : "string",
"policy" : {
"device_control": {
"configurations": [
{
"control_mode": "string",
"device_class": "string"
}
],
"exclusion_list": [
{
"control_mode": "string",
"product_id": "string",
"serial_number": "string",
"vendor_id": "string"
}
]
},
"file_exclusions": [
{
"file_hash": "string",
"md5": "string",
"file_name": "string",
"category_id": "string",
"reason": "string"
}
],
"memoryviolation_actions": {
"memory_violations": [
{
"action": "string",
"violation_type": "string"
}
],
"memory_violations_ext": [
{
"action": "string",
"violation_type": "string"
}
],
"memory_exclusion_list": "[]"
},
"policy": [
{

COPY
CODE

CylancePROTECT User API Guide — v2.0 rev10

"name": "string",
"value": "string"
}
],
"policy_name": "string",
"script_control": {
"activescript_settings": {
"control_mode": "string"
},
"global_settings": {
"allowed_folders": "",
"control_mode": "string"
},
"macro_settings": {
"control_mode": "string"
},
"powershell_settings": {
"console_mode": "string",
"control_mode": "string"
}
},
"filetype_actions": {
"suspicious_files": [
{
"actions": "string",
"file_type": "executable"
}
],
"threat_files": [
{
"actions": "string",
"file_type": "executable"
}
]
},
"logpolicy": {
"log_upload": "string",
"maxlogsize": "string",
"retentiondays": "string"
}

Request

}
}

CylancePROTECT User API Guide — v2.0 rev10

Create Policy Response Schema
{

Response

"device_control": {
"configurations": [
{
"control_mode": "string",
"device_class": "string"
}
],
"exclusion_list": [
{
"control_mode": "string",
"product_id": "string",
"serial_number": "string",
"vendor_id": "string"
}
]
},
"file_exclusions": [
{
"file_hash": "string",
"md5": "string",
"file_name": "string",
"category_id": "string",
"reason": "string",
"cloud_score": "string",
"av_industry": "string",
"file_type": "string",
"research_class_id": "string",
"research_subclass_id": "string"
}
],
"memoryviolation_actions": {
"memory_violations": [
{
"action": "string",
"violation_type": "string"
}
],
"memory_violations_ext": [
{
"action": "string",
"violation_type": "string"
}
],
"memory_exclusion_list": []
},
"policy": [

COPY
CODE

CylancePROTECT User API Guide — v2.0 rev10

{
"name": "string",
"value": "string"
}
],
"policy_name": "string",
"script_control": {
"activescript_settings": {
"control_mode": "string"
},
"global_settings": {
"allowed_folders": "string",
"control_mode": "string"
},
"macro_settings": {
"control_mode": "string"
},
"powershell_settings": {
"console_mode": "string",
"control_mode": "string"
}
},
"filetype_actions": {
"suspicious_files": [
{
"actions": "string",
"file_type": "executable"
}
],
"threat_files": [
{
"actions": "string",
"file_type": "executable"
}
]
},
"logpolicy": {
"log_upload": "string",
"maxlogsize": "string",
"retentiondays": "string"
},
"policy_id": "e1b44f3c-5a47-4d7f-b97d-1e63f792c0b9",
"policy_utctimestamp": "9/22/2017 4:23:51 PM"

Response

}
409 Conflict – The policy name specified already exists.

CylancePROTECT User API Guide — v2.0 rev10

The request JSON schema contains the following fields:

Field Name

Description
Device Control allows or blocks access to USB Mass Storage devices.
NOTE: All Device Classes must be included in the Request.
Control Mode (control_mode):
• Block – Blocks the USB Mass Storage device from connecting to the endpoint.
• FullAccess – Allows the USB Mass Storage device to connect to the endpoint.
Device Class (device_class):
• AndroidUSB – A portable device running Android OS, like a smartphone or tablet.
• iOS – An Apple portable device running iOS, like an iPhone or iPad.

device_control

NOTE: iOS devices will not change when Device Control is enabled and set to Block,
unless the device is powered off. Apple includes their charging capability within functions
of the device that are required for our iOS device blocking capability. Non-Apple devices
do not bundle their charging capability in this manner and are not impacted.
• StillImage – The device class containing scanners, digital cameras, multi-mode video
cameras with frame capture, and frame grabbers.
• USBCDDVDRW – A USB optical drive.
• USBDrive – A USB hard drive or USB flash drive.
• VMWareMount – VMWare USB Passthrough, which allows a VMware virtual machine
client to access USB devices connected to the host.
• WPD – Windows Portable Device, which uses the Microsoft Windows Portable Device
driver technology, such as mobile phones, digital cameras, and portable media players.
Device Control Exclusion List allows or blocks access to specific USB Mass Storage devices.
• control_mode – Allows or blocks the specific USB Mass Storage device.
••Block - Blocks the USB Mass Storage device from connecting to the endpoint.
••FullAccess – Allows the USB Mass Storage device to connect to the endpoint.

exclusion_list

• product_id – The product identifier for the USB Mass Storage device. This information
is optional.
• Serial_number – The serial number for the USB Mass Storage device. This information
is optional.
• vendor_id – The vendor identifier for the USB Mass Storage device. This information
is required.
NOTE: One way to find the Vendor ID for a USB Mass Storage device is to enable
Device Control in a policy, assign that policy to an endpoint, then attach the USB
Mass Storage device to the endpoint. You can view External Device logs in the Cylance
Console, on the Protection page or the Device Details page (External Devices tab).

CylancePROTECT User API Guide — v2.0 rev10

Field Name

file_exclusions

Description
Policy Safe List are file exclusions specific to the policy, and any endpoints assigned to the
policy will allow the excluded files to run.
• category_id – A list of categories to identify the type of file. This information is optional.
••1 – None
••2 – Admin Tool
••3 – Internal Application
••4 – Commercial Software
••5 – Operating System
••6 – Drivers
••7 – Security Software
•
•
•
•

filetype_actions

file_hash – The SHA256 hash for the file. This information is required.
file_name – The name of the file being excluded. This information is required.
md5 – The MD5 hash for the file. This information is optional.
reason – The reason the file was excluded. This information is required.

The Auto-Quarantine of Unsafe (threat_files) and Abnormal (suspicious_files).
• actions – Set Auto-Quarantine to Enable or Disable.
••0 – Disabled
••1 – Enabled
• file_type – The only option is “executable”.
• suspicious_files – Abnormal files
• threat_files – Unsafe files

logpolicy

memory_exclusion_
list

The executable files to exclude from Memory Protection. This must be a relative path to the
excluded executable file.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
The Violation Types for Memory Protection.
NOTE: All Violation Types must be included in the Request.
• dyldinjection (DYLD Injection) – 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.
• 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.
• maliciouspayload (Malicious Payload) – A generic shellcode and payload detection
associated with exploitation has been detected.
• 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.
• 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.

memoryviolation_
actions

• outofprocesscreatethread (Remote Threat 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.
• 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.
• 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.
• 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.
• 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.
• outofprocesswritepe (Remote Write PE to Memory) – A process has modified memory in
another process to contain an executable image. Generally, this indicates that an attacker
is attempting to execute code without first writing that code to disk.
• 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).
• 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).

CylancePROTECT User API Guide — v2.0 rev10

Field Name

memoryviolation_
actions

Description
• 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).
• 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).
• 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.
Various policy settings are contained within this section.
NOTE: All policy settings must be included in the Request.

policy

• auto_blocking – Setting to Auto Quarantine Unsafe threats.
••0 – Disabled
••1 – Enabled
• auto_delete – Setting to automatically delete quarantined files after a set number of
days. If this feature is enabled, set “days_until_deleted” for the number of days to retain
a quarantined file.
••0 – Disabled
••1 – Enabled
• auto_uploading – Setting to automatically upload files that Cylance has not seen before.
Cylance will perform an analysis on the file and provide details to assist in manual
analysis and triage.
••0 – Disabled
••1 – Enabled
• 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.
• device_control – Setting to enable or disable the Device Control feature.
••0 – Disabled
••1 – Enabled
• 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.
••0 – Disabled
••1 – Run Recurring (performs a scan every nine days)
••2 – Run Once (runs a full disk scan upon installation only)
• kill_running_threats – Setting to kill processes and children processes regardless of the
state when a threat is detected (EXE or DLL).
••0 – Disabled
••1 – Enabled
• logpolicy – Setting to enable or disable the Agent logging feature.
• low_confidence_threshold – Setting to adjust the Cylance Score threshold between
Unsafe and Abnormal threats. The default is -600, therefore:
••A Cylance Score of -600 to -1000 is Unsafe.
••A Cylance Score of 0 to -599 is Abnormal.
••A Cyalnce Score greater than 0 is Safe.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description

policy

• memory_exploit_detection – Setting to enable or disable the Memory Protection
feature. This affects “memory_violation_actions” (“memory_violations” and “memory_
violations_ext”).
• optics – Setting to enable or disable CylanceOPTICS.
••0 – Disabled
••1 – Enabled
• optics_application_control_auto_upload – Setting to allow the automatic uploading of
Application Control related Focus Data.
••0 – Disabled
••1 – Enabled
• optics_malware_auto_upload – Setting to allow the automatic uploading of Threat
related Focus data.
••0 – Disabled
••1 – Enabled
• optics_memory_defense_auto_upload – Setting to allow the automatic uploading of
Memory Protection related Focus data.
••0 – Disabled
••1 – Enabled
• optics_script_control_auto_upload – Setting to allow the automatic uploading of Script
Control related Focus data.
••0 – Disabled
••1 – Enabled
• 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.
• prevent_service_shutdown – Setting that protects the Cylance service from being
shutdown, either manually or by another process.
• sample_copy_path – Setting to copy all file samples to a network share (CIFS/SMB). Use
the fully qualified path.
Example: \\server_name\shared_folder.
• 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.
• 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.
• script_control – Setting to enable or disable the Script Control feature.
••0 – Disabled
••1 – Enabled
• show_notifications – Setting to enable or disable Desktop Notifications on the endpoint.
••0 – Disabled
••1 – Enabled
• threat_report_limit – The number of threats to upload to the Console.
• trust_files_in_scan_exception_list – Setting to exclude executable files from Memory
Protection actions. The value is the relative path to the excluded executable files.
• watch_for_new_files – Setting to analyze new or modified executable files for threats.

policy_name

The name of the policy.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
The policy settings for Script Control.
• activescript_settings – Setting for Active Script.
••control_mode
•• Alert – An alert is sent when an Active Script event occurs. The Active Script is
allowed to run.
•• Block – The Active Script is blocked and an alert is sent.

script_control

• global_settings
••allowed_folders – The relative path to scripts that are allowed to run when Script
Control is enabled.
••control_mode – Setting to enable or disable Script Control.
•• 0 – Disable
•• 1 – Enable
• macro_settings – Setting for Microsoft Office Macros.
••control_mode
•• Alert – An alert is sent when an Office Macro event occurs. The Macro is
allowed to run.
•• Block – The Office Macro is blocked and an alert is sent.
• powershell_settings – Settings for PowerShell scripts.
••console_mode – The PowerShell Console is blocked to prevent PowerShell command
usage, including one-liners. The PowerShell control_mode must be set to Block.
••control_mode
•• Alert – An alert is sent when a PowerShell Script event occurs. The PowerShell
Script is allowed to run.
•• Block – The PowerShell Script is blocked and an alert is sent.

user_id

The unique ID for the User creating the policy. Only Administrators can create policies.
To get the user_id, use Get User.

The response JSON schema contains most of the fields from the request schema, with the following additional fields:

Field Name

Description

policy_id

The unique identifier for the policy.

policy_utctimestamp

The date and time the policy was created, in UTC.

CylancePROTECT User API Guide — v2.0 rev10

Update Policy
Allows the caller to update an existing policy.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2
US Government: https://protectapi.us.cylance.com/policies/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2

Method

HTTP/1.1 PUT

Request
Headers

Authorization: Bearer < JWT Token returned by Auth API> with the policy:update scope encoded.
Content-Type: application/json
Update Policy Request Schema
{

Request

"user_id": "string",
"policy": {
"policy": [
{
"name": "string",
"value": "string"
}
],
"memoryviolation_actions": {
"memory_violations": [
{
"violation_type": "string",
"action": "string"
}
],
"memory_violations_ext": [
{
"violation_type": "string",
"action": "string"
}
],
"memory_exclusion_list": []
},
"policy_utctimestamp": "/Date(1518476769274+0000)/",
"filetype_actions": {
"suspicious_files": [
{
"file_type": "string",
"actions": "string"

COPY
CODE

CylancePROTECT User API Guide — v2.0 rev10

}
],
"threat_files": [
{
"actions": "string",
"file_type": "string"
}
]
},
"logpolicy": {
"maxlogsize": "string",
"log_upload": null,
"retentiondays": "string"
},
"checksum": "string",
"file_exclusions": [],
"policy_name": "string",
"policy_id": "string"

Request

}
}

CylancePROTECT User API Guide — v2.0 rev10

Update Policy Response Schema

{

Response

COPY
CODE

CylancePROTECT User API Guide — v2.0 rev10

}
]
},
"logpolicy": {
"maxlogsize": "string",
"log_upload": null,
"retentiondays": "string"
},
"checksum": "string",
"file_exclusions": [],
"policy_name": "string",
"policy_id": "string"

Response

}
}
204 No Content

CylancePROTECT User API Guide — v2.0 rev10

The request and response JSON schemas contains the following fields:

Field Name

file_exclusions

filetype_actions

The Auto-Quarantine of Unsafe (threat_files) and Abnormal (suspicious_files).
• actions – Set Auto-Quarantine to Enable or Disable.
••0 – Disable
••1 – Enable
• file_type – The only option is “executable”.
• suspicious_files – Abnormal files
• threat_files – Unsafe files

logpolicy

memory_exclusion_
list

The executable files to exclude from Memory Protection. This must be a relative path to the
excluded executable file.

CylancePROTECT User API Guide — v2.0 rev10

Field Name

memoryviolation_
actions

CylancePROTECT User API Guide — v2.0 rev10

Field Name

memoryviolation_
actions

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description
Various policy settings are contained within this section.
NOTE: All policy settings must be included in the Request.
• auto_blocking – Setting to automatically block found threats.
• auto_delete – Setting to automatically delete quarantined files after a set number of
days. If this feature is enabled, set “days_until_deleted” for the number of days to retain
a quarantined file.
••0 – Disabled
••1 – Enabled
• auto_uploading – Setting to automatically upload files that Cylance has not seen before.
Cylance will perform an analysis on the file and provide details to assist in manual
analysis and triage.
••0 – Disabled
••1 – Enabled

policy

• 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.
• device_control – Setting to enable or disable the Device Control feature.
••0 – Disabled
••1 – Enabled
• 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.
••0 – Disabled
••1 – Run Recurring (performs a scan every nine days)
••2 – Run Once (runs a full disk scan upon installation only)
• kill_running_threats – Setting to kill processes and children processes regardless of the
state when a threat is detected (EXE or DLL).
••0 – Disabled
••1 – Enabled
• logpolicy – Setting to enable or disable the Agent logging feature.
• low_confidence_threshold – Setting to adjust the Cylance Score threshold between
Unsafe and Abnormal threats. The default is -600, therefore:
••A Cylance Score of -600 to -1000 is Unsafe.
••A Cylance Score of 0 to -599 is Abnormal.
••A Cyalnce Score greater than 0 is Safe.
• memory_exploit_detection – Setting to enable or disable the Memory Protection
feature. This affects “memory_violation_actions” (“memory_violations” and “memory_
violations_ext”).
• optics – Setting to enable or disable CylanceOPTICS.
••0 – Disabled
••1 – Enabled

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description

policy

• optics_application_control_auto_upload – Setting to allow the automatic uploading of
Application Control related Focus Data.
••0 – Disabled
••1 – Enabled
• optics_malware_auto_upload – Setting to allow the automatic uploading of Threat
related Focus data.
••0 – Disabled
••1 – Enabled
• optics_memory_defense_auto_upload – Setting to allow the automatic uploading of
Memory Protection related Focus data.
••0 – Disabled
••1 – Enabled
• optics_script_control_auto_upload – Setting to allow the automatic uploading of Script
Control related Focus data.
••0 – Disabled
••1 – Enabled
• 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.
• prevent_service_shutdown – Setting that protects the Cylance service from being
shutdown, either manually or by another process.
• sample_copy_path – Setting to copy all file samples to a network share (CIFS/SMB). Use
the fully qualified path.
Example: \\server_name\shared_folder.
• 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.
• 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.
• script_control – Setting to enable or disable the Script Control feature.
••0 – Disabled
••1 – Enabled
• show_notifications – Setting to enable or disable Desktop Notifications on the endpoint.
••0 – Disabled
••1 – Enabled
• threat_report_limit – The number of threats to report to the Console.
• trust_files_in_scan_exception_list – Setting to exclude executable files from Memory
Protection actions. The value is the relative path to the excluded executable files.
• 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_utctimestamp

The date and time the policy was created, in UTC.

CylancePROTECT User API Guide — v2.0 rev10

Delete Policy
Delete a policy from the Console.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2/
US Government: https://protectapi.us.cylance.com/policies/v2/
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2/

Method

HTTP/1.1 DELETE

Request
Headers

Authorization: Bearer < JWT Token returned by Auth API> with the policy:delete scope encoded.

Request

Append the Tenant Policy ID to the Service Endpoint.

Response

204 No Content

Delete Policies
Delete multiple policies from the Console.
Service
Endpoint

North America: https://protectapi.cylance.com/policies/v2
US Government: https://protectapi.us.cylance.com/policies/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/policies/v2

Method

HTTP/1.1 DELETE

Request
Headers

Authorization: Bearer < JWT Token returned by Auth API> with the policy:delete scope encoded.
Content-Type: application/json
Delete Tenant Policies Request Schema
{
"tenant_policy_ids": [
"string",
"string",
"string",
"string",
"string"
]

Request

COPY
CODE

}
Response

204 No Content

The request JSON schema contains the following fields:

Field Name
string

Description
Replace “string” with the Tenant Policy ID.
Example: “012a3456-78b9-0c12-3d4e-f56g78hijklm”

CylancePROTECT User API Guide — v2.0 rev10

Zone API
Create Zone
Create (add) a zone to your Console.
Service
Endpoint

North America: https://protectapi.cylance.com/zones/v2
US Government: https://protectapi.us.cylance.com/zones/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/zones/v2

Method

HTTP/1.1 POST

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the zone:create scope encoded.
Content-Type: application/json
Post Zone Request Schema
{
"name": "string",
"policy_id": "string",
"criticality": "string"

Request

COPY
CODE

}
201 Created
Post Zone Response Schema
{

Response

"id": "string",
"name": "string",
"criticality": "string",
"policy_id": "string",
"date_created": "2017-06-15T21:35:11.994Z"

COPY
CODE

}
400 BadRequest – The Tenant ID could not be retrieved from the JWT token specified in the
Authorization header.
• The zone name value provided is not a valid value for a name.
• The zone criticality provided is not a valid value for criticality.
401 Unauthorized – The JWT token was 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 zone name provided already exists in your organization.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The request JSON schema contains the following fields:

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

name

The name of the Zone.

policy_id

The unique ID for the policy assigned to the Zone.

The response JSON schema contains the following fields:

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

date_created

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

The unique ID for the Zone.

name

The name of the Zone.

policy_id

The unique ID for the policy assigned to the Zone.

CylancePROTECT User API Guide — v2.0 rev10

Get Zones
Request zone information for your organization. This will return the top 100 records.
Service
Endpoint

North America: https://protectapi.cylance.com/zones/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/zones/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/zones/v2?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the zone:list scope encoded.

Request

Append the following (optional) query string parameters:
• page: The page number to request.
• page_size: The number of zone records to retrieve per page.
200 OK
Get Zones Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"criticality": "string",
"zone_rule_id": "string",
"policy_id": "string",
"update_type": "string",
"date_created": "2017-06-15T21:35:11.994Z",
"date_modified": "2017-06-15T21:35:11.994Z"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The zone unique identifier is not valid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The zone requested doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

date_created

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

date_modified

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

The unique ID of the zone.

name

The name of the zone.

policy_id

The unique ID of the policy assigned to the zone.

update_type

The update type for the zone.

zone_rule_id

The unique ID for the zone rule created for the zone.

Get Device Zones
Request zone information for a specified device in your organization. This will return the top 100 records.

Service
Endpoint

North America: https://protectapi.cylance.com/zones/v2/{unique_device_id}/zones?page=m&page_
size=n
US Government: https://protectapi.us.cylance.com/zones/v2/{unique_device_id}/
zones?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/zones/v2/{unique_device_id}/
zones?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the zone:list scope encoded.

Request

Append the following (optional) query string parameters:
• page: The page number to request.
• page_size: The number of zone records to retrieve per page.

CylancePROTECT User API Guide — v2.0 rev10

200 OK
Get Zones Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"criticality": "string",
"zone_rule_id": "string",
"policy_id": "string",
"update_type": "string",
"date_created": "2017-06-15T21:35:11.994Z",
"date_modified": "2017-06-15T21:35:11.994Z"
}
]

Response

COPY
CODE

}
400 BadRequest – The Tenant ID could not be retrieved from the JWT token specified in the
Authorization header.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
500 InternalServerError – An unforeseeable error has occurred.
The response JSON schema contains the following fields:

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

date_created

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

date_modified

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

The unique ID of the zone.

name

The name of the zone.

policy_id

The unique ID of the policy assigned to the zone.

update_type

The update type for the zone.

zone_rule_id

The unique ID for the zone rule created for the zone.

Get Zone
Request zone information for a specific zone in your organization.
CylancePROTECT User API Guide — v2.0 rev10

Service
Endpoint

North America: https://protectapi.cylance.com/zones/v2/{unique_zone_id}
US Government: https://protectapi.us.cylance.com/zones/v2/{unique_zone_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/zones/v2/{unique_zone_id}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the zone:read scope encoded.

Request

None
200 OK
Get Zone Response Schema
{
"id": "string",
"name": "string",
"criticality": "string",
"zone_rule_id": "string",
"policy_id": "string",
"date_created": "2017-06-15T21:35:11.994Z",
"date_modified": "2017-06-15T21:35:11.994Z"

Response

COPY
CODE

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

date_created

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

date_modified

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

The unique ID of the zone.

name

The name of the zone.

policy_id

The unique ID of the policy assigned to the zone.

zone_rule_id

The unique ID for the zone rule created for the zone.

CylancePROTECT User API Guide — v2.0 rev10

Update Zone
Update a zone in your organization.
Service
Endpoint

Method

HTTP/1.1 PUT

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the zone:update scope encoded.
Content-Type: application/json
Put Zone Request Schema
{
"name": "string",
"policy_id": "string",
"criticality": "string"

Request

COPY
CODE

}

Response

200 OK
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The zone name provided is not a valid value for a name.
• The zone criticality provided is not a valid value for criticality.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The zone requested doesn’t exist.
409 Conflict – The zone name provided already exists in the organization.
500 InternalServerError – An unforeseeable error has occurred.

The request JSON schema contains the following fields:

Field Name

Description

criticality

The value of the zone – Low, Medium, or High.

name

The name of the zone.

policy_id

The unique ID of the policy assigned to the zone.

CylancePROTECT User API Guide — v2.0 rev10

Delete Zone
Delete (remove) a zone from your Console.
Service
Endpoint

Method

HTTP/1.1 DELETE

Request
Headers

Authorization: Bearer < JWT Token returned by Auth API> with the zone:delete scope encoded.

Request

None

Response

200 OK
400 BadRequest – The Tenant ID could not be retrieved from the JWT token specified in the
Authorization header.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The zone requested doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

Threat API
Get Threat
Request threat details for a specific threat.
Service
Endpoint

North America: https://protectapi.cylance.com/threats/v2/{hash}
US Government: https://protectapi.us.cylance.com/threats/v2/{hash}
All Other Regions: https://protectapi-{region-code}.cylance.com/threats/v2/{hash}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the threat:read scope encoded.

Request

Append the SHA256 for the threat to the service endpoint.
200 OK
Get Threat Response Schema
{
"name": "string",
"sha256": "string",
"md5": "string",
"signed": true,
"cylance_score": 0,
"av_industry": 0,
"classification": "string",
"sub_classification": "string",
"global_quarantine": true,
"safelisted": true,
"cert_publisher": "string",
"cert_issuer": "string",
"cert_timestamp": "2017-06-15T21:35:11.994Z",
"file_size": 0,
"unique_to_cylance": true,
"running": "string",
"auto_run": true,
"detected_by": "string"

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The Threat Hash ID specified is invalid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The threat requested doesn’t exist.
500 InternalServerError – An unforeseeable error has occurred.
The response JSON schema contains the following fields:

CylancePROTECT User API Guide — v2.0 rev10

Field Name

Description

auto_run

Indicates if the file is set to automatically run on system startup.

av_industry

The score provided by the antivirus industry.

cert_issuer

The ID for the certificate issuer.

cert_publisher

The ID for the certificate publisher.

cert_timestamp

The date and time (in UTC) when the file was signed using the certificate.

classification

The threat classification for the threat.

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.

detected_by

The name of the Cylance module that detected the threat.

file_size

The size of the file.

global_quarantine

Identifies if the threat is on the Global Quarantine list.

md5

The MD5 hash for the threat.

name

The name of the threat.

running

Identifies if the threat is executing, or another executable loaded or called it.

safelisted

Identifies if the threat is on the Safe List.

sha256

The SHA256 hash for the threat.

signed

Identifies the file as signed or not signed.

sub_classification

The threat sub-classification for the threat.

unique_to_cylance

The threat was identified by Cylance but not by other antivirus sources.

CylancePROTECT User API Guide — v2.0 rev10

Get Threats
Allows a caller to request a page with a list of Console threat resources belonging to a Tenant, sorted by the last found date, in
descending order (most recent policy 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

North America: https://protectapi.cylance.com/threats/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/threats/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/threats/v2?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the threat:list scope encoded.

Request

Append the following optional query string parameters:
• page: The page number to request.
• page_size: The number of device records to retrieve per page.
200 OK
Get Threats Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"name": "string",
"sha256": "string",
"md5": "string",
"cylance_score": 0,
"av_industry": 0,
"classification": "string",
"sub_classification": "string",
"global_quarantined": true,
"safelisted": true,
"file_size": 0,
"unique_to_cylance": true
"last_found": "2017-06-15T21:35:11.994Z"
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The Threat Hash ID specified is invalid.
401 Unauthorized – The JWT token was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The threat requested doesn’t exist.
429 TooManyRequests – The rate limit has been reached.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

av_industry

The score provided by the antivirus industry.

cert_issuer

The ID for the certificate issuer.

cert_publisher

The ID for the certificate publisher.

cert_timestamp

The date and time (in UTC) when the file was signed using the certificate.

classification

The threat classification for the threat.

cylance_score

file_size

The size of the file.

global_quarantined

Identifies if the threat is on the Global Quarantine list.

md5

The MD5 hash for the threat.

name

The name of the threat.

safelisted

Identifies if the threat is on the Safe List.

sha256

The SHA256 hash for the threat.

signed

Identifies the file as signed or not signed.

sub_classification

The threat sub-classification for the threat.

unique_to_cylance

The threat was identified by Cylance but not by other antivirus sources.

Get Threat Devices
Request threat details for a specific threat.

Service
Endpoint

North America: https://protectapi.cylance.com/threats/v2/{hash}/devices?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/threats/v2/{hash}/devices?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/threats/v2/{hash}/
devices?page=m&page_size=n

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the threat:devicelist scope encoded.

CylancePROTECT User API Guide — v2.0 rev10

Request

Append the following (optional) query string parameters:
••page: The page number to request.
••page_size: The number of device records to retrieve per page.
200 OK
Get Threat Devices Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"id": "string",
"name": "string",
"state": "Offline",
"agent_version": "string",
"policy_id": "string",
"date_found": "2017-06-15T21:35:11.994Z",
"file_status": "Quarantined",
"file_path": "string",
"ip_addresses": [
"string1",
"string2" ],
"mac_addresses": [
"string1",
"string2" ]
}
]

Response

COPY
CODE

}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The Threat Hash ID specified is invalid.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
500 InternalServerError – An unforeseeable error has occurred.

CylancePROTECT User API Guide — v2.0 rev10

The response JSON schema contains the following fields:

Field Name

Description

agent_version

The agent version installed on the device.

date_found

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

fie_path

The path where the file was found on the device.

file_status

Current quarantine status of the file on the device.
• 0 – Default
• 1 – Quarantined
• 2 – Whitelisted
• 3 – Suspicious
• 4 – FileRemoved
• 5 – Corrupt

The device ID.

ip_addresses

The list of IP addresses for the device.

mac_addresses

The list of MAC addresses for the device.

name

The device name for the device.

policy_id

The unique identifier of the policy assigned to the device, or null if no policy is assigned.

serial_number

The API key of the device.

state

The state of the device.
• 0 – Offline
• 1 – Online

CylancePROTECT User API Guide — v2.0 rev10

Get Threat Download URL
Request a download link for a given file. Use the download link to download the file.
Service
Endpoint

North America: https://protectapi.cylance.com/threats/v2/download/{sha256}
US Government: https://protectapi.us.cylance.com/threats/v2/download/{sha256}
All Other Regions: https://protectapi-{region-code].cylance.com/threats/v2/download/{sha256}

Method

HTTP/1.1 GET

Request
Headers

Accept: application/json
Authorization: Bearer < JWT Token returned by Auth API> with the threat:read scope encoded.

Request

Append the following (optional) query string parameters:
sha256: The SHA256 hash for the file.
200 OK
Get Threat Download URL Schema
{

COPY
CODE

"url": "string"
}

Response

400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The provided SHA256 hash is invalid.
••Not associated with the Tenant.
••Agent reported SHA1 and MD5 hashes do not match values in the Console.
••SHA1 or MD5 hash is empty.
• 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 was not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
500 InternalServerError – An unforeseeable error has occurred.

The response JSON schema contains the following fields:

Field Name
url

Description
The URL you can use to download the file. The API call only provides the URL, it does not
download the file for you.

CylancePROTECT User API Guide — v2.0 rev10

API Tools

API Tools
The following is information about some REST and JSON tools that might help you when using the CylancePROTECT APIs.
NOTE: Cylance supports CylancePROTECT 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).

REST Clients
Although the intent of the CylancePROTECT API is to facilitate easy integration of Cylance and other systems through the
organization’s developed code, using or testing the CylancePROTECT API doesn’t require any specific programming knowledge. Free
tools are available for download that allow you to make ad hoc REST requests to the CylancePROTECT API. Some examples are:
• F
iddler (http://www.telerik.com/fiddler) – Free web debugging proxy. Also has an easy-to-use composer and replay features
for HTTP requests.
• Postman (https://www.getpostman.com) – Google Chrome browser extension designed for testing REST APIs. There are also
native Windows, macOS, and Linux clients available.

JSON Validators
CylancePROTECT API requests and responses use JSON for the body payload. If the body used in the request doesn’t conform to
proper JSON formatting, it will result in an HTTP response of 400 – Bad Request. To ensure that your JSON is properly formatted,
use one of these free, popular tools:
• J SON Formatter and Validator (http://jsonformatter.curiousconcept.com) – Online, simple interface with options to define/
transform the output according to the desired level of white space. Highlights and provides informative descriptions of errors.
• Notepad++ (https://notepad-plus-plus.org) – Freeware text editor. In addition to being a powerful replacement for Microsoft
Notepad, it supports a wide variety of plug-in extensions, including various JSON formatting and validation tools (like JSTool
and JSON Viewer).

CylancePROTECT User API Guide — v2.0 rev10

+1-844-CYLANCE
sales@cylance.com
www.cylance.com
400 Spectrum Center Drive, Irvine, CA 92618
©2018 Cylance Inc. Cylance® and CylancePROTECT® and all associated logos and designs are trademarks or registered
trademarks of Cylance Inc. All other registered trademarks or trademarks are property of their respective owners.

20180430-0301

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.7
Linearized                      : Yes
Create Date                     : 2018:04:30 16:56:40-07:00
Creator                         : Adobe InDesign CC 13.1 (Macintosh)
Modify Date                     : 2018:04:30 17:11:48-07:00
Has XFA                         : No
Language                        : en-US
XMP Toolkit                     : Adobe XMP Core 5.6-c015 84.159810, 2016/09/10-02:41:30
Metadata Date                   : 2018:04:30 17:11:48-07:00
Creator Tool                    : Adobe InDesign CC 13.1 (Macintosh)
Instance ID                     : uuid:4ee44c57-3e7a-4e4e-8815-c58b1cd560ce
Original Document ID            : xmp.did:16783b37-b7d6-4288-b346-fe598dcb48f3
Document ID                     : xmp.id:2930bb12-8ebc-4862-9d7f-4a88e3bb8a84
Rendition Class                 : proof:pdf
Derived From Instance ID        : xmp.iid:cf6cb88f-18f5-4bff-9153-807b966ad1c0
Derived From Document ID        : xmp.did:0858a504-79db-48a3-8f2d-8d87711fc8c5
Derived From Original Document ID: xmp.did:16783b37-b7d6-4288-b346-fe598dcb48f3
Derived From Rendition Class    : default
History Action                  : converted
History Parameters              : from application/x-indesign to application/pdf
History Software Agent          : Adobe InDesign CC 13.1 (Macintosh)
History Changed                 : /
History When                    : 2018:04:30 16:56:40-07:00
Format                          : application/pdf
Producer                        : Adobe PDF Library 15.0
Trapped                         : False
Page Count                      : 97

EXIF Metadata provided by EXIF.tools

Cylance PROTECT API Guide V2.0 Rev10

Navigation menu

Versions of this User Manual:

Views

Navigation