4.7.1. Classification and Data

4.7.1.1. Node Classification in SIMP

From the Puppet, Inc. website:

Hiera is a key/value lookup tool for configuration data, built to set node-specific data without repeating yourself.

SIMP uses Hiera to attempt to make configuration of the overall system easier for our end users by providing a simple, centralized, method for setting class parameters using automatic parameter lookup.

It is highly recommended that you read the Hiera Documentation prior to jumping into using a SIMP system.

4.7.1.2. Hiera in SIMP

SIMP users are expected to make extensive use of Hiera to set parameters, particularly those that are deep within the code.

The default Hiera hierarchy used by SIMP defined at the environment level in the Hiera configuration file and looks like the following:

---
version: 5
defaults:
  datadir: data
  data_hash: yaml_data

hierarchy:

  - name: Per-node data
    paths:
    - "hosts/%{trusted.certname}.yaml"
    - "hosts/%{facts.fqdn}.yaml"
    - "hosts/%{facts.hostname}.yaml"

  - name: Per-domain data
    paths:
    - "domains/%{facts.domain}.yaml"

  - name: Per-OS data
    paths:
    - "%{facts.os.family}.yaml"
    - "%{facts.os.name}/%{facts.os.release.full}.yaml"
    - "%{facts.os.name}/%{facts.os.release.major}.yaml"
    - "%{facts.os.name}.yaml"

  - name: Per-hostgroup data - See site.pp for more information
    paths:
    - "hostgroups/%{hostgroup}.yaml"

  - name: General data
    paths:
    - "default.yaml"
    - "common.yaml"

  - name: SIMP specific data - Please do not modify
    paths:
    - "simp_config_settings.yaml"
    - "scenarios/%{simp_scenario}.yaml"

Warning

This may not be accurate for your version of SIMP, please check your local Hiera settings!

The rest of this document will use this hierarchy as a reference.

4.7.1.3. Assigning Classes to Nodes

The SIMP profile module includes other classes needed for a secure baseline, which are discussed below in the SIMP scenarios section. The lists of included classed are controlled by the simp::classes and simp::server::classes class parameters:

  • The simp::classes parameter is available for all nodes.

  • The simp::server::classes parameter is available only for the SIMP Server.

To preserve various levels of ordering and overrides, it is highly recommended that you use the simp::classes and simp::server::classes class parameters in Hiera to manage standard class inclusions.

This allows you to use the -- knockout prefix to exclude classes at any level of your hierarchy, which, in turn, allows you to use your own modules to manage specific applications that SIMP manages by default.

Example: Adding a Class to Standard List
---
simp::classes:
  - gnome
Example: Removing a Class from Client Nodes
---
simp::classes:
  - '--ntpd'
Example: Removing a Class from Client Nodes and the SIMP Server
---
simp::classes:
  - '--ntpd'

simp::server::classes:
  - '--ntpd'

4.7.1.3.1. Legacy Method

SIMP also includes class inclusion functionality via a top-level classes array in your Hiera hierarchy. Though this is no longer recommended, it is still supported.

In this case, instead of using the knockout prefix, there is also a class_exclusions array that will be used to remove classes from the include list. Note, however, this array cannot be applied to any classes included via simp::classes or simp::server::classes.

4.7.1.4. Assigning Defined Types to Nodes

Defined types do not have the ability to receive parameters via Hiera in the traditional sense. To include a defined type on a node, one could use create_resources, but this is messy and discouraged. Instead, create your own profile or a site module with site-specific manifests. For example, /etc/puppetlabs/code/environments/production/modules/site/manifests/my_site.pp.

Note

You can find a working example of this in the Configure PXE Boot section of the documentation

4.7.1.5. SIMP Scenarios

SIMP scenarios are groups of classes, settings, and simp_options that ensure the system is compliant and secure.

There are currently four SIMP scenarios:

  • simp

  • simp_lite

  • poss

  • remote_access

The simp scenario includes all security features enabled by default, including iptables and svckill. This scenario is what stock SIMP used to look like in previous releases.

The simp_lite scenario offers many security features, with a few explicitly turned off. This scenario was designed to make it easier to implement SIMP in an existing environment, because it might not be trivial to flip SELinux to Enforcing on all nodes.

