SIMP Compliance Engine reference

SCE Data structure

The SIMP Compliance Engine is capable of reading data formatted in YAML or JSON. The data is structured in a set of hashes, with specific top-level keys.

Top-level data elements

Key	Name	Description
version	Version (Required)	The SIMP Compliance Engine data version. Currently `2.0.0`
profiles	Compliance Profile	A checklist of the Checks, CEs, and Controls to add (or remove) from the profile.
checks	Check	A configuration setting such as a Puppet class parameter. This will be converted into Puppet resources and applied to systems if enforced.
ce	Configuration Element (CE)	A general configuration setting such as a DISA STIG control or CIS control where there is an explicit defined setting that must be enforced.

Compliance Profile

Compliance Profiles are hashes defined in the profiles hash. The key is used in the compliance_markup::enforcement and compliance_markup::verify_profiles parameters to indicate the profile should be used during enforcement and reporting, respectively. Profile names can be any unique string value. The profile hash must contain at minimum a controls hash, a ces hash, or a checks hash. All or any combination of those can be used in the same profile simultaneously.

Profile data elements

Key	Data type	Description
title	string	Optional. Short description of the profile.
description	string	Optional. Longer description of the profile.
controls	hash	Key is compared with controls entries of CEs and Checks, if value is `true`.
ces	hash	Key is a reference to an entry in the top-level `ce` hash. Enforced if value is `true`.
checks	hash	Key is a reference to an entry in the top-level `check` hash. Enforced if value is `true`.
confine	hash	Key is a Puppet fact key. Value is an array of acceptable values of the Puppet fact.

Profile examples

---
version: 2.0.0
profiles:
  custom_profile_1:
    title: 'An example profile'
    description: 'This profile contains sample data and information.  It should not be used in a production environment.'
    controls:
      sample:control:1: true
      sample:control:2: false
    ces:
      sample:configuration:element:def:1: true
      sample:configuration:element:def:2: false
    confine:
      os.name:
        - CentOS
  another:profile:
    ces: 
      example:ce:def:2: true
    confine:
      os.name:
        - windows
  this.is.also.a.valid.profile:
    controls:
      example.control.3: true
  example:profile:4:
    checks:
      example.check:def:4: true

Check

Checks can be referenced directly by name in Profile definitions, or must be enabled either through Controls, or reference a CE that is enabled in the Profile (either directly or through Controls).

Checks are hashes defined in the top-level checks hash. The check name can be any unique string value. The check definition must contain they type, settings, and either controls or ces, depending on the method chosen to enable it. Both controls and ces can be present in a single check and be used to enable it in multiple profiles.

Check data elements

Key	Data type	Description
type	string	Required. Currently only `puppet-class-parameter` is supported.
settings	hash	Required. `parameter` key is the Puppet class parameter to manage. `value` key is the desired value to enforce.
controls	hash	Key is a reference used in profile definitions. Value is either `true` to enable the ce based on the control, or `false` to disable based on the control.
ces	array	Values are strings that match keys in the top-level `ce` hash. This indicates the configuration setting being enforced is associated with the CE definition.
confine	hash	Optional. Key is a Puppet fact key (Use dot notation for structured facts). Value is an array of acceptable values of the Puppet fact.

Check example

---
version: 2.0.0
checks:
  sample:check:def:1: 
    type: 'puppet-class-parameter'
    settings:
      parameter: 'sample_class::sample_parameter_1'
      value: true
    ces:
      - sample:configuration:element:def:1
      - different:sample:configuration:element:def:1
  sample:check:def:4:
    type: 'puppet-class-parameter'
    settings:
      parameter: 'sample_class::sample_parameter_4'
      value: ['data1', 'data2', 'data3']
    controls:
      sample:control:1: true

Configuration Element

The Configuration Element (CE) is an optional intermediary component that contains additional detail about the recommendation from an industry benchmark. The CE can be referenced by name in the profile definition, or enabled indirectly through Controls. CEs are also referenced directly by Checks that enforce the configuration settings required to comply with the recommendation.

Configuration Element data elements

