AbideDevUtils

Helper library and CLI app for Abide development.

Issues and pull requests are welcome!

Features

CLI

• Type abide -h to see the CLI help menu
• All commands have help menus
• Tested on MacOS, should also work on Linux

PDK-like manifest generation from local ERB templates

• Create a directory in your module called object_templates to hold ERB files
• Generate manifests from those ERB files

XCCDF to Hiera conversion

• Convert the contents of an XCCDF XML file to Hiera

Coverage Reporting

• Generate a coverage report (i.e. how many CIS controls are covered by classes in your module)

Jira Integration

• Create Jira issues in bulk from coverage reports

Puppet Comply Report Generation

• Allows you ot programatically generate compliance reports from Puppet Comply

Supports Configuration via Local YAML file

• Fully configurable via the ~/.abide_dev.yaml file

Installation

CLI app

Install from RubyGems:

gem install abide_dev_utils

Then to access the help menu:

abide -h

As a dependency

Add this line to your application's Gemfile:

gem 'abide_dev_utils'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install abide_dev_utils

Build it yourself

Clone this repo:

git clone <this repo>

Build the gem:

bundle exec rake build

The gem will be located at pkg/<gem file>

Install the gem:

gem install pkg/<gem file>

Usage

• abide -h - CLI top-level help menu
• abide <command> -h - Command-specific help menu

Overview of Commands

• abide comply - Command namespace for Puppet Comply commands
  • abide comply report - Creates a scan report in YAML format by scraping Puppet Comply
• abide jira - Command namespace for Jira commands
  • abide jira auth - Authenticate with Jira. Only useful as a stand-alone command to test authentication
  • abide jira from_coverage - Creates a parent issue with subtasks from a Puppet coverage report
  • abide jira get_issue - Gets a specific Jira issue
  • abide jira new_issue - Creates a new Jira issue
• abide puppet - Command namespace for Puppet commands
  • abide puppet coverage - Generate a "coverage" report. This examines how many manifests you have in your Puppet module versus how many CIS controls exist in the local Hiera data and gives you a breakdown of what percentage of the selected CIS benchmark / profile you have successfully covered.
  • abide puppet new - Generate a new manifest from a local ERB template. Functions similar to pdk new except you can create arbitrary manifests.
• abide test - BUGGED Runs a module's test suite. Currently has issues with local gem environments.
• abide xccdf - Command namespace for XCCDF commands
  • abide xccdf to_hiera - Converts a benchmark XCCDF file to a Hiera yaml file

Comply Command Reference

report

• Required positional parameters:
  • COMPLY_URL - The URL of Puppet Comply
  • COMPLY_PASSWORD - The password for the Puppet Comply user
• Options:
  • --out-file, -o - The path to save the scan report. Defaults to ./comply_scan_report.yaml
  • --username, -u - The Puppet Comply username. Defaults to comply
  • --status, -s - A comma-separated list of check statuses to ONLY include in the report. Valid statuses are: pass, fail, error, notapplicable, notchecked, unknown, informational
  • --only, -O - A comma-separated list of node certnames to ONLY build reports for. No other nodes will have reports built for them except the ones specified. This option is mutually exclusive with --ignore and, if both are set, this options will take precedence over --ignore.
  • --ignore, -I - A comma-separated list of node certnames to ignore building reports for. This options is mutually exclusive with --only and, if both are set, --only will take precedence over this option.

Examples:

Generating a report of all failed and err'd scan checks

abide comply report https://comply.my.instance 'my_comply_password!' -s fail,error

Generating a report for certain nodes only

abide comply report https://comply.my.instance 'my_comply_password!' -O specific-node.my.instance

Jira Command Reference

from_coverage

• Required positional parameters:
  • REPORT - A path to a JSON file generated by the abide puppet coverage command
  • PROJECT - A Jira project code. This is typically an all-caps abbreviation of a Jira project
• Options:
  • --dry-run, -d - Prints the results of this command to the console instead of actually creating Jira issues

Puppet Command Reference

coverage

• Required positional parameters:
  • CLASS_DIR - The path to the directory in your module that holds manifests named after the benchmark controls
  • HIERA_FILE - The path to the Hiera file generated by the abide xccdf to_hiera command
• Options:
  • --out-file, -o - The path to save the coverage report JSON file
  • --profile, -p - A benchmark profile to generate the report for. By default, generates the report for all profiles

new

• Required positional parameters:
  • TYPE - The type of object you would like to generate. This value is the name of an ERB template without .erb located in your template directory
  • NAME - The fully namespaced name of the new object. Subdirectories will be automatically created within manifests based on the namespacing of this parameter if the directories do not exist.
