Skip Navigation
  1. BlackBerry Docs
  2. Cylance Endpoint Security
  3. CylancePROTECT Desktop Upgrade
  4. Upgrading to CylancePROTECT Desktop 3.x
  5. Configure and test macro detection (Windows only)
  6. Migrate script control macro exclusions to the new memory protection configuration (Windows only)

Migrate script control macro exclusions to the new memory protection configuration (
Windows
 only)

If you previously added macro exclusions on the Script Control tab of your device policies, you must migrate those exclusions to the new memory protection configuration for
CylancePROTECT Desktop
 for
Windows
 3.x. If you want to migrate the script control exclusions manually, you can simply record the exclusions you added on the Script Control tab of your device policies, then add the same exclusions on the Memory Actions tab in your device policies.
Follow the steps below if you want to migrate the existing script control exclusions using a PowerShell script that
BlackBerry
 provides.
The steps below apply to tenants managed using the
Cylance
 console. If you manage tenants using the Multi-Tenant Console, see KB 92149.
  • Verify that PowerShell is installed on your computer and that PowerShell scripts are not blocked by security software, including
    CylancePROTECT Desktop
    . If
    CylancePROTECT Desktop
     is installed on your computer, in the device policy assigned to your device, verify that
    Script Control > Block PowerShell console usage
     is turned off.
  • In the
    Cylance
     console, add an integration with the following API privileges and record the resulting application ID and secret:
    • Policies
      : Read, Modify
    • Users
      : Read
  • In
    Settings > Integrations
    , record the
    Tenant ID
    .
  • When you run the script, you will specify the email address of a
    Cylance
     console administrator account. Verify that the account that you want to use has the Administrator role.
  • In the device policies where you want to migrate exclusions from script control to memory protection, verify that script control is enabled and that macro exclusions are present.
    • The script will ignore policies with script control disabled and policies that do not have any script control exclusions.
    • The script does not migrate exclusion lists with multibyte characters. You must add these exclusions manually.
  1. Open a PowerShell command prompt and change the directory to the location of the script.
  2. Run the script using the appropriate parameters from the table below.
    • Run the script in
      -dryRun
       mode first to preview the migration without making any changes. This will produce an output file that you can use to identify and correct any issues.
    • Run the script for the specific device policies that you plan to use for testing. After your testing and validation of the 3.x agent, you can use the script to apply the migration to your production device policies.
    Parameter
    Required or optional
    Description
    -copySCExclusions
    Required
    This command executes the migration of macro exclusions from the script control configuration to the new memory protection configuration.
    -allPolicies
    OR
    -policy ‘
    <policy_name>
    ’
    Required
    -allPolicies
     executes the migration for all device policies in your tenant.
    -policy ‘
    <policy_name>’
    '
     executes the migration for a specified device policy.
    -dryRun
    Optional
    This command previews the execution of the script without making any changes. When you run the script in this mode, it creates an output file in the directory that the script is executed from.
    -tenantId ‘
    <tenant_ID>
    ’
    Required
    This command specifies the ID of your
    Cylance Endpoint Security
     tenant.
    -apiKey ‘
    <application_ID>
    ’
    Required
    This command specifies the application ID of the integration that you added in Settings > Integrations.
    -apiSecret ‘
    <application_secret>
    ’
    Required
    This command specifies the application secret of the integration that you added in Settings > Integrations.
    -userEmail ‘
    <admin_email>
    ’
    Required
    This command specifies the email address of the
    Cylance
     console administrator account that you want to use to execute the migration. The account must have the Administrator role.
    -region ‘
    <region_code>
    ’
    Required
    This command specifies the region of your
    Cylance Endpoint Security
     tenant. Use one of the following values:
    • North America:
      na
       (default value if not specified)
    • Japan:
      apne1
    • Australia:
      au
    • Europe:
      euc1
    • South America:
      sae1
    • GovCloud:
      us
    -Ignore158xWarning
    Optional
    This command makes the migration process ignore errors related to the size limit for memory protection exclusions, which has been increased from 64 KB for older versions of
    CylancePROTECT Desktop
     to 2 MB for version 3.x.
    Use this parameter only if all devices that are associated with the target device policy use agent 3.x or later.
    -ignore158xCompatibility
    Optional
    This command is related to a specific defect with
    CylancePROTECT Desktop
     for
    Windows
     2.1.1580 and 1584 (see KB 88218). The fix for the defect (adding an additional asterisk(*) to the wildcard value in an exclusion path to make the wildcard **) is built into the script by default. If you use this parameter, the fix that is built into the script is disabled.
    Use this parameter if the target device policy is associated with devices with agent 1578 or earlier and devices with agent 3.x or later. If the policy is associated with any devices with agent 158x, do not use this parameter.
    -includeExtensions
    <extensions>
    Optional
    This command specifies the extensions to migrate to the memory protection configuration (for example, -
    includeExtensions ps1, ja, xlxs
    ).
    If you don’t use this parameter, all extensions are migrated.
When you run the script in
-dryRun
 mode, you may encounter the following error in the output file: “Entering Modify '
<policy_name>
' Policy... logError : The requested policy has not been converted to MemoryProtection v2.” This can occur if a device policy has not been edited for some time. To resolve this issue, in the management console, open and save the policy.
The PowerShell output will indicate if any script control exclusions could not be migrated. You must add these exclusions to the memory protection configuration manually.
Example: Run the script in -dryRun mode
.\sc2memdef_copy.ps1 -copySCExclusions -allPolicies -dryRun -tenantId '00000000-0000-0000-0000-000000000000' -apiKey '00000000-0000-0000-0000-000000000000' -apiSecret '00000000-0000-0000-0000-000000000000' -userEmail 'user@blackberry.com' -region 'na'
Example: Run the script for a specific device policy
.\sc2memdef_copy.ps1 -copySCExclusions -policy 'userPolicy' -tenantId '00000000-0000-0000-0000-000000000000' -apiKey '00000000-0000-0000-0000-000000000000' -apiSecret '00000000-0000-0000-0000-000000000000' -userEmail 'user@blackberry.com' -region 'na'
Example: Run the script for all device policies
.\sc2memdef_copy.ps1 -copySCExclusions -allPolicies -tenantId '00000000-0000-0000-0000-000000000000' -apiKey '00000000-0000-0000-0000-000000000000' -apiSecret '00000000-0000-0000-0000-000000000000' -userEmail 'user@blackberry.com' -region 'na'
  • On the Memory Actions tab of the target device policies, check the migrated exclusions and delete any that do not apply to the new Dangerous VBA Macro violation type.
  • Delete the PowerShell integration that you added to the management console.