Key	Data type	Description
title	string	Optional. Title of the benchmark recommendation or configuration setting.
description	string	Optional. Longer description of the recommendation or configuration setting.
controls	hash	Key is a reference used in profile definitions. Value is either `true` to enable the ce based on the control, or `false` to disable based on the control.
identifiers	hash	Optional. Key is industry benchmark name (i.e. `cis`, `disa`, etc.) Value is an array of strings, containing benchmark rule numbers, CCE ids, and other references to relevant external information.
oval-ids	array	Optional. Values are strings containing the oval-id of the benchmark recommendation from the original XCCDF files. Used by the Console to reference data in the original XCCDF files.
imported_data	hash	Optional. Used to store extraneous data from the original benchmark XCCDF files.
confine	hash	Optional. Key is a Puppet fact key. Value is an array of acceptable values of the Puppet fact.

Configuration Element example

---
version: 2.0.0
ce:
  sample:configuration:element:def:1:
    controls:
      sample:control:1: true
      sample:control:3: true
    title: 'This is the first sample configuration element.'
    description: 'This is an example description. Descriptions are optional.  This CE will be enforced by compliance_profile_1 because it is explicitly enabled in the ces hash.  This CE is referenced by sample:check:def:1.'
    confine:
      os.release.major:
        - 7
        - 8
      os.name:
        - CentOS
        - OracleLinux
        - RedHat
  sample:configuration:element:def:2:
    controls:
      sample:control:4: true
    title: 'This is the second sample configuration element.'
    description: 'This is an example description. Descriptions are optional.  This CE will not be enforced by custom_profile_1 because it is explicitly disabled in the ces hash.'

Complete data set

This sample data shows all of the data elements merged into a single file and how they relate:

---
version: 2.0.0
profiles:  # This hash contains the Compliance Profile definitions
  custom_profile_1:
    controls:  # This has contains the Controls included in the Profile
      sample:control:1: true # This Control is enabled. All CEs and Checks also containing this control will be enforced.
      sample:control:2: false # This Control is disabled. All CEs and Checks also containing this control will not be enforced.
    ces: # This hash contains the Configuration Elements included in the Profile
      sample:configuration:element:def:1: true  # This CE is enabled and will be enforced
      sample:configuration:element:def:2: false # This CE is disabled and will not be enforced
    confine: # This profile will only be enforced on CentOS systems.
      os.name:
        - CentOS
ce:  # This hash contains the Configuration Element definitions
  sample:configuration:element:def:1:  # Enabled in the 'ces' hash in custom_profile_1
    controls: # This hash contains the Controls this CE complies with.
      sample:control:1: true # Enabled in the Controls has in custom_profile_1
      sample:control:3: true #
    title: 'This is the first sample configuration element.'
    description: 'This is an example description. Descriptions are optional.  This CE will be enforced by compliance_profile_1 because it is explicitly enabled in the ces hash.  This CE is referenced by sample:check:def:1.'
    confine: # This hash contains Puppet facts that must match for the CE to be enforced.  All confines must be positively matched.
      os.release.major: # Structured Puppet fact name, the array contains the accepted values
        - 7
        - 8
      os.name:
        - CentOS
        - OracleLinux
        - RedHat
  sample:configuration:element:def:2:  # Disabled in the 'ces' hash in custom_profile_1
    controls: # This hash contains the Controls this CE complies with.
      sample:control:4: true # Not used in this example
    title: 'This is the second sample configuration element.'
    description: 'This is an example description. Descriptions are optional.  This CE will not be enforced by custom_profile_1 because it is explicitly disabled in the ces hash.' 
  sample:configuration:element:def:3:  # Not listed in the 'ces' hash in custom_profile_1
    controls: # This hash contains the Controls this CE complies with.
      sample:control:1: true # Enabled in the Controls has in custom_profile_1
      sample:control:3: true # Not used in this example
    title: 'This is the third sample configuration element.'
    description: 'This is an example description. Descriptions are optional.  This CE will be enforced by custom_profile_1 because sample:control:1 is explicitly enabled in the controls has in both definitions.'
