Forge Home

Modules

Topics

Resources

PuppetEcosystemPuppet CommunityUpdates
Premium module

cem_windows

Compliance Enforcement Module for Windows
Project URLRSS FeedReport issues

2,042 downloads

36 latest version

Version information

  • 1.2.1 (latest)
  • 1.2.0
  • 1.1.2
  • 1.1.1
  • 1.1.0
  • 1.0.7
  • 1.0.6
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
released May 31st 2022
This version is compatible with:
  • Puppet Enterprise 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x
  • Puppet >= 6.23.0 < 8.0.0
Tags: security, hardening, compliance, cis, comply

Documentation

puppetlabs/cem_windows — version 1.2.1 May 31st 2022

cem_windows

Spec Tests

Table of contents

Introducing the Compliance Enforcement Modules

The cem_windows module is one of two Compliance Enforcement Modules (CEM). These Puppet-supported modules were developed to bring your Puppet Enterprise (PE) managed nodes into compliance with Center for Internet Security (CIS) rules.

By default, CEM enforces CIS rules for the Level 1 server profile on Windows Server 2016 and Windows Server 2019, and the Level 1 corporate enterprise profile on Windows 10 Enterprise.

This readme file provides instructions for installing CEM and customizing the configuration settings to meet your organization’s compliance requirements. For a list of available parameters, see the CEM reference.

After you have installed and configured CEM, PE will run on any classified nodes without user intervention to enforce compliance.

To manage Linux nodes, navigate to cem_linux.

Setup

Before you install CEM, review the System requirements to ensure that CEM can be run on the operating systems in your environment. Then, contact a Puppet sales representative to purchase CEM.

System requirements

cem_windows supports the following operating systems and CIS benchmarks:

Operating system Framework Level Profile
Windows Server 2019 CIS Benchmarks v1.2.1 1 Member Server
Windows Server 2016 CIS Benchmarks v1.3.0 1 Member Server
Windows 10 Enterprise CIS Benchmarks v1.12.0 1 Corporate Enterprise

Tip: CEM uses Desired State Configuration (DSC) modules and the validation_mode parameter to ensure that resources do not remain in a "flapping" state. For more information, see securitypolicydsc.

Install CEM with Code Manager

For installation instructions, see Puppet Forge Premium Content.

Usage

By default, cem_windows enforces CIS rules that are dependent on your operating system. The Level 1 Member Server profile is enforced on Windows Server 2016 and Windows Server 2019, and the Level 1 Corporate Enterprise profile is enforced on Windows 10 Enterprise.

If you installed CEM with Code Manager and assigned the cem_windows class to a node group in the PE console, the default profile is automatically enforced. If you installed CEM without Code Manager, add include cem_windows to the profile assigned to your node to enable CEM.

To configure specific benchmarks, you can use Hiera.

Caution: CEM's default settings are fully CIS compliant. Too much customization can cause your configurations to be noncompliant.

Controls ignored by default: Controls 2.3.1.1 and 2.3.1.5 are ignored by default because of non-idempotent and Puppet run issues. For details and configuration options, see Controls ignored by default to prevent operational issues.

Find and set configuration options

Configuration options include top-level configuration options, framework configuration options, and CIS-specific configuration options.

You can find the configuration options for a specific control in the CEM Windows Reference. The reference is divided into sections, with each section representing a benchmark. In those benchmarks, you will see each control listed with several subsections:

  • Parameters:
    • Configuration options for a control, along with the data type and default value.
  • Config Example:
    • Snippet of Hiera that can be used to configure a control.
  • Supported Levels:
    • The supported levels for a CIS control.
  • Supported Profiles:
    • The supported profiles for a CIS control.
  • Alternate Config IDs:
    • The alternate config IDs for a control. Any of these config IDs, along with the full control name, can be used as a key in the control_config hash.
  • Resource:
    • The name of the Puppet resource that enforces the control.

Alternate config IDs

You can specify controls in the control_config hash by referencing the full control name, the control number, the normalized control name, or the normalized control number. You cannot mix and match these forms and must pick a single control ID form to use for your config. Full control names and control numbers are copied verbatim from the benchmarks and are case-sensitive. Normalized control names have lowercase letters and contain only alphanumeric characters and underscores. Normalized control numbers are always prefixed with a c and contain only numeric characters separated by underscores.

