Cylance OPTICS API Guide V2.0 Rev2
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 133 [warning: Documents this large are best viewed by clicking the View PDF Link!]
CylanceOPTICS™
API Guide
Product: CylanceOPTICS API
Document: CylanceOPTICS API Guide. This guide is a
succinct resource for analysts, administrators, and
customers who are reviewing or evaluating the product.
Document Release Date: v2.0 rev 2, November 2018
About Cylance: Cylance is the first company to apply
artificial intelligence, algorithmic science, and machine
learning to cybersecurity and improve the way companies,
governments, and end-users proactively solve the world’s
most difficult security problems. Using a breakthrough
predictive analysis process, CylanceP
P quickly and accurately
identifies what is safe and what is a threat, not just what is
in a blacklist or whitelist. By coupling sophisticated math
and machine learning with a unique understanding of an
attacker’s mentality, Cylance provides the technology and
services to be truly predictive and preventive against
advanced threats. For more information, visit cylance.com.
Global Headquarters
400 Spectrum Center Drive, Irvine, CA 92618
Consulting Services Hotline
+1-877-97DEFEND • +1-877-973-3336
Corporate Contact
+1-914-CYLANCE • +1-914-295-2623
Email
partnersupport@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
CylanceOPTICS API Guide – v2.0 rev2 Page 3 of 133
Contents
Overview............................................................................................... 5
RESTful API .......................................................................................... 6
CylanceOPTICS Detection .......................................................... 6
Get Detections .......................................................................... 6
Update Detection ..................................................................... 9
Get Detection ......................................................................... 10
Get Detection Recent .......................................................... 15
Get Detections CSV .............................................................. 16
Delete Detection ................................................................... 18
Delete Detections ................................................................. 19
CylanceOPTICS Package Deployment ................................. 20
Get Packages ......................................................................... 20
Create Package ...................................................................... 23
Get Package ........................................................................... 25
Delete Package ...................................................................... 27
Create Package Execution.................................................. 28
Get Package Executions ..................................................... 31
Get Package Execution ....................................................... 34
Delete Package Execution .................................................. 36
CylanceOPTICS Detection Rules ............................................ 39
Get Detection Rule Content ............................................... 39
Get Detection Rule List ....................................................... 41
Get Detection Rule CSV List .............................................. 43
Validate Detection Rule ...................................................... 44
Create Detection Rule ......................................................... 48
Update Detection Rule ........................................................ 51
Deactivate / Delete Detection Rule ................................. 55
Get Detection Rule Natural Language Representation
.................................................................................................... 56
Get Detection Rule Counts................................................. 57
CylanceOPTICS Detection Rule Sets .................................... 58
Get Detection Rule Set List ................................................ 58
Get Detection Rule Set Content ........................................ 60
Create Detection Rule Set .................................................. 64
Retrieve Default Detection Rule Set ................................ 69
Update Detection Rule Set ................................................. 72
Delete Detection Rule Set .................................................. 76
Delete Multiple Detection Rule Sets ............................... 76
Get Detection Rule Set CSV List ........................................ 78
CylanceOPTICS Detection Exceptions .................................. 79
Get Detection Exceptions List ........................................... 79
Get Detection Exception Content ..................................... 81
Get Detection Exceptions CSV List ................................... 83
Create Detection Exception ................................................ 85
Update Detection Exception .............................................. 88
Deactivate / Delete Detection Exception ....................... 91
CylanceOPTICS Device Commands ....................................... 92
Lockdown Device Command .............................................. 93
Get Device Lockdown History ............................................ 94
Request File Retrieval from Device ................................. 96
Check File Retrieval Status from Device ........................ 98
Get Retrieved Files Results ............................................. 101
CylanceOPTICS Focus View .................................................. 103
Get Focus View List ........................................................... 104
Search for Focus View Results ....................................... 106
Generate a Focus View ..................................................... 108
Get a Focus View Summary ............................................ 111
Get Focus View Results .................................................... 113
CylanceOPTICS InstaQuery ................................................... 116
Get InstaQueries ................................................................. 116
Create InstaQuery .............................................................. 119
Get InstaQuery .................................................................... 124
CylanceOPTICS API Guide – v2.0 rev2 Page 5 of 133
Overview
Cylance offers CylanceOPTICS APIs as an alternative way of interacting with the system.
Note: This guide covers the CylanceOPTICS API calls only. For information about configuring custom applications in the Cylance
Console, see the Cylance User API guide.
CylanceOPTICS API Guide – v2.0 rev2 Page 6 of 133
RESTful API
CylanceOPTICS Detection
The CylanceOPTICS Detection API allows users to interact with Detection Events triggered by the CylanceOPTICS Context
Analysis Engine (CAE). CAE allows users to take automated response actions against malicious or suspicious behavior detected
on endpoints utilizing both machine learning models and static behavior-based rules.
The CylanceOPTICS Detection API enables further automation of analyzing, triaging, and responding to malicious or suspicious
activity prevented or detected by CylanceOPTICS. The workflows currently available through this API include:
• Gathering a summary Detection Events that have occurred in a tenant including a Detection Event’s ID, severity, description,
occurrence time, associated device, and status.
• Gathering the specific Detection Details of Detection Events that have occurred in a tenant including the artifacts associated
with a Detection Event, the status of automated response actions that have been taken against a Detection Event, and other
granular details that compose the Detection Event.
• Deleting a single or multiple Detection Events from a tenant.
• Updating a Detection Event’s status and comments in a tenant.
Get Detections
Allows a caller to request a page with a list of detections belonging to a tenant, sorted in descending order (most recent
detection listed first). The page number and page size parameters are optional. When the values are not specified, the default
values are 1 and 20 respectively.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/detections/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/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 opticsdetect:list scope encoded.
Request
Append the following optional query string parameters:
• start: The start date-time of the query range.
• end: The end date-time of the query range.
• severity: The detection severity filter. Supports OR filters via multiple queries. Possible values are:
o Informational
o Low
o Medium
o High
• detection_type: The detection type filter. Supports OR filters via multiple queries.
• detected_on: The detection on filter. Supports OR filters via multiple queries.
• event_number: The event number filter. Supports OR filters via multiple queries.
CylanceOPTICS API Guide – v2.0 rev2 Page 7 of 133
• device: The device name filter. Supports OR filters via multiple queries.
• status: Possible values are:
o New
o In Progress
o Follow Up
o Reviewed
o Done
o False Positive
• page: The page number to request. Defaults to 1.
• page_size: The number of detection records to retrieve per page. Defaults to 20.
• sort: Sort by the following fields (adding “-“ in front of a value denotes descending order):
o Severity
o OccurrenceTime
o Status
o Device
o PhoneticId
o Description
Response
200 OK
Get Detections Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"Id": "string",
"PhoneticId": "string",
"Severity": "string",
"DetectionDescription": "string",
"OccurrenceTime": "2018-06-14T03:05:45.866Z",
"Device": {
"name": "string",
"CylanceId": "string"
},
"Status": "string"
}
]
}
400 BadRequest – Returned for the following reasons:
• The tenant ID could not be retrieved from the JWT token specified in the Authorization header.
CylanceOPTICS API Guide – v2.0 rev2 Page 8 of 133
• The page number or page size specified are less than or equal to zero.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The detection resources page requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Server Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
page_items
The list of detections belonging to the requested page, each displaying the following
information:
• DetectionDescription: The description of the detection.
• Device:
o CylanceId: The ID for the device.
o Device: The name of the device.
• Id: The unique ID for the detection.
• OccurrenceTime: The time at which the detection occurred.
• PhoneticId: The easy-to-read version of the ID that is probabilistically unique.
• Severity: The criticality of an observance of a detection.
• Status: The status of the detection workflow.
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.
CylanceOPTICS API Guide – v2.0 rev2 Page 9 of 133
Update Detection
Allows a caller to update the status and comment fields for an existing detection for a tenant.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2
US Government: https://protectapi.us.cylance.com/detections/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:update scope encoded.
Request
Post Detection Request Schema
[
{
"detection_id": "string",
"field_to_update": {
"status": "string",
"comment": "string"
}
}
]
Response
200 OK – Successful update
Post Detection Response Schema
[
{
"detection_id": "string",
"response": "string"
}
]
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such detection.
CylanceOPTICS API Guide – v2.0 rev2 Page 10 of 133
500 InternalServerError – An unforeseeable error has occurred.
The request JSON schema contains the following fields:
Field Name Description
comment
The comment on the detection.
status
The status of the detection.
• Done: All actions are complete for this detection.
• False Positive: The detection is considered a false positive.
• Follow Up: This detection requires someone to follow-up on it.
• In Progress: The detection is currently being reviewed and worked on.
• New: The detection is new.
• Reviewed: The detection has been reviewed, but no actions have been taken.
Get Detection
Allows a caller to request a specific detection resource belonging to a tenant. Use Get Detections to obtain the unique detection
ID.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2/{unique_detection_id}/details
US Government: https://protectapi.us.cylance.com/detections/v2/{unique_detection_id}/details
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2/{unique_detection_id}/details
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:read scope encoded.
Request None
Response
200 OK
Get Detection Response Schema
{
"Id": "string",
"ActivationTime": "2018-06-14T21:38:11.543Z",
"AppliedExceptions": "Unknown Type: list",
"AssociatedArtifacts": [
{}
],
CylanceOPTICS API Guide – v2.0 rev2 Page 11 of 133
"Comment": "string",
"DetectionRule": {},
"Detector": {},
"Device": {
"name": "string",
"id": "string"
},
"Name": "string",
"OccurrenceTime": "2018-06-14T21:38:11.543Z",
"Product": {},
"PhoneticId": "string",
"ReceivedTime": "2018-06-14T21:38:11.543Z",
"SchemaVersion": 0,
"Severity": "string",
"SeveritySortLevel": 0,
"Status": "string",
"StatusSortLevel": 0,
"TenantId": "string",
"ZoneIds": [
"string"
],
"Trace": {},
"Context": {},
"InvolvedArtifacts": {},
"Responses": [
{
"Status": "New",
"Comment" : "string",
"TenantId" : "string",
"PhoneticId" : "string",
"DetectionId" : "string",
"OccurrenceTime": "2018-06-14T21:38:11.543Z",
"ActionResults": {
"addtionalProp1": {
"HandlingResponderVersion": 0,
"HandlingResponderName": "string",
"Results": [
{
"Status": {
"Message": "string",
"Code": {
"Ordinal": 0,
"Reason": "string",
"Name": "string"
}
CylanceOPTICS API Guide – v2.0 rev2 Page 12 of 133
}
}
]
},
"additonalProp2": {
"HandlingResponderVersion": 0,
"HandlingResponderName": "string",
"Results": [
{
"Status": {
"Message": "string",
"Code": {
"Ordinal": 0,
"Reason": "string",
"Name": "string"
}
}
}
]
},
"additonalProp3": {
"HandlingResponderVersion": 0,
"HandlingResponderName": "string",
"Results": [
{
"Status": {
"Message": "string",
"Code": {
"Ordinal": 0,
"Reason": "string",
"Name": "string"
}
}
}
]
}
},
"AssociatedArtifacts": [
{}
],
"ResponseRuleId": "string",
"SchemaVersion": 0,
"ResponseRuleVersion": 0,
"ReceivedTime": "2018-06-14T21:38:11.543Z",
"ObjectType": "string"
CylanceOPTICS API Guide – v2.0 rev2 Page 13 of 133
}
]
}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The unique identifier for the detection is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The detection resource requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
ActivationTime
The time at which this particular detection first started occurring.
AppliedExceptions
The exceptions that were applied to the detection.
ArtifactsOfInterest
The artifact associated with the rule that triggered the exception. This is a dynamic object.
AssociatedArtifacts
List of artifacts that were involved in this detection. These are dynamic objects.
Comment
The comment on the detection.
Context
The context of the detection.
DetectionRule
The description of the rule from which this detection originated.
• Category: The category of the rule.
• Description: The description of the rule.
• Id: The ID of the rule.
• Name: The name of the rule.
• Version: The version of the rule.
Detector
The description of the plugin that originated the detection.
• Name: The name of the detector.
• Version: The version of the detector.
Device
A capture of the current state of the device.
CylanceOPTICS API Guide – v2.0 rev2 Page 14 of 133
• CylanceId: The ID for the device.
• Name: The name of the device.
Id
The detection’s unique identifier.
InvolvedArtifacts
The artifacts involved in this detection.
Name
The name of the detection.
ObjectType
The object type for the detection.
OccurrenceTime
The time at which the detection occurred.
PhoneticId
The easy-to-read version of the ID that is probabilistically unique.
Product
The description of the Cylance product that originated the detection.
• Name: The name of the product.
• Version: The version of the product.
ReceivedTime
The time when the detection was received.
Responses
The reponses to the detection.
• Status: The status of the response.
• Comment: The comment on the response.
• TenantId: The tenant ID the response belongs to.
• PhoneticId: The easy-to-read version of the ID that is probabilistically unique.
• DetectionId: The identifier for the detection event that warranted the response.
• OccurrenceTime: The time at which the response actions were taken.
• ActionResults:
o HandlingResponderVersion: The version of the Responder plugin that
performed this response.
o HandlingResponderName: The name of the Responder plugin that performed
this response.
o Results:
Status: The status of the result.
• Message: The message of the result.
• Code:
o Ordinal: The indicator code for the success of the
action.
o Reason: The detailed description explaining the
indicator code.
o Name: The friendly name of the status code.
• AssociatedArtifacts: The artifacts upon which the action occurred.
• ResponseRuleId: The ID of the response rule that triggered this response.
• SchemaVersion: The version of the schema to which this object conforms.
• ResponseRuleVersion: The version of the response rule.
• ReceivedTime: The time the response was received.
CylanceOPTICS API Guide – v2.0 rev2 Page 15 of 133
• ObjectType: The type of the object for the response.
SchemaVersion
The version of the schema to which this object conforms.
Severity
The criticality of an observance of this detection.
SeveritySortLevel
The sort level for this severity.
Status
The status of the detection in the workflow.
StatusSortLevel
The sort level for the status.
Trace
The trace information.
• Event: The CylanceOPTICS Event that triggered the state.
• StateName: The name of a state that was traversed.
TenantId
The ID for the tenant.
ZoneIds
A list of IDs for the zones associated with the detection.
Get Detection Recent
Allows a caller to request a count of recent CylanceOPTICS detection resources belonging to a tenant.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2/recent
US Government: https://protectapi.us.cylance.com/detections/v2/recent
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2/recent
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:list scope encoded.
Request
Append the following optional query string parameter:
• since: The date-time of the recent detections to retrieve.
Response
200 OK
Get Detection Recent Response Schema
{
"num_after": 0,
"num_unaddressed": 0
}
400 BadRequest – Returned for the following reasons:
• The tenant ID could not be retrieved from the JWT token specified in the Authorization header.
CylanceOPTICS API Guide – v2.0 rev2 Page 16 of 133
• The unique identifier for the execution is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The execution resource requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
num_after
The number of detections after the “since” date-time.
num_unaddressed
The number of unaddressed detections after the “since” date-time.
Get Detections CSV
Allows a caller to request a CSV export of the list of CylanceOPTICS detection resources belonging to a tenant.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2/csv
US Government: https://protectapi.us.cylance.com/detections/v2/csv
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2/csv
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:list scope encoded.
Request
Append the following optional query string parameters:
• start: The start date-time of the query range.
• end: The end date-time of the query range.
• severity: The detection severity filter. Supports OR filters via multiple queries. Possible values are:
o Informational
o Low
o Medium
o High
• detection_type: The detection type filter. Supports OR filters via multiple queries.
• detected_on: The detection on filter. Supports OR filters via multiple queries.
• event_number: The event number filter. Supports OR filters via multiple queries.
• device: The device name filter. Supports OR filters via multiple queries.
• status: Possible values are:
o New
o In Progress
CylanceOPTICS API Guide – v2.0 rev2 Page 17 of 133
o Follow Up
o Reviewed
o Done
o False Positive
• page: The page number to request. Defaults to 1.
• page_size: The number of detection records to retrieve per page. Defaults to 20.
• sort: Sort by the following fields (adding “-“ in front of a value denotes descending order):
o Severity
o OccurrenceTime
o Status
o Device
o PhoneticId
o Description
Response
204 No Content – Detection deleted
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The unique identifier for the detection is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – Returned if the detection resource to update does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
Export detections for a tenant in CSV format. Any provided filters will be applied, but limit/offset parameters will not. All
detections for the tenant will be exported.
CylanceOPTICS API Guide – v2.0 rev2 Page 18 of 133
Delete Detection
Allows a caller to soft delete a specific CylanceOPTICS detection resource belonging to a tenant. Use Get Detections to obtain the
unique detection ID.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2/{unique_detection_id}
US Government: https://protectapi.us.cylance.com/detections/v2/{unique_detection_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2/{unique_detection_id}
Method HTTP/1.1 DELETE
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:delete scope encoded.
Request None
Response
200 OK – deleted
Delete Detection Response Schema
{
"id": "string",
"success": true
}
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The detection'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.
• Cannot delete CylanceOPTICS detecion.
404 NotFound – Returned if the detecion resource to update doesn't exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later
CylanceOPTICS API Guide – v2.0 rev2 Page 19 of 133
Delete Detections
Allows a caller to delete CylanceOPTICS detection resources for a specific tenant.
Service
Endpoint
North America: https://protectapi.cylance.com/detections/v2/
US Government: https://protectapi.us.cylance.com/detections/v2/
All Other Regions: https://protectapi-{region-code}.cylance.com/detections/v2/
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsdetect:delete scope encoded.
Request None
Response
200 OK
Delete Detections Response Schema
[
{
"id": "string",
"success": true
}
]
400 BadRequest – Malformed request.
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.
CylanceOPTICS API Guide – v2.0 rev2 Page 20 of 133
CylanceOPTICS Package Deployment
CylanceOPTICS users can now interact with a hardened Python interpreter that is present locally on each endpoint that is
running CylanceOPTICS v2.3.1000 or higher. This new feature allows users to interact with their endpoints in an efficient and
technical manner to accomplish tasks on endpoints in an automated fashion. By default, Cylance is supporting 5 capabilities to
collect different forensic artifacts from targeted endpoints. These capabilities include:
• Collecting Master File Table (MFT) artifacts from NTFS volumes.
• Collecting entire Windows Registry Hives from endpoints.
• Collecting entire Windows Event Log files from endpoints.
• Collecting Web Browser History Databases from Chrome, Firefox, Internet Explorer, Edge, Opera, and Safari.
• Collecting common Application Execution Records, including Amcache, Prefetch, and Shimcache.
Users can also configure and deploy Custom Packages to conduct custom, scripted actions against endpoints. This allows
customers to upload in-house or third-party scripts and applications to Cylance’s cloud services and deploy them to endpoints.
This scripting is done via interacting with the local Python interpreter built into CylanceOPTICS, allowing for an easily extensible
set of capabilities.
After packages have been deployed and executed on endpoints, users can automatically upload the resulting data to SMB shares
or SFTP servers for centralized collection and analysis by other forensic or incident response tools. Users can also configure
packages to store the results locally on the endpoints for retrieval at a later time.
The CylanceOPTICS Package Deployment supports up to 20 packages for your organization. Each package has a maximum file
size of 15MB.
These capabilities and workflows around the Package Deployment feature are exposed via Cylance’s API.
Note: This addendum only covers CylanceOPTICS Package Deployment API information. Read the Cylance User API guide for
configuration information.
Get Packages
Allows a caller to request a page with a list of packages belonging to a tenant, sorted by the uploaded date, in descending order
(most recent uploaded package listed first). The page number and page size parameters are optional. When the values are not
specified, the default values are 1 and 20 respectively.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/packages/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/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 opticspkgconfig:list scope encoded.
Request
Append the following optional query string parameters:
• page: The page number to request. Defaults to 1.
• page_size: The number of packages records to retrieve per page. Defaults to 20.
• sort: Sort by the following fields (adding "-" in front of value denotes descending order).
CylanceOPTICS API Guide – v2.0 rev2 Page 21 of 133
o packageId
o uploadedOn
o uploadedBy.id
o uploadedBy.login
o size
o status - Possible values are "started", "success, "failed", "timeout"
o timeout
o packageDescriptor.name
• packageId: Filter by packageId.
• uploadedOn: Filter by uploaded timestamp in UTC.
• uploadedBy.Id - Filter by user id the user who uploaded the package.
• updatedBy.Login - Filter by email fo the user who uploaded the package.
• size - Filter by size of the package in bytes.
• status - Filter by status of the package upload process. Possible values are "started", "success, "failed",
"timeout".
• timeout - Filter by the amount of time in seconds for package to upload before status changes to "timeout".
• packageDescriptor.name
• category - Filter by package's category. Possible values are "custom", "cylance".
Response
200 OK
Get Packages Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"packageId": "string",
"uploadedOn": "2018-04-30T23:25:22.788Z",
"uploadedBy": {
"id": "string",
"login": "string"
},
"size": 0,
"status": "started",
"timeout": 0,
"downloadUrl": "string",
"packageDescriptor": {
"name": "string",
"description": "string",
"examples": [
{
"invocationString": "string",
CylanceOPTICS API Guide – v2.0 rev2 Page 22 of 133
"description": "string"
}
],
"packageInfo": {
"fileType": "python",
"fileName": "string",
"entryPoint": "main for Python packages."
},
"version": 0,
"packageId": "string"
},
"category": "custom"
}
]
}
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 are less than or equal to zero.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The package resources page requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Server Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
page_items
The list of packages belonging to the requested page, each displaying the following information:
• category: The category of the package. Values are custom or cylance.
• downloadUrl: The URL to download the package from.
• packageDescriptor: The package metadata, provided by the user.
o description: The description of the package.
o examples: A list of examples of how to use the package.
invocationString: An example of how to invoke the package.
description: A description of what the example does.
o name: The name of the package.
o packageId: The unique identifier for the package.
o
packageInfo: Package level documentation / annotation.
CylanceOPTICS API Guide – v2.0 rev2 Page 23 of 133
fileType: The file type of the package. Only Python is supported.
fileName: The name of the package file.
entryPoint: The point of execution for the package.
o version: The version of the package.
• packageId: The unique identifier for the package.
• size: The size of the package, in bytes.
• status: The status of the package in the upload process.
• timeout: The amount of time (seconds) for a package upload before the status changes
to timeout.
• uploadedBy: The unique identifiers of the user who uploaded the package.
o id: The unique ID for the user.
o login: The email address of the user.
• uploadedOn: The date and time (UTC) when the package was uploaded.
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 Package
Allows a caller to create a new package resource for a tenant.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2
US Government: https://protectapi.us.cylance.com/packages/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/v2
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgconfig:create scope encoded.
Request
Post Package Request Schema
{
"checksum": "string",
"packageDescriptor": {
"name": "string",
"description": "string",
"examples": [
{
"invocationString": "string",
"description": "string"
CylanceOPTICS API Guide – v2.0 rev2 Page 24 of 133
}
],
"packageInfo": {
"fileType": "python",
"fileName": "string",
"entryPoint": "main"
},
"version": 0
}
}
Response
202 Accepted – Successful request
Post Package Response Schema
{
"packageId": "string",
"uploadTo": "string",
"packageUrl": "string"
}
400 BadRequest – Returned for the following reasons:
• The uploaded Package exceeds the 15MB size limit per package.
• The maximum number of 20 packages exceeded.
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.
The request JSON schema contains the following fields:
Field Name Description
checksum
The SHA-256 hash of the package.
packageDescriptor
Package metadata provided by the user.
• description: The description of the package.
• examples: A list of examples of how to use the package.
o description: A description of what the example does.
o invocationString: An example of how to invoke the package.
• name: The name of the package.
CylanceOPTICS API Guide – v2.0 rev2 Page 25 of 133
• packageInfo: Package level documentation / annotation.
o entryPoint: The point of execution for the package.
o fileType: The file type of the package. Note: Only Python is supported.
o fileName: The name of the package file.
• version: The version of the package.
The response JSON schema contains the following fields:
Field Name Description
packageId
The ID of the packaged uploaded.
packageUrl
The URL to retrieve the package in the future, after the actual package is uploaded.
uploadTo
The URL to which the package is uploaded.
Get Package
Allows a caller to request a specific package resource belonging to a tenant. Use Get Packages to obtain the unique package ID.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/{unique_package_id}
US Government: https://protectapi.us.cylance.com/packages/v2/{unique_package_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/v2/{unique_package_id}
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgconfig:read scope encoded.
Request None
Response
200 OK
Get Package Response Schema
{
"packageId": "string",
"uploadedOn": "2018-05-01T21:27:59.029Z",
"uploadedBy": {
"id": "string",
"login": "string"
},
"size": 0,
"status": "started",
"timeout": 0,
"downloadUrl": "string",
CylanceOPTICS API Guide – v2.0 rev2 Page 26 of 133
"packageDescriptor": {
"name": "string",
"description": "string",
"examples": [
{
"invocationString": "string",
"description": "string"
}
],
"packageInfo": {
"fileType": "python",
"fileName": "string",
"entryPoint": "string"
},
"version": 0,
"packageId": "string"
},
"category": "custom"
}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The unique identifier for the package is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The package resource requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
category The category of the package. Values are
custom
or
cylance
.
downloadUrl
The URL to download the package from.
packageDescriptor
The package metadata, provided by the user.
• description: The description of the package.
• examples: A list of examples of how to use the package.
o
description: A description of what the example does.
CylanceOPTICS API Guide – v2.0 rev2 Page 27 of 133
o invocationString: An example of how to invoke the package.
• name: The name of the package.
• packageInfo: Package level documentation / annotation.
o entryPoint: The point of execution for the package.
o fileName: The name of the package file.
o fileType: The file type of the package. Only Python is supported.
• packageId: The unique identifier for the package.
• version: The version of the package.
packageId
The unique identifier for the package.
size
The size of the package, in bytes.
status
The status of the package in the upload process. Statuses are started, success, failed, and
timeout.
timeout
The amount of time (seconds) for a package upload before the status changes to timeout.
uploadedBy
The unique identifiers of the user who uploaded the package.
• id: The unique ID for the user.
• login: The email address of the user.
uploadedOn
The date and time (UTC) when the package was uploaded.
Delete Package
Allows a caller to delete a specific package resource belonging to a tenant. Use Get Packages to obtain the unique package ID.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/{unique_package_id}
US Government: https://protectapi.us.cylance.com/packages/v2/{unique_package_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/v2/{unique_package_id}
Method HTTP/1.1 DELETE
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgconfig:delete scope encoded.
Request None
Response
204 No Content – Package deleted
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The unique identifier for the package is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden
CylanceOPTICS API Guide – v2.0 rev2 Page 28 of 133
• The JWT token did not contain the proper scope to perform this action.
• Cannot delete the CylanceOPTICS package.
404 NotFound – Returned if the package resource to update does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
Create Package Execution
Allows a caller to create (add) a new CylanceOPTICS package execution resource for a specific tenant, which triggers a package to
execute on the device or on devices in a specific zone.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/executions
US Government: https://protectapi.us.cylance.com/packages/v2/executions
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/v2/executions
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgdeploy:create scope encoded.
Request
Post Package Execution Request Schema
{
"execution": {
"name": "string",
"target": {
"devices": [
"string"
],
"zones": [
"string"
]
},
"destination": "string",
"packageExecutions": [
{
"arguments": [
"string"
],
"package": "string"
}
],
"keepResultsLocally": false
CylanceOPTICS API Guide – v2.0 rev2 Page 29 of 133
}
}
Response
202 Accepted – Package is being executed
Post Package Execution Request Schema
{
"name": "string",
"target": {
"devices": [
"string"
],
"zones": [
"string"
]
},
"destination": "string",
"packageExecutions": [
{
"arguments": [
"string"
],
"package": "string"
}
],
"keepResultsLocally": false,
"id": "string",
"createdAt": "2018-05-02T00:33:12.092Z",
"createdBy": {
"id": "string",
"login": "string"
},
"deviceStatuses": {
"acked": 0,
"succeeded": 0,
"failed": 0
},
"deviceCount": 0
}
400 BadRequest – Malformed request.
CylanceOPTICS API Guide – v2.0 rev2 Page 30 of 133
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.
The request JSON schema contains the following fields:
Field Name Description
execution
The execution object to be created.
• destination: The FTP, SFTP, or SAMBA URL for saving the results.
• keepResultsLocally: The setting to save the results to the local disk drive. If true, the
results are saved to file://[Cylance Data Directory]/Optics.
• name: The name of the execution.
• packageExecutions: The list of packages to execute.
o arguments: The list of arguments for the package. See examples from
packageDescriptor.
o package: The URL to download the package resource from.
• target: The devices and/or zones to execute the packages against.
o devices: The list of device IDs to execute the packages against.
o zones: The list of zone IDs to execute the packages against.
The response JSON schema contains the following fields:
Field Name Description
createdAt
The date and time (UTC) when the execution was requested.
createdBy
The user who requested the execution.
• id: The unique ID for the user.
• login: The email address of the user.
destination
The FTP, SFTP, or SAMBA URL for saving the results.
deviceCount
The number of online devices at the moment the package execution request was made.
deviceStatuses
The statuses of the package executions on the devices.
• acked (acknowledged): The number of devices that received the package execution
command but have not yet responded.
• failed: The number of devices that failed to execute the packages.
• succeeded: The number of devices that have successfully executed the packages.
id
The ID of the execution resource.
CylanceOPTICS API Guide – v2.0 rev2 Page 31 of 133
keepResultsLocally
The setting to save the results to the local disk drive. If true, the results are saved to
file://[Cylance Data Directory]/Optics.
name
The name of the execution.
packageExecutions
The list of packages to execute.
• arguments: The list of arguments for the package. See examples from
packageDescriptor.
• package: The URL to download the package resource from.
target
The devices and/or zones to execute the packages against.
• devices: The list of device IDs to execute the packages against.
• zones: The list of zone IDs to execute the packages against.
Get Package Executions
Allows a caller to request a page with a list of package executions belonging to a tenant, sorted by the uploaded date, in
descending order (most recent uploaded package execution listed first). The page number and page size parameters are optional.
When the values are not specified, the default values are 1 and 20 respectively.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/executions?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/packages/v2/executions?page=m&page_size=n
All Other Regions: https://protectapi-{region-
code}.cylance.com/packages/v2/executions?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 opticspkgdeploy:list scope encoded.
Request
Append the following optional query string parameters:
• page: The page number to request. Defaults to 1.
• page_size: The number of packages records to retrieve per page. Defaults to 20.
• sort: Sort by the following fields (adding "-" in front of value denotes descending order).
o id
o name
o createdAt
o createdBy.id
o createdBy.login
o deviceCount
• id: Filter by ID of execution.
• name: Filter by name of execution.
• createAt: Filter by date and time of when the execution was requested in UTC.
• createdBy.Id: Filter by ID of the user who requested the execution.
•
createdBy.Login: Filter by the email address of the user who requested the execution.
CylanceOPTICS API Guide – v2.0 rev2 Page 32 of 133
• deviceCount: Filter by the number of online devices at the moment the package execution request was made.
Response
200 OK
Get Package Executions Response Schema
{
"page_number": 0,
"page_size": 0,
"total_pages": 0,
"total_number_of_items": 0,
"page_items": [
{
"name": "string",
"target": {
"devices": [
"string"
],
"zones": [
"string"
]
},
"destination": "string",
"packageExecutions": [
{
"arguments": [
"string"
],
"package": "string"
}
],
"keepResultsLocally": false,
"id": "string",
"createdAt": "2018-05-02T23:18:08.719Z",
"createdBy": {
"id": "string",
"login": "string"
},
"deviceStatuses": {
"acked": 0,
"succeeded": 0,
"failed": 0
},
"deviceCount": 0
CylanceOPTICS API Guide – v2.0 rev2 Page 33 of 133
}
]
}
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 are less than or equal to zero.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The package resources page requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
page_items
The list of executions belonging to the requested page, each displaying the following
information:
• createdAt: The date and time (UTC) when the execution was requested.
• createdBy: The user who requested the execution.
o id: The ID of the user who requested the execution.
o login: The email address of the user who requested the execution.
• destination: The FTP, SFTP, or SAMBA URL for saving the results.
• deviceCount: The number of online devices at the moment the package execution
request was made.
• deviceStatuses: The statuses of the package executions on the devices.
o acked (acknowledged): The number of devices that received the package
execution command but have not yet responded.
o failed: The number of devices that failed to execute the packages.
o succeeded: The number of devices that have successfully executed the
packages.
• id: The ID of the execution resource.
• keepResultsLocally: The setting to save the results to the local disk drive. If true, the
results are saved to file://[Cylance Data Directory]/Optics.
• name: The name of the execution.
• packageExecutions: The list of packages to execute.
o arguments: The list of arguments for the package. See examples from
packageDescriptor.
o
package: The URL to download the package resource from.
CylanceOPTICS API Guide – v2.0 rev2 Page 34 of 133
• target: The devices and/or zones to execute the packages against.
o devices: The list of device IDs to execute the packages against.
o zones: The list of zone IDs to execute the packages against.
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.
Get Package Execution
Allows a caller to request a specific package execution resource belonging to a tenant. Use Get Package Executions to obtain the
unique package execution ID.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/executions/{unique_exeuction_id}
US Government: https://protectapi.us.cylance.com/packages/v2/executions/{unique_exeuction_id}
All Other Regions: https://protectapi-{region-
code}.cylance.com/packages/v2/executions/{unique_exeuction_id}
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgdeploy:read scope encoded.
Request None
Response
200 OK
Get Package Execution Response Schema
{
"name": "string",
"target": {
"devices": [
"string"
],
"zones": [
"string"
]
},
"destination": "string",
"packageExecutions": [
{
"arguments": [
"string"
CylanceOPTICS API Guide – v2.0 rev2 Page 35 of 133
],
"package": "string"
}
],
"keepResultsLocally": false,
"id": "string",
"createdAt": "2018-05-02T23:18:08.719Z",
"createdBy": {
"id": "string",
"login": "string"
},
"deviceStatuses": {
"acked": 0,
"succeeded": 0,
"failed": 0
},
"deviceCount": 0
}
400 BadRequest – Returned for the following reasons:
• The tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The unique identifier for the execution is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The execution resource requested does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
createdAt
The date and time (UTC) when the execution was requested.
createdBy
The user who requested the execution.
• id: The unique ID for the user.
• login: The email address of the user.
destination
The FTP, SFTP, or SAMBA URL for saving the results.
deviceCount
The number of online devices at the moment the package execution request was made.
CylanceOPTICS API Guide – v2.0 rev2 Page 36 of 133
deviceStatuses
The statuses of the package executions on the devices.
• acked (acknowledged): The number of devices that received the package execution
command but have not yet responded.
• failed: The number of devices that failed to execute the packages.
• succeeded: The number of devices that have successfully executed the packages.
id
The ID of the execution resource.
keepResultsLocally
The setting to save the results to the local disk drive. If true, the results are saved to
file://[Cylance Data Directory]/Optics.
name
The name of the execution.
packageExecutions
The list of packages to execute.
• arguments: The list of arguments for the package. See examples from
packageDescriptor.
• package: The URL to download the package resource from.
target
The devices and/or zones to execute the packages against.
• devices: The list of device IDs to execute the packages against.
• zones: The list of zone IDs to execute the packages against.
Delete Package Execution
Allows a caller to delete a specific package resource belonging to a tenant. Use Get Package Executions to obtain the unique
package ID.
Service
Endpoint
North America: https://protectapi.cylance.com/packages/v2/execution/{unique_exeuction_id}
US Government: https://protectapi.us.cylance.com/packages/v2/execution/{unique_exeuction_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/packages/v2/execution/{unique_exeuction_id}
Method HTTP/1.1 DELETE
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticspkgdeploy:delete scope encoded.
Request None
Response
204 No Content – Package deleted
Delete Package Execution Response Schema
{
"name": "string",
"target": {
"devices": [
"string"
CylanceOPTICS API Guide – v2.0 rev2 Page 37 of 133
],
"zones": [
"string"
]
},
"destination": "string",
"packageExecutions": [
{
"arguments": [
"string"
],
"package": "string"
}
],
"keepResultsLocally": false,
"id": "string",
"createdAt": "2018-05-02T23:18:08.719Z",
"createdBy": {
"id": "string",
"login": "string"
},
"deviceStatuses": {
"acked": 0,
"succeeded": 0,
"failed": 0
},
"deviceCount": 0
}
400 BadRequest – Returned for the following reasons:
• The Tenant ID cannot be retrieved from the JWT token.
• The unique identifier for the package is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden
• The JWT token did not contain the proper scope to perform this action.
• Cannot delete the CylanceOPTICS package.
404 NotFound – Returned if the package execution resource to update does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
CylanceOPTICS API Guide – v2.0 rev2 Page 38 of 133
The response JSON schema contains the following fields:
Field Name Description
createdAt
The date and time (UTC) when the execution was requested.
createdBy
The user who requested the execution.
• id: The unique ID for the user.
• login: The email address of the user.
destination
The FTP, SFTP, or SAMBA URL for saving the results.
deviceCount
The number of online devices at the moment the package execution request was made.
deviceStatuses
The statuses of the package executions on the devices.
• acked (acknowledged): The number of devices that received the package execution
command but have not yet responded.
• failed: The number of devices that failed to execute the packages.
• succeeded: The number of devices that have successfully executed the packages.
id
The ID of the execution resource.
keepResultsLocally
The setting to save the results to the local disk drive. If true, the results are saved to
file://[Cylance Data Directory]/Optics.
name
The name of the execution.
packageExecutions
The list of packages to execute.
• arguments: The list of arguments for the package. See examples from
packageDescriptor.
• package: The URL to download the package resource from.
target
The devices and/or zones to execute the packages against.
• devices: The list of device IDs to execute the packages against.
• zones: The list of zone IDs to execute the packages against.
CylanceOPTICS API Guide – v2.0 rev2 Page 39 of 133
CylanceOPTICS Detection Rules
The CylanceOPTICS Detection Rules API allows users to create or update rules to help monitor an organization for security
threats or anomalous behavior. The flexibility of Detection Rules allows users to monitor for broad behavior characteristics (for
example, files being created with certain naming patterns) or search for a targeted series of events (for example, a process with a
certain file signature thumbprint that then creates files and initiates network connections).
The CylanceOPTICS Detection Rules API includes:
• Getting the content of a Detection Rule
• Getting a list of Detection Rules for a tenant
• Getting a list of Detection Rules as a CSV file
• Validating a Detection Rule
• Creating a Detection Rule
• Updating a Detection Rule
• Deactivating (or soft deleting) a Detection Rule
• Getting a natural language representation of a Detection Rule
• Getting a count of how many Detection Rules exist in a tenant
Note: This addendum only covers CylanceOPTICS Detection Rules API information. Read the Cylance User API guide for
configuration information.
Get Detection Rule Content
Allows a caller to retrieve the content of a Detection Rule in its native JSON structure. The structure of CylanceOPTICS Detection
Rules is beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine Custom Rule Guide knowledge
base article for a more detailed explanation. The underlying logic extracts from the JWT specified as the Bearer value in the
Authorization request header the tenant's unique identifier to associate the Detection Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/{rule_id}
US Government: https://protectapi.us.cylance.com/rules/v2/{rule_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/{rule_id}
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:read scope encoded.
Request None
Response
200 OK
Get Detection Rule Content Response Schema
{
"Id": "631015e5…",
"Name": "My Detection Rule",
CylanceOPTICS API Guide – v2.0 rev2 Page 40 of 133
"Description": "My Detection Rule Description",
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "badapp.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
"Tags": [
"CylanceOPTICS"
CylanceOPTICS API Guide – v2.0 rev2 Page 41 of 133
],
"Version": 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such detection rule found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the entirety of the Detection Rule logic. This schema is further explained in the
CylanceOPTICS Context Analysis Engine Custom Rule Guide knowledge base article.
Get Detection Rule List
Allows a caller to retrieve a list of Detection rules available in a tenant. The underlying logic extracts from the JWT specified as
the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/rules/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/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 opticsrule:list scope encoded.
Request None
Response
200 OK
Get Detection Rule List Response Schema
{
“page_size”: 10,
“total_pages”: 1,
“page_items”: [
"Id": "631015e5…",
"Version": 1,
CylanceOPTICS API Guide – v2.0 rev2 Page 42 of 133
"Name": "My Detection Rule",
"Description": "My Detection Rule Description",
"LastModified": "2018-11-26T23:36:22.954Z",
"ModifiedBy": {
"id": "efad5148…",
"login": "user@test.com"
},
"Severity": "Medium",
"DeviceCount": 0,
"RulesetCount": 0,
"Category": "Cylance Rules",
"OperatingSystems": [
{
"Name": "Windows"
}
]
],
“total_number_of_items”: 10,
“page_number”: 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
page_size
The number of items on the page.
total_pages
The total number of pages of this size.
total_number_of_items
The total number of Detection Rules in the tenant.
page_number
The current page number of results.
page_items
A list of Exception objects that are available in the tenant that will contain the following fields.
Id
The unique ID of the Detection Rule.
CylanceOPTICS API Guide – v2.0 rev2 Page 43 of 133
Version
The version of the Detection Rule.
Name
The name of the Detection Rule.
Description
The description of the Detection Rule.
LastModified
The timestamp (in UTC) of the last time that the Detection Rule was modified.
ModifiedBy
An object detailing the last user to modify the Detection Rule. It includes the following fields:
• id: The unique ID of the user who modified the Detection Rule.
• login: The email address of the user who modified the Detection Rule.
Severity
The severity assigned to the Detection Rule. Possible values are:
• High
• Medium
• Low
• Informational
DeviceCount
The number of devices that have the Detection Rule applied.
RulesetCount
The number of Detection Rule Sets that have the Detection Rule enabled.
Category
The category or rule grouping that the Detection Rule belongs to. Possible values include:
• Custom: Custom rules that users have uploaded to a tenant.
• Cylance Rules: Cylance-official rules.
• Cylance Experimental: Cylance rules that are deemed to be experimental in their nature.
OperatingSystems
An object detailing the operating systems that the Detection Rule can be applied to. It will
include the “name” field. This can consist of:
• “Windows”
• “MacOS”
Get Detection Rule CSV List
Allows a caller to retrieve a CSV where every line represents a Detection Rule available in the tenant. The underlying logic
extracts from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to
associate the Detection Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/csv
US Government: https://protectapi.us.cylance.com/rules/v2/csv
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/csv
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:list scope encoded.
CylanceOPTICS API Guide – v2.0 rev2 Page 44 of 133
Request None
Response
200 OK – Will initiate a CSV file download.
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response CSV contains the following fields:
Field Name Description
Name
The name of the Detection Rule.
Id
The unique ID of the Detection Rule.
Version
The version of the Detection Rule.
Description
The description of the Detection Rule.
Severity
The severity of the Detection Rule.
Category
The category that the Detection Rule belongs to.
Last Modified
The timestamp (in UTC) of the last time that the Detection Rule was modified.
Modified By
The email address of the user who last modified the Detection Rule.
Device Count
The number of devices that have the Detection Rule applied.
Ruleset Count
The number of Detection Rule Sets that have the Detection Rule enabled.
Validate Detection Rule
Allows a caller to validate a Detection Rule’s JSON by sending the native JSON structure of a Detection Rule to a validation
service. The structure of CylanceOPTICS Detection Rules is beyond the scope of this document. Refer to the CylanceOPTICS
Context Analysis Engine Custom Rule Guide knowledge base article for a more detailed explanation. The underlying logic extracts
from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the
Detection Rule resource with.
CylanceOPTICS API Guide – v2.0 rev2 Page 45 of 133
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/validate
US Government: https://protectapi.us.cylance.com/rules/v2/validate
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/validate
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:read scope encoded.
Request
Post Detection Rule Validation Request Schema
{
"Name": "My Detection Rule",
"Description": "My Detection Rule Description",
“Severity”: “Medium”,
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "badapp.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
CylanceOPTICS API Guide – v2.0 rev2 Page 46 of 133
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Position": "PostActivation"
}
],
"Filters": [
{
"Type": "Event",
"Data": {
"Category": "Process",
"SubCategory": "",
"Type": "*"
}
}
]
}
],
"Tags": [
"CylanceOPTICS"
]
}
Response
200 OK
Post Detection Rule Validation Response Schema
{
"valid": true,
"warnings": [
"string"
],
"errors": [
"string"
]
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
CylanceOPTICS API Guide – v2.0 rev2 Page 47 of 133
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
valid
Returns ‘true’ if the Detection Rule passes validation. Returns ‘false’ if the Detection Rule does
not pass validation.
warnings
A list of warning message strings that may impact the performance or validity of the Detection
Rule.
errors
A list of error message that will prevent the Detection Rule from validating and operating
correctly.
CylanceOPTICS API Guide – v2.0 rev2 Page 48 of 133
Create Detection Rule
Allows a caller to create a new Detection Rule by sending the native JSON structure of a Detection Rule. The structure of
CylanceOPTICS Detection Rules is beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine
Custom Rule Guide knowledge base article for a more detailed explanation. The underlying logic extracts from the JWT specified
as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule resource
with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2
US Government: https://protectapi.us.cylance.com/rules/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:create scope encoded.
Request
Post Detection Rule Content Request Schema
{
"Name": "My Detection Rule",
"Description": "My Detection Rule Description",
“Severity”: “Medium”,
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
CylanceOPTICS API Guide – v2.0 rev2 Page 49 of 133
"Data": "badapp.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Position": "PostActivation"
}
],
"Filters": [
{
"Type": "Event",
"Data": {
"Category": "Process",
"SubCategory": "",
"Type": "*"
}
}
]
}
],
"Tags": [
"CylanceOPTICS"
]
}
Response
202 OK – Rule created successfully.
Post Detection Rule Content Response Schema
{
"Name": "My Detection Rule",
"Description": "My Detection Rule Description",
"Severity": "Medium",
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
CylanceOPTICS API Guide – v2.0 rev2 Page 50 of 133
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "badapp.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Position": "PostActivation"
}
],
"Filters": [
{
"Type": "Event",
"Data": {
"Category": "Process",
"SubCategory": "",
"Type": "*"
}
}
]
}
CylanceOPTICS API Guide – v2.0 rev2 Page 51 of 133
],
"Tags": [
"CylanceOPTICS"
],
"RuleSourceGrouping": "Custom Rule",
"Id": "b25285ba-8633-4a13-bf3c-21f0ddbd1569",
"Version": 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the entirety of the Detection Rule logic. This schema is further explained in the
CylanceOPTICS Context Analysis Engine Custom Rule Guide knowledge base article.
Note that the ‘id’ and ‘version’ fields are automatically populated when the request is submitted.
Update Detection Rule
Allows a caller to update a Detection Rule by sending a new JSON structure. The structure of CylanceOPTICS Detection Rules is
beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine Custom Rule Guide knowledge base
article for a more detailed explanation. The underlying logic extracts from the JWT specified as the Bearer value in the
Authorization request header the tenant's unique identifier to associate the Detection Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/{rule_id}
US Government: https://protectapi.us.cylance.com/rules/v2/{rule_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/{rule_id}
Method HTTP/1.1 PUT
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:update scope encoded.
Request
Update Detection Rule Content Request Schema
{
"Name": "My Detection Rule",
"Description": "My New Detection Rule Description",
“Severity”: “Medium”,
CylanceOPTICS API Guide – v2.0 rev2 Page 52 of 133
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "badapp_12312.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Position": "PostActivation"
}
],
"Filters": [
{
"Type": "Event",
"Data": {
"Category": "Process",
CylanceOPTICS API Guide – v2.0 rev2 Page 53 of 133
"SubCategory": "",
"Type": "*"
}
}
]
}
],
"Tags": [
"CylanceOPTICS"
]
}
Response
202 OK – Rule created successfully.
Update Detection Rule Content Response Schema
{
"Name": "My Detection Rule",
"Description": "My Detection Rule Description",
“Severity”: “Medium”,
"ObjectType": "DetectionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "MaliciousApp",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": " badapp_12312.exe"
}
],
CylanceOPTICS API Guide – v2.0 rev2 Page 54 of 133
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Position": "PostActivation"
}
],
"Filters": [
{
"Type": "Event",
"Data": {
"Category": "Process",
"SubCategory": "",
"Type": "*"
}
}
]
}
],
"Tags": [
"CylanceOPTICS"
],
"RuleSourceGrouping": "Custom Rule",
"Id": "b25285ba-8633-4a13-bf3c-21f0ddbd1569",
"Version": 2
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such Detection Rule found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
CylanceOPTICS API Guide – v2.0 rev2 Page 55 of 133
The response JSON schema contains the entirety of the Detection Rule logic. This schema is further explained in the
CylanceOPTICS Context Analysis Engine Custom Rule Guide knowledge base article.
Note that the ‘id’ and ‘version’ fields are automatically populated when the request is submitted.
Deactivate / Delete Detection Rule
Allows a caller to ‘soft delete’ a Detection Rule and remove it from Detection Rule Sets. The underlying logic extracts from the
JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection
Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/{rule_id}/deactivate
US Government: https://protectapi.us.cylance.com/rules/v2/{rule_id}/deactivate
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/{rule_id}/deactivate
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:update scope encoded.
Request None
Response
200 OK
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
Note that Detection Rule Sets are not automatically communicated to all endpoints when updates to Detection Rules are made.
To ensure that the latest logic is applied to endpoints in the quickest manner, re-save any affected Detection Rule Sets (either via
the UI or API.)
CylanceOPTICS API Guide – v2.0 rev2 Page 56 of 133
Get Detection Rule Natural Language Representation
Allows a caller to retrieve the ‘natural language’ representation of a rule. This process converts the Detection Rule logic into a
series of ‘AND’s, ‘OR’s, and ‘NOT’s to describe what the Detection Rule looks for. The underlying logic extracts from the JWT
specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule
resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/{rule_id}/natlang
US Government: https://protectapi.us.cylance.com/rules/v2/{rule_id}/natlang
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/{rule_id}/natlang
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:read scope encoded.
Request None
Response
200 OK
Update Detection Rule Natural Language Response Schema
{
"Name": "My Detection Rule",
"Paths": [
[
{“Instigating Process Name is ‘badapp_12312.exe’.}
]
]
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
CylanceOPTICS API Guide – v2.0 rev2 Page 57 of 133
Get Detection Rule Counts
Allows a caller to retrieve counts of how many devices, Detection Rule Sets, and policies that have a particular Detection Rule
applied. The underlying logic extracts from the JWT specified as the Bearer value in the Authorization request header the tenant's
unique identifier to associate the Detection Rule resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rules/v2/{rule_id}/counts
US Government: https://protectapi.us.cylance.com/rules/v2/{rule_id}/counts
All Other Regions: https://protectapi-{region-code}.cylance.com/rules/v2/{rule_id}/counts
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsrule:read scope encoded.
Request None
Response
200 OK
Get Detection Rule Count Response Schema
{
"DeviceCount": 0,
"RulesetCount": 0,
"PolicyCount": 0
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such Detection Rule found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
DeviceCount
The number of devices that have the requested Detection Rule applied.
RulesetCount
The number of Detection Rule Sets that have the requested Detection Rule enabled.
PolicyCount
The number of Device Policies that have the requested Detection Rule applied.
CylanceOPTICS API Guide – v2.0 rev2 Page 58 of 133
CylanceOPTICS Detection Rule Sets
The CylanceOPTICS Detection Rule Set API allows users to create a set of rules and apply that set to Device Policies.
The CylanceOPTICS Detection Rule Set API includes:
• Getting content for a Detection Rule Set
• Getting a list of Detection Rule Sets
• Creating a Detection Rule Set
• Retrieving a Default Detection Rule Set (retrieving a default template)
• Updating a Detection Rule Set
• Deleting a Detection Rule Set
• Deleting multiple Detection Rule Sets
• Getting a list of Detection Rule Sets as a CSV file
Note: This addendum only covers CylanceOPTICS Detection Rule Set API information. Read the Cylance User API guide for
configuration information.
Get Detection Rule Set List
Allows a caller to retrieve a list of Detection Rule Sets available in a tenant. The underlying logic extracts from the JWT specified
as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule Set
resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/ rulesets/v2?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/ rulesets/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 opticsruleset:list scope encoded.
Request
Append the following parameters to the request to sort and filter the results:
• description: Case-insensitive query parameter to filter or sort by the Description field.
• last_modified: Case-insensitive query parameter to filter or sort by the Last Modified field.
• modified_by.id: Case-insensitive query parameter to filter or sort by a user’s unique ID.
• modified_by.login: Case-insensitive query parameter to filter or sort by a user’s email address.
• device_count: Filter or sort the list by the number of applied devices.
• sort: Sort by field (adding ‘-‘ in front of value denotes descending order.)
Response
200 OK
Get Detection Rule Set List Response Schema
{
“page_size”: 10,
“total_pages” 1,
“page_items”: [
CylanceOPTICS API Guide – v2.0 rev2 Page 59 of 133
"name": "My Detection Rule Set",
"description": "My Detection Rule Set Description",
"notification_message": "My Detection Rule Set Notification",
"id": "ae53bc38…",
"last_modified": "2018-11-26T23:36:22.810Z",
"modified_by": {
"id": "6572fe36…",
"login": "user@test.com"
},
"policies": [
"6521ffee…"
],
"device_count": 0,
"category": "Cylance"
],
“total_number_of_items”: 10,
“page_number”: 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
page_size
The number of items on the page.
total_pages
The total number of pages of this size.
total_number_of_items
The total number of Exceptions in the tenant.
page_number
The current page number of results.
page_items
A list of Exception objects that are available in the tenant that will contain the following fields.
name
The name of the Detection Rule Set
description
The description of the Detection Rule Set.
id
The unique ID of the Detection Rule Set.
CylanceOPTICS API Guide – v2.0 rev2 Page 60 of 133
last_modified
The timestamp (in UTC) of the last time that the Detection Rule Set was modified.
modified_by
An object detailing the last user to modify the Detection Rule Set. It includes the following fields:
• id: The unique ID of the user who modified the Detection Rule Set.
• login: The email address of the user who modified the Detection Rule Set.
policies
A list of policy IDs that a Detection Rule Set is applied to.
Device_count
The number of devices that have the Detection Rule Set applied.
category
The category or rule grouping that the Detection Rule Set belongs to. Possible values include:
• Custom: Custom Detection Rule Sets that have been created by a user.
• Cylance: Detection Rule Sets that have been created by Cylance.
Get Detection Rule Set Content
Allows a caller to retrieve the content of a Detection Rule Set including Detection Rules, Response Actions, Detection Exceptions,
Package Playbooks, and the Polices where the Detection Rule Set is applied. The underlying logic extracts from the JWT specified
as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule Set
resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2/{ruleset_id}
US Government: https://protectapi.us.cylance.com/ rulesets/v2/{ruleset_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2/{ruleset_id}
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:read scope encoded.
Request None
Response
200 OK
Get Detection Rule Set Content Response Schema
{
"name": "My Detection Rule Set",
"description": "My Detection Rule Set Description",
"notification_message": "My Detection Rule Set Notification",
"category": "Cylance",
"id": "decd5e3a…",
"last_modified": "2018-11-26T23:36:22.839Z",
"modified_by": {
"id": "54ea98ae…",
CylanceOPTICS API Guide – v2.0 rev2 Page 61 of 133
"login": "user@test.com"
},
"rules": [
{
"detection_rule_id": "4f722b34… ",
"detection_rule_version": 1,
"detection_name": "Dropper/Downloader",
"detection_description": "A process has created a new executable file and then executed that file",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.839Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34…",
"response_rule_id": "6eb12c34… ",
"response_rule_version": 1,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.839Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7…",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": [
"d5e4ffcc…"
]
}
]
}
400 Bad Request – Malformed request.
CylanceOPTICS API Guide – v2.0 rev2 Page 62 of 133
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such Detection Rule Set found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
CylanceOPTICS API Guide – v2.0 rev2 Page 63 of 133
The response JSON schema contains the following fields:
Field Name Description
name
The name of the Detection Rule Set.
description
The description of the Detection Rule Set.
notification_message
The message to display on the endpoint when a Detection Rule is triggered.
id
The unique ID of the Detection Rule Set
last_modified
The timestamp (in UTC) of the last time that the Detection Rule Set was modified.
modified_by
An object detailing the last user to modify the Detection Rule Set. It includes the following fields:
• id: The unique ID of the user who modified the Detection Rule Set.
• login: The email address of the user who modified the Detection Rule Set.
rules
A list of Detection Rule objects and their associated Response Actions, Detection Exceptions,
and Package Playbooks. Each object in the list will contain the following fields.
detection_rule_id
The unique ID of the Detection Rule.
detection_rule_version
The version of the Detection Rule.
detection_name
The name of the Detection Rule.
detection_description
The description of the Detection Rule Set.
category
The category of the Detection Rule.
severity
The severity assigned to the Detection Rule. Possible values are:
• High
• Medium
• Low
• Informational
operating_systems
An object detailing the operating systems that the Detection Rule can be applied to. It will
include the “name” field. This can consist of:
• “Windows”
• “MacOS”
date_added
The timestamp (in UTC) when the Detection Rule was added to the tenant.
enabled
Determines whether or not a Detection Rule is enabled in the Detection Rule Set. When viewing
the content of a Detection Rule Set, this should always be set to ‘true.’
notification_enabled
Determines whether or not the message defined in the ‘notification_message’ field should
display on the device when the Detection Rule is triggered.
CylanceOPTICS API Guide – v2.0 rev2 Page 64 of 133
responses
A list of response objects for each Response Action enabled for a particular Detection Rule. Each
object will include the following fields:
• template_id: The ID of the response template to use (this is provided by Cylance.)
• response_rule_id: The ID of the response rule to enable (these are provided by
Cylance.)
• response_rule_version: The version of the response rule to enable (this is provided by
Cylance.)
• description: The description / name of the response rule.
• value: A currently unused field.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set
• created: The date that the Response Rule was added to the tenant.
exceptions
A list of Exception Rule objects that should be applied to the Detection Rule. Each object will
include the following fields:
• exception_id: The unique ID of the Exception Rule.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set.
• name: The name of the Exception Rule.
playbooks
A list of Package Playbook unique IDs that will be executed when the Detection Rule is triggered
on the device.
Create Detection Rule Set
Allows a caller to create a new Detection Rule Set. Detection Rule Sets can require a large number of fields and unique IDs to
function properly. It is recommended that callers make a GET request to ‘/rulesets/v2/default’ to obtain a properly formatted
template prior to submitting a POST request described below. The underlying logic extracts from the JWT specified as the Bearer
value in the Authorization request header the tenant's unique identifier to associate the Detection Rule Set resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2
US Government: https://protectapi.us.cylance.com/rulesets/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:create scope encoded.
Request
Post Detection Rule Set Content Request Schema
{
"name": "My Detection Rule Set",
"description": "My Detection Rule Set Description",
"notification_message": "My Detection Rule Set Notification",
"category": "Custom",
"rules": [
{
"detection_rule_id": "4f722b34… ",
CylanceOPTICS API Guide – v2.0 rev2 Page 65 of 133
"detection_rule_version": 0,
"detection_name": "Dropper/Downloader",
"detection_description": "A process has created a new executable file and then executed that file",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.828Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34… ",
"response_rule_id": "6eb12c34…",
"response_rule_version": 0,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.828Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7… ",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": [
"eefd51ea…"
]
}
]
}
Response
202 OK – Ruleset created.
Post Detection Rule Set Content Response Schema
{
"name": "My Detection Rule Set",
"description": "My Detection Rule Set Description",
"notification_message": "My Detection Rule Set Notification",
"category": "Custom",
CylanceOPTICS API Guide – v2.0 rev2 Page 66 of 133
“id”: “4568e4ac…
"last_modified": "2018-11-26T23:36:22.828Z",
"modified_by": {
"id": "string",
"login": "string"
},
"rules": [
{
"detection_rule_id": "4f722b34… ",
"detection_rule_version": 0,
"detection_name": "Dropper/Downloader",
"detection_description": "A process has created a new executable file and then executed that file",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.828Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34… ",
"response_rule_id": "6eb12c34…",
"response_rule_version": 0,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.828Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7… ",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": [
"eefd51ea…"
]
}
]
CylanceOPTICS API Guide – v2.0 rev2 Page 67 of 133
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
name
The name of the Detection Rule Set.
description
The description of the Detection Rule Set.
notification_message
The message to be displayed on the endpoint when a Detection Rule is triggered.
id
The unique ID of the Detection Rule Set.
last_modified
The timestamp (in UTC) of the last time that the Detection Rule Set was modified.
modified_by
An object detailing the last user to modify the Detection Rule Set. It includes the following fields:
• id: The unique ID of the user who modified the Detection Rule Set.
• login: The email address of the user who modified the Detection Rule Set.
rules
A list of Detection Rule objects and their associated Response Actions, Detection Exceptions,
and Package Playbooks. Each object in the list will contain the following fields.
detection_rule_id
The unique ID of the Detection Rule.
detection_rule_version
The version of the Detection Rule.
detection_name
The name of the Detection Rule.
detection_description
The description of the Detection Rule Set.
category
The category of the Detection Rule.
severity
The severity assigned to the Detection Rule. Possible values are:
• High
• Medium
• Low
CylanceOPTICS API Guide – v2.0 rev2 Page 68 of 133
• Informational
operating_systems
An object detailing the operating systems that the Detection Rule can be applied to. It will
include the “name” field. This can consist of:
• “Windows”
• “MacOS”
date_added
The timestamp (in UTC) that the Detection Rule was added to the tenant.
enabled
Determines whether or not a Detection Rule is enabled in the Detection Rule Set. When viewing
the content of a Detection Rule Set, this should always be set to ‘true.’
notification_enabled
Determines whether or not the message defined in the ‘notification_message’ field should
display on the device when the Detection Rule is triggered.
responses
A list of response objects for each Response Action enabled for a particular Detection Rule. Each
object will include the following fields:
• template_id: The ID of the response template to use (this is provided by Cylance.)
• response_rule_id: The ID of the response rule to enable (these are provided by
Cylance.)
• response_rule_version: The version of the response rule to enable (this is provided by
Cylance.)
• description: The description / name of the response rule.
• value: A currently unused field.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set.
• created: The date that the Response Rule was added to the tenant.
exceptions
A list of Exception Rule objects that should be applied to the Detection Rule. Each object will
include the following fields:
• exception_id: The unique ID of the Exception Rule.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set.
• name: The name of the Exception Rule.
playbooks
A list of Package Playbook unique IDs that will be executed when the Detection Rule is triggered
on the device.
Due to the complexity and dependency on correct unique IDs for Detection Rules, Playbooks, Exceptions, and Response Actions.
It is recommended that the caller make a GET request to ‘/rulesets/v2/default’ to obtain a properly formatted default Detection
Rule Set template which can then be modified and submitted in a POST request. The ‘default’ template is covered in the next
section.
CylanceOPTICS API Guide – v2.0 rev2 Page 69 of 133
Retrieve Default Detection Rule Set
Allows a caller to retrieve a properly formatted default Detection Rule Set template that includes all of the Detection Rules,
Exceptions, Playbooks, and Response Actions available in a tenant. The output of this request can be modified and submitted as
a POST request to ‘rulesets/v2’ to create a new Detection Rule Set. The underlying logic extracts from the JWT specified as the
Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule Set resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2/default
US Government: https://protectapi.us.cylance.com/rulesets/v2/default
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2/default
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:read scope encoded.
Request None
Response
200 OK
Get Default Detection Rule Set Content Response Schema
{
"name": "",
"description": "",
"notification_message": "",
"category": "Custom",
"rules": [
{
"detection_rule_id": "4f722b34… ",
"detection_rule_version": 0,
"detection_name": "Dropper/Downloader",
"detection_description": "A process has created a new executable file and then executed that file",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.828Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34… ",
CylanceOPTICS API Guide – v2.0 rev2 Page 70 of 133
"response_rule_id": "6eb12c34…",
"response_rule_version": 0,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.828Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7… ",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": [
"eefd51ea…"
]
}
]
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
name
The name of the Detection Rule Set.
description
The description of the Detection Rule Set.
notification_message
The message to be displayed on the endpoint when a Detection Rule is triggered.
rules
A list of Detection Rule objects and their associated Response Actions, Detection Exceptions,
and Package Playbooks. Each object in the list will contain the following fields.
CylanceOPTICS API Guide – v2.0 rev2 Page 71 of 133
detection_rule_id
The unique ID of the Detection Rule.
detection_rule_version
The version of the Detection Rule.
detection_name
The name of the Detection Rule.
detection_description
The description of the Detection Rule Set.
category
The category of the Detection Rule
severity
The severity assigned to the Detection Rule. Possible values are:
• High
• Medium
• Low
• Informational
operating_systems
An object detailing the operating systems that the Detection Rule can be applied to. It will
include the “name” field. This can consist of:
• “Windows”
• “MacOS”
date_added
The timestamp (in UTC) that the Detection Rule was added to the tenant.
enabled
Determines whether or not a Detection Rule is enabled in the Detection Rule Set. When viewing
the content of a Detection Rule Set, this should always be set to ‘true.’
notification_enabled
Determines whether or not the message defined in the ‘notification_message’ field should be
displayed on the device when the Detection Rule is triggered.
responses
A list of response objects for each Response Action enabled for a particular Detection Rule. Each
object will include the following fields:
• template_id: The ID of the response template to use (this is provided by Cylance.)
• response_rule_id: The ID of the response rule to enable (these are provided by
Cylance.)
• response_rule_version: The version of the response rule to enable (this is provided by
Cylance.)
• description: The description / name of the response rule.
• value: A currently unused field.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set
• created: The date that the Response Rule was added to the tenant.
exceptions
A list of Exception Rule objects that should be applied to the Detection Rule. Each object will
include the following fields:
• exception_id: The unique ID of the Exception Rule.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set.
• name: The name of the Exception Rule.
CylanceOPTICS API Guide – v2.0 rev2 Page 72 of 133
playbooks
A list of Package Playbook unique IDs that will be executed when the Detection Rule is triggered
on the device.
Update Detection Rule Set
Allows a caller to update a Detection Rule Set by sending a new JSON structure. The underlying logic extracts from the JWT
specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule
Set resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2/{ruleset_id}
US Government: https://protectapi.us.cylance.com/rulesets/v2/{ruleset_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2/{ruleset_id}
Method HTTP/1.1 PUT
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:update scope encoded.
Request
Update Detection Rule Content Request Schema
{
"name": "My Detection Rule Set",
"description": "My New Detection Rule Set Description",
"notification_message": "My New Detection Rule Set Notification",
"category": "Custom",
"rules": [
{
"detection_rule_id": "adceb34… ",
"detection_rule_version": 1,
"detection_name": "Powershell Download",
"detection_description": "Powershell was detected attempting to download a file from a remote location.",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.828Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34… ",
"response_rule_id": "6eb12c34…",
CylanceOPTICS API Guide – v2.0 rev2 Page 73 of 133
"response_rule_version": 0,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.828Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7… ",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": []
}
]
}
Response
202 OK – Ruleset updated.
Update Detection Rule Content Response Schema
{
"name": "My Detection Rule Set",
"description": "My New Detection Rule Set Description",
"notification_message": "My New Detection Rule Set Notification",
"category": "Custom",
"rules": [
{
"detection_rule_id": "adceb34… ",
"detection_rule_version": 1,
"detection_name": "Powershell Download",
"detection_description": "Powershell was detected attempting to download a file from a remote location.",
"category": "Cylance Rules",
"severity": "Medium",
"operating_systems": [
{
"Name": "Windows"
}
],
"date_added": "2018-11-26T23:36:22.828Z",
"enabled": true,
"notification_enabled": true,
"responses": [
{
"template_id": "4f722b34… ",
CylanceOPTICS API Guide – v2.0 rev2 Page 74 of 133
"response_rule_id": "6eb12c34…",
"response_rule_version": 0,
"description": "Delete file",
"value": {},
"enabled": true,
"created": "2018-11-26T23:36:22.828Z"
}
],
"exceptions": [
{
"exception_id": "d2cf6cc7… ",
"enabled": true,
"name": "My Detection Exception"
}
],
"playbooks": []
}
]
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such Detection Rule found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
name
The name of the Detection Rule Set.
description
The description of the Detection Rule Set.
notification_message
The message to be displayed on the endpoint when a Detection Rule is triggered.
rules
A list of Detection Rule objects and their associated Response Actions, Detection Exceptions,
and Package Playbooks. Each object in the list will contain the following fields.
detection_rule_id
The unique ID of the Detection Rule.
detection_rule_version
The version of the Detection Rule.
CylanceOPTICS API Guide – v2.0 rev2 Page 75 of 133
detection_name
The name of the Detection Rule.
detection_description
The description of the Detection Rule Set.
category
The category of the Detection Rule
severity
The severity assigned to the Detection Rule. Possible values are:
• High
• Medium
• Low
• Informational
operating_systems
An object detailing the operating systems that the Detection Rule can be applied to. It will
include the “name” field. This can consist of:
• “Windows”
• “MacOS”
date_added
The timestamp (in UTC) that the Detection Rule was added to the tenant.
enabled
Determines whether or not a Detection Rule is enabled in the Detection Rule Set. When viewing
the content of a Detection Rule Set, this should always be set to ‘true.’
notification_enabled
Determines whether or not the message defined in the ‘notification_message’ field should be
displayed on the device when the Detection Rule is triggered.
responses
A list of response objects for each Response Action enabled for a particular Detection Rule. Each
object will include the following fields:
• template_id: The ID of the response template to use (this is provided by Cylance.)
• response_rule_id: The ID of the response rule to enable (these are provided by
Cylance.)
• response_rule_version: The version of the response rule to enable (this is provided by
Cylance.)
• description: The description / name of the response rule.
• value: A currently unused field.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set
• created: The date that the Response Rule was added to the tenant.
exceptions
A list of Exception Rule objects that should be applied to the Detection Rule. Each object will
include the following fields:
• exception_id: The unique ID of the Exception Rule.
• enabled: This will always be ‘true’ when viewing a Detection Rule Set.
• name: The name of the Exception Rule.
playbooks
A list of Package Playbook unique IDs that will be executed when the Detection Rule is triggered
on the device.
CylanceOPTICS API Guide – v2.0 rev2 Page 76 of 133
Delete Detection Rule Set
Allows a caller to delete a Detection Rule Set. The underlying logic extracts from the JWT specified as the Bearer value in the
Authorization request header the tenant's unique identifier to associate the Detection Rule Set resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2/{ruleset_id}
US Government: https://protectapi.us.cylance.com/rulesets/v2/{ruleset_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2/{ruleset_id}
Method HTTP/1.1 DELETE
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:delete scope encoded.
Request None
Response
204 OK – Ruleset deleted
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
Delete Multiple Detection Rule Sets
Allows a caller to delete multiple Detection Rule Sets in a single request. The underlying logic extracts from the JWT specified as
the Bearer value in the Authorization request header the tenant's unique identifier to associate the Detection Rule Set resource
with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2
US Government: https://protectapi.us.cylance.com/rulesets/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2
Method HTTP/1.1 DELETE
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:delete scope encoded.
CylanceOPTICS API Guide – v2.0 rev2 Page 77 of 133
Request
Delete Detection Rule Sets Content Request Schema
{
“ids”: [
“eefa15ea…”
]
}
Response
200 OK – Rulesets deleted
Delete Detection Rule Sets Content Request Schema
[
{
"id": " eefa15ea…",
"success": true,
"message": "string"
}
]
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The request JSON schema contains the following fields:
Field Name Description
ids
A list of Detection Rule Set IDs to be deleted.
The response JSON schema contains the following fields:
Field Name Description
id
A Detection Rule Set ID that was attempted to be deleted.
success
A Boolean field denoting whether or not the Detection Rule Set ID was deleted.
message
A string containing any error, success, or warning messages.
CylanceOPTICS API Guide – v2.0 rev2 Page 78 of 133
Get Detection Rule Set CSV List
Allows a caller to retrieve a CSV where every line represents a Detection Rule Set available in the tenant. The underlying logic
extracts from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to
associate the Detection Rule Set resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/rulesets/v2/csv
US Government: https://protectapi.us.cylance.com/rulesets/v2/csv
All Other Regions: https://protectapi-{region-code}.cylance.com/rulesets/v2/csv
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsruleset:list scope encoded.
Request None
Response
200 OK – Will initiate a CSV file download.
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response CSV contains the following fields:
Field Name Description
Id
The unique ID of the Exception.
Last Modified
The timestamp (in UTC) of the last time that the Detection Rule Set was modified.
Modified By
The email address of the user who last modified the Detection Rule Set.
Name
The name of the Detection Rule Set.
Description
The description of the Detection Rule Set.
Notification
The Notification Message to display on a device if the Detection Rule triggers.
Category
The category of the Detection Rule Set.
Device Count
The number of devices that have the Detection Rule Set applied.
CylanceOPTICS API Guide – v2.0 rev2 Page 79 of 133
CylanceOPTICS Detection Exceptions
The CylanceOPTICS Detection Exceptions API allows users to add exceptions to their detection rules. Users can create a
Detection Exception from a false positive detection, from the Detection Summary page, and from the Detection Details page.
The CylanceOPTICS Detection Exceptions API includes:
• Getting the content for a Detection Exception
• Getting a list of Detection Exceptions for a tenant
• Getting a list of Detection Exceptions as a CSV file
• Creating a Detection Exception
• Updating a Detection Exception
• Deactivating (or soft deleting) a Detection Exception
Note: This addendum only covers CylanceOPTICS Detection Exceptions API information. Read the Cylance User API guide for
configuration information.
Get Detection Exceptions List
Allows a caller to retrieve a list of Exception rules available in a tenant. The underlying logic extracts from the JWT specified as
the Bearer value in the Authorization request header the tenant's unique identifier to associate the Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2
US Government: https://protectapi.us.cylance.com/exceptions/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:list scope encoded.
Request None
Response
200 OK
Get Detection Exception List Response Schema
{
“page_size”: 10,
“total_pages”: 1
"page_items": [
{
"Id": "631015e5…",
"Name": "My Exception",
"Description": "My Exception Description",
"DeviceCount": 0,
"LastModified": "2018-11-26T23:36:23.000Z",
CylanceOPTICS API Guide – v2.0 rev2 Page 80 of 133
"ModifiedBy": {
"id": "382eabd4…",
"login": "user@test.com"
},
"OperatingSystems": [
{
"Name": "Windows"
}
],
"PolicyCount": 0,
"RulesetCount": 0,
"Version": 1
}
],
“total_number_of_items”: 10
“page_number”: 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
page_size
The number of items on the page.
total_pages
The total number of pages of this size.
total_number_of_items
The total number of Exceptions in the tenant.
page_number
The current page number of results.
page_items
A list of Exception objects that are available in the tenant that will contain the following fields.
Id
The unique ID of the Exception.
Name
The name of the Exception.
description
The description of the Exception.
CylanceOPTICS API Guide – v2.0 rev2 Page 81 of 133
DeviceCount
The number of devices that have the Exception applied.
LastModified
The timestamp (in UTC) of the last time that the Exception was modified.
ModifiedBy
An object detailing the last user to modify the Exception. It includes the following fields:
• id: The unique ID of the user who modified the Exception.
• login: The email address of the user who modified the Exception.
OperatingSystems
An object detailing the operating systems that the Exception can be applied to. It will include the
“name” field. This can consist of:
• “Windows”
• “MacOS”
PolicyCount
The number of policies that have the Exception applied.
RulesetCount
The number of Detection Rule Sets that have the Exception enabled.
Version
The version of the Exception.
Get Detection Exception Content
Allows a caller to retrieve the content of an Exception in its native JSON structure. The structure of CylanceOPTICS Exception
Rules is beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine Custom Rule Guide for a more
detailed explanation. The underlying logic extracts from the JWT specified as the Bearer value in the Authorization request
header the tenant's unique identifier to associate the Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2/{exception_id}
US Government: https://protectapi.us.cylance.com/exceptions/v2/{exception_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2/{exception_id}
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:read scope encoded.
Request None
Response
200 OK
Get Detection Exception Content Response Schema
{
"Id": "631015e5…",
"Name": "My Exception",
"Description": "My Exception Description",
"ObjectType": "ExceptionRule",
CylanceOPTICS API Guide – v2.0 rev2 Page 82 of 133
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "UnsignedProc",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "iexplore.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
"Tags": [
"CylanceOPTICS, Exception"
],
"Version": 1
CylanceOPTICS API Guide – v2.0 rev2 Page 83 of 133
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such exception found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the entirety of the Exception logic. This schema is similar to that of the CylanceOPTICS
Context Analysis Engine rules which are further explained in the ‘CylanceOPTICS Context Analysis Engine Custom Rules Guide’ KB
Article.
Get Detection Exceptions CSV List
Allows a caller to retrieve a CSV where every line represents an Exception rule available in the tenant. The underlying logic
extracts from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to
associate the Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2/csv
US Government: https://protectapi.us.cylance.com/exceptions/v2/csv
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2/csv
Method HTTP/1.1 GET
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:list scope encoded.
Request None
Response
200 OK – Will initiate a CSV file download.
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
CylanceOPTICS API Guide – v2.0 rev2 Page 84 of 133
CylanceOPTICS API Guide – v2.0 rev2 Page 85 of 133
The response CSV contains the following fields:
Field Name Description
Name
The name of the Exception.
Id
The unique ID of the Exception.
Version
The version of the Exception.
Description
The description of the Exception.
Last Modified
The timestamp (in UTC) of the last time that the Exception was modified.
Modified By
The email address of the user who last modified the Exception.
Device Count
The number of devices that have the Exception applied.
Ruleset Count
The number of Detection Rule Sets that have the Exception enabled.
Create Detection Exception
Allows a caller to create a new Detection Exception by sending the native JSON structure of a Detection Exception. The structure
of CylanceOPTICS Exception Rules is beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine
Custom Rule Guide knowledge base article for a more detailed explanation. The underlying logic extracts from the JWT specified
as the Bearer value in the Authorization request header the tenant's unique identifier to associate the Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2
US Government: https://protectapi.us.cylance.com/exceptions/v2
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:create scope encoded.
Request
Post Detection Exception Content Request Schema
{
"Name": "My Exception",
"Description": "My Exception Description",
"ObjectType": "ExceptionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
CylanceOPTICS API Guide – v2.0 rev2 Page 86 of 133
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "UnsignedProc",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "iexplore.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
"Tags": [
"CylanceOPTICS, Exception"
]
}
Response
202 OK – ExceptionRule created successfully.
Post Detection Exception Content Response Schema
{
"Id": "631015e5…",
"Name": "My Exception",
"Description": "My Exception Description",
CylanceOPTICS API Guide – v2.0 rev2 Page 87 of 133
"ObjectType": "ExceptionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "UnsignedProc",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "iexplore.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
"Tags": [
"CylanceOPTICS, Exception"
],
CylanceOPTICS API Guide – v2.0 rev2 Page 88 of 133
"Version": 1
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the entirety of the Exception logic. This schema is similar to that of the CylanceOPTICS
Context Analysis Engine rules which are further explained in the CylanceOPTICS Context Analysis Engine Custom Rule Guide
knowledge base article.
Note that the ‘id’ and ‘version’ fields are automatically populated when the request is submitted.
Update Detection Exception
Allows a caller to update a Detection Exception by sending a new JSON structure. The structure of CylanceOPTICS Exception
Rules is beyond the scope of this document. Refer to the CylanceOPTICS Context Analysis Engine Custom Rule Guide for a more
detailed explanation. The underlying logic extracts from the JWT specified as the Bearer value in the Authorization request
header the tenant's unique identifier to associate the Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2/{exception_id}
US Government: https://protectapi.us.cylance.com/exceptions/v2/{exception_id}
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2/{exception_id}
Method HTTP/1.1 PUT
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:update scope encoded.
Request
Update Detection Exception Content Request Schema
{
"Name": "My Exception",
"Description": "My Exception Description",
"ObjectType": "ExceptionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
CylanceOPTICS API Guide – v2.0 rev2 Page 89 of 133
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "UnsignedProc",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "my_application.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
"Tags": [
"CylanceOPTICS, Exception"
]
}
Response
202 OK – ExceptionRule created successfully.
Update Detection Exception Content Response Schema
{
CylanceOPTICS API Guide – v2.0 rev2 Page 90 of 133
"Id": "631015e5…",
"Name": "My Exception",
"Description": "My Exception Description",
"ObjectType": "ExceptionRule",
"OperatingSystems": [
{
"Name": "Windows"
}
],
"Plugin": {
"Name": "OpticsDetector"
},
"Product": {
"Name": "CylanceOPTICS"
},
"SchemaVersion": 1,
"States": [
{
"Name": "UnsignedProc",
"Scope": "Global",
"Function": "Function",
"FieldOperators": {
"Function": {
"Type": "EqualsAny",
"Operands": [
{
"Source": "LiteralSet",
"Data": "my_application.exe"
}
],
"OperandType": "string",
"Options": {
"IgnoreCase": true
}
}
},
"Actions": [
{
"Type": "AOI",
"ItemName": "InstigatingProcess",
"Postiion": "PostActivation"
}
]
}
],
CylanceOPTICS API Guide – v2.0 rev2 Page 91 of 133
"Tags": [
"CylanceOPTICS, Exception"
],
"Version": 2
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such Exception found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the entirety of the Exception logic. This schema is similar to that of the CylanceOPTICS
Context Analysis Engine rules which are further explained in the CylanceOPTICS Context Analysis Engine Custom Rule Guide
knowledge base article.
Note that the ‘id’ and ‘version’ fields are automatically populated when the request is submitted.
Deactivate / Delete Detection Exception
Allows a caller to ‘soft delete’ a Detection Exception and remove it from Detection Rule Sets. The underlying logic extracts from
the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the
Exception resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/exceptions/v2/{exception_id}/deactivate
US Government: https://protectapi.us.cylance.com/exceptions/v2/{exception_id}/deactivate
All Other Regions: https://protectapi-{region-code}.cylance.com/exceptions/v2/{exception_id}/deactivate
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticsexception:update scope encoded.
Request None
CylanceOPTICS API Guide – v2.0 rev2 Page 92 of 133
Response
200 OK
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such resource found.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
Note that Detection Rule Sets are not automatically communicated to all endpoints when updates to Detection Exceptions are
made. To ensure that the latest logic is applied to endpoints in the quickest manner, re-save any affected Detection Rule Sets
(either via the UI or API.)
CylanceOPTICS Device Commands
The CylanceOPTICS Device Commands API allows users to perform actions on the endpoint. For example, locking down an
endpoint or retrieving a file from an endpoint.
The CylanceOPTICS Device Commands API includes:
• Locking down an endpoint
• Getting Device Lockdown History for a tenant
• Requesting a file retrieval from an endpoint
• Checking the file retrieval status for an endpoint
• Getting the retrieved file results
Note: This addendum only covers CylanceOPTICS Device Commands API information. Read the Cylance User API guide for
configuration information.
CylanceOPTICS API Guide – v2.0 rev2 Page 93 of 133
Lockdown Device Command
Allows a caller to create a CylanceOPTICS device lockdown command resource for a specific device. The underlying logic extracts
from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the
device lockdown command resource with.
Service
Endpoint
North America:
https://protectapi.cylance.com/devicecommands/v2/{deviceID}/lockdown?value=true&expires=d
US Government:
https://protectapi.us.cylance.com/devicecommands/v2/{deviceID}/lockdown?value=true&expires=d
All Other Regions: https://protectapi-{region-
code}.cylance.com/devicecommands/v2/{deviceID}/lockdown?value=true&expires=d
Method HTTP/1.1 PUT
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticscommand:create scope encoded.
Request
Append the following optional query string parameters:
• value: Whether to lockdown or not. Default to true.
• expires: Duration of the lockdown. Format: ‘d:hh:mm’.
o Maximum: 3 days.
o Minimum: 5 minutes.
Response
201 OK – Command created
Put Lockdown Command Response Schema
{
"id": "DEVICE_ID",
"hostname": "TEST_HOST",
"tenant_id": "TENANT_ID",
"connection_status": "connected",
"optics_device_version": "2.1.1000.478",
"password": "foo",
"lockdown_expiration": "2016-01-01T00:00:00Z",
"lockdown_initiated": "2016-01-01T00:00:00Z",
"lockdown_history": [
{
"user_id": "USER_ID",
"timestamp": "2016-01-01T00:00:00Z",
"command": "ClearLockdown"
}
]
}
CylanceOPTICS API Guide – v2.0 rev2 Page 94 of 133
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such device.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
The response JSON schema contains the following fields:
Field Name Description
id
The unique device ID that the lockdown command was issued to.
hostname
The hostname of the device that the lockdown command was issued to.
tenant_id
The unique tenant ID of the tenant that the device belongs to.
connection_status
Displays whether or not the device is connected to Cylance’s cloud services.
optics_device_version
Returns the numerical version of CylanceOPTICS that the device is running.
password
The password required to unlock the device.
lockdown_expiration
The timestamp (in UTC) of when the current device lockdown is set to expire.
lockdown_initiated
The timestamp (in UTC) of when the current device lockdown was initiated.
lockdown_history
A list of historical device lockdown commands issued to a particular device.
user_id
The unique ID of the user who locked down the device.
timestamp
The timestamp (in UTC) of when the command was initiated.
command
The command that was executed.
Get Device Lockdown History
Allows a caller to request the current lockdown state and lockdown history for a specific device. The underlying logic extracts
from the JWT specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the
device lockdown command resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/devicecommands/v2/{deviceID}/lockdown
US Government: https://protectapi.us.cylance.com/devicecommands/v2/{deviceID}/lockdown
All Other Regions: https://protectapi-{region-code}.cylance.com/devicecommands/v2/{deviceID}/lockdown
Method HTTP/1.1 GET
CylanceOPTICS API Guide – v2.0 rev2 Page 95 of 133
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticscommand:read scope encoded.
Request None
Response
200 OK
Get Lockdown Status and History Response Schema
{
"id": "DEVICE_ID",
"hostname": "TEST_HOST",
"tenant_id": "TENANT_ID",
"connection_status": "connected",
"optics_device_version": "2.1.1000.478",
"password": "foo",
"lockdown_expiration": "2016-01-01T00:00:00Z",
"lockdown_initiated": "2016-01-01T00:00:00Z",
"lockdown_history": [
{
"user_id": "USER_ID",
"timestamp": "2016-01-01T00:00:00Z",
"command": "ClearLockdown"
}
]
}
400 Bad Request – Malformed request.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 Not Found – No such device.
500 InternalServerError – An unforeseeable error has occurred.
503 Service unavailable – Please try again later.
CylanceOPTICS API Guide – v2.0 rev2 Page 96 of 133
The response JSON schema contains the following fields:
Field Name Description
id
The unique device ID that the lockdown command was issued to.
hostname
The hostname of the device that the lockdown command was issued to.
tenant_id
The unique tenant ID of the tenant that the device belongs to.
connection_status
Displays whether or not the device is connected to Cylance’s cloud services.
optics_device_version
Returns the numerical version of CylanceOPTICS that the device is running.
password
The password required to unlock the device.
lockdown_expiration
The timestamp (in UTC) of when the current device lockdown is set to expire.
lockdown_initiated
The timestamp (in UTC) of when the current device lockdown was initiated.
lockdown_history
A list of historical device lockdown commands issued to a particular device.
user_id
The unique ID of the user who locked down the device.
timestamp
The timestamp (in UTC) of when the command was initiated.
command
The command that was executed.
Request File Retrieval from Device
Allows a caller to request that the specified file be retrieved from a specified device and stored in Cylance’s cloud console for
later analysis. The underlying logic extracts from the JWT specified as the Bearer value in the Authorization request header the
tenant's unique identifier to associate the file retrieval command resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/devicecommands/v2/{deviceID}/getfile
US Government: https://protectapi.us.cylance.com/devicecommands/v2/{deviceID}/getfile
All Other Regions: https://protectapi-{region-code}.cylance.com/devicecommands/v2/{deviceID}/getfile
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticscommand:read scope encoded.
Request
Get Request File Retrieval Request Schema
{
“file_path”: “C:\path\to\file.txt”
}
CylanceOPTICS API Guide – v2.0 rev2 Page 97 of 133
Response
200 OK
Get Request File Retrieval Response Schema
{
"data": {
"tenant_id": "TENANT_ID",
"user_id": "USER_ID",
"device_id": "DEVICE_ID",
"created_at": "2017-01-01T00:00:00Z",
"filepath": "REQUESTED_FILE_PATH",
"download_url": "UNIQUE_URL”
"file_status": "PENDING",
"file_status_description": "Too Large | Does Not Exist",
"password": "foo",
"md5": "d41d8cd98f00b204e9800998ecf8427e",
"sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"correlation_id": "00000000000000000000000000000000",
"user_login": "test@cylance.com",
"hostname": "Test-PC"
}
}
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 are less than or equal to zero.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The requested device does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Server Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
data
An object containing the various fields associated with the file retrieval request.
tenant_id
The unique ID of the tenant associated with the file retrieval request.
user_id
The unique ID of the user who requested the file retrieval.
CylanceOPTICS API Guide – v2.0 rev2 Page 98 of 133
device_id
The unique ID of the device that the file retrieval was requested on.
created_at
The timestamp (in UTC) of when the file retrieval was requested.
filepath
The file path of the requested file.
download_url
The unique URL and parameters required to download the retrieved file.
file_status
The status of the file retrieval. This will always be “PENDING” for newly created file retrievals.
file_status_description
Displays any errors or status messages associated with the retrieval request.
password
The password required to decrypt the retrieved file.
md5
The MD5 hash of the retrieved file.
sha1
The SHA1 hash of the retrieved fie.
sha256
The SHA256 hash of the retrieved file.
correlation_id
The correlation ID associated with this action.
user_login
The email address of the user who initiated the file retrieval request
hostname
The hostname of the device that the file retrieval was requested on.
Check File Retrieval Status from Device
Allows a caller to check the status of a previously requested file retrieval operation. The underlying logic extracts from the JWT
specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the file retrieval
command resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/devicecommands/v2/{deviceID}/getfile:get
US Government: https://protectapi.us.cylance.com/devicecommands/v2/{deviceID}/getfile:get
All Other Regions: https://protectapi-{region-code}.cylance.com/devicecommands/v2/{deviceID}/getfile:get
Method HTTP/1.1 POST
Request
Headers
Accept: application/json
Authorization: Bearer <JWT Token returned by Auth API> with the opticscommand:read scope encoded.
Request
Get File Retrieval Status Request Schema
{
“file_path”: “C:\path\to\file.txt”
}
Response
200 OK
Get File Retrieval Status Response Schema
{
"data": {
CylanceOPTICS API Guide – v2.0 rev2 Page 99 of 133
"tenant_id": "TENANT_ID",
"user_id": "USER_ID",
"device_id": "DEVICE_ID",
"created_at": "2017-01-01T00:00:00Z",
"filepath": "REQUESTED_FILE_PATH",
"download_url": " UNIQUE_URL”
"file_status": "REQUEST | RETRY_REQUEST | PENDING | AVAILABLE | UNAVAILABLE | DOES_NOT_EXIST",
"file_status_description": "Too Large | Does Not Exist",
"password": "foo",
"md5": "d41d8cd98f00b204e9800998ecf8427e",
"sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"correlation_id": "00000000000000000000000000000000",
"user_login": "test@cylance.com",
"hostname": "Test-PC"
}
}
400 BadRequest – Returned for the following reasons:
• The Tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The unique identifier for the detection is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The InstaQuery resource does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
data
An object containing the various fields associated with the file retrieval request.
tenant_id
The unique ID of the tenant associated with the file retrieval request.
user_id
The unique ID of the user who requested the file retrieval.
device_id
The unique ID of the device that the file retrieval was requested on.
created_at
The timestamp (in UTC) of when the file retrieval was requested.
filepath
The file path of the requested file.
CylanceOPTICS API Guide – v2.0 rev2 Page 100 of 133
download_url
The unique URL and parameters required to download the retrieved file.
file_status
The status of the file retrieval. Possible values are:
• REQUEST: The file retrieval has not been requested, but the user may issue a request
for it.
• RETRY_REQUEST: The file retrieval has been requested previously but no results were
received. It can be requested again.
• PENDING: The file retrieval has been requested but has not yet been completed.
• DOES_NOT_EXIST: The file retrieval has been requested but is not present on the
device.
• AVAILABLE: The file is available for download. A download link (found in the
download_url field) is generated and valid for the next 10 minutes.
• UNAVAILABLE: The file is not available. This status may indicate that the requested
device is not online, or the requested device failed to upload the file. This status will
become RETRY_REQUEST after an hour.
file_status_description
Displays any errors or status messages associated with the retrieval request.
password
The password required to decrypt the retrieved file.
md5
The MD5 hash of the retrieved file.
sha1
The SHA1 hash of the retrieved fie.
sha256
The SHA256 hash of the retrieved file.
correlation_id
The correlation ID associated with this action.
user_login
The email address of the user who initiated the file retrieval request
hostname
The hostname of the device that the file retrieval was requested on.
CylanceOPTICS API Guide – v2.0 rev2 Page 101 of 133
Get Retrieved Files Results
Allows a caller to obtain a history of file retrieval requests for all devices in the tenant. The underlying logic extracts from the JWT
specified as the Bearer value in the Authorization request header the tenant's unique identifier to associate the file retrieval
command resource with.
Service
Endpoint
North America: https://protectapi.cylance.com/devicecommands/v2/retrieved_files?page=m&page_size=n
US Government: https://protectapi.us.cylance.com/devicecommands/v2/ retrieved_files?page=m&page_size=n
All Other Regions: https://protectapi-{region-code}.cylance.com/devicecommands/v2
retrieved_files?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 opticscommand:read scope encoded.
Request
Append the following query string parameters:
• q: Case-insensitive search term.
• page: The page number to request. Defaults to 1.
• page_size: The number of file retrieval records to retrieve per page. Defaults to 20.
• sort: Sort by field (adding ‘-‘ in front of the value denotes descending order.)
Response
200 OK
Get Retrieved File Results Response Schema
[
{
"tenant_id": "TENANT_ID",
"user_id": "USER_ID",
"device_id": "DEVICE_ID",
"created_at": "2017-01-01T00:00:00Z",
"filepath": "REQUESTED_FILE_PATH”,
"download_url": "UNIQUE_URL”
"file_status": "REQUEST | RETRY_REQUEST | PENDING | AVAILABLE | UNAVAILABLE | DOES_NOT_EXIST",
"file_status_description": "Too Large | Does Not Exist",
"password": "foo",
"md5": "d41d8cd98f00b204e9800998ecf8427e",
"sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"correlation_id": "00000000000000000000000000000000",
"user_login": "test@cylance.com",
"hostname": "Test-PC"
}
]
CylanceOPTICS API Guide – v2.0 rev2 Page 102 of 133
400 BadRequest – Returned for the following reasons:
• The tenant ID could not be retrieved from the JWT token specified in the Authorization header.
• The unique identifier for the execution is not valid.
401 Unauthorized – The JWT token is not specified, has expired, or is otherwise invalid.
403 Forbidden – The JWT token did not contain the proper scope to perform this action.
404 NotFound – The InstaQuery resource does not exist.
500 InternalServerError – An unforeseeable error has occurred.
503 Service Unavailable – Unable to respond at this time, please retry later.
The response JSON schema contains the following fields:
Field Name Description
data
An object containing the various fields associated with the file retrieval request.
tenant_id
The unique ID of the tenant associated with the file retrieval request.
user_id
The unique ID of the user who requested the file retrieval.
device_id
The unique ID of the device that the file retrieval was requested on.
created_at
The timestamp (in UTC) of when the file retrieval was requested.
filepath
The file path of the requested file.
download_url
The unique URL and parameters required to download the retrieved file.
file_status
The status of the file retrieval. Possible values are:
• REQUEST: The file retrieval has not been requested, but the user may issue a request
for it.
• RETRY_REQUEST: The file retrieval has been requested previously but no results were
received. It can be requested again.
• PENDING: The file retrieval has been requested but has not yet been completed.
• DOES_NOT_EXIST: The file retrieval has been requested but is not present on the
device.
• AVAILABLE: The file is available for download. A download link (found in the
download_url field) is generated and valid for the next 10 minutes.
UNAVAILABLE: The file is not available. This status may indicate that the requested device is not
online, or the requested device failed to upload the file. This status will become
RETRY_REQUEST after an hour.
file_status_description
Displays any errors or status messages associated with