checks:  # This hash contains the Check definitions
  sample:check:def:1: # Will be enforced by custom_profile_1 because it has sample:configuration:element:def:1 listed in the ces hash.
    type: 'puppet-class-parameter' # This denotes the setting type.  Only 'puppet-class-parameter' is supported at this time.
    settings: # This hash contains the parameters and values that will be set via Puppet
      parameter: 'sample_class::sample_parameter_1'
      value: true
    ces:  # This array contains the Configuration Elements this setting complies with.
      - sample:configuration:element:def:1 # A CE from this example
      - different:sample:configuration:element:def:1 # A CE from a different data set 
  sample:check:def:2: # Will not be enforced by custom_profile_1 because the CE is explicitly disabled there
    type: 'puppet-class-parameter'
    settings:
      parameter: 'sample_class::sample_parameter_2'
      value: 3
    ces:
      - sample:configuration:element:def:2
  sample:check:def:3: # Will be enforced by custom_profile_1 because the sample:control:1 Control is enabled in both the profile and the CE
    type: 'puppet-class-parameter'
    settings:
      parameter: 'sample_class::sample_parameter_3'
      value: false
    ces:
      - sample:configuration:element:def:3
  sample:check:def:4: # Will be enforced by custom_profile_1 because the sample:control:1 Control is enabled in the Profile and in this Check
    type: 'puppet-class-parameter'
    settings:
      parameter: 'sample_class::sample_parameter_4'
      value: ['data1', 'data2', 'data3']
    controls:
      sample:control:1: true
    ces:
      - different:sample:configuration:element:def:2 # A CE from a different data set
   

Additional data examples can be found here

Puppet Class Reference

Classes

compliance_markup: The compliance markup helper class

Defined types

compliance_markup::map: A wrapper to ensure that the mapper is called during the appropriate phase of the catalog compile.

Functions

compliance_markup::compliance_map: Provides a mechanism for mapping compliance data to settings in Puppet
compliance_markup::enforcement: Hiera entry point for the SIMP Compliance Engine
compliance_markup::loaded_maps: Returns the compliance data keys from the loaded compliance maps

Classes

compliance_markup

This class should be included after all other classes in your site so that the mapper can properly analyze the standing catalog.

Parameters

The following parameters are available in the compliance_markup class.

`compliance_map`

Data type: Hash

The compliance Hash to which to map

This defaults to Data In Modules

`validate_profiles`

Data type: Optional[Array[String[1]]]

Compliance profiles that you wish to validate against

Default value: undef

`report_types`

Data type: Array[ Enum[ 'full', 'non_compliant', 'compliant', 'unknown_resources', 'unknown_parameters', 'custom_entries' ] ]

The types of entries that you want to report on

full => Include all report types*
non_compliant => Report on non-compliant parameters*
unknown_parameters => Report on parameters that are mapped but not included in the catalog*
custom_entries => Report custom calls to compliance_markup::compliance_map() from the codebase
compliant => Report on compliant parameters
unknown_resources => Report on classes that are mapped but not included in the catalog
This is ignored if options is specified

Default value: [‘non_compliant’, ‘unknown_parameters’, ‘custom_entries’]

`report_format`

Data type: Enum['json','yaml']

The output format for the report

Default value: ‘json’

`report_on_client`

Data type: Boolean

Save a copy of the report on the client as a File resource

This will make the report show up in PuppetDB but may also expose unwanted vulnerability information

Default value: false

`report_on_server`

Data type: Boolean

Save a copy of the report on the puppet server

Default value: true

`server_report_dir`

Data type: Optional[Stdlib::Absolutepath]

The path where the server should store reports

If you change this, you must make sure that the puppet server can write to the location.
By default, this is written to Puppet[:vardir] as the Puppet server sees it: /opt/puppetlabs/server/data/puppetserver/simp/compliance_reports

Default value: undef

`custom_report_entries`

A hash that will be included in the compliance report under the heading site_data

This can be used for adding anything to the compliance report. The hash is simply processed with to_yaml

`options`

Data type: Optional[Hash]

The options to pass directly to the compliance_markup::compliance_map validation function

If specified, various other options may be ignored

Default value: undef

`custom_report_data`

Data type: Optional[Hash]

Default value: undef

Defined types

compliance_markup::map

Defines appear to be run after all classes

The options hash is passed directly to the compliance_markup::compliance_map() function

Parameters