Example of alternate config IDs:

  • Full control name: (L1) Ensure 'Enforce password history' is set to '24 or more password(s)'
  • Control number: 1.1.1
  • Normalized control name: ensure_enforce_password_history_is_set_to_24_or_more_passwords
  • Normalized number: c1_1_1

Resource data

The data that drives CEM Windows is located in directories and files with the following structure:

data/windows/windows/<facts.os.release.major>.yaml

These Hiera files contain definitions for each Puppet resource that enforces a control.

Caution: Do not modify the resource definitions that drive CEM Windows. If you must change the behavior of a control, configure the control by using the control_config hash.

Top-level configuration options

These options are configured at the top level of the module. In Hiera, these options are prefixed with cem_windows:

  • framework - Enum['cis'] - the compliance framework to use. CEM supports only cis. Default: cis.
  • config - Optional[Hash] - the location for all non-top-level configuration options. Default: undef.
  • allow_on_domain_controller: - Boolean - If cem_windows detects that it is running on a domain controller, CEM does not enforce controls and logs a warning to inform the user. In this way, CEM helps to prevent the enforcement of compliance settings on domain controllers that could negatively impact an entire domain. Default: true.
  • enable_long_paths - Boolean - Enables support for long path names in the Windows registry. Setting this option to false can cause issues with some DSC modules used in cem_windows. Default: true.
  • privileged_user - Optional[String] - If the Puppet agent does not run under a user with local administrator privileges, you must supply the name of a user with local administrator privileges. This is used by DSC to enforce a state on a machine. Default: undef.
  • privileged_password - Sensitive[Any] - If you specified a privileged user, use this option to specify a password for that user account. Default: undef.
  • allow_local_account_rdp - Boolean - By default, cem_windows disables remote desktop protocol (RDP) access for non-domain accounts. If you set this option to true, local accounts on the node can make RDP connections to the node. Default: false.

Framework configuration options