• Options:
  • --template-dir, -t - Name of the template directory relative to your module's root directory. Defaults to object_templates
  • --root-dir, -r - Path to the root directory of your module. Defaults to the current working directory
  • --absolute-template-dir, -A - Allows you to specify an absolute path with --template-dir. This is useful if your template directory is not relative to your module's root directory
  • --template-name, -n - Allows you to specify a template name if it is different than the TYPE parameter
  • --vars, -V - Comma-separated key=value pairs to pass in to the template renderer. This allows you to pass arbitrary values that can be used in your templates.
  • --spec-template, -S - Path to an ERB template to use for rspec test generation instead of the default
  • --force, -f - Skips any prompts and executes the command

abide puppet new exposes a few variables for you to use in your templates by default:

• @obj_name - The value of the NAME parameter passed into the command
• @vars - A hash of any key=value pairs you passed into the command using --vars

Examples:

Lets assume we have a module at ~/test_module and we have a directory in that module called object_templates. In the template directory, we have two ERB template files: control_class.erb and util_class.erb.

• control_class.erb

# @api private
class <%= @obj_name %> (
  Boolean $enforce = true,
  Hash $config = {},
) {
  if $enforce {
    warning('Class not implemented yet')
  }
}

• util_class.erb

class <%= @obj_name %> (
<% if @vars.key?('testvar1') -%>
  $testparam1 = '<%= @vars['testvar1'] %>',
<% else -%>
  $testparam1 = undef,
<% end -%>
) {
  file { $testparam1:
    ensure => file,
    mode   => '<%= @vars.fetch('testvar2', '0644') %>',
  }
}

$ cd ~/test_module
$ ls object_templates
control_class.erb  util_class.erb
$ ls manifests
init.pp
$ abide puppet new control_class 'test_module::controls::test_new_control'
Created file /Users/the.dude/test_module/manifests/controls/test_new_control.pp
Created file /Users/the.dude/test_module/spec/classes/controls/test_new_control_spec.rb
$ abide puppet new util_class 'test_module::utils::test_new_util' -v 'testvar1=dude,testvar2=sweet'
Created file /Users/the.dude/test_module/manifests/utils/test_new_util.pp
Created file /Users/the.dude/test_module/spec/classes/utils/test_new_util_spec.rb
$ cat manifests/controls/test_new_control.pp
# @api private
class test_module::controls::test_new_control (
  Boolean $enforce = true,
  Hash $config = {},
) {
  if $enforce {
    warning('Class not implemented yet')
  }
}

$ cat manifests/utils/test_new_util.pp
class test_module::utils::test_new_util (
  $testparam1 = 'dude',
) {
  file { 'dude':
    ensure => file,
    mode   => 'sweet',
  }
}

NOTE: You can use two special prefixes on your template files to denote where the rspec test should be generated for that object. If the prefix c- is used, the test will be generated in the spec/classes directory. If the prefix d- is used, the test will be generated in the spec/defines directory. For example, to create a template for a defined type, name the template something like this: d-my_defined_type.pp.erb.

XCCDF Command Reference

to_hiera

NOTE: When converting XCCDF files to Hiera, control names are sanitized. This means that some characters will be changed to ensure the resulting control names in the Hiera file are valid for both YAML and Puppet class names. Here's what gets changed:

• All letters are coverted to lower case

• The first and last characters of the control name is dropped if they are not letters (a-z)

• If a control name has a prefix of l1_, l2_, or ng_, that prefix is dropped

  • Differentiation between profile level occurs outside of control names

• The characters / and \ are deleted. This means that paths are smashed together

• Whitespace and the characters (, ), ., and - are substituted with underscores (_)

• Required positional parameters:

  • XCCDF_FILE - Path to an XCCDF XML file

• Options:

  • --benchmark-type, -b - The type of benchmark. Defaults to cis
  • --out-file, -o - A path to a file where you would like to save the generated Hiera
  • --parent-key-prefix, -p - Allows you to append a prefix to all top-level Hiera keys

Docker

A Dockerfile has been provided in this repo for convenience since Ruby environments can be painful to deal with. To abide_dev_utils with Docker:

• Build the Dockerfile: docker build . -t abide_dev_utils --build-arg version=<semver>
• Run the commands using the container: docker run -it abide_dev_utils --help
• The container declares a volume for external resources such as files. To use the volume, add the following flag to your docker run commands: -v /path/to/my/files:/extvol
  • When using the volume, all paths should be absolute based on the root directory /extvol

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hsnodgrass/abide_dev_utils.

License

The gem is available as open source under the terms of the MIT License.