The poss option is the bare-bones option. It only includes the pupmod class, to configure Puppet agent on clients. All of the simp_options default to false, so SIMP will not do a lot of modification to clients through Puppet when using this scenario.

The remote_access scenario includes the SSH module and the authentication stack, namely PAM and nsswitch. This scenario is useful for those who want to retain remote access to their machine while leaving virtually everything else untouched.

These scenarios are defined in the pupmod-simp-simp module. For more details refer to this module.

Note

The SIMP Server is exempt from most of these settings, and will be using most features from the simp scenario by default. The SIMP server should only have services on it related to Puppet and systems management, and SIMP modules all work with all security features enabled. See the puppet.your.domain.yaml in the data/hosts directory for details.

4.7.1.6. The SIMP Compliance Engine

The SIMP Compliance Engine allows users to enable validation and enforcement of inbuilt and/or custom compliance. SIMP Community Edition contains freely available profiles generally maintained by the community. SIMP Enterprise Edition contains additional profiles targeted more at commercial regulations. Enforcement is done at the Puppet class parameter level and validation may be done against both classes and defined resource types.

This capability is provided by the simp-compliance_markup Puppet module and will be renamed at some point in the future to simp-compliance_engine for clarity.

Important

Your system must be configured to use at least Hiera version 5 for the Compliance Engine to function properly.

SIMP 6.3+ supports this capability out of the box but earlier versions may need to perform a Hiera migration.

4.7.1.6.1. Enabling the SIMP Compliance Engine

In the Puppet implementation, the Compliance Engine is a Hiera backend that provides data from SIMP compliance profile data sets for use in configuring Puppet classes via automatic parameter lookup.

The following example demonstrates how to enable the SIMP Compliance Engine in an example hiera.yaml configuration.

---
version: 5
defaults:
  datadir: "data"
  data_hash: "yaml_data"
hierarchy:
  # Anything defined at this level of the hierarchy will override settings
  # in the SIMP Compliance Engine
  - name: "Higher Priority Items"
    paths:
      - "mandatory.yaml"

  - name: "SIMP Compliance Engine"
    lookup_key: "compliance_markup::enforcement"

  # Anything defined at this level of the hierarchy will be overridden by
  # the SIMP Compliance Engine.
  - name: "Lower Priority Items"
    paths:
      - "optional.yaml"

Note

Hierarchy lookups happen from top to bottom and stop at the first match. This means that if the SIMP Compliance Engine is in enforcing mode and is at the top of the hierarchy, then it cannot be overridden except by an ENC. See the Hiera config file syntax page for additional information.

After configuring Hiera, you then need to include the compliance_markup class.

include 'compliance_markup'

4.7.1.6.2. Discovering Available Profiles

Prior to SIMP 6.4, all profile data was embedded into the simp-compliance_markup module. As of 6.4, the data has been split across the modules with each SIMP module containing the module’s specific profile data in the SIMP directory.

Data for modules that are not maintained by the SIMP organization are still housed in simp-compliance_markup.

At this time, SIMP CE comes with two publicly available profiles, disa_stig and nist_800_53:rev4.

A simp subcommand will eventually be provided to help discover available profiles in different environments but, for now, you can use the following code snippet:

ruby -r yaml -e "puts Dir. \
  glob('/etc/puppetlabs/code/environments/production/modules/*/{SIMP,simp}/compliance_profiles/*.yaml'). \
  map{|x| begin YAML.load_file(x); rescue; end; }.compact. \
  map{|x| x['profiles'] && x['profiles'].keys}. \
  compact.flatten.sort.uniq"

4.7.1.6.3. Profile Enforcement

The selection of profiles to enforce is based on the lookup_key entry in the hiera.yaml configuration as shown in the previous section.

In this case, the lookup_key, is compliance_markup::enforcement and should be set in Hiera as an Array of compliance profiles that you would like to apply, in priority order.

If you wanted to conform with the requirements of the DISA STIG, you would apply the disa_stig profile as shown below:

---
compliance_markup::enforcement:
  - "disa_stig"

