abide_dev_utils 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75678bc1c177a3187619cfec9d2c25e566b08d91439c3b46c578c4202f4d9a7c
-  data.tar.gz: f9749e6c8ad3d5b0439a8fe0fd03ba3ea91e5c0052057eea43b3862c08b45fbd
+  metadata.gz: d9e993f8a435b4be58831bc98cf1658533c8c1084f14c96c1a12ecd73ff89da6
+  data.tar.gz: 1120b6cc91eac28ff8168e808f13c16cf6c6d844b5928f04f4f4bb6d7cda0bcb
 SHA512:
-  metadata.gz: 97ba4b3b0898a40ed6df3facaf3aa03beb2d1375d61e1915c6566e107e6edffa083ab7af93827c2679c14a2503504cafd40d9275b12708f582c3723953b5c9c7
-  data.tar.gz: 2680eb354112e27223d590a645318ea14c4988dd0e331bf5a5f3b347402ead6398c8c07c1b7ded55704d76011522ff790459cf40452ceba8ca15dc2a19a76a7a
+  metadata.gz: bcf0b6aa95f003e5402be98cc797202949368ceff62e6cdb778f4002e452716ef5ef833bc0bcd34bb797f628997e1c807d88f191048a5afec767bd8bcb7dc7a3
+  data.tar.gz: 2ca0b4fb33d0329f13e3ce04d317427b4ba67c9937b4df739d991a1692871d19c17d1eeb24d5035573a676560795ae466e6df65148693258718aeda115c9e1d8

data/README.md

@@ -2,15 +2,48 @@
 
 Helper library and CLI app for Abide development.
 
+## 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
+
+### Supports Configuration via Local YAML file
+
+* Fully configurable via the `~/.abide_dev.yaml` file
+
 ## Installation
 
 ### CLI app
 
-```sh
-$ gem install abide_dev_utils
-...
-$ abide -h
-```
+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:
 
@@ -26,9 +59,159 @@ 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
 
-Coming soon, in the mean time run `abide -h` and `abide [command] -h` for help.
+* `abide -h` - CLI top-level help menu
+* `abide <command> -h` - Command-specific help menu
+
+### Overview of Commands
+
+* `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
+
+### 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.
+
+`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
+
+```text
+# @api private
+class <%= @obj_name %> (
+  Boolean $enforce = true,
+  Hash $config = {},
+) {
+  if $enforce {
+    warning('Class not implemented yet')
+  }
+}
+
+```
+
+* util_class.erb
+
+```text
+class <%= @obj_name %> (
+<% if @vars.key?('testvar1') -%>
+  $testparam1 = '<%= @vars['testvar1'] %>',
+<% else -%>
+  $testparam1 = undef,
+<% end -%>
+) {
+  file { $testparam1:
+    ensure => file,
+    mode   => '<%= @vars.fetch('testvar2', '0644') %>',
+  }
+}
+
+```
+
+```text
+$ 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
+$ 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
+$ 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',
+  }
+}
+
+```
+
+### XCCDF Command Reference
+
+#### to_hiera
+
+* 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
 
 ## Development
 

data/lib/abide_dev_utils/cli/abstract.rb

@@ -3,7 +3,7 @@
 module Abide
   module CLI
     # @abstract
-    class Command < CmdParse::Command
+    class AbideCommand < CmdParse::Command
       include AbideDevUtils::Config
       def initialize(cmd_name, cmd_short, cmd_long, **opts)
         super(cmd_name, **opts)

data/lib/abide_dev_utils/cli/puppet.rb

@@ -4,7 +4,7 @@ require 'abide_dev_utils/cli/abstract'
 
 module Abide
   module CLI
-    class PuppetCommand < Command
+    class PuppetCommand < AbideCommand
       CMD_NAME = 'puppet'
       CMD_SHORT = 'Commands related to Puppet code'
       CMD_LONG = 'Namespace for commands related to Puppet code'
@@ -15,7 +15,7 @@ module Abide
       end
     end
 