The following parameters are available in the compliance_markup::map defined type.

`options`

Data type: Any

Default value: {}

Functions

compliance_markup::compliance_map

Type: Ruby 4.x API

It should be used once, after all of your classes have been included and is designed for use in classes to validate that parameters are properly set.

The easiest method for doing this is to add it as the last line of site.pp.

When called, the parameters of all classes will be evaluated against global scope variables followed by data from lookup().

The variable space against which the class parameters will be evaluated must be structured as the following hash:

  compliance_map :
    <compliance_profile> :
      <class_name>::<parameter> :
        'identifiers' :
          - 'ID String'
        'value'      : 'Compliant Value'

For instance, if you were mapping to NIST 800-53 in the SSH class, you could use something like the following in Hiera:

  compliance_map :
    nist_800_53 :
      ssh::permit_root_login :
        'identifiers' :
          - 'CCE-1234'
        'value'      : false

‘value’ items have some special properties. Hashes and Arrays will be matched using ‘==’ in Ruby.

Everything else will be converted to a String and can be provided a Ruby regular expression of the following format: ‘re:REGEX’ where ‘REGEX’ does not include the starting and trailing slashes.

Example:

    'value' : 're:oo'

Matches: ‘foo’ and ‘boo’ but not ‘bar’

You may also add compliance data directly to your modules outside of a parameter mapping. This is useful if you have more advanced logic that is required to meet a particular internal requirement.

NOTE: The parser does not know what line number and, possibly, what file the function is being called from based on the version of the Puppet parser being used.

Global Options

If a Hash is passed as the only argument, then this will configure the global report settings.

The following options are supported:

:report_types

Default: [ 'non_compliant', 'unknown_parameters', 'custom_entries' ]

A String, or Array that denotes which types of reports should be
generated.

Valid Types:
  **full**               => The full report, with all other types
                            included.
  **non_compliant**      => Items that differ from the reference
                            will be reported.
  **compliant**          => Compliant items will be reported.
  **unknown_resources**  => Reference resources without a
                            system value will be reported.
  **unknown_parameters** => Reference parameters without a system
                            value will be reported.
  **custom_entries**     => Any one-off custom calls to
                            compliance_map will be reported.

:site_data

Default: None

A valid *Hash* that will be converted *as passed* and emitted
into your node compliance report.

This can be used to add site-specific or other information to the
report that may be useful for post-processing.

:format

Default: 'json'

A String that indicates what output style to use. Valid values are
'json' and 'yaml'.

:client_report

Default: false

A Boolean which, if set, will place a copy of the report on the
client itself. This will ensure that PuppetDB will have a copy of the
report for later processing.

:server_report

Default: true

A Boolean which, if set, will store a copy of the
report on the Server.

:server_report_dir

Default: Puppet[:vardir]/simp/compliance_reports

An Absolute Path that specifies the location on
the *server* where the reports should be stored.

A directory will be created for each FQDN that
has a report.

:default_map

Default: None

The default map that should be used if no others can be found. This
will probably never be manually set during normal usage via the
compliance_markup module

:catalog_to_compliance_map

Default: false

A Boolean which, if set, will dump a compatible compliance_map of
*all* resources and defines that are in the current catalog.

This will be written to ``server_report_dir`` prefaced by the unique catalog ID.

NOTE: This is an experimental feature and subject to change without notice

Example: Only non-compilant entries and store them on the client and the server

  compliance_map({
    :report_types  => [
      'non_compliant',
      'unknown_parameters',
      'custom_entries'
    ],
    :client_report => true,
    :server_report => true
  })

Custom Content

The following optional ordered parameters may be used to add your own compliance data at any location:

:compliance_profile => ‘A String, or Array, that denotes the compliance profile(s) to which you are mapping.’ :identifier => ‘A unique identifier String or Array for the policy to which you are mapping.’ :notes => ‘An optional String that allows for arbitrary notes to include in the compliance report’

Example:

  if $circumstance {
    compliance_map('nist_800_53','CCE-1234','Note about this section')
    ...code that applies CCE-1234...
  }

`compliance_markup::compliance_map(Hash $map_data)`

The compliance_markup::compliance_map function.

