Prepare to upgrade the module

Before you upgrade the module, learn about the target release. Familiarize yourself with any updates that were implemented to comply with Center for Internet Security (CIS) Benchmarks or with Defense Information Systems Agency (DISA) Security Technical Implementation Guidelines (STIGs). 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 document major updates, such as the introduction of additional operating systems, new or changed CIS Benchmarks, and new or changed STIG standards. You can also learn about defect fixes, minor changes, and known issues.
  2. Learn about the CIS Benchmark or STIG standard that you plan to enforce in the new release. Review the associated controls and configuration options:
    • For a list of supported CIS Benchmarks and STIG standards, see Prepare to install the module.
    • If you plan to enforce CIS Benchmarks, you can find a list of benchmarks and associated controls in the CEM Linux 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.
    • If you plan to enforce STIG controls, you can find a list of benchmarks and associated controls in the CEM Linux Reference on Puppet Forge. For more detailed information about STIG controls, go to the STIG Viewer. If CEM was updated to accommodate updates in a STIG standard, look for a list of changes in the Reference section on the documentation website.
  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 to version 1.8.0, specify the CEM declaration as shown:
      mod 'puppetlabs/cem_linux', '1.8.0'
    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 or STIG standard 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 reference section indicates 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."

    To find any documented control updates for CEM for Linux, see Reference: Benchmarks and controls.
  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 Linux 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, contact Puppet Support. Support engineers are prepared to assist you before, during, and after the upgrade.