-    class PuppetCoverageCommand < Command
+    class PuppetCoverageCommand < AbideCommand
       CMD_NAME = 'coverage'
       CMD_SHORT = 'Generates control coverage report'
       CMD_LONG = 'Generates report of valid Puppet classes that match with Hiera controls'
@@ -53,7 +53,7 @@ module Abide
       end
     end
 
-    class PuppetNewCommand < Command
+    class PuppetNewCommand < AbideCommand
       CMD_NAME = 'new'
       CMD_SHORT = 'Generates a new Puppet object from templates'
       CMD_LONG = 'Generates a new Puppet object (class, test, etc.) from templates stored in the module repo'

data/lib/abide_dev_utils/ppt/new_obj.rb

@@ -12,36 +12,16 @@ module AbideDevUtils
 
       def initialize(obj_type, obj_name, opts: {}, vars: {})
         @obj_type = obj_type
-        @obj_name = obj_name.split(':').reject(&:empty?).join('::') # removes 
-        @obj_basename = obj_name.split('::')[-1]
-        @root_dir = Pathname.new(opts.fetch(:root_dir, Dir.pwd))
-        @tmpl_dir = if opts.fetch(:absolute_template_dir, false)
-                      opts.fetch(:tmpl_dir)
-                    else
-                      "#{@root_dir}/#{opts.fetch(:tmpl_dir, 'object_templates')}"
-                    end
-        @tmpl_name = opts.fetch(:tmpl_name, "#{@obj_type}.erb")
-        @tmpl_path = Pathname.new("#{@tmpl_dir}/#{@tmpl_name}")
-        @type_path_map = opts.fetch(:type_path_map, {})
+        @obj_name = namespace_format(obj_name)
+        @opts = opts
         @vars = vars
+        class_vars
+        validate_class_vars
       end
 
-      def obj_path
-        case @obj_type
-        when 'class'
-          obj_path_from_name
-        else
-          custom_obj_path
-        end
-      end
-
-      def template?
-        @tmpl_path.file?
-      end
+      attr_reader :obj_type, :obj_name, :tmpl_name, :root_dir, :tmpl_dir, :tmpl_path, :type_path_map, :obj_path, :vars
 
       def render
-        raise AbideDevUtils::Errors::Ppt::TemplateNotFoundError, @tmpl_path.to_s unless template?
-
         ERB.new(File.read(@tmpl_path.to_s), 0, '<>-').result(binding)
       end
 
@@ -79,34 +59,69 @@ module AbideDevUtils
 
       private
 
