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_engine::enforcement parameter to indicate the profile should be used during enforcement. 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 the 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 in Data Examples.

Validating Data with the JSON Schema¶

The compliance_engine gem ships a JSON Schema (draft 2020-12) describing the SCE data format. Any schema-aware tool can validate your compliance data files against it. The schema's location can be printed with:

ruby -r compliance_engine -e 'puts ComplianceEngine.schema_path'

For example, using check-jsonschema (which accepts YAML instances directly):

check-jsonschema \
    --schemafile "$(ruby -r compliance_engine -e 'print ComplianceEngine.schema_path')" \
    SIMP/compliance_profiles/*.yaml

All of the data examples in this documentation validate against the shipped schema.

Hiera Backend Reference¶

The compliance_engine gem provides a Hiera 5 backend implemented as the compliance_engine::enforcement lookup function. It discovers compliance data from every module on the environment's modulepath (see Puppet Integration).

To activate it, add the following to your environment's hiera.yaml:

---
version: 5
hierarchy:
  - name: "SIMP Compliance Engine"
    lookup_key: "compliance_engine::enforcement"
    # All options are optional
    options:
      # Also honor the legacy compliance_markup::* Hiera keys during a
      # migration from the compliance_markup module
      compliance_markup_compatibility: true
      # Default enforcement tolerance (can also be set per-node with the
      # compliance_engine::enforcement_tolerance Hiera key)
      enforcement_tolerance: 40

Hiera Keys¶

The backend reads the following keys from your Hiera data:

Key	Data type	Description
`compliance_engine::enforcement`	array of strings	The compliance profiles to enforce, in order from highest priority to lowest.
`compliance_engine::compliance_map`	hash	Inline compliance data in the SCE data format, merged with the data discovered in modules. Useful for profile customization.
`compliance_engine::enforcement_tolerance`	integer	Risk-tolerance threshold for enforcement. Overrides the backend's `enforcement_tolerance` option.

Migrating from `compliance_markup`¶

The legacy compliance_markup Puppet module has been replaced by the compliance_engine gem. With the compliance_markup_compatibility backend option enabled, the old keys continue to work during a migration:

Legacy key	Replacement	Compatibility behavior
`compliance_markup::enforcement`	`compliance_engine::enforcement`	Both lists are merged (union, duplicates removed).
`compliance_markup::compliance_map`	`compliance_engine::compliance_map`	Both hashes are deep-merged; the new key wins on conflicts.
`compliance_markup::enforcement_tolerance_level`	`compliance_engine::enforcement_tolerance`	Legacy key is used only when the new key is unset. Note the name change: `_level` is dropped.

The following compliance_markup features were part of the module's reporting class and have no equivalent in compliance_engine, which is a Hiera backend only (see Reporting):

the compliance_markup Puppet class and its parameters (validate_profiles, report_types, report_format, report_on_client, report_on_server, server_report_dir, custom_report_data, options)
the compliance_markup::map defined type
the compliance_markup::compliance_map(), compliance_markup::loaded_maps(), and compliance_markup::telemetry() functions

Debug lookups (compliance_engine::debug::*) are planned but not yet implemented — do not rely on them.

Command Line Interface¶

The gem installs a compliance_engine command that can inspect compliance data without a Puppet run.

Command	Description
`compliance_engine hiera --profile PROFILE [PROFILE ...]`	Dump the Hiera data produced by enforcing the given profile(s).
`compliance_engine lookup KEY --profile PROFILE [PROFILE ...]`	Look up a single Hiera key for the given profile(s).
`compliance_engine profiles`	List available profiles. Note: only profiles that reference CEs or Controls are listed; profiles containing only `checks` entries are not shown.
`compliance_engine dump`	Dump all discovered compliance data, per source file.
`compliance_engine version`	Print the gem version.
`compliance_engine inspect`	Start an interactive Ruby shell with the loaded data.

Global options:

Option	Description
`--module PATH [PATH ...]`	Load compliance data from individual module directories.
`--modulepath PATH [PATH ...]`	Load compliance data from every module on a modulepath.
`--modulezip FILE`	Load compliance data from a zipped Puppet environment.
`--facts JSON`	Facts (as a JSON string) used to evaluate `confine` blocks.
`--enforcement-tolerance N`	Risk-tolerance threshold used when resolving data.
`--verbose` / `--debug`	Increase log output.

Examples:

# List the profiles available on a modulepath
compliance_engine profiles \
    --modulepath /etc/puppetlabs/code/environments/production/modules

# Show the Hiera data that enforcing a profile would produce
compliance_engine hiera --profile cis:level:1:server \
    --modulepath /etc/puppetlabs/code/environments/production/modules

# Look up a single key for a profile
compliance_engine lookup simp::sysctl::kernel__randomize_va_space \
    --profile cis:level:1:server \
    --modulepath /etc/puppetlabs/code/environments/production/modules