cem_spec_helper 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 958824c04b72632cdae95ca8d81696f8fb2e350136fec56b77956f0a447b1d3f
-  data.tar.gz: 9417760548af44edcab45a1630a99376711e0d70a9d8df503351db20c1a7b746
+  metadata.gz: c25d50ec3d0761a950dfd6ddfa13e2b0fa23bf560719ae876af59a6936763a0d
+  data.tar.gz: cca59a9b38dd4d71159ed5d2470c7bac58ba22b1bc31e7b5401e56f74a4124d2
 SHA512:
-  metadata.gz: 1b7f14db0527bba11b2e1fa9074a74e4cde1f73221b00333c0629db4452bd22a10517713f90b9d8ac1711f0f06611377d8392ed7999448d8c457dd78c4ce99e9
-  data.tar.gz: e16599f307d82bc98d5298d60ebfe6f97103dee035170b874e454f0ca3d01ac2327256fc6e61027657f966e529eb899ddbf5e38dae0ac1204e5cb5ee55713589
+  metadata.gz: 37c4136b44f120e95966409d55821c4bc7ab19af6b89951579fbac086b1882cacd36af971af24e9df2697b5222a92395fce90e1d16e9bfa3a2558aa2250bc2b6
+  data.tar.gz: db3690625195985e32e4585511cecd646127878cefd85ee7a9d4d12ed4b9422c49f5c7494f0404e2d758949e0693d5404540c3c84a5e01036addc9f325843e17

data/lib/cem_spec_helper/mapping_data_spec.rb

@@ -4,10 +4,30 @@ require 'yaml'
 
 module CemSpecHelper
   module MappingDataSpec
+    # The root directory for mapping data fixtures
     MAP_ROOT = File.join(Dir.pwd, 'spec', 'fixtures', 'data', 'mapping').freeze
+    # The root directory for synthetic mapping data
     SYNTHETIC_MAP_ROOT = File.join(Dir.pwd, 'spec', 'fixtures', 'unit', 'puppet_x', 'puppetlabs', 'cem', 'data_processor', 'mapping').freeze
-
+    # The key prefix for the mappings
+    MAPPINGS_KEY = "#{CemSpecHelper::MODULE_NAME}::mappings"
+    # The top key types for each framework.
+    TOP_KEY_TYPES = {
+      'cis' => ['hiera_title', 'hiera_title_num', 'number', 'title'].freeze,
+      'stig' => ['vulnid', 'ruleid'].freeze,
+    }.freeze
+
+    # Because of the slight variation in the directory structure for Windows, we need to
+    # load the mapping data differently for Windows than for Linux.
+    # @return [Array<Mapping>] An array of Mapping objects
     def load_mapping_data
+      return load_windows_mapping_data if CemSpecHelper::MODULE_NAME.match?(/windows$/)
+
+      load_linux_mapping_data
+    end
+
+    # Load the mapping data for Linux
+    # @return [Array<Mapping>] An array of Mapping objects
+    def load_linux_mapping_data
       # Get frameworks with maps
       Dir[File.join(MAP_ROOT, '*')].each_with_object([]) do |fw_dir, arr|
         framework = File.basename(fw_dir)
@@ -29,6 +49,28 @@ module CemSpecHelper
       end
     end
 
+    # Load the mapping data for Windows
+    # @return [Array<Mapping>] An array of Mapping objects
+    def load_windows_mapping_data
+      # Get frameworks with maps
+      Dir[File.join(MAP_ROOT, '*')].each_with_object([]) do |fw_dir, arr|
+        framework = File.basename(fw_dir)
+        # Get OS major versions in frameworks
+        Dir[File.join(fw_dir, '*')].each do |ver_dir|
+          ver = File.basename(ver_dir)
+          mapping = Mapping.new(framework, 'windows', ver)
+          # Get map names and load map files
+          Dir[File.join(ver_dir, '*.yaml')].each do |map_file|
+            map_type = File.basename(map_file, '.yaml')
+            mapping.add_map(map_type, map_file)
+          end
+          arr << mapping
+        end
+      end
+    end
+
+    # Load the synthetic mapping data
+    # @return [Array<Mapping>] An array of Mapping objects
     def load_synthetic_mapping_data
       # Get frameworks with maps
       Dir[File.join(SYNTHETIC_MAP_ROOT, '*')].each_with_object([]) do |fw_dir, arr|
@@ -43,37 +85,74 @@ module CemSpecHelper
       end
     end
 
+    # Find the mapping data for a given framework, OS, and major OS version, and return the maps
+    # filtered by level and profile.
+    # @param framework [String] The framework to find the mapping data for
+    # @param os [String] The OS to find the mapping data for
+    # @param majver [String] The major OS version to find the mapping data for
+    # @param level [String] The level to filter the maps by. For STIG, this is the MAC.
+    # @param profile [String] The profile to filter the maps by. For STIG, this is the confidentiality.
+    # @return [Array<Hash>] An array of hashes representing the maps
+    def find_mapping_data(framework, os, majver = nil, level = 'level_1', profile = 'server')
+      majver = 1 if os == 'Synthetic'
+      md = (os == 'Synthetic') ? synthetic_mapping_data : mapping_data
+      md.find { |m| m.framework == framework && m.os == os && m.majver == majver.to_s }.maps
+        .map do |m|
+          top_key = TOP_KEY_TYPES[framework]&.find do |key|
+            m.key?("#{MAPPINGS_KEY}::#{framework}::#{key}")
+          end
+          raise "No top key found for #{framework}" if top_key.nil?
+
+          m["#{MAPPINGS_KEY}::#{framework}::#{top_key}"][level][profile]
+        end
+    end
+
+    # @return [Array<Mapping>] An array of Mapping objects
     def synthetic_mapping_data
       @synthetic_mapping_data ||= load_synthetic_mapping_data
     end
 
+    # @return [Array<Mapping>] An array of Mapping objects
     def mapping_data
       @mapping_data ||= load_mapping_data
     end
 
+    # This class represents a mapping of a framework, OS, and major OS version.
     class Mapping
       attr_reader :framework, :os, :majver, :module_name
 
-      def initialize(framework, os, majver, module_name: 'cem_linux')
+      # @param framework [String] The framework to create the mapping for
+      # @param os [String] The OS to create the mapping for
+      # @param majver [String] The major OS version to create the mapping for
+      def initialize(framework, os, majver)
         @framework = framework
         @os = os
         @majver = majver
-        @module_name = module_name
+        @module_name = CemSpecHelper::MODULE_NAME
         @maps = {}
       end
 
+      # @return [Array<Hash>] An array of hashes representing the maps
       def maps
         @maps.values
       end
 
+      # Add a map to the mapping
+      # @param type [String] The type of map to add
+      # @param map_file [String] The path to the map file to add
       def add_map(type, map_file)
         @maps[type] = YAML.load_file(map_file)
       end
 
+      # @return [Array<String>] An array of the map types
       def map_types
         @maps.keys
       end
 
+      # Verify that all the mappings have the same size
+      # @param keys_with_array_val [Hash] A hash of keys with array values
+      # @return [TrueClass] True if all the mappings have the same size
+      # @raise [RuntimeError] If the mappings do not have the same size
       def verify_map_size(keys_with_array_val = find_keys_with_array_val(@maps.dup))
         result = keys_with_array_val.each_with_object([]) do |(id, map), res|
           actual_length = 1 + map.length
@@ -84,6 +163,10 @@ module CemSpecHelper
         true
       end
 
+      # Verify that all mappings are one-to-one, or that there are no duplicate IDs shared between
+      # maps.
+      # @return [TrueClass] True if all mappings are one-to-one
+      # @raise [RuntimeError] If there are duplicate IDs shared between maps
       def verify_one_to_one
         results = @maps.keys.each_with_object([]) do |t, arr|
           keys_with_array_val = find_keys_with_array_val(@maps[t])
@@ -103,6 +186,7 @@ module CemSpecHelper
         true
       end
 
