Skip Navigation

Create policy

Service endpoint
/policies/v2
Optional query string parameters
Example
https://protectapi.cylance.com/policies/v2
Method
HTTP/1.1 POST
Request headers
  • Content-Type: application/json
  • Authorization: Bearer
    JWT Token returned by Auth API
    with the policy:create scope encoded.

Request

The following example creates a policy with most features enabled and includes some sample exclusions. You can copy this example, change the user_id, and this should create an example policy in your tenant.
This example is provided just for testing the API. Do not use this example policy on your devices. Device policies should be tested before applying to a large number of devices in your organization.
"policy_name": "testPolicy", "script_control": { "activescript_settings": { "control_mode": "Alert", "control_mode_v2":"BlockAbnormal" }, "global_settings": { "allowed_folders": ["/path.py"], "allowed_folders_ext": [ { "comment": "any test 200 chars long" } ], "control_mode": "Alert", "score_all_scripts": false, "upload_script_to_cloud": false, "must_obtain_score_from_cloud": false, "alert_suspicious_script_exec_only": false }, "macro_settings": { "control_mode": "Alert" }, "powershell_settings": { "control_mode": "Block", "console_mode": "Block", "control_mode_v2":"BlockAbnormal" } }

Response

Please see the Response status codes for more information.

Request JSON schema

Field Name
Description
checksum
Checksum is required when creating a policy. This uses an empty value.
Example:
"checksum": ""
device_control
Device Control allows or blocks access to USB mass storage devices. device_control must be enabled under
policy
.
All device_class entries must be included in the request.
  • AndroidUSB: This is a portable device running Android OS, like a smartphone or a tablet.
    An Android device could connect and be identified as Android, Still Image, or Windows Portable Device. If you want to block Android devices, consider blocking Still Image and Windows Portable Devices as well.
  • iOS: This is an Apple portable device running iOS, like an iPhone or iPad.
    iOS devices will not charge when Device Control is enabled and set to Block, unless the Apple device is powered off. Apple includes their charging capability within functions of the device that are required for our iOS device blocking capability. Non-Apple devices do not bundle their charging capability in this manner and are not impacted.
  • StillImage: This is the device class containing scanners, digital cameras, multi-mode video cameras with frame capture, and frame grabbers.
  • USBCDDVDRW:  This is a USB optical drive.
  • USBDrive: This is a USB hard drive or USB flash drive.
  • VMWareMount: This is a VMware USB Passthrough, which allows a VMware virtual machine client to access USB devices connected to the host.
  • WPD: This is a Windows Portable Device, which uses the Microsoft Windows Portable Device driver technology, such as mobile phones, digital cameras, and portable media players.
Device control exclusion list allows or blocks access to specific USB mass storage devices.
  • comment: This adds details about the exclusion. This information is optional.
  • control_mode: This allows or blocks the specific USB mass storage device.
    • Block: This does not allow the USB mass storage device from connecting to the endpoint.
    • FullAccess: This allows the USB mass storage device to connect to the endpoint.
  • product_id: This is the product identifier for the USB mass storage device. This information is optional.
  • serial_number: This is the serial number for the USB mass storage device. This information is optional.
  • vendor_id: This is the vendor identifier for the USB mass storage device. This information is required.