Returns: Any

`map_data`

Data type: Hash

`compliance_markup::compliance_map(Variant[String[1], Array[String[1]]] $compliance_profile, Variant[String[1], Array[String[1]]] $identifiers, Optional[String[1]] $notes)`

The compliance_markup::compliance_map function.

Returns: Any

`compliance_profile`

Data type: Variant[String[1], Array[String[1]]]

`identifiers`

Data type: Variant[String[1], Array[String[1]]]

`notes`

Data type: Optional[String[1]]

compliance_markup::enforcement

Type: Ruby 4.x API

Hiera entry point for the SIMP Compliance Engine

To activate this hiera backend, add the following to your hiera.yaml:

---
version: 5
hierarchy:
  - name: SIMP Compliance Engine
    lookup_key: compliance_markup::enforcement
    # All options are optional
    options:
      # Ignore all default data dirs and use these instead
      data_dirs:
        - /fully/qualified/data_dir
      # Add all items from these paths to the data sources
      # Stacks on both `data_dirs` and the inbuilt paths
      aux_paths:
        - /fully/qualified/path

Then, tell it what profile(s) to enforce by adding the following to your Hiera configuration for your target node(s):

---
# Enforce your custom company profile, then the STIG, then the NIST 800-53 Rev 4
compliance_markup::enforcement:
  - 'your_company_profile'
  - 'disa_stig'
  - 'nist_800_53:rev4'

`compliance_markup::enforcement(String $key, Hash $options, Puppet::LookupContext $context)`

Hiera entry point for the SIMP Compliance Engine

Returns: Any The discovered value or Undef if not found

`key`

Data type: String

The key to look up in the backend

`options`

Data type: Hash

Required by Hiera

`context`

Data type: Puppet::LookupContext

The context in which the Hiera backend is being called

compliance_markup::loaded_maps

Type: Ruby 4.x API

Returns the compliance data keys from the loaded compliance maps

`compliance_markup::loaded_maps()`

Returns the compliance data keys from the loaded compliance maps

Returns: Any

compliance_markup::telemetry

Type: Ruby 4.x API

The compliance_markup::telemetry function.

`compliance_markup::telemetry(String $key)`

The compliance_markup::telemetry function.

Returns: Any

`key`

Data type: String

SIMP Compliance Engine reference

SCE Data structure

Top-level data elements

Compliance Profile

Profile data elements

Profile examples

Check

Check data elements

Check example

Configuration Element

Configuration Element data elements

Configuration Element example

Complete data set

Puppet Class Reference

Table of Contents

Classes

compliance_markup

Parameters

compliance_map

validate_profiles

report_types

report_format

report_on_client

report_on_server

server_report_dir

custom_report_entries

options

custom_report_data

Defined types

compliance_markup::map

Parameters

options

Functions

compliance_markup::compliance_map

Global Options

Custom Content

compliance_markup::compliance_map(Hash $map_data)

map_data

compliance_markup::compliance_map(Variant[String[1], Array[String[1]]] $compliance_profile, Variant[String[1], Array[String[1]]] $identifiers, Optional[String[1]] $notes)

compliance_profile

identifiers

notes

compliance_markup::enforcement

compliance_markup::enforcement(String $key, Hash $options, Puppet::LookupContext $context)

key

options

context

compliance_markup::loaded_maps

compliance_markup::loaded_maps()

compliance_markup::telemetry

compliance_markup::telemetry(String $key)

key

`compliance_map`

`validate_profiles`

`report_types`

`report_format`

`report_on_client`

`report_on_server`

`server_report_dir`

`custom_report_entries`

`options`

`custom_report_data`

`options`

`compliance_markup::compliance_map(Hash $map_data)`

`map_data`

`compliance_markup::compliance_map(Variant[String[1], Array[String[1]]] $compliance_profile, Variant[String[1], Array[String[1]]] $identifiers, Optional[String[1]] $notes)`

`compliance_profile`

`identifiers`

`notes`

`compliance_markup::enforcement(String $key, Hash $options, Puppet::LookupContext $context)`

`key`

`options`

`context`

`compliance_markup::loaded_maps()`

`compliance_markup::telemetry(String $key)`

`key`