+      # @return [String] A string representation of the mapping
       def to_s
         "Mapping[#{framework}, #{os}, #{majver}]"
       end
@@ -110,7 +194,7 @@ module CemSpecHelper
       private
 
       def top_key(type)
-        [module_name, 'mappings', framework, type].join('::')
+        [MAPPINGS_KEY, framework, type].join('::')
       end
 
       def find_keys_with_array_val(hsh)

data/lib/cem_spec_helper/resource_data_spec.rb

@@ -4,25 +4,46 @@ require 'yaml'
 
 module CemSpecHelper
   module ResourceDataSpec
+    # The root directory for all resource data fixtures
     DATA_ROOT = File.join(Dir.pwd, 'spec', 'fixtures', 'data')
+    # The root directory for RedHat family resource data fixtures
     REDHAT_FAMILY_ROOT = File.join(DATA_ROOT, 'RedHat')
+    # The root directory for RedHat resource data fixtures
     REDHAT_ROOT_DIR = File.join(REDHAT_FAMILY_ROOT, 'RedHat')
+    # The major versions of RedHat resource data fixtures
     REDHAT_MAJVER = [7, 8].freeze
+    # The root directory for CentOS resource data fixtures
     CENTOS_ROOT_DIR = File.join(REDHAT_FAMILY_ROOT, 'CentOS')
+    # The major versions of CentOS resource data fixtures
     CENTOS_MAJVER = [7].freeze
+    # The root directory for OracleLinux resource data fixtures
     ORACLE_ROOT_DIR = File.join(REDHAT_FAMILY_ROOT, 'OracleLinux')
+    # The major versions of OracleLinux resource data fixtures
     ORACLE_MAJVER = [7, 8].freeze
+    # The root directory for AlmaLinux resource data fixtures
     ALMA_ROOT_DIR = File.join(REDHAT_FAMILY_ROOT, 'AlmaLinux')
+    # The major versions of AlmaLinux resource data fixtures
     ALMA_MAJVER = [8].freeze
+    # The root directory for Windows resource data fixtures
     WINDOWS_ROOT_DIR = File.join(DATA_ROOT, 'windows', 'windows')
+    # The major versions of Windows resource data fixtures
     WINDOWS_MAJVER = [10, 2016, 2019, 2022].freeze
-
+    # The root directory for synthetic resource data fixtures
     SYNTHETIC_DATA_ROOT = File.join(Dir.pwd, 'spec', 'fixtures', 'unit', 'puppet_x', 'puppetlabs', 'cem', 'data_processor')
-
+    # The special controls that are not mapped to a framework
     SPECIAL_CONTROLS = ['cem_options', 'cem_protected'].freeze
+    # The key prefix for the resources
+    RESOURCES_KEY = "#{CemSpecHelper::MODULE_NAME}::resources"
 
-    def find_resource_data(distro, majver = nil, as_objects: false)
-      case distro
+    # Finds and loads resource data for a given OS and major version
+    # @param osname [String] The name of the OS
+    # @param majver [String] The major version of the OS
+    # @param as_objects [Boolean] Whether or not to return the resource data as objects or hashes
+    # @return [Array<Hash>] An array of hashes containing the resource data
+    # @return [Array<Resource>] An array of Resource objects
+    # @raise [ArgumentError] If the OS name or major version is not found
+    def find_resource_data(osname, majver = nil, as_objects: false)
+      case osname
       when 'RedHat'
         redhat_resource_data(majver, as_objects: as_objects)
       when 'CentOS'
@@ -31,45 +52,66 @@ module CemSpecHelper
         oracle_resource_data(majver, as_objects: as_objects)
       when 'AlmaLinux'
         alma_resource_data(majver, as_objects: as_objects)
-      when 'Windows'
+      when /^[Ww]indows$/
         windows_resource_data(majver, as_objects: as_objects)
-      when 'Synthetic'
-        load_resource_data(SYNTHETIC_DATA_ROOT, 'test_resource_data', as_objects: as_objects)
+      when /^[Ss]ynthetic/
+        synthetic_resource_data(as_objects: as_objects)
       else