The framework configuration options are available as key-value pairs within the cem_windows::config: hash.

  • control_configs - Optional[Hash] — location for all rule-specific configurations. Default: undef.
  • only - Optional[Array[String]] — takes an array of control class names (manifests/benchmarks/<benchmark>/controls/*.pp). The classes specified here are included in the catalog. Takes precedence over the ignore: option. Default: undef.
  • ignore - Optional[Array[String]] — takes an array of control class names (manifests/benchmarks/<benchmark>/controls/*.pp). The classes specified here are not included in the catalog. If only: is specified, this option does nothing. Default: undef.

CIS-specific configuration options

The CIS-specific configuration options are available as key-value pairs within the cem_windows::config: hash. These options are applicable only to the CIS compliance framework.

  • profile - Optional[Enum['member_server', 'corporateenterprise']] — the name of the benchmark profile. corporateenterprise is supported only on Windows 10 Enterprise operating systems. Default for Windows Server operating systems: member_server. Default for Windows 10 Enterprise operating systems: corporate_enterprise.
  • level - Optional[Enum['1', '2']] — the name of the profile level. The only value supported by CEM is 1. Default: 1.

For a list of configuration options, see the CEM Windows Reference.

Configuration examples

The following examples demonstrate the use of CEM in a production environment.

Run DSC resources as a specific user

DSC requires local administrator privileges to modify Windows resources. Normally, the Puppet agent runs under a user account with these permissions. However, if the Puppet agent on a node does not have local administrator permissions, you can use Hiera to configure a user account that does have the required permissions. Use a configuration based on the following structure:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::privileged_user: <user name>
cem_windows::privileged_pass: <user password>

Allow local accounts to access nodes

To allow a local user account to access a node with RDP, set the top-level option allow_local_account_rdp to true. For example:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::allow_local_account_rdp: true

Enforce specific rules

To configure CEM to enforce only specific rules, you can use the only key. For example:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::framework: 'cis'
cem_windows::config:
  profile: 'member_server'
  level: '1'
  only:
    - 'c18_9_97_1_1'
    - 'c18_9_97_1_2'

Ignore specific rules

To configure CEM to ignore specific rules, you can use the ignore key. For example:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::framework: 'cis'
cem_windows::config:
  profile: 'member_server'
  level: '1'
  ignore:
    - 'c18_9_97_1_1'
    - 'c18_9_97_1_2'

Restriction: The only key and the ignore key are mutually exclusive, with only taking precedence. If you specify both keys, CEM does not use the value of the ignore key and enforces only the rules specified with only.

Configure individual rules

You can customize most rules by using the control_configs key and supplying the key with a hash value. To customize rules, use a configuration based on the following structure:

<recommendation name>:
  <recommendation param>: <value>

For example, if you want to configure the rules used in the previous examples, the configuration would look like:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::framework: 'cis'
cem_windows::config:
  profile: 'member_server'
  level: '1'
  control_configs:
    c18_9_97_1_1:
      allowbasic: '0'
    c18_9_97_1_2:
      allowunencryptedtraffic: '0'

Rename Administrator and guest accounts

To rename the local Administrator account to user_1, use the following configuration:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::config:
  control_configs:
    c2_3_1_5:
      value: 'user_1'

Important: If you do not specify a name for the Administrator account, the account is renamed to magic by default.

To rename the local Guest account to user_2, use the following configuration:

# control-repo/data/nodes/winserv2019.contoso.com.yaml
---
cem_windows::config:
  control_configs:
    c2_3_1_6:
      value: 'user_2'

Important: If you do not specify a name for the Guest account, the account is renamed to pumpkin by default.

Known issues and limitations

cem_windows has the following known issues and limitations:

  • Some controls can fail scans. During a Comply scan, you might see error messages about CIS recommended guidelines that are not enforced. These error messages are triggered by bugs in the CIS-CAT Pro Assessor that is bundled with Comply. CEM correctly enforces these settings. The following controls are affected:

    • 1.1.5 - Windows Server 2016 and Windows Server 2019
    • 1.1.6 - Windows Server 2016 and Windows Server 2019
    • 2.3.10.7 - Windows Server 2016
    • 18.2.1 - Windows Server 2019
    • 18.4.1 - Windows Server 2016 and Windows Server 2019
    • 18.4.8 - Windows Server 2016
    • 18.4.9 - Windows Server 2016 and Windows Server 2019
    • 18.4.12 - Windows Server 2016
    • 18.8.21.5 - Windows Server 2016
    • 18.9.47.5.1.2 - Windows Server 2019
    • 18.9.62.3.9.1 - Windows Server 2016

  • Puppet runs are not idempotent. If you see DSC resources showing corrective changes in a Puppet run, for example, Unknown feature "custom_isync", you are running an incompatible version of Puppet. cem_windows requires the Puppet agent to be at any version 6 level, starting with v6.23, or at v7.8 or later.

  • If the Puppet agent fails to upgrade when you use the puppetlabs/puppet_agent module, restart the computer or virtual machine where the Puppet agent is running to help ensure that updates are applied.

  • If you use remote desktop protocol (RDP) to access nodes, users who are members of the groups Guests and local accounts will not be able to log in by default. To provide access to these groups, set the cem_windows::allow_local_account_rdp parameter to true.

  • If non-admin users cannot log in to nodes, the issue might be related to event logs. By default, Windows Event Log does not clear events. When the event log of a node is full, only administrators can log in. To clear the event logs manually, find the specific recommendation in your compliance framework and configure the setting. In the Windows registry, locate the following key:

    HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\EventLog\Application:Retention

    Then, set the Retention value to 0.

  • You cannot disable Windows Remote Management (WinRM). The WinRM service is required for the DSC modules and cannot be disabled.

Controls ignored by default to prevent operational issues

  • 2.3.1.1 (Ensure 'Accounts: Administrator account status' is set to 'Disabled') - If this control is applied, it can cause non-idempotent runs. The control can also cause Puppet run failures if you attempt to run Puppet manually while logged in as Administrator.
  • 2.3.1.5 (Configure 'Accounts: Rename administrator account') - If this control is applied, it can cause non-idempotent runs. The control can also cause Puppet run failures if you attempt to run Puppet manually while logged in as Administrator.

To enable controls ignored by default, create an ignore config that doesn't include the controls. For example, the following configuration ignores control 1.1.1, thus overriding the default ignore list:

cem_windows::config:
  ignore:
    - 'c1_1_1'

The following configuration removes all controls from the ignore list:

cem_windows::config:
  ignore: []