Migrate script control macro exclusions to the new memory protection configuration
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
Windows3.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
- Verify that PowerShell is installed on your computer and that PowerShell scripts are not blocked by security software, includingCylancePROTECT Desktop. IfCylancePROTECT Desktopis installed on your computer, in the device policy assigned to your device, verify thatScript Control > Block PowerShell console usageis turned off.
- In theCylanceconsole, add an integration with the following API privileges and record the resulting application ID and secret:
- Policies: Read, Modify
- Users: Read
- InSettings > Integrations, record theTenant ID.
- When you run the script, you will specify the email address of aCylanceconsole 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.
- Open a PowerShell command prompt and change the directory to the location of the script.
- Run the script using the appropriate parameters from the table below.
ParameterRequired or optionalDescription-copySCExclusionsRequiredThis command executes the migration of macro exclusions from the script control configuration to the new memory protection configuration.-allPoliciesOR-policy ‘<policy_name>’Required-allPoliciesexecutes the migration for all device policies in your tenant.-policy ‘executes the migration for a specified device policy.<policy_name>’'-dryRunOptionalThis 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>’RequiredThis command specifies the ID of yourCylance Endpoint Securitytenant.-apiKey ‘<application_ID>’RequiredThis command specifies the application ID of the integration that you added in Settings > Integrations.-apiSecret ‘<application_secret>’RequiredThis command specifies the application secret of the integration that you added in Settings > Integrations.-userEmail ‘<admin_email>’RequiredThis command specifies the email address of theCylanceconsole administrator account that you want to use to execute the migration. The account must have the Administrator role.-region ‘<region_code>’RequiredThis command specifies the region of yourCylance Endpoint Securitytenant. Use one of the following values:
- Run the script in-dryRunmode 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.
-Ignore158xWarningOptionalThis 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 ofCylancePROTECT Desktopto 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.-ignore158xCompatibilityOptionalThis command is related to a specific defect withCylancePROTECT DesktopforWindows2.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>OptionalThis 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.
- North America:na(default value if not specified)
- South America:sae1
When you run the script in
-dryRunmode, 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 'firstname.lastname@example.org' -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 'email@example.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 'firstname.lastname@example.org' -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.