-        raise "Unknown distro: #{distro}"
+        raise "Unknown OS: #{osname}"
       end
     end
 
+    # Shortcut methods for loading resource data for a specific OS
+    # @param majver [String] The major version of the OS
+    # @param as_objects [Boolean] Whether or not to return the resource data as objects or hashes
+    # @return [Array<Hash>] An array of hashes containing the resource data
+    # @return [Array<Resource>] An array of Resource objects
+    # @raise [ArgumentError] If the major version is not found
     def redhat_resource_data(majver = nil, as_objects: false)
       raise ArgumentError, "major version #{majver} not found" unless majver.nil? || REDHAT_MAJVER.include?(majver.to_i)
 
       load_resource_data(REDHAT_ROOT_DIR, majver, as_objects: as_objects)
     end
 
+    # @param (see #redhat_resource_data)
+    # @return (see #redhat_resource_data)
+    # @raise (see #redhat_resource_data)
     def centos_resource_data(majver = nil, as_objects: false)
       raise ArgumentError, "major version #{majver} not found" unless majver.nil? || CENTOS_MAJVER.include?(majver.to_i)
 
       load_resource_data(CENTOS_ROOT_DIR, majver, as_objects: as_objects)
     end
 
+    # @param (see #redhat_resource_data)
+    # @return (see #redhat_resource_data)
+    # @raise (see #redhat_resource_data)
     def oracle_resource_data(majver = nil, as_objects: false)
       raise ArgumentError, "major version #{majver} not found" unless majver.nil? || ORACLE_MAJVER.include?(majver.to_i)
 
       load_resource_data(ORACLE_ROOT_DIR, majver, as_objects: as_objects)
     end
 
+    # @param (see #redhat_resource_data)
+    # @return (see #redhat_resource_data)
+    # @raise (see #redhat_resource_data)
     def alma_resource_data(majver = nil, as_objects: false)
       raise ArgumentError, "major version #{majver} not found" unless majver.nil? || ALMA_MAJVER.include?(majver.to_i)
 
       load_resource_data(ALMA_ROOT_DIR, majver, as_objects: as_objects)
     end
 
+    # @param (see #redhat_resource_data)
+    # @return (see #redhat_resource_data)
+    # @raise (see #redhat_resource_data)
     def windows_resource_data(majver = nil, as_objects: false)
       raise ArgumentError, "major version #{majver} not found" unless majver.nil? || WINDOWS_MAJVER.include?(majver.to_i)
 
       load_resource_data(WINDOWS_ROOT_DIR, majver, as_objects: as_objects)
     end
 
+    # Shortcut method for loading synthetic resource data
+    # @param as_objects [Boolean] Whether or not to return the resource data as objects or hashes
+    # @return (see #redhat_resource_data)
     def synthetic_resource_data(as_objects: false)
       load_resource_data(SYNTHETIC_DATA_ROOT, 'test_resource_data', as_objects: as_objects)
     end
@@ -78,10 +120,12 @@ module CemSpecHelper
     # @param distro [String]
     # @param majver [String]
     # @param benchmark [String] either cis or stig
+    # @param max [nil, Integer] maximum number of resources to return. If nil, returns all
     # @return [Hash] A hash of control_name => [resource type, resource title]
-    def single_control_resources(distro, majver = nil, benchmark = 'cis')
+    def single_control_resources(distro, majver = nil, benchmark = 'cis', max: nil)
       resources = find_resource_data(distro, majver, as_objects: true)
       resources.select! { |res| res.controls(include_special: false).length == 1 }
+      resources = max.nil? ? resources : resources.first(max)
       resources.map! do |res|
         [res.controls.first, [res.type, res.title]]
       end
@@ -96,34 +140,94 @@ module CemSpecHelper
       resources
     end
 
