abide_dev_utils 0.10.1 → 0.11.2

data/lib/abide_dev_utils/cem/generate/coverage_report.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+require 'pathname'
+require 'yaml'
+require 'abide_dev_utils/ppt'
+require 'abide_dev_utils/validate'
+require 'abide_dev_utils/cem/benchmark'
+
+module AbideDevUtils
+  module CEM
+    module Generate
+      # Methods and objects used to construct a report of what CEM enforces versus what
+      # the various compliance frameworks expect to be enforced.
+      module CoverageReport
+        def self.generate(format_func: :to_h, opts: {})
+          opts = AbideDevUtils::CEM::CoverageReport::ReportOptions.new(opts)
+          pupmod = AbideDevUtils::Ppt::PuppetModule.new
+          benchmarks = AbideDevUtils::CEM::Benchmark.benchmarks_from_puppet_module(pupmod,
+                                                                                  ignore_all_errors: opts.ignore_all_errors)
+          benchmarks.map do |b|
+            AbideDevUtils::CEM::CoverageReport::BenchmarkReport.new(b)
+                                                              .send(report_type, **{ profile: profile, level: level })
+                                                              .send(format_func)
+          end
+        end
+
+        class ReportOptions
+          DEFAULTS = {
+            benchmark: nil,
+            profile: nil,
+            level: nil,
+            format_func: :to_h,
+            ignore_all_errors: false,
+            xccdf_dir: nil,
+          }.freeze
+
+          attr_reader(*DEFAULTS.keys)
+
+          def initialize(opts = {})
+            @opts = DEFAULTS.merge(opts)
+            DEFAULTS.each_key do |k|
+              instance_variable_set "@#{k}", @opts[k]
+            end
+          end
+
+          def report_type
+            @report_type ||= (xccdf_dir.nil? ? :basic_coverage : :correlated_coverage)
+          end
+        end
+
+        class Filter
+          KEY_FACT_MAP = {
+            os_family: 'os.family',
+            os_name: 'os.name',
+            os_release_major: 'os.release.major',
+          }.freeze
+
+          attr_reader(*KEY_FACT_MAP.keys)
+
+          def initialize(pupmod, **filters)
+            @pupmod = pupmod
+            @benchmark = filters[:benchmark]
+            @profile = filters[:profile]
+            @level = filters[:level]
+            KEY_FACT_MAP.each_key do |k|
+              instance_variable_set "@#{k}", filters[k]
+            end
+          end
+
+          def resource_data
+            @resource_data ||= find_resource_data
+          end
+
+          def mapping_data
+            @mapping_data ||= find_mapping_data
+          end
+
+          private
+
+          def find_resource_data
+            fact_array = fact_array_for(:os_family, :os_name, :os_release_major)
+            @pupmod.hiera_conf.local_hiera_files_with_facts(*fact_array, hierarchy_name: 'Resource Data').map do |f|
+              YAML.load_file(f.path)
+            end
+          rescue NoMethodError
+            @pupmod.hiera_conf.local_hiera_files(hierarchy_name: 'Resource Data').map { |f| YAML.load_file(f.path) }
+          end
+
+          def find_mapping_data
+            fact_array = fact_array_for(:os_name, :os_release_major)
+            begin
+              data_array = @pupmod.hiera_conf.local_hiera_files_with_facts(*fact_array, hierarchy_name: 'Mapping Data').map do |f|
+                YAML.load_file(f.path)
+              end
+            rescue NoMethodError
+              data_array = @pupmod.hiera_conf.local_hiera_files(hierarchy_name: 'Mapping Data').map { |f| YAML.load_file(f.path) }
+            end
+            filter_mapping_data_array_by_benchmark!(data_array)
+            filter_mapping_data_array_by_profile!(data_array)
+            filter_mapping_data_array_by_level!(data_array)
+            data_array
+          end
+
+          def filter_mapping_data_array_by_benchmark!(data_array)
+            return unless @benchmark
+
+            data_array.select! do |d|
+              d.keys.all? do |k|
+                k == 'benchmark' || k.match?(/::#{@benchmark}::/)
+              end
+            end
+          end
+
+          def filter_mapping_data_array_by_profile!(data_array)
+            return unless @profile
+
+            data_array.reject! { |d| nested_hash_value(d, @profile).nil? }
+          end
+
+          def filter_mapping_data_array_by_level!(data_array)
+            return unless @level
+
+            data_array.reject! { |d| nested_hash_value(d, @level).nil? }
+          end
+
+          def nested_hash_value(obj, key)
+            if obj.respond_to?(:key?) && obj.key?(key)
+              obj[key]
+            elsif obj.respond_to?(:each)
+              r = nil
+              obj.find { |*a| r = nested_hash_value(a.last, key) }
+              r
+            end
+          end
+
+          def filter_stig_mapping_data(data_array); end
+
+          def fact_array_for(*keys)
+            keys.each_with_object([]) { |(k, _), a| a << fact_filter_value(k) }.compact
+          end
+
+          def fact_filter_value(key)
+            value = instance_variable_get("@#{key}")
+            return if value.nil? || value.empty?
+
+            [KEY_FACT_MAP[key], value]
+          end
+        end
+
+        class OldReport
+          def initialize(benchmarks)
+            @benchmarks = benchmarks
+          end
+
+          def self.generate
+            coverage = {}
+            coverage['classes'] = {}
+            all_cap = ClassUtils.find_all_classes_and_paths(puppet_class_dir)
+            invalid_classes = find_invalid_classes(all_cap)
+            valid_classes = find_valid_classes(all_cap, invalid_classes)
+            coverage['classes']['invalid'] = invalid_classes
+            coverage['classes']['valid'] = valid_classes
+            hiera = YAML.safe_load(File.open(hiera_path))
+            profile&.gsub!(/^profile_/, '') unless profile.nil?
+
+            matcher = profile.nil? ? /^profile_/ : /^profile_#{profile}/
+            hiera.each do |k, v|
+              key_base = k.split('::')[-1]
+              coverage['benchmark'] = v if key_base == 'title'
+              next unless key_base.match?(matcher)
+
+              coverage[key_base] = generate_uncovered_data(v, valid_classes)
+            end
+            coverage
+          end
+
+          def self.generate_uncovered_data(ctrl_list, valid_classes)
+            out_hash = {}
+            out_hash[:num_total] = ctrl_list.length
+            out_hash[:uncovered] = []
+            out_hash[:covered] = []
+            ctrl_list.each do |c|
+              if valid_classes.include?(c)
+                out_hash[:covered] << c
+              else
+                out_hash[:uncovered] << c
+              end
+            end
+            out_hash[:num_covered] = out_hash[:covered].length
+            out_hash[:num_uncovered] = out_hash[:uncovered].length
+            out_hash[:coverage] = Float(
+              (Float(out_hash[:num_covered]) / Float(out_hash[:num_total])) * 100.0
+            ).floor(3)
+            out_hash
+          end
+
+          def self.find_valid_classes(all_cap, invalid_classes)
+            all_classes = all_cap.dup.transpose[0]
+            return [] if all_classes.nil?
+
+            return all_classes - invalid_classes unless invalid_classes.nil?
+
+            all_classes
+          end
+
+          def self.find_invalid_classes(all_cap)
+            invalid_classes = []
+            all_cap.each do |cap|
+              invalid_classes << cap[0] unless class_valid?(cap[1])
+            end
+            invalid_classes
+          end
+
+          def self.class_valid?(manifest_path)
+            compiler = Puppet::Pal::Compiler.new(nil)
+            ast = compiler.parse_file(manifest_path)
+            ast.body.body.statements.each do |s|
+              next unless s.respond_to?(:arguments)
+              next unless s.arguments.respond_to?(:each)
+
+              s.arguments.each do |i|
+                return false if i.value == 'Not implemented'
+              end
+            end
+            true
+          end
+        end
+
+        # Class manages organizing report data into various output formats
+        class ReportOutput
+          attr_reader :controls_in_resource_data, :rules_in_map, :timestamp,
+                      :title
+
+          def initialize(benchmark, controls_in_resource_data, rules_in_map)
+            @benchmark = benchmark
+            @controls_in_resource_data = controls_in_resource_data
+            @rules_in_map = rules_in_map
+            @timestamp = DateTime.now.iso8601
+            @title = "Coverage Report for #{@benchmark.title_key}"
+          end
+
+          def uncovered
+            @uncovered ||= rules_in_map - controls_in_resource_data
+          end
+
+          def uncovered_count
+            @uncovered_count ||= uncovered.length
+          end
+
+          def covered
+            @covered ||= rules_in_map - uncovered
+          end
+
+          def covered_count
+            @covered_count ||= covered.length
+          end
+
+          def total_count
+            @total_count ||= rules_in_map.length
+          end
+
+          def percentage
+            @percentage ||= covered_count.to_f / total_count
+          end
+
+          def to_h
+            {
+              title: title,
+              timestamp: timestamp,
+              benchmark: benchmark_hash,
+              coverage: coverage_hash,
+            }
+          end
+
+          def to_json(opts = nil)
+            JSON.generate(to_h, opts)
+          end
+
+          def to_yaml
+            to_h.to_yaml
+          end
+
+          def benchmark_hash
+            {
+              title: @benchmark.title,
+              version: @benchmark.version,
+              framework: @benchmark.framework,
+            }
+          end
+
+          def coverage_hash
+            {
+              total_count: total_count,
+              uncovered_count: uncovered_count,
+              uncovered: uncovered,
+              covered_count: covered_count,
+              covered: covered,
+              percentage: percentage,
+              controls_in_resource_data: controls_in_resource_data,
+              rules_in_map: rules_in_map,
+            }
+          end
+        end
+
+        # Creates ReportOutput objects based on the given Benchmark
+        class BenchmarkReport
+          def initialize(benchmark, opts = AbideDevUtils::CEM::CoverageReport::ReportOptions.new)
+            @benchmark = benchmark
+            @opts = opts
+          end
+
+          def controls_in_resource_data
+            @controls_in_resource_data ||= find_controls_in_resource_data
+          end
+
+          def controls_in_mapping_data
+            @controls_in_mapping_data ||= find_controls_in_mapping_data
+          end
+
+          def basic_coverage(level: @opts.level, profile: @opts.profile)
+            map_type = @benchmark.map_type(controls_in_resource_data[0])
+            rules_in_map = @benchmark.rules_in_map(map_type, level: level, profile: profile)
+            AbideDevUtils::CEM::CoverageReport::ReportOutput.new(@benchmark, controls_in_resource_data, rules_in_map)
+          end
+
+          # def correlated_coverage(level: @opts.level, profile: @opts.profile)
+          #   correlation = ReportOutputCorrelation.new(basic_coverage(level: level, profile: profile))
+          # end
+
+          private
+
+          def find_controls_in_resource_data
+            controls = @benchmark.resource_data["#{@benchmark.module_name}::resources"].each_with_object([]) do |(rname, rval), arr|
+              arr << case rval['controls'].class.to_s
+                     when 'Hash'
+                       rval['controls'].keys
+                     when 'Array'
+                       rval['controls']
+                     else
+                       raise "Invalid controls type: #{rval['controls'].class}"
+                     end
+            end
+            controls.flatten.uniq.select do |c|
+              case @benchmark.framework
+              when 'cis'
+                @benchmark.map_type(c) != 'vulnid'
+              when 'stig'
+                @benchmark.map_type(c) == 'vulnid'
+              else
+                raise "Cannot find controls for framework #{@benchmark.framework}"
+              end
+            end
+          end
+
+          def find_controls_in_mapping_data
+            controls = @benchmark.map_data[0].each_with_object([]) do |(_, mapping), arr|
+              mapping.each do |level, profs|
+                next if level == 'benchmark'
+
+                profs.each do |_, ctrls|
+                  arr << ctrls.keys
+                  arr << ctrls.values
+                end
+              end
+            end
+            controls.flatten.uniq
+          end
+        end
+
+        class ReportOutputCorrelation
+          def initialize(cov_rep)
+            @cov_rep = cov_rep
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/generate/reference.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'shellwords'
+require 'timeout'
+require 'yaml'
+require 'abide_dev_utils/markdown'
+require 'abide_dev_utils/output'
+require 'abide_dev_utils/ppt'
+require 'abide_dev_utils/cem/benchmark'
+
+module AbideDevUtils
+  module CEM
+    module Generate
+      # Holds objects and methods for generating a reference doc
+      module Reference
+        MAPPING_PATH_KEY = 'Mapping Data'
+        RESOURCE_DATA_PATH_KEY = 'Resource Data'
+
+        def self.generate(data = {})
+          pupmod = AbideDevUtils::Ppt::PuppetModule.new
+          doc_title = case pupmod.name
+                      when 'puppetlabs-cem_linux'
+                        'CEM Linux Reference'
+                      when 'puppetlabs-cem_windows'
+                        'CEM Windows Reference'
+                      else
+                        'Reference'
+                      end
+          benchmarks = AbideDevUtils::CEM::Benchmark.benchmarks_from_puppet_module(pupmod)
+          case data.fetch(:format, 'markdown')
+          when 'markdown'
+            file = data[:out_file] || 'REFERENCE.md'
+            MarkdownGenerator.new(benchmarks, pupmod.name, file: file).generate(doc_title)
+          else
+            raise "Format #{data[:format]} is unsupported! Only `markdown` format supported"
+          end
+        end
+
+        def self.generate_markdown
+          AbideDevUtils::Markdown.new('REFERENCE.md').generate
+        end
+
+        def self.config_example(control, params_array)
+          out_str = ['cem_windows::config:', '  control_configs:', "    \"#{control}\":"]
+          indent = '      '
+          params_array.each do |param_hash|
+            val = case param_hash[:type]
+                  when 'String'
+                    "'#{param_hash[:default]}'"
+                  else
+                    param_hash[:default]
+                  end
+
+            out_str << "#{indent}#{param_hash[:name]}: #{val}"
+          end
+          out_str.join("\n")
+        end
+
+        # Generates a markdown reference doc
+        class MarkdownGenerator
+          SPECIAL_CONTROL_IDS = %w[dependent cem_options cem_protected].freeze
+
+          def initialize(benchmarks, module_name, file: 'REFERENCE.md')
+            @benchmarks = benchmarks
+            @module_name = module_name
+            @file = file
+            @md = AbideDevUtils::Markdown.new(@file)
+          end
+
+          def generate(doc_title = 'Reference')
+            md.add_title(doc_title)
+            benchmarks.each do |benchmark|
+              progress_bar = AbideDevUtils::Output.progress(title: "Generating Markdown for #{benchmark.title_key}",
+                                                            total: benchmark.controls.length)
+              md.add_h1(benchmark.title_key)
+              benchmark.controls.each do |control|
+                next if SPECIAL_CONTROL_IDS.include? control.id
+                next if benchmark.framework == 'stig' && control.id_map_type != 'vulnid'
+
+                control_md = ControlMarkdown.new(control, @md, @module_name, benchmark.framework)
+                control_md.generate!
+                progress_bar.increment
+              rescue StandardError => e
+                raise "Failed to generate markdown for control #{control.id}. Original message: #{e.message}"
+              end
+            end
+            AbideDevUtils::Output.simple("Saving markdown to #{@file}")
+            md.to_file
+          end
+
+          private
+
+          attr_reader :benchmarks, :md
+        end
+
+        class ConfigExampleError < StandardError; end
+
+        class ControlMarkdown
+          def initialize(control, md, module_name, framework, formatter: nil)
+            @control = control
+            @md = md
+            @module_name = module_name
+            @framework = framework
+            @formatter = formatter.nil? ? TypeExprValueFormatter : formatter
+            @control_data = {}
+          end
+
+          def generate!
+            heading_builder
+            control_params_builder
+            control_levels_builder
+            control_profiles_builder
+            config_example_builder
+            control_alternate_ids_builder
+            dependent_controls_builder
+            resource_reference_builder
+          end
+
+          private
+
+          def heading_builder
+            @md.add_h2("#{@control.number} - #{@control.title}")
+          end
+
+          def control_has_valid_params?
+            return true if @control.params? || @control.resource.cem_options? || @control.resource.cem_protected?
+            return true if @control.resource.manifest? && @control.resource.manifest.declaration.parameters?
+
+            false
+          end
+
+          def resource_param(ctrl_param)
+            return unless @control.resource.manifest?
+
+            @control.resource.manifest.declaration.parameters&.find { |x| x.name == "$#{ctrl_param[:name]}" }
+          end
+
+          def param_type_expr(ctrl_param, rsrc_param)
+            @control_data[ctrl_param[:name]] = {} unless @control_data.key?(ctrl_param[:name])
+            @control_data[ctrl_param[:name]][:type_expr] = rsrc_param&.type_expr? ? rsrc_param&.type_expr : ctrl_param[:type]
+            return unless @control_data[ctrl_param[:name]][:type_expr]
+
+            " - [ #{@md.code(@control_data[ctrl_param[:name]][:type_expr])} ]"
+          end
+
+          def param_default_value(ctrl_param, rsrc_param)
+            @control_data[ctrl_param[:name]] = {} unless @control_data.key?(ctrl_param[:name])
+            @control_data[ctrl_param[:name]][:default] = ctrl_param[:default] || rsrc_param&.value
+            return unless @control_data[ctrl_param[:name]][:default]
+
+            " - #{@md.italic('Default:')} #{@md.code(@control_data[ctrl_param[:name]][:default])}"
+          end
+
+          def control_params_builder
+            return unless control_has_valid_params?
+
+            @md.add_ul('Parameters:')
+            [@control.param_hashes, @control.resource.cem_options, @control.resource.cem_protected].each do |collection|
+              collection.each do |hsh|
+                rparam = resource_param(hsh)
+                str_array = [@md.code(hsh[:name]), param_type_expr(hsh, rparam), param_default_value(hsh, rparam)]
+                @md.add_ul(str_array.compact.join, indent: 1)
+              end
+            end
+          end
+
+          def control_levels_builder
+            return unless @control.levels
+
+            @md.add_ul('Supported Levels:')
+            @control.levels.each do |l|
+              @md.add_ul(@md.code(l), indent: 1)
+            end
+          end
+
+          def control_profiles_builder
+            return unless @control.profiles
+
+            @md.add_ul('Supported Profiles:')
+            @control.profiles.each do |l|
+              @md.add_ul(@md.code(l), indent: 1)
+            end
+          end
+
+          def control_alternate_ids_builder
+            return if @framework == 'stig'
+
+            @md.add_ul('Alternate Config IDs:')
+            @control.alternate_ids.each do |l|
+              @md.add_ul(@md.code(l), indent: 1)
+            end
+          end
+
+          def dependent_controls_builder
+            dep_ctrls = @control.resource.dependent_controls
+            return if dep_ctrls.nil? || dep_ctrls.empty?
+
+            @md.add_ul('Dependent controls:')
+            dep_ctrls.each do |ctrl|
+              puts "DEPENDENT: #{ctrl.id}"
+              @md.add_ul(@md.code(ctrl.display_title), indent: 1)
+            end
+          end
+
+          def config_example_builder
+            out_str = []
+            indent = '      '
+            @control.param_hashes.each do |param_hash|
+              next if param_hash[:name] == 'No parameters'
+
+              val = @formatter.format(@control_data[param_hash[:name]][:default],
+                                      @control_data[param_hash[:name]][:type_expr],
+                                      optional_strategy: :placeholder)
+              out_str << "#{indent}#{param_hash[:name]}: #{val}"
+            end
+            return if out_str.empty?
+
+            out_str.unshift("    #{@control.title.dump}:")
+            out_str.unshift('  control_configs:')
+            out_str.unshift("#{@module_name}::config:")
+            @md.add_ul('Hiera Configuration Example:')
+            @md.add_code_block(out_str.join("\n"), language: 'yaml')
+          rescue StandardError => e
+            err_msg = [
+              "Failed to generate config example for control #{@control.id}",
+              "Error: #{e.message}",
+              "Control: Data #{@control_data.inspect}",
+              e.backtrace.join("\n")
+            ].join("\n")
+            raise ConfigExampleError, err_msg
+          end
+
+          def resource_reference_builder
+            @md.add_ul("Resource: #{@md.code(@control.resource.to_reference)}")
+          end
+        end
+
+        # Holds methods for formmating values based on type expressions
+        class TypeExprValueFormatter
+          UNDEF_VAL = 'undef'
+
+          # Formats a value based on a type expression.
+          # @param value [Any] the value to format
+          # @param type_expr [String] the type expression to use for formatting
+          # @param optional_strategy [Symbol] the strategy to use for optional values
+          # @return [Any] the formatted value
+          def self.format(value, type_expr, optional_strategy: :undef)
+            return value if value == 'No parameters'
+
+            case type_expr
+            when /^(String|Stdlib::(Unix|Windows|Absolute)path|Enum)/
+              quote(value)
+            when /^Optional\[/
+              optional(value, type_expr, strategy: optional_strategy)
+            else
+              return type_expr_placeholder(type_expr) if value.nil?
+
+              quote(value)
+            end
+          end
+
+          # Escapes and quotes a string. If value is not a string, returns value.
+          # @param value [Any] the string to quote.
+          # @return [String] the quoted string.
+          # @return [Any] the value if it is not a string.
+          def self.quote(value)
+            if value.is_a?(String)
+              value.inspect
+            else
+              value
+            end
+          end
+
+          # Checks if a value is considered undef.
+          # @param value [Any] the value to check.
+          # @return [Boolean] true if value is considered undef (nil or 'undef').
+          def self.undef?(value)
+            value.nil? || value == UNDEF_VAL
+          end
+
+          # Returns the display representation of the value with an Optional type expression.
+          # If the value is not nil or 'undef', returns the quoted form of the value.
+          # @param value [Any] the value to format.
+          # @param type_expr [String] the type expression.
+          # @param strategy [Symbol] the strategy to use. Valid strategies are :undef and :placeholder.
+          #   :undef will return 'undef' if the value is nil or 'undef'.
+          #   :placeholder will return a peeled type expression placeholder if the value is nil or 'undef'.
+          # @return [String] the formatted value.
+          # @return [Any] the quoted value if it is not nil.
+          def self.optional(value, type_expr, strategy: :undef)
+            return UNDEF_VAL if undef?(value) && strategy == :undef
+            return type_expr_placeholder(peel_type_expr(type_expr)) if undef?(value) && strategy == :placeholder
+
+            quote(value)
+          end
+
+          # Returns a "peeled" type expression. Peeling a type expression removes the
+          # first layer of the type expression. For example, if the type expression is
+          # Optional[String], the peeled type expression is String.
+          # @param type_expr [String] the type expression to peel.
+          # @return [String] the peeled type expression.
+          def self.peel_type_expr(type_expr)
+            return type_expr unless type_expr.include?('[')
+
+            type_expr.match(/^[A-Z][a-z0-9_]*\[(?<peeled>[A-Za-z0-9:,_{}=>\[\]\\\s]+)\]$/)[:peeled]
+          end
+
+          # Formats the type expression as a placeholder.
+          # @param type_expr [String] The type expression to format.
+          # @return [String] The formatted type expression.
+          def self.type_expr_placeholder(type_expr)
+            "<<Type #{type_expr}>>"
+          end
+        end
+      end
+    end
+  end
+end