Skip Navigation

Update policy

Update an existing policy. The request contents for update policy are similar to create policy, except you must include the policy_id in the update policy request.
Service endpoint
/policies/v2
Optional query string parameters
Example
https://protectapi.cylance.com/policies/v2
Method
HTTP/1.1 PUT
Request headers
  • Content-Type: application/json
  • Authorization: Bearer
    JWT Token returned by Auth API
    with the policy:update scope encoded

Request

"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 you create a policy. Checksum 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.
device_class:
All device_class entries must be included in the request.
  • AndroidUSB 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
    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 is the device class containing 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.
  • VMWareMoun: is the
    VMware
    USB Passthrough, which allows a
    VMware
    virtual machine client to access USB devices connected to the host.
  • WPD is a
    Windows
    portable device, which uses the
    Microsoft Windows
    portable device driver technology, such as mobile phones, digital cameras, and portable media players.
exclusion_list: Device control exclusion list allows or blocks access to specific USB mass storage devices.
  • comment: This is optional information about why the exclusion was added.
  • control_mode: Allows or blocks the specific USB mass storage device.
    • Block does not allow the USB mass storage device from connecting to the endpoint.
    • FullAccess 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). For example:
"exclusion_list": [ { "vendor_id": "1234", "comment": "Test device control exclusion", "serial_number": 987654321", "product_id": "5678", "control_mode": "FullAccess" } ]
file_exclusions
This setting 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 the 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: Tis is the reason the file was excluded. This information is required.
Example:
"file_exclusions": [ { "reason": "Test Exclusion", "category_id": "2", "md5": "d41d8cd98f00b204e9800998ecf8427e", "file_hash": "bf17366ee3bb8068a9ad70fc9e68 496e7e311a055bf4ffeeff53cc5d29ccce52", "file_name": "filename" } ]
filetype_actions
This setting is used for the auto-quarantine of unsafe (threat_files) and abnormal (suspicious_files).
  • actions: This is the setting to enable or disable auto quarantine and auto upload.
    • 0 - auto-quarantine OFF, auto-upload OFF
    • 1 - auto-quarantine ON, auto-upload OFF
    • 2 - auto-quarantine OFF, auto-upload ON
    • 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: These are abnormal files.
  • threat_files: These are unsafe files.
Examples of filetype_actions settings and the results in the management console.
filetype_actions settings
Management console results
threat_files
suspicious_files
Unsafe auto-quarantine
Abnormal auto-quarantine
Auto upload
0
0
No
n/a
No
2
2
No
n/a
Yes
1
0
Yes
No
No
3
2
Yes
No
Yes
1
1
Yes
Yes
No
3
3
Yes
Yes
Yes
logpolicy
These are the agent log file settings.
  • log_upload: 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. All memory_violations and memory_violations_ext entries must be included in the Request. 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 Injection): An environment variable has been set that will cause a shared library to be injected into a launched process. Attacks can modify the plist of applications like Safari or replace applications with bash scripts, causing their modules to be loaded automatically when an application starts.
  • 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.
Example:
"memory_exclusion_list_v2": [ "\\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_contro: 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 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). 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.
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 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. The name must be unique to your tenant.
script_control
These are the policy settings for script control. script_control must be enabled (set to "1") under policy.
activescript_settings
  • control_mode: These are the settings 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: These are 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 higher). 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 sgent 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 settings 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. Value can either be 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
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.