+    # Finds all resources that implement multiple controls
+    # @param distro [String]
+    # @param majver [String]
+    # @param benchmark [String] either cis or stig
+    # @param max [nil, Integer] maximum number of resources to return
+    # @return [Hash] A hash of control_name => [resource type, resource title]
+    def multi_control_resources(distro, majver = nil, benchmark = 'cis', max: nil)
+      resources = find_resource_data(distro, majver, as_objects: true)
+      resources.select! { |res| res.controls(include_special: false).length > 1 }
+      resources = max.nil? ? resources : resources.first(max)
+      resources.map! do |res|
+        [res.controls, [res.type, res.title]]
+      end
+      resources = resources.to_h
+      # Reduce to just benchmark-related keypairs
+      case benchmark
+      when 'cis'
+        resources.reject! { |k, _v| k.match?(%r{^V-}) }
+      when 'stig'
+        resources.select! { |k, _v| k.match?(%r{^V-}) }
+      end
+      resources
+    end
+
+    # Loads resource data from a given root directory and major version
+    # @param root_dir [String] The root directory to load resource data from
+    # @param majver [Integer, String, nil] The major version of the OS. If nil,
+    #   loads all resource data from the root directory.
+    # @param as_objects [Boolean] Whether or not to return the resource data as objects or hashes
+    # @return [Array<Hash>] An array of hashes containing the resource data
+    # @return [Array<Resource>] An array of Resource objects
+    # @return [Hash] A hash of found major versions => resource data arrays. Is only returned
+    #   if the majver parameter is nil.
+    # @raise [ArgumentError] If the root directory is not a valid path
+    # @raise [RuntimeError] If the resource data file is not found
     def load_resource_data(root_dir, majver = nil, as_objects: false)
-      raise "root_dir \"#{root_dir}\" is not a valid path" unless File.directory?(root_dir)
+      raise ArgumentError, "root_dir \"#{root_dir}\" is not a valid path" unless File.directory?(root_dir)
 
       unless majver.nil?
         file_path = File.join(root_dir, "#{majver}.yaml")
         raise "Resource data file \"#{file_path}\" not found" unless File.file?(file_path)
 
-        resources = YAML.load_file(file_path)['cem_linux::resources']
+        resources = YAML.load_file(file_path)[RESOURCES_KEY]
         final_resources = as_objects ? resources.map { |k, v| Resource.new(k, v) } : resources
         return final_resources
       end
 
       Dir[File.join(root_dir, '*')].each_with_object({}) do |rdata, hsh|
-        resources = YAML.load_file(rdata)['cem_linux::resources']
+        resources = YAML.load_file(rdata)[RESOURCES_KEY]
         final_resources = as_objects ? resources.map { |k, v| Resource.new(k, v) } : resources
         hsh[File.basename(rdata, '.yaml')] = final_resources
       end
     end
 
+    # Finds all controls in the given array of Resource objects
+    # @param rdata_objects [Array<Resource>] An array of Resource objects
+    # @return [Array<String>] An array of control names
+    def all_controls(rdata_objects)
+      rdata_objects.map(&:controls).flatten
+    end
+
+    # Finds all controls that are duplicated in the given array of Resource objects
+    # @param rdata_objects [Array<Resource>] An array of Resource objects
+    # @return [Array<String>] An array of control names
     def duplicate_controls(rdata_objects)
-      all_controls = rdata_objects.map(&:controls).flatten
+      all = all_controls(rdata_objects)
       # Lets go O(n^2) solution!
-      all_controls.select { |c| all_controls.count(c) > 1 }.reject { |c| SPECIAL_CONTROLS.include?(c) }.uniq
+      all.select { |c| all.count(c) > 1 }.reject { |c| SPECIAL_CONTROLS.include?(c) }.uniq
+    end
+
+    # Finds all controls that are not mapped in the given array of Resource objects and mapping data array
+    # @param rdata_objects [Array<Resource>] An array of Resource objects
+    # @param mdata_array [Array<Hash>] An array of hashes containing mapping data
+    # @return [Array<String>] An array of control names
+    def not_in_mapping_data(rdata_objects, mdata_array)
+      all = all_controls(rdata_objects)
+      mdata_array.compact.each do |m|
+        all -= m.keys
+      end
+      all.reject { |c| SPECIAL_CONTROLS.include?(c) }.uniq
     end
 
