Skip to content

Latest commit

 

History

History
489 lines (319 loc) · 13.5 KB

REFERENCE.md

File metadata and controls

489 lines (319 loc) · 13.5 KB

Reference

Table of Contents

Classes

Defined types

Functions

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_data

Data type: Optional[Hash]

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

Default value: undef

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

Defined types

compliance_markup::map

phase of the catalog compile.

Defines appear to be run after all classes

Parameters

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

options

Data type: Hash

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

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>:: : '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 only 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... }

Puppet::Functions.create_function(:'compliance_markup::compliance_map') do

compliance_markup::compliance_map(Hash $map_data)

The compliance_markup::compliance_map function.

Returns: Nil

map_data

Data type: Hash

The full Hash of mapping data

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: Nil

compliance_profile

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

Denotes the compliance profile(s) to which you are mapping

identifiers

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

A unique identifier for the policy to which you are mapping

notes

Data type: Optional[String[1]]

Allows for arbitrary notes to include in the compliance report

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

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'

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: Nil