Prepare to upgrade the module

Before you upgrade the module to a new version, learn about the new version and familiarize yourself with any updates that were implemented to comply with Center for Internet Security (CIS) Benchmarks. Then, test the upgrade in a non-production environment and troubleshoot any issues.

1. To learn about a new SCE release, review the Release notes for Windows, which provide information about major updates, such as the introduction of additional operating systems and new or changed CIS Benchmarks. You can also learn about defect fixes, minor changes, and known issues. For detailed information about updated benchmarks, see Reference: Benchmarks and controls.
2. Learn about the CIS Benchmark that you plan to enforce in the new release. Review the associated controls and configuration options:
   • For a list of supported benchmarks in SCE, see Prepare to install the module.
   • For details about the supported benchmarks and associated controls, see the Reference on Puppet Forge. You can also download benchmark information from the CIS Benchmarks List. If you are using SCE with Security Compliance Management (formerly Puppet Comply), you can view details about the benchmarks in Security Compliance Management.
3. Identify a test environment. Many users follow the instructions in Environments. You can also use any alternative method that works for you.
   Testing is important because SCE can make hundreds of changes to a system, and many of those changes are critical to components. By testing and troubleshooting issues in advance, you can help to prevent issues later.
4. In the test environment, upgrade the module. To help simplify the process, you can use a Puppetfile:
   1. Update the version in the module declaration. To upgrade the module to v2.0.0 or later, replace cem_windows with sce_windows and specify the version number as shown in this example for v2.0.0:

      mod 'puppetlabs/sce_windows', '2.0.0'

      To upgrade the module to a version earlier than v2.0.0, specify the declaration as shown in this example for v1.5.1:

      mod 'puppetlabs/cem_windows', '1.5.1'

   2. Commit the change to the appropriate branch or test environment.
   3. Deploy the change by using Code Manager or r10k. For instructions about using Code Manager and r10k, see Managing code with Code Manager.
5. Verify that the module is successfully upgraded in the test environment.
6. Determine whether the configuration must be updated. If so, make a list of the required updates. If you upgraded the module to v2.0.0 or later, you must replace any cem_windows references with sce_windows in the configuration of your test environment.

   If the relevant CIS Benchmark was updated in the release, the configuration typically requires updates because controls might have been added or removed, or their numbers or titles might have changed. For example, if your configuration uses a "normalized number" control ID ("c1_1_1" or similar), pay close attention to any controls whose number changed because you must update the corresponding control ID in your configuration. If the release notes indicate that the number for control "1.1.1" changed to "1.1.2," you must replace "c1_1_1" in your configuration with "c1_1_2."

   Control updates are documented in Reference: Benchmarks and controls. For example, if you are upgrading the module to v1.5.0, you would go to the reference section and then locate the information for your operating system:

   • Control updates introduced for CIS Microsoft Windows 10 Enterprise Benchmark v2.0.0
   • Control updates introduced for CIS Microsoft Windows Server 2019 Benchmark v2.0.0
   • Control updates introduced for CIS Microsoft Windows Server 2016 Benchmark v2.0.0

7. Implement any required configuration updates. This step is crucial to help prevent errors caused by misconfiguration.
   You can simplify configuration by using the Hiera key-value store as described in Getting started with Hiera. Take the following actions:

   1. Update the configuration of the test environment. For instructions, see Overview of configuration options.
   2. Ensure that the updates are deployed to the test environment. For example, if you are using Hiera and Code Manager, you must update the Hiera YAML files, commit the changes to the appropriate branch of your control repository, and trigger Code Manager.
8. To detect and resolve any errors, take the following actions:
   1. Look for errors in Puppet runs in your test environment.
   2. If you detect errors, review and update your configuration. For help with configuration options, see the Reference.
   3. If the configuration is correct but errors persist, enable debug logging on the Puppet primary server and review the puppetserver.log file. For more information, see Puppet Server logging.
      In the logs, SCE log entries are prefixed with SCE. CEM log entries are prefixed with CEM or cem.
   4. Optionally, for additional insight into errors, enable tracing and debugging when you run the Puppet agent.
   5. If you are unable to resolve the errors, take one of the following actions:
      • PE users can post a question in the #compliance Slack channel in the Puppet Community or open a ticket with Puppet Support.
      • Open source Puppet users can post a question in the #compliance Slack channel in the Puppet Community, open a ticket on the sce_issues webpage in GitHub, or open a ticket with Puppet Support. As an open source Puppet user, your options vary depending on the support package that you purchased with SCE.
9. To plan the upgrade in the production environment, consider the following questions:
   • Should the upgrade occur in stages or on all nodes simultaneously?
   • What is the risk of the upgrade, and is further testing required to mitigate the risk?
   • In the rare event that the upgrade is not successful, what is the plan to roll back the changes, given the fact that SCE cannot revert changes automatically?

   For assistance with these questions, you can contact Puppet Support. Support engineers are prepared to assist you before, during, and after the upgrade.