+    # The Resource class represents a single resource from the resource data file
     class Resource
       attr_reader :title, :type
 
+      # @param title [String] The title of the resource
+      # @param data [Hash] The resource data
       def initialize(title, data)
         @title = title
         @data = data
@@ -132,6 +236,8 @@ module CemSpecHelper
         @control_data = load_control_data
       end
 
+      # @return [Array<String>] An array of control names implemented by the resource
+      # @param include_special [Boolean] Whether or not to include special controls (cem_options, cem_protected)
       def controls(include_special: true)
         ctrls = @no_params ? @control_data : @control_data.keys
         return ctrls if include_special
@@ -139,12 +245,14 @@ module CemSpecHelper
         ctrls.reject { |c| SPECIAL_CONTROLS.include?(c) }
       end
 
+      # @return [Hash] A hash of parameter names => default values
       def params
         # rubocop:disable Style/CollectionMethods
         control_data.map { |_, v| v if v.is_a?(Hash) }.flatten.compact.uniq.inject(:merge)
         # rubocop:enable Style/CollectionMethods
       end
 
+      # @return [TrueClass, FalseClass] Whether or not the resource has any duplicate control names
       def verify_no_duplicate_controls
         controls.uniq == controls
       end

data/lib/cem_spec_helper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CemSpecHelper
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/cem_spec_helper.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+# This module is meant to be included in the spec_helper.rb file.
+# It is not meant to be used directly.
 module CemSpecHelper
+  MODULE_NAME = File.basename(Dir.pwd).gsub(/^puppetlabs-/, '')
+
   # Makes it so the CemSpecHelper module has to be included in the spec_helper.rb file.
   def self.included(base)
     require 'cem_spec_helper/mapping_data_spec'
@@ -8,10 +12,60 @@ module CemSpecHelper
     require 'cem_spec_helper/version'
 
     RSpec.configure do |config|
+      config.include CemSpecHelper::GeneralSpec
+      config.extend CemSpecHelper::GeneralSpec
       config.include CemSpecHelper::MappingDataSpec
       config.extend CemSpecHelper::MappingDataSpec
       config.include CemSpecHelper::ResourceDataSpec
       config.extend CemSpecHelper::ResourceDataSpec
     end
   end
+
+  module GeneralSpec
+    # The type of control ID used in the mapping data, resource data, or control configs.
+    # @param id [String] The control ID
+    # @param framework [String] The framework to use. If nil, will try both CIS and STIG.
+    # @return [Symbol] The type of control ID
+    def control_id_type(id, framework = nil)
+      case framework
+      when 'cis'
+        cis_control_id_type(id)
+      when 'stig'
+        stig_control_id_type(id)
+      else
+        # stig_control_id_type can return nil, cis_control_id_type will return 'title'
+        stig_control_id_type(id) || cis_control_id_type(id)
+      end
+    end
+
+    # The type of control ID used in the CIS mapping data, resource data, or control configs.
+    # @param id [String] The control ID
+    # @return (see #control_id_type)
+    def cis_control_id_type(id)
+      case id
+      when /^([0-9]\.)+/
+        :number
+      when /^[A-Za-z0-9_]+$/
+        :hiera_title
+      when /^c[0-9_]+$/
+        :hiera_title_num
+      else
+        :title
+      end
+    end
+
+    # The type of control ID used in the STIG mapping data, resource data, or control configs.
+    # @param id [String] The control ID
+    # @return (see #control_id_type)
+    def stig_control_id_type(id)
+      case id
+      when /^V-\d{6}$/
+        :vulnid
+      when /^SV-\d{6}r\d{6}_rule$/
+        :ruleid
+      else
+        nil
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cem_spec_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - abide-team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-21 00:00:00.000000000 Z
+date: 2023-09-22 00:00:00.000000000 Z
 dependencies: []
 description: Provides helper methods, classes, modules, etc. for RSpec testing the
   CEM modules