Skip Navigation
  1. BlackBerry Docs
  2. Cylance Endpoint Security
  3. Cylance User API guide
  4. Policy API
  5. Get policy

Get policy

Get details for a policy, using the policy ID.
Service endpoint
/policies/v2/{policy_id}
Optional query string parameters
—
Example
https://protectapi.cylance.com/policies/v2/d5c6d6a3-0599-4fb5-96bc-0fdc7eacb6ea
Method
HTTP/1.1 GET
Request headers
  • Accept: application/json
  • Authorization: Bearer
    JWT Token returned by Auth API
     with the policy:read scope encoded

Request

None

Response

Please see the Response status codes for more information.

Response JSON schema

Field Name
Description
appcontrol
Application control allows restricting any changes to applications on a device. Only the applications that exist on a device before enabling application control are allowed to execute on that device. Any new applications, as well as changes to the executables of existing applications, will be denied.
The agent updater will also be disabled when application control is enabled.
  • Allowed_folders: allows applications and additions to the specified folders. It must be an absolute path (for example, c:\temp_appcontrol)
  • Changewindow_enabled:
    • 0 - Closed: No changes can be made to any applications on the device.
    • 1 - Open: Allow, edit, and run new applications on the device. This includes updating applications.
  • Lockdown:
    • Action:
      • The deny action blocks (denies) the lockdown_type.
    • Lockdown_type:
      • Executionfromexternaldrives indicates execution of a file from an external drive, like a USB hard drive or USB flash drive.
      • pechange indicates changes made to existing applications on the device.
checksum
Checksum is used to detect errors that may have occurred during transmission or storage of data.
device_control
Device control
  • control_mode:
    • Block does not allow the selected device_class to connect to the device.
    • FullAccess allows the selected device_class to connect to the device.
  • device_class:
    • AndroidUSB is a portable device running Android OS, like a smartphone or tablet.An Android device could connect and be identified as Android, Still Image, or Windows Portable Device (WPD). When blocking Android devices, consider also blocking Still Image and Windows Portable Devices.
    • iOS 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 iOS device is powered off. Apple includes their charging capability within functions of the device that are required for our iOS device blocking capability.
    • StillImage is the device class that includes scanners, digital cameras, multi-mode video cameras with frame capture, and frame grabbers.
    • USBCDDVDRW is a USB optical drive.
    • USBDrive is a USB hard drive or USB flash drive.
    • VMWareMount is the VMware USB Passthrough that allows a VMware virtual machine client to access USB devices connected to the host.
    • WPD is a portable device that uses the
      Microsoft Windows
       Portable Device (WPD) driver technology, such as a mobile phone, digital camera, and portable media players.
  • exclusion_list: These are control exclusions that allow full access or block connecting a USB device. The vendor_id is required.
    • comment: This is optional information about why the exclusion was added.
    • control_mode:
      • Block: does not allow the specified vendor_id from connecting to the device.
      • FullAccess: allows the specified vendor_id to connect to the device.
    • date_added: This is the date and time the device control exclusion was added to the policy.
    • product_id: Some manufacturers provide a unique identifier for each USB product they make. This information is optional.
    • serial_number: Some manufacturers provide a unique serial number for each USB device they make. This information is optional.
    • vendor_id: This is the unique identifier for the manufacturer of the USB device.
file_exclusions
The policy safe list identifies file exclusions specific to the policy, and any devices assigned to the policy will allow the excluded files to run.
  • av_industry:
    • false: The file hash has not been identified by the anti-virus industry.
    • true: The file hash has been identified by the anti-virus industry.
  • category_id: This is the category selected when adding the file to the policy safe list.
    • 1 = None
    • 2 = Admin Tool
    • 3 = Internal Application
    • 4 = Commercial Software
    • 5 = Operating System
    • 6 = Drivers
    • 7 = Security Software
  • cloud_score: This is the
    Cylance
     Score displayed in the console. The score can go up to 100.
  • file_hash: This is the SHA256 has for the file. This information is required.
  • file_name: This is the name of the file. This is "null" if the filename is not available.
  • file_type: This is the file scanner type. Should always return
    1
     for executable.
  • infinity: This is the
    Cylance
     Cloud score. This is "null" if no score is available.
  • md5: This is the MD5 hash for the file. This information is optional.
  • reason: This is the reason for adding the file to the policy safe list. The reason must be added when creating the file exclusion.
  • research_class_id: This is the
    Cylance
     threat classification. If "infinity" is null, then the research_class_id is not available.
    • 1 = Trusted
    • 2 = PUP
    • 3 = Malware
    • 4 = File Unavailable
    • 5 = Possible PUP
    • 6 = Dual Use
  • research_subclass_id: Some threat classification have sub-classes to help administrators determine if a file should be blocked or allowed to run. See Threat classifications for more information.
filetype_actions
These actions indicate the autoquarantine of unsafe and abnormal files.
  • actions: This is the setting to enable or disable auto quarantine and auto upload.
    • 0 - AutoQuarantine OFF and AutoUpload OFF
    • 1 - AutoQuarantine ON and AutoUpload OFF
    • 2 - AutoQuarantine OFF and AutoUpload ON
    • 3 - AutoQuarantine ON and AutoUpload ON
  • file_type: The only option is "executable".
  • suspicious_files: These are abnormal files.
  • threat_files: These are unsafe files.
logpolicy
These are the Agent log file settings.
  • log_upload: This is the setting to enable or disable uploading log files.
    • null: Disabled
    • 1: Enabled
  • maxlogsize: This is the maximum file size (in MB) for a single log file.
  • retentiondays: This is the number of days to save 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_violation_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_exclusion
_list_v2
These are the executable files to exclude from memory protection. This must be a relative path to the excluded executable file (for example: \\temp).
policy
Various policy settings are contained within this section. All policy settings must be included in the request. 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
  • 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 is the setting 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 children 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).
    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.
    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.
    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 settingto 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 the setting the maximum amount of device storage reserved for use by
    CylanceOPTICS
    , in MB. The minimum value is 500 and the maximum value is 1000.
    Example: 
    {
    "name": "optics_set_disk_usage_maximum_fixed",
    "value": "1000"
}
  • 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_id
This is the unique identifier for the policy.
policy_name
This is the name of the policy.
policy_utctimestamp
This is the date and time the policy was created (in UTC).
script_control
These are the Script Control settings in a policy.
  • activescript_settings:
    • control_mode: This setting allows or blocks ActiveScript usage.
      • Allow
      • Block
  • global_settings:
    • allowed_folders: This setting specifies folder exclusions, including subfolders, for script control. This setting specifies a relative path.
    • control_mode: This setting allows or blocks ActiveScript and PowerShell usage with Agent 1370 or lower.
      • Allow
      • Block
  • macro_settings:
    • control_mode: This setting allows or blocks Macro usage.
      Microsoft
       Office macros use Visual Basic for Applications (VBA).
      • Allow
      • Block
      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: This setting allows or blocks the PowerShell console. This affects PowerShell command usage, including PowerShell one-liners.
      • Allow
      • Block
    • control_mode: This setting allows or blocks PowerShell usage.
      • Allow
      • Block