+      def class_vars
+        @tmpl_name = @opts.fetch(:tmpl_name, "#{@obj_type}.erb")
+        @root_dir = Pathname.new(@opts.fetch(:root_dir, Dir.pwd))
+        @tmpl_dir = if @opts.fetch(:absolute_template_dir, false)
+                      @opts.fetch(:tmpl_dir)
+                    else
+                      "#{@opts.fetch(:root_dir, Dir.pwd)}/#{@opts.fetch(:tmpl_dir, 'object_templates')}"
+                    end
+        @tmpl_path = Pathname.new("#{@tmpl_dir}/#{@opts.fetch(:tmpl_name, "#{@obj_type}.erb")}")
+        @type_path_map = @opts.fetch(:type_path_map, {})
+        @obj_path = new_obj_path
+      end
+
+      def validate_class_vars
+        raise AbideDevUtils::Errors::PathNotDirectoryError, @root_dir unless Dir.exist? @root_dir
+        raise AbideDevUtils::Errors::PathNotDirectoryError, @tmpl_dir unless Dir.exist? @tmpl_dir
+        raise AbideDevUtils::Errors::Ppt::TemplateNotFoundError, @tmpl_path.to_s unless @tmpl_path.file?
+      end
+
+      def basename(obj_name)
+        obj_name.split('::')[-1]
+      end
+
+      def new_obj_path
+        if obj_type == 'class'
+          obj_path_from_name
+        else
+          custom_obj_path
+        end
+      end
+
+      def namespace_format(name)
+        name.split(':').reject(&:empty?).join('::')
+      end
+
       def obj_path_from_name
         parts = @obj_name.split('::')[1..-2]
         parts.insert(0, 'manifests')
-        parts.insert(-1, "#{@obj_basename}#{DEFAULT_EXT}")
+        parts.insert(-1, "#{basename(@obj_name)}#{DEFAULT_EXT}")
         path = @root_dir + Pathname.new(parts.join('/'))
         path.to_s
       end
 
       def custom_obj_path
-        map_val = @type_path_map.fetch(@obj_type.to_sym, nil)
+        map_val = type_path_map.fetch(@obj_type.to_sym, nil)
         return obj_path_from_name if map_val.nil?
 
         if map_val.respond_to?(:key?)
-          custom_obj_path_from_hash(map_val)
+          custom_obj_path_from_hash(map_val, @obj_name)
         else
           abs_path = Pathname.new(map_val).absolute? ? map_val : "#{Dir.pwd}/#{map_val}"
-          "#{abs_path}/#{@obj_basename}#{DEFAULT_EXT}"
+          "#{abs_path}/#{basename(@obj_name)}#{DEFAULT_EXT}"
         end
       end
 
-      def custom_obj_path_from_hash(map_val)
+      def custom_obj_path_from_hash(map_val, obj_name)
         raise AbideDevUtils::Errors::Ppt::CustomObjPathKeyError, map_val unless map_val.key?(:path)
 
         abs_path = Pathname.new(map_val[:path]).absolute? ? map_val[:path] : "#{Dir.pwd}/#{map_val[:path]}"
         if map_val.key?(:extension)
-          "#{abs_path}/#{@obj_basename}#{map_val[:extension]}"
+          "#{abs_path}/#{basename(obj_name)}#{map_val[:extension]}"
         else
-          "#{abs_path}/#{@obj_basename}#{DEFAULT_EXT}"
+          "#{abs_path}/#{basename(obj_name)}#{DEFAULT_EXT}"
         end
       end
     end

data/lib/abide_dev_utils/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AbideDevUtils
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/abide_dev_utils/xccdf/cis/hiera.rb

@@ -25,6 +25,7 @@ module AbideDevUtils
             relative_select: './xccdf:select'
           }
         }.freeze
+        NEXT_GEN_WINDOWS = /(next_generation_windows_security)/.freeze
 
         attr_reader :title, :version
 
@@ -111,11 +112,19 @@ module AbideDevUtils
         end
 
         def normalize_str(str)
-          str.delete('-').gsub(/\s/, '_').downcase
+          nstr = str.downcase
+          nstr.gsub!(/[^a-z]$/, '')
+          nstr.gsub!(/^[^a-z]/, '')
+          nstr.gsub!(/^(l1_|l2_|ng_)/, '')
+          nstr.delete!('-')
+          nstr.gsub!(/(\s|\(|\))/, '_')
+          nstr
         end
 
         def normalize_profile_name(prof)
-          normalize_str("profile_#{prof}")
+          prof_name = normalize_str("profile_#{prof}")
+          prof_name.gsub!(NEXT_GEN_WINDOWS, 'ngws')
+          prof_name
         end
 
         def normalize_ctrl_name(ctrl)
@@ -125,12 +134,10 @@ module AbideDevUtils
 
         def make_parent_key(doc, prefix)
           doc_title = normalize_str(doc.xpath(XPATHS[:benchmark][:title]).children.to_s)
-          if prefix.nil?
-            doc_title
-          else
-            sepped_prefix = prefix.end_with?('::') ? prefix : "#{prefix}::"
-            "#{sepped_prefix.chomp}#{doc_title}"
-          end
+          return doc_title if prefix.nil?
+
+          sepped_prefix = prefix.end_with?('::') ? prefix : "#{prefix}::"
+          "#{sepped_prefix.chomp}#{doc_title}"
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abide_dev_utils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Heston Snodgrass
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-16 00:00:00.000000000 Z
+date: 2021-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri