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 CEM release, review the Release notes, 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.
    Tip: For an example of the changes associated with a benchmark update, see the CEM for Windows v1.5.0 updates in the Release notes.
  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 CEM, see Prepare to install the module.
    • For details about the supported benchmarks and associated controls, see the CEM Windows Reference on Puppet Forge. You can also download benchmark information from the CIS Benchmarks List. If you are using CEM with Puppet Comply, you can view details about the benchmarks in Comply.
  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 CEM 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 CEM. To help simplify the process, you can use a Puppetfile:
    1. In the Puppetfile, update the version in the CEM module declaration. For example, to upgrade cem_windows to version 1.5.1, specify the CEM declaration as shown:
      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 CEM module is successfully upgraded in the test environment.
  6. Determine whether the CEM configuration must be updated. If so, make a list of the required updates.

    In many cases, you can upgrade CEM without additional configuration. However, if the relevant CIS Benchmark was updated in the release, the CEM 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 CEM to v1.5.0, you would go to the reference section and then locate the information for your operating system:
  7. Implement any required configuration updates. This step is crucial to help prevent CEM 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 Find and set 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 CEM Windows 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.
      Tip: In the log list, CEM errors 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, post a question in the #compliance Slack channel in the Puppet Community or open a ticket with Puppet Support.
  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 CEM cannot revert changes automatically?
    Tip: For assistance with these questions, you can contact Puppet Support. Support engineers are prepared to assist you before, during, and after the upgrade.