Version information
This version is compatible with:
- ,
Start using this module
Add this module to your Puppetfile:
mod 'simp-compliance_markup', '1.0.1'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with compliance_markup
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
Overview
This module adds a function compliance_map()
to the Puppet language. The
compliance_map()
function provides the ability for users to compare their
in-scope class parameters against a set of compliant parameters, either in
Hiera or at the global scope. Users may also provide custom inline policy
documentation and mapping documentation.
The goal of this module is to make it easier for users to both detect, and report on, deviations from a given policy inside their Puppet codebase.
Module Description
This module provides the function compliance_map()
and does not provide any
manifest code.
Setup
What compliance_markup affects
Presently, the compliance_map()
function will create a File resource
targeting Puppet[:vardir]/compliance_report.yaml
. It may, in the future,
create a file on the server and/or upload materials directly to PuppetDB.
Usage
This function provides a mechanism for mapping compliance data to settings in Puppet.
It is primarily designed for use in classes to validate that parameters are properly set.
When called, the parameters in the calling class will be evaluated against top level parameters or Hiera data, in that order.
The variable space against which the class parameters will be evaluated must be structured as the following hash:
compliance::<compliance_profile>::<class_name>::<parameter> :
'identifier' : '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::nist_800_53::ssh::permit_root_login :
'identifier' : 'CCE-1234'
'value' : false
Alternatively, you may add compliance data 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.
The following optional parameters may be used to add your own compliance data:
:compliance_profile => 'A String, or Array, that denotes the compliance
profile(s) to which you are mapping.'
:identifier => 'A unique identifier String for the policy to which you
are mapping.'
:notes => 'An *optional* String that allows for arbitrary notes to
include in the compliance report'
Reference
Example 1 - Standard Usage
Manifest
class foo (
$var_one => 'one',
$var_two => 'two'
) {
# This will validate all parameters
compliance_map()
}
$compliance_profile = 'my_policy'
include 'foo'
Hiera.yaml
:backends:
- 'yaml'
:yaml:
:datadir: '/path/to/your/hieradata'
:hierarchy:
"compliance_profiles/%{compliance_profile}"
"global"
Hieradata
---
# In file /path/to/your/hieradata/compliance_profiles/my_policy.yaml
compliance::my_policy::foo::var_one :
'identifier' : 'CCE-1234'
'value' : 'not one'
Example 2 - Custom Compliance Map
if $::circumstance {
compliance_map('nist_800_53','CCE-1234','Note about this section')
...code that applies CCE-1234...
}
Limitations
Depending on the version of Puppet being used, the compliance_map()
function
may not be able to precisely determine where the function has been called and a
best guess may be provided.
Development
Patches are welcome to the code on the Onyx Point Github account. If you provide code, you are guaranteeing that you own the rights for the code or you have been given rights to contribute the code.
Acceptance tests
To run the tests for this module perform the following actions after installing
bundler
:
bundle update
bundle exec rake acceptance
Packaging
Running rake pkg:rpm[...]
will develop an RPM that is designed to be
integrated into a SIMP environment. This module is
not restricted to, or dependent on, the SIMP environment in any way.
2016-09-28 Release 1.0.1
- Move GitHub org from
onyxpoint
tosimp
2016-03-07 Release 1.0.0
- Move Forge org from
onyxpoint
tosimp
- Provide Ruby 1.8.7 compatibility
- Ensure that a report is written on every run.
- Updated to properly handle the hash references
2015-12-07 Release 0.1.0
- Initial Release
Copyright 2015 - Onyx Point, Inc. Project Structure based on the SIMP puppet-module-skeleton project from https://github.com/simp/puppet-module-skeleton Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.