The next run of Puppet on the nodes to which this Hiera data applies would then have their parameters set to meet the STIG requirements as mapped by parameter in the associated compliance profile.

Additional profiles may be made available by various Puppet modules, such as those provided by SIMP EE.

4.7.1.6.4. Code-Level Compliance Validation

The SIMP Compliance Engine also provides a mechanism for generating reports based on the Puppet parameters that are set at compile time and where those differ from the parameters that are expected for a particular compliance profile.

Note

Enforcement and validation are two distinct capabilities and the settings of one do not affect the other. This allows you to validate against multiple profiles independently of any particular enforcement setting.

In the following example, we want to validate against the nist_800_53_r4 profile:

---
compliance_markup::validate_profiles:
  - "nist_800_53_r4"

By default, reports will be generated on the Puppet server and written to the server’s vardir which, by default, is /opt/puppetlabs/server/data/puppetserver/simp/compliance_reports. Only the latest compliance report for a host is stored. The report is a YAML format that may easily be offloaded for analysis and processing and fully documented in the simp-compliance_markup Puppet module.

4.7.1.7. SIMP File Structure

The default Puppet environment in SIMP is located at /etc/puppetlabs/code/environments/production and contains almost all necessary files for a Puppet infrastructure. It will look like this:

/etc/puppetlabs/code/environments/production/
├── environment.conf
├── data/
├── manifests/
└── modules/

  • environment.conf

  • manifests/

    • Contains SIMP’s site.pp.

  • data/

    • Default location of the YAML files used by Hiera; contains your node data.

  • modules/

    • Default install location of Puppet modules. Populated automatically for you by simp config.

The skeleton for SIMP’s Puppet environment is installed by the simp-environment-skeleton RPM into /usr/share/simp/environment-skeleton/puppet. This skeleton is copied into the production Puppet environment by simp config. However, at any time, you can regenerate this skeleton SIMP Omni-Environment by using simp environment new.

4.7.1.8. Second Modulepath

SIMP utilizes a second modulepath in the SIMP Omni-Environment to ensure that deployment tools like r10k do not squash keydist and some krb5 files. For the production environment, the path is /var/simp/environments/production/site_files/. PKI Certificates are stored there.

4.7.1.9. Hiera

There are three Hiera Configuration Layers in Hiera 5. SIMP configures Hiera at the environment level, via /etc/puppetlabs/code/environments/<environment name>/hiera.yaml. The global level configuration file at /etc/puppetlabs/puppet/hiera.yaml still exists but its hierarchy is empty in a fresh system and probably should remain that way for general usage.

The default hiera.yaml for a SIMP environment is shown in Hiera in SIMP and its syntax is explained in Hiera configuration file. The corresponding Hiera data directory layout in a fresh SIMP system (or a new environment created by simp environment new) is as follows:

/etc/puppetlabs/code/environments/production/data/
├── default.yaml
├── hostgroups/
├── hosts/
├── scenarios/
└── simp_config_settings.yaml

  • data/simp_config_settings.yaml

    • Contains the variables needed to configure SIMP. Added by simp config.

  • data/scenarios/

    • Directory containing settings for SIMP Scenarios. The scenario selected is set in manifests/site.pp. This is done automatically for you when you run simp config.

  • data/hosts/

    • Settings for specific hosts. By populating this directory with host name files, you can assign parameters to specific hosts. Based on SIMP’s hiera.yaml, Hiera looks for the name in following formats:

      • %{trusted.certname}.yaml

      • %{facts.fqdn}.yaml

      • %{facts.hostname}.yaml

  • data/hostgroups/

    • Settings for specific groups of hosts. The hostgroup of a node is computed using a top-scope $hostgroup variable. By default, this is set via SIMP’s top-level site.pp. Then, nodes assigned to $hostgroup will read Hiera from a file named <hostgroup>.yaml in this directory.

  • data/default.yaml

    • Settings that should be applied to all systems in the environment.

Important

Do not change or update the scenarios YAML files or simp_config_settings.yaml. If you want to change any of the settings contained in these files for one or more hosts, override the settings in Hiera files earlier in the hierarchy, instead.