One way to find the Vendor ID for a USB mass storage device is to enable Device Control in a policy, assign that policy to an endpoint, then attach the USB mass storage device to the endpoint. You can view External Device logs in the management console, on the Protection page or the Device Details page (External Devices tab).
Example:
"exclusion_list": [ { "vendor_id": "1234", "comment": "Test device control exclusion", "serial_number": 987654321", "product_id": "5678", "control_mode": "FullAccess" } ]
file_exclusions
This adds file exclusions to the policy safe list, under file actions. Policy safe list are file exclusions specific to the policy, and any endpoints assigned to the policy will allow the excluded files to run.
  • category_id: This is a list of categories to identify the type of file. This information is optional.
    • 1 - None
    • 2 - AdminTool
    • 3 - InternalApplication
    • 4 - CommercialSoftware
    • 5 - OperatingSystem
    • 6 - Drivers
    • 7 - SecuritySoftware
  • file_hash: This is the SHA256 hash for the file. This information is required.
  • file_name: This is the name of the file being excluded. This information is optional.
  • md5: This is the MD5 hash for the file. This information is optional.
  • reason: This is the reason the file was excluded. This information is required.
Example:
"exclusion_list": [ { "reason": "Test Exclusion", "category_id": "2", "md5": "d41d8cd98f00b204e9800998ecf8427e", "file_hash": "bf17366ee3bb8068a9ad70fc9e68 496e7e311a055bf4ffeeff53cc5d29ccce52", "file_name": "filename" } ]
filetype_actions
These actions indicate the autoquarantine of unsafe and abnormal files.
  • actions: Set auto-quarantine and auto-upload to enable or disable.
    • 0: auto-quarantine OFF, auto-upload OFF
    • 1: auto-quarantine ON, auto-upload OFF\
    • 2: auto-quarantine OFF, auto-upload OFF
    • Use for suspicious_files when threat_files is set to 3 and Auto-Quarantine for suspicious_files is disabled.
    • 3: auto-quarantine ON, auto-upload ON
  • file_type: The only option is "executable".
  • suspicious_files: Abnormal files
  • threat_files: Unsafe files
logpolicy
These are the agent log file settings.
  • log_upload: This is the setting to enable or disable uploading agent log files.
    • null: Disabled
    • 1: Enabled
  • maxlogsize: This is the maximum file size (in MB) for a single agent log file.
  • retentiondays: This is the number of days to save agent log files. Log files older than the set number of days will be deleted.
memoryviolation
_actions
These are the violation types for memory protection. The following 3 rows explain the possible violation types:
memory_violations
  • lsassread (LSASS read): Memory belonging to the
    Windows
    Local Security Authority process has been accessed in a manner that indicates an attempt to obtain users' passwords.
  • outofprocessallocation (remote allocation of memory): A process has allocated memory in another process. Most allocations will only occur within the same process. This generally indicates an attempt to inject code or data into another process, which may be a first step in reinforcing a malicious presence on a system.
  • outofprocessapc (remote APC scheduled): A process has diverted the execution of another process’s thread. This is generally used by an attacker to activate a malicious presence that has been injected into another process.
  • outofprocesscreatethread (remote thread creation): A process has created a new thread in another process. A process’s threads are usually only created by that same process. This is generally used by an attacker to activate a malicious presence that has been injected into another process.
  • outofprocessmap (remote mapping of memory): A process has introduced code and/or data into another process. This may indicate an attempt to begin executing code in another process and thereby reinforce a malicious presence.
  • outofprocessoverwritecode (remote overwrite code): A process has modified executable memory in another process. Under normal conditions, executable memory will not be modified, especially by another process. This usually indicates an attempt to divert execution in another process.
  • outofprocessunmapmemory (remote unmap of memory): A process has removed a
    Windows
    executable from the memory of another process. This may indicate an intent to replace the executable image with a modified copy for the purpose of diverting execution.
  • outofprocesswrite (remote write to memory): A process has modified memory in another process. This is usually an attempt to store code or data in previously allocated memory (see OutOfProcessAllocation), but it is possible that an attacker is trying to overwrite existing memory in order to divert execution for a malicious purpose.
  • outofprocesswritepe (remote write PE to memory): A process has modified memory in another process to contain an executable image. Generally, this indicates that an attacker is attempting to execute code without first writing that code to disk.
  • overwritecode (overwrite code): The code residing in a process’s memory has been modified using a technique that may indicate an attempt to bypass Data Execution Prevention (DEP).
  • stackpivot (stack pivot): The stack for a thread has been replaced with a different stack. Generally, the system will only allocate a single stack for a thread. An attacker would use a different stack to control execution in a way that is not blocked by Data Execution Prevention (DEP).
  • stackprotect (stack protect): The memory protection of a thread’s stack has been modified to enable execution permission. Stack memory should not be executable, so usually this means that an attacker is preparing to run malicious code stored in stack memory as part of an exploit, an attempt which would otherwise be blocked by Data Execution Prevention (DEP).
memory_violations
_ext
  • dyldinjection (DYLD injections): An environment variable has been set that will cause a shared library to be injected into a launched process. Attacks can modify the plist of applications like Safari or replace applications with bash scripts, causing their modules to be loaded automatically when an application starts.
  • maliciouspayload (malicious payload): A generic shellcode and payload detection associated with exploitation has been detected.
  • trackdataread (RAM scraping): A process is trying to read valid magnetic stripe track data from another process. Typically related to point of sale systems (POS).
  • zeroallocate (zero allocate): A null page has been allocated. The memory region is typically reserved, but in certain circumstances, it can be allocated. Attacks can use this to setup privilege escalation by taking advantage of some known null de-reference exploit, typically in the kernel.
memory_violations
_ext_v2
  • childprocessprotect (Memory Permission Changes in Child Processes) - Windows only: A violating process has spawned a child process and has modified memory access permissions in that child process.
  • dangerouscomobject (Dangerous COM Object) - Windows only: A Malicious code that has a reference to a Component Object Model (COM) object has been detected.
  • dangerouseenvvariable (Dangerous Environment Variable) - Windows only:  An environment variable that may have malicious code attached has been detected.
  • directsyscall (Direct System Calls) - Windows only: Aan attempt to silently inject malicious code into other processes has been detected. This violation type cannot be blocked.
  • doppelganger (Doppelganger): A new (malicious) process was started from a file that has not yet been written to the file system. The file writer transaction is usually rolled back after the process start (so the malicious file is never committed to disk), and any attempt to scan the file on disk will only see the unmodified benign file.
  • maliciouslowintegrity (Low Integrity Process Start) - Windows only: A process has been set to run with a low integrity level.
  • oopprotect (Memory Permission Changes in Other Processes) - Windows only: A violating process has modified memory access permissions within another process. This is usually done to inject code into another process to make memory executable by modifying memory access permissions. There are few legitimate uses of this.
  • stolensystemtoken (Stolen System Token) - Windows only: An access token has been modified to allow a user to bypass security access controls.
  • syscallprobe (System Call Monitoring) - Windows only: A system call made to an application or operating system has been detected.
  • systemdllwrite (System DLL Overwrite) - Windows only: An attempt to overwrite a system DLL has been detected.
memory_exclusion
_list_v2
These are the executable files to exclude from Memory Protection. This must be a relative path to the excluded executable file.
Example:
"memory_exclusions_list_v2": [ { "violations": [], "path": "C:\\temp\\file1.txt" }, { "violations": [], "path": "C:\\temp\\file2.txt" } ]
policy
Various policy settings are contained within this section. Some policy settings are enabled under
policy
and configured in a different section, like device_control and logpolicy. For most policy settings, the possible values will be either 0 (disabled) or 1 (enabled). The remaining cells in this table explain policy settings in detail.
Automatic policy settings
  • auto_blocking: This is the setting to auto quarantine unsafe threats.
  • auto_delete: This is the setting to automatically delete quarantined files after a set number of days. If this feature is enabled, set "days_until_deleted" for the number of days to retain a quarantined file.
  • auto_uploading: This is the setting to automatically upload files that
    BlackBerry
    has not seen before.
    BlackBerry
    will perform an analysis on the file and provide details to assist in manual analysis and triage.
  • autoit_auto_uploading: This setting is currently not in use.
  • pdf_auto_uploading
  • powershell_auto_uploading
  • python_auto_uploading
Various policy settings
  • custom_thumbprint:
  • days_until_deleted: This is the setting for the number of days to retain a quarantined file. Quarantined files older than the set number of days will be automatically deleted. The minimum number of days is 14, the maximum number of days is 365. The "auto-delete" setting must be enabled.
  • device_control: This is the setting to enable or disable the device control feature.
  • docx_auto_uploading: This setting is currently not in use.
  • full_disc_scan: This is the setting to have
    Cylance
    analyze all executable files on disk to detect any dormant threats. This is the background threat detection setting.
    • 0: Disabled
    • 1: Run Recurring (performs a scan every nine days)
    • 2: Run Once (runs a full disk scan upon installation only)
  • kill_running_threats: This is the setting to kill processes and child processes regardless of the state when a threat is detected (EXE or DLL).
  • logpolicy: This setting is not used.
  • memory_exploit_detection: This is the setting to enable or disable the memory protection feature. This affects "memory_violation_actions" ("memory_violations" and "memory_violations_ext").
  • sample_copy_path: This is the setting to copy all file samples to a network share (CIFS/SMB). For Example:
    { "name": "sample_copy_path", "value": "\\\\server_name\\shared_folder" }
  • scan_exception_list: This is the setting to exclude specific folders and subfolders from being scanned by full_disc_scan and watch_for_new_files. Set the value to the absolute path for the excluded files. For example:
    { "name": "scan_exception_list", "value": [ "c:\\temp" ] }
  • scan_max_archive_size: This is the setting for the maximum archive file size (in MB) to be scanned. The value can be 0 to 150. If set to 0, then archive files will not be scanned. For example:
    { "name": "scan_max_archive_size", "value": "0" }
  • script_control: This is the setting to enable or disable the script control feature. Also set the script_control settings (see below in this table).
Various policy settings continued
  • show_notifications: This is the setting to enable or disable desktop notifications on the endpoint for
    CylancePROTECT Desktop
    events.
  • threat_report_limit: This is the number of threats to upload to the console.
    Example:
    { "name": "threat_report_limit", "value": "500" }
  • trust_files_in_scan_exception_list: This is the setting to allow execution of files in the excluded folders. This is related to the scan_exception_list.
  • watch_for_new_files: This is the setting to analyze new or modified executable files for threats.
  • ole_auto_uploading: This setting is currently not in use.
  • prevent_service_shutdown: This is the setting that protects the
    Cylance
    service from being shutdown, either manually or by another process.
  • sample_copy_path: This is the setting to copy all file samples to a network share (CIFS/SMB).
    Example:
    { "name": "sample_copy_path", "value": "\\\\server_name\\shared_folder" }
Optics policy settings
  • optics: This is the setting to enable or disable
    CylanceOPTICS
    .
  • optics_application_control_auto_upload: This is the setting to allow the automatic uploading of application control related focus data.
  • optics_malware_auto_upload: This is the setting to allow the automatic uploading of threat related focus data.
  • optics_memory_defense_auto_upload: This is the setting to allow the automatic uploading of memory protection related Focus Data.
  • optics_script_control_auto_upload: This is the setting to allow the automatic uploading of script control related focus data.
  • optics_sensors_advanced_executable_parsing: This is the setting to enable recording data fields associated with portable executable (PE) files, such as file version, import functions, and packer types. This is enhanced portable executable parsing in the policy settings.
  • optics_sensors_advanced_powershell_visibility: This is the setting to enable recording commands, arguments, scripts, and content entered directly into the Powershell Console and the Powershell Integrated Scripting Environment (ISE).
  • optics_sensors_advanced_wmi_visibility: This is the setting to enable recording additional Windows Management Instrumentation (WMI) attributes and parameters.
  • optics_sensors_dns_visibility: This is the setting to enable recording commands and arguments of commands issued directly or indirectly to the Windows Management Instrumentation (WMI) interpreter.
  • optics_sensors_enhanced_file_read_visibility: This is the setting to enable monitoring file reads within an identified set of directories.
  • optics_sensors_enhanced_process_hooking_visibility: This is the setting to enable recording process information from the Win32 API and Kernel Audit messages to detect forms of process hooking and injection.
  • optics_sensors_private_network_address_visibility: This is the setting to enable recording network connections within the RFC 1918 and RFC 3419 address spaces.
  • optics_sensors_windows_event_log_visibility: This is the setting to enable recording
    Windows
    Security Events and their associated attributes.
  • optics_set_disk_usage_maximum_fixed: This is used to set the maximum amount of device storage reserved for use by
    CylanceOPTICS
    , in MB. The minimum value is 500 and the maximum value is 1000.
    Example:
    { "name": "optics_set_disk_usage_maximum_fixed", "value": "1000" }
  • optics_show_notifications: This is the setting to enable or disable desktop notifications on the endpoint for
    CylanceOPTICS
    events.
  • optics_show_notification: This is the setting to enable or disable
    CylanceOPTICS
    desktop notifications on the device.
policy_name
This is the name of the policy. The name must be unique to your tenant.
script_control
The policy settings for script control. script_control must be enabled (set to "1") under policy.
activescript_settings
  • control_mode: These are the setting for active script.
    • Alert: The script is allowed to run and an alert is sent when an event occurs.
    • Block: The script is blocked and an alert is sent.
  • control_mode_v2:
    • Allow: The script is allowed to run.
    • Alert: The script is allowed to run and an alert is sent when an event occurs.
    • Block: The script is blocked and an alert is sent.
    • Block UNSAFE: The script will be scored and blocked if found to be unsafe.
    • Block ABNORMAL and UNSAFE: The script will be scored and blocked if found to be abnormal or unsafe.
global_settings
  • allowed_folders: The relative path to scripts that are allowed to run when script control is enabled. Script control folder exclusions apply to all agent versions (agent 1310 or later). For example:
    "allowed_folders": [ "\\temp_scriptcontrol" ]
  • control_mode: This is the setting to enable or disable script control for agent version 1370 or earlier. This works for active scripts and PowerShell. This does not work for macros. To use script control with macros, use agent version 1380 or later.
    • Allow: An alert is sent when an active script or PowerShell event occurs. The script is allowed to run.
    • Block: The active script or PowerShell is blocked and an alert is sent.
  • score_all_scripts: This boolean setting controls if all scripts are going to be scored, including scripts with the control_mode_v2 setting set to Alert or Block. Scripts with the setting set to Block UNSAFE or Block ANORMARL and UNSAFE will be scored automatically and this setting will be ignored.
  • upload_script_to_cloud: This boolean setting controls if all scripts will be uploaded to BlackBerry services when attempting to obtain the score of a script. If set to "false", Infinity will be searched to see if it already has the score. If it does not, the script will not be uploaded for scanning and will be assigned "UNSCORED".
  • must_obtain_score_from_cloud: This boolean setting allows you to forcefully obtain a score from Infinity before deciding what to do with a script execution. When a cached result is used, this setting will be ignored.
    • True: When a score can't be obtained from Infinity and control_mode_v2 = Block, Block UNSAFE, or Block ABNORMAL and UNSAFE, the state will be set to "UNSCORED" and "Block".
    • False: When a score can't be obtained from Infinity, the state will be combined with local classifiers and follow the control_mode_v2 setting. If the local classifier is not available, the score will be set to "UNSCORED".
  • alert_suspicious_script_exec_only: This boolean setting allows you to generate events only for scripts that are suspicious or were not evaluated.
macro_settings
  • control_mode: These are the setting for
    Microsoft Office
    macros.
    • Alert: An alert is sent when an
      Microsoft Office
      macro event occurs. The macro is allowed to run.
    • Block: The
      Microsoft Office
      macro is blocked and an alert is sent.
    The script control macros feature works with agent version 1578 and earlier. For newer agents, use the Dangerous VBA Macros violation type with memory protection. Any macro exclusions created for script control of newer agents must be added to the memory protection exclusions for the Dangerous VBA Macros violation type.
powershell_settings
  • console_mode: The PowerShell console is blocked to prevent PowerShell command usage, including one-liners. To use this feature, the PowerShell control_mode must be set to Block. Values can be either Allow or Block
  • control_mode:
    • Alert: The script is allowed to run and an alert is sent when an event occurs.
    • Block: The script is blocked and an alert is sent.
  • control_mode_v2:
    • Allow: The script is allowed to run.
    • Alert: The script is allowed to run and an alert is sent when an event occurs.
    • Block: The script is blocked and an alert is sent.
    • Block UNSAFE: The script will be scored and blocked if found to be unsafe.
    • Block ABNORMAL and UNSAFE: The script will be scored and blocked if found to be abnormal or unsafe.
script_control continued
About disabling script control
For Agent versions 1430 and later, you can disable script control for active script, PowerShell, or macros. Disabling script control allows the selected script type to run and does not send an alert to the console.
To disable script control for a specific script type, do not include the script type in the create policy API request. For example: script control for macros is disabled.
"script_control": { "global_settings": { "allowed_folders": null, "control_mode": "Alert", "score_all_scripts": false, "upload_script_to_cloud":true, "must_obtain_score_from_cloud":true, "alert_suspicious_script_exec_only": false }, "activescript_settings": { "control_mode": "Alert" "control_mode_v2":"Block UnSAFE" }, "powershell_settings": { "control_mode": "Alert", "console_mode": "Allow" "control_mode_v2":"Block UnSAFE" } }
user_id
This is the unique ID for the user creating the policy. Only administrators can create policies.
To get the user_id, use Get users.

Response JSON schema

This table only covers descriptions not covered in the Request JSON Schema Descriptions table (see previous table).
Field Name
Description
policy_id
This is the unique identifier for the policy.
policy_utctimestamp
This is the date and time (in UTC) when the policy was created.