abide_dev_utils 0.9.5 → 0.10.1

data/lib/abide_dev_utils/xccdf/diff/benchmark.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'abide_dev_utils/xccdf/diff/benchmark/number_title'
+require 'abide_dev_utils/xccdf/diff/benchmark/property'
+require 'abide_dev_utils/xccdf/diff/utils'
+require 'abide_dev_utils/xccdf/parser'
+
+module AbideDevUtils
+  module XCCDF
+    # Holds methods and classes used to diff XCCDF-derived objects.
+    module Diff
+      # Class for benchmark diffs
+      class BenchmarkDiff
+        include AbideDevUtils::XCCDF::Diff::BenchmarkPropertyDiff
+        attr_reader :self, :other, :opts
+
+        DEFAULT_OPTS = {
+          only_classes: %w[rule],
+        }.freeze
+
+        # Used for filtering by level and profile
+        LVL_PROF_DEFAULT = [nil, nil].freeze
+
+        # @param xml1 [String] path to the first benchmark XCCDF xml file
+        # @param xml2 [String] path to the second benchmark XCCDF xml file
+        # @param opts [Hash] options hash
+        def initialize(xml1, xml2, opts = {})
+          @self = new_benchmark(xml1)
+          @other = new_benchmark(xml2)
+          @opts = DEFAULT_OPTS.merge(DEFAULT_PROPERTY_DIFF_OPTS).merge(opts)
+          @levels = []
+          @profiles = []
+        end
+
+        def method_missing(method_name, *args, &block)
+          if opts.key?(method_name)
+            opts[method_name]
+          elsif @diff&.key?(method_name)
+            @diff[method_name]
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          opts.key?(method_name) || @diff&.key?(method_name) || super
+        end
+
+        # Memoized getter for all "numbered" children for the "self" benchmark based on optional filters in opts
+        def self_numbered_children
+          @self_numbered_children ||= find_all_numbered_children(@self,
+                                                                 only_classes: opts[:only_classes],
+                                                                 level: opts[:level],
+                                                                 profile: opts[:profile])
+        end
+
+        # Memoized getter for all "numbered" children for the "other" benchmark based on optional filters in opts
+        def other_numbered_children
+          @other_numbered_children ||= find_all_numbered_children(@other,
+                                                                  only_classes: opts[:only_classes],
+                                                                  level: opts[:level],
+                                                                  profile: opts[:profile])
+        end
+
+        # Basic title diff
+        def numbered_children_title_diff
+          {
+            self: self_numbered_children.map { |c| c.title.to_s } - other_numbered_children.map { |c| c.title.to_s },
+            other: other_numbered_children.map { |c| c.title.to_s } - self_numbered_children.map { |c| c.title.to_s },
+          }
+        end
+
+        # Returns the output of a NumberTitleDiff object's diff function based on self_numbered_children and other_numbered_children
+        def number_title_diff
+          NumberTitleDiff.new(self_numbered_children, other_numbered_children).diff
+        end
+
+        # Hash of data about the "self" benchmark and the diff parameters
+        def from_benchmark
+          @from_benchmark ||= from_to_hash(@self)
+        end
+
+        # Hash of data about the "other" benchmark and the diff parameters
+        def to_benchmark
+          @to_benchmark ||= from_to_hash(@other)
+        end
+
+        # All levels that numbered children have been filtered on
+        def levels
+          @levels.flatten.uniq.empty? ? [:all] : @levels.flatten.uniq
+        end
+
+        # All profiles that numbered children have been filtered on
+        def profiles
+          @profiles.flatten.uniq.empty? ? [:all] : @profiles.flatten.uniq
+        end
+
+        # Returns a diff of the changes from the "self" xml (xml1) to the "other" xml (xml2)
+        # This function is memoized because the diff operation is expensive. To run the diff
+        # operation again, set the `new` parameter to `true`
+        # @param new [Boolean] Set to `true` to force a new diff operation
+        # return [Hash] the diff in hash format
+        def diff(new: false)
+          return @diff if @diff && !new
+
+          @diff = {}
+          @diff[:number_title] = number_title_diff
+          { from: from_benchmark, to: to_benchmark, diff: @diff }
+        end
+
+        private
+
+        # Returns a Benchmark object from a XCCDF xml file path
+        # @param xml [String] path to a XCCDF xml file
+        def new_benchmark(xml)
+          AbideDevUtils::XCCDF::Parser.parse(xml)
+        end
+
+        # Returns a hash of benchmark data
+        # @param obj [AbideDevUtils::XCCDF::Parser::Objects::Benchmark]
+        # @return [Hash] diff-relevant benchmark information
+        def from_to_hash(obj)
+          {
+            title: obj.title.to_s,
+            version: obj.version.to_s,
+            compared: {
+              levels: levels,
+              profiles: profiles,
+            }
+          }
+        end
+
+        # Function to check if a numbered child meets inclusion criteria based on filtering
+        # options.
+        # @param child [Object] XCCDF parser object that includes AbideDevUtils::XCCDF::Parser::Objects::NumberedObject.
+        # @param only_classes [Array] class names as strings. When this is specified, only objects with those class names will be considered.
+        # @param level [String] Specifies the benchmark profile level to filter children on. Only applies to Rules linked to Profiles that have levels.
+        # @param profile [String] Specifies the benchmark profile to filter children on. Only applies to Rules that have linked Profiles.
+        # @return [TrueClass] if child meets all filtering criteria and should be included in the set.
+        # @return [FalseClass] if child does not meet all criteria and should be excluded from the set.
+        def include_numbered_child?(child, only_classes: [], level: nil, profile: nil)
+          return false unless valid_class?(child, only_classes)
+          return true if level.nil? && profile.nil?
+
+          validated_props = valid_profile_and_level(child, level, profile)
+          should_include = validated_props.none?(&:nil?)
+          new_validated_props_vars(validated_props) if should_include
+          should_include
+        end
+
+        # Adds level and profile to respective instance vars
+        # @param validated_props [Array] two item array: first item - profile level, second item - profile title
+        def new_validated_props_vars(validated_props)
+          @levels << validated_props[0]
+          @profiles << validated_props[1]
+        end
+
+        # Checks if the child's class is in the only_classes list, if applicable
+        # @param child [Object] the child whose class will be checked
+        # @param only_classes [Array] an array of class names as strings
+        # @return [TrueClass] if only_classes is empty or if child's class is in only_classes
+        # @return [FalseClass] if only_classes is not empty and child's class is not in only_classes
+        def valid_class?(child, only_classes = [])
+          only_classes.empty? || only_classes.include?(child.label)
+        end
+
+        # Returns a two-item array of a valid level and a valid profile
+        # @param child [Object] XCCDF parser object or array of XCCDF parser objects
+        # @param level [String] a profile level
+        # @param profile [String] a partial / full profile title
+        # @return [Array] two-item array: first item - Profile level or nil, second item - Profile title or nil
+        def valid_profile_and_level(child, level, profile)
+          return LVL_PROF_DEFAULT unless child.respond_to?(:linked_profile)
+
+          validate_profile_obj(child.linked_profile, level, profile)
+        end
+
+        # Returns array (or array of arrays) of valid level and valid profile based on child's linked profiles
+        # @param obj [Object] AbideDevUtils::XCCDF::Parser::Objects::Profile objects or array of them
+        # @param level [String] a profile level
+        # @param profile [String] a partial / full profile title
+        # @return [Array] two-item array: first item - Profile level or nil, second item - Profile title or nil
+        # @return [Array] Array of two item arrays if `obj` is an array of profiles
+        def validate_profile_obj(obj, level, profile)
+          return LVL_PROF_DEFAULT if obj.nil?
+          return validate_profile_objs(obj, level, profile) if obj.respond_to?(:each)
+
+          validated_level = valid_level?(obj, level) ? obj.level : nil
+          validated_profile = valid_profile?(obj, profile) ? obj.title.to_s : nil
+          [validated_level, validated_profile]
+        end
+
+        # Returns array of arrays of valid levels and valid profiles based on all children's linked profiles
+        # @param objs [Array] Array of AbideDevUtils::XCCDF::Parser::Objects::Profile objects
+        # @param level [String] a profile level
+        # @param profile [String] a partial / full profile title
+        # @return [Array] Array of two-item arrays
+        def validate_profile_objs(objs, level, profile)
+          found = [LVL_PROF_DEFAULT]
+          objs.each do |obj|
+            validated = validate_profile_obj(obj, level, profile)
+            next if validated.any?(&:nil?)
+
+            found << validated
+          end
+          found
+        end
+
+        # Checks if a given object has a matching level. This is done
+        # via a basic regex match on the object's #level method
+        # @param obj [AbideDevUtils::XCCDF::Parser::Objects::Profile] the profile object
+        # @param level [String] a level to check
+        # @return [TrueClass] if level matches
+        # @return [FalseClass] if level does not match
+        def valid_level?(obj, level)
+          return true if level.nil? || obj.level.nil?
+
+          obj.level.match?(/#{Regexp.escape level}/i)
+        end
+
+        # Checks if a given profile object has a matching title or id. This
+        # is done with a regex match against the profile's title as a string
+        # or against it's object string representation (the ID).
+        # @param obj [AbideDevUtils::XCCDF::Parser::Objects::Profile] the profile object
+        # @param profile [String] a profile string to check
+        # @return [TrueClass] if `profile` matches either the profile's title or ID
+        # @return [FalseClass] if `profile` matches neither
+        def valid_profile?(obj, profile)
+          return true if profile.nil?
+
+          obj.title.to_s.match?(/#{Regexp.escape profile}/i) ||
+            obj.to_s.match?(/#{Regexp.escape profile}/i)
+        end
+
+        # Finds all children of the benchmark that implement AbideDevUtils::XCCDF::Parser::Objects::NumberedObject
+        # that are not filtered out based on optional parameters. This method recursively walks down the hierarchy
+        # of the benchmark to ensure that all deeply nested objects are accounted for.
+        # @param benchmark [AbideDevUtils::XCCDF::Parser::Objects::Benchmark] the benchmark to check
+        # @param only_classes [Array] An array of class names. Only children with the specified class names will be returned
+        # @param level [String] A profile level. Only children that have linked profiles that match this level will be returned
+        # @param profile [String] A profile title / id. Only children that have linked profiles that match this title / id will be returned
+        # @param numbered_children [Array] An array of numbered children to check. If this is empty, we start checking at the top-level of
+        #   the benchmark. To get all of the benchmark's numbered children, this should be an empty array when calling this method.
+        # @return [Array] A sorted array of numbered children.
+        def find_all_numbered_children(benchmark, only_classes: [], level: nil, profile: nil, numbered_children: [])
+          benchmark.find_children_that_respond_to(:number).each do |child|
+            numbered_children << child if include_numbered_child?(child,
+                                                                  only_classes: only_classes,
+                                                                  level: level,
+                                                                  profile: profile)
+            find_all_numbered_children(child,
+                                       only_classes: only_classes,
+                                       level: level,
+                                       profile: profile,
+                                       numbered_children: numbered_children)
+          end
+          numbered_children.sort
+        end
+
+        # Returns a subset of benchmark children based on a property of that child and search values
+        def find_subset_of_children(children, property, search_values)
+          children.select { |c| search_values.include?(c.send(property)) }
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/xccdf/diff/utils.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AbideDevUtils
+  module XCCDF
+    module Diff
+      # Holds the result of a diff on a per-item basis.
+      class DiffChangeResult
+        attr_reader :type, :old_value, :new_value
+
+        def initialize(type, old_value, new_value)
+          @type = type
+          @old_value = old_value
+          @new_value = new_value
+        end
+
+        def to_h
+          { type: type, old_value: old_value, new_value: new_value }
+        end
+
+        def to_a
+          [type, old_value, new_value]
+        end
+
+        def to_s
+          "#{type}: #{old_value} -> #{new_value}"
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/xccdf/diff.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'hashdiff'
+
+module AbideDevUtils
+  module XCCDF
+    # Contains methods and classes used to diff XCCDF-derived objects.
+    module Diff
+      DEFAULT_DIFF_OPTS = {
+        similarity: 1,
+        strict: true,
+        strip: true,
+        array_path: true,
+        delimiter: '//',
+        use_lcs: true,
+      }.freeze
+
+      # Represents a change in a diff.
+      class ChangeSet
+        attr_reader :change, :key, :value, :value_to
+
+        def initialize(change:, key:, value:, value_to: nil)
+          validate_change(change)
+          @change = change
+          @key = key
+          @value = value
+          @value_to = value_to
+        end
+
+        def to_s
+          value_change_string(value, value_to)
+        end
+
+        def to_h
+          {
+            change: change,
+            key: key,
+            value: value,
+            value_to: value_to,
+          }
+        end
+
+        def can_merge?(other)
+          return false unless (change == '-' && other.change == '+') || (change == '+' && other.change == '-')
+          return false unless key == other.key || value_hash_equality(other)
+
+          true
+        end
+
+        def merge(other)
+          unless can_merge?(other)
+            raise ArgumentError, 'Cannot merge. Possible causes: change is identical; key or value do not match'
+          end
+
+          new_to_value = value == other.value ? nil : other.value
+          ChangeSet.new(
+            change: '~',
+            key: key,
+            value: value,
+            value_to: new_to_value
+          )
+        end
+
+        def merge!(other)
+          new_props = merge(other)
+          @change = new_props.change
+          @key = new_props.key
+          @value = new_props.value
+          @value_to = new_props.value_to
+        end
+
+        private
+
+        def value_hash_equality(other)
+          equality = false
+          value.each do |k, v|
+            equality = true if v == other.value[k]
+          end
+          equality
+        end
+
+        def validate_change(chng)
+          raise ArgumentError, "Change type #{chng} in invalid" unless ['+', '-', '~'].include?(chng)
+        end
+
+        def change_string(chng)
+          case chng
+          when '-'
+            'Remove'
+          when '+'
+            'Add'
+          else
+            'Change'
+          end
+        end
+
+        def value_change_string(value, value_to)
+          change_str = []
+          change_diff = Hashdiff.diff(value, value_to || {}, AbideDevUtils::XCCDF::Diff::DEFAULT_DIFF_OPTS)
+          return if change_diff.empty?
+          return value_change_string_single_type(change_diff, value) if all_single_change_type?(change_diff)
+
+          change_diff.each do |chng|
+            change_str << if chng.length == 4
+                            "#{change_string(chng[0])} #{chng[1][0]} \"#{chng[2]}\" to \"#{chng[3]}\""
+                          else
+                            "#{change_string(chng[0])} #{chng[1][0]} with value #{chng[2]}"
+                          end
+          end
+          change_str.join(', ')
+        end
+
+        def value_change_string_single_type(change_diff, value)
+          "#{change_string(change_diff[0][0])} #{value[:number]} - #{value[:level]} - #{value[:title]}"
+        end
+
+        def all_single_change_type?(change_diff)
+          change_diff.length > 1 && change_diff.map { |x| x[0] }.uniq.length == 1
+        end
+      end
+
+      # Class used to diff two Benchmark profiles.
+      class ProfileDiff
+        def initialize(profile_a, profile_b, opts = {})
+          @profile_a = profile_a
+          @profile_b = profile_b
+          @opts = opts
+        end
+
+        def diff
+          @diff ||= new_diff
+        end
+
+        private
+
+        def new_diff
+          Hashdiff.diff(@profile_a, @profile_b, AbideDevUtils::XCCDF::Diff::DEFAULT_DIFF_OPTS).each_with_object({}) do |change, diff|
+            val_to = change.length == 4 ? change[3] : nil
+            change_key = change[2].is_a?(Hash) ? change[2][:title] : change[2]
+            if diff.key?(change_key)
+              diff[change_key] = merge_changes(
+                [
+                  diff[change_key][0],
+                  ChangeSet.new(change: change[0], key: change[1], value: change[2], value_to: val_to),
+                ]
+              )
+            else
+              diff[change_key] = [ChangeSet.new(change: change[0], key: change[1], value: change[2], value_to: val_to)]
+            end
+          end
+        end
+
+        def merge_changes(changes)
+          return changes if changes.length < 2
+
+          if changes[0].can_merge?(changes[1])
+            [changes[0].merge(changes[1])]
+          else
+            changes
+          end
+        end
+      end
+
+      # Class used to diff two AbideDevUtils::XCCDF::Benchmark objects.
+      class BenchmarkDiff
+        def initialize(benchmark_a, benchmark_b, opts = {})
+          @benchmark_a = benchmark_a
+          @benchmark_b = benchmark_b
+          @opts = opts
+        end
+
+        def properties_to_diff
+          @properties_to_diff ||= %i[title version profiles]
+        end
+
+        def title_version
+          @title_version ||= diff_title_version
+        end
+
+        def profiles(profile: nil)
+          @profiles ||= diff_profiles(profile: profile)
+        end
+
+        private
+
+        def diff_title_version
+          diff = Hashdiff.diff(
+            @benchmark_a.to_h.reject { |k, _| k.to_s == 'profiles' },
+            @benchmark_b.to_h.reject { |k, _| k.to_s == 'profiles' },
+            AbideDevUtils::XCCDF::Diff::DEFAULT_DIFF_OPTS
+          )
+          diff.each_with_object({}) do |change, tdiff|
+            val_to = change.length == 4 ? change[3] : nil
+            change_key = change[2].is_a?(Hash) ? change[2][:title] : change[2]
+            tdiff[change_key] = [] unless tdiff.key?(change_key)
+            tdiff[change_key] << ChangeSet.new(change: change[0], key: change[1], value: change[2], value_to: val_to)
+          end
+        end
+
+        def diff_profiles(profile: nil)
+          diff = {}
+          other_hash = @benchmark_b.to_h[:profiles]
+          @benchmark_a.to_h[:profiles].each do |name, data|
+            next if profile && profile != name
+
+            diff[name] = ProfileDiff.new(data, other_hash[name], @opts).diff
+          end
+          diff
+        end
+      end
+
+      def self.diff_benchmarks(benchmark_a, benchmark_b, opts = {})
+        profile = opts.fetch(:profile, nil)
+        profile_key = profile.nil? ? 'all_profiles' : profile
+        benchmark_diff = BenchmarkDiff.new(benchmark_a, benchmark_b, opts)
+        transform_method_sym = opts.fetch(:raw, false) ? :to_h : :to_s
+        diff = if profile.nil?
+                 benchmark_diff.profiles.each do |_, v|
+                   v.transform_values! { |x| x.map!(&transform_method_sym) }
+                 end
+               else
+                 benchmark_diff.profiles(profile: profile)[profile].transform_values! { |x| x.map!(&transform_method_sym) }
+               end
+        return diff.values.flatten if opts.fetch(:raw, false)
+
+        {
+          'benchmark' => benchmark_diff.title_version.transform_values { |x| x.map!(&:to_s) },
+          profile_key => diff.values.flatten,
+        }
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/xccdf/parser/objects/digest_object.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module AbideDevUtils
+  module XCCDF
+    module Parser
+      module Objects
+        # Methods for providing and comparing hash digests of objects
+        module DigestObject
+          # Excludes instance variables that are not used in the digest
+          def exclude_from_digest(exclude)
+            unless exclude.is_a?(Array) || exclude.is_a?(Symbol)
+              raise ArgumentError, 'exclude must be an Array or Symbol'
+            end
+
+            @exclude_from_digest ||= []
+            if exclude.is_a?(Array)
+              exclude.map! do |e|
+                normalize_exclusion(e)
+              end
+              @exclude_from_digest += exclude
+            else
+              @exclude_from_digest << normalize_exclusion(exclude)
+            end
+            @exclude_from_digest.uniq!
+          end
+
+          # Exclusions are instance variable symbols and must be prefixed with "@"
+          def normalize_exclusion(exclude)
+            exclude = "@#{exclude}" unless exclude.to_s.start_with?('@')
+            exclude.to_sym
+          end
+
+          # Checks SHA256 digest equality
+          def digest_equal?(other)
+            digest == other.digest
+          end
+
+          # Returns a SHA256 digest of the object, including the digests of all
+          # children
+          def digest
+            return @digest if defined?(@digest)
+
+            parts = [labeled_self_digest]
+            children.each { |child| parts << child.digest } unless children.empty?
+            @digest = parts.join('|')
+            @digest
+          end
+
+          # Returns a labeled digest of the current object
+          def labeled_self_digest
+            return "#{label}:#{Digest::SHA256.hexdigest(digestable_instance_variables)}" if respond_to?(:label)
+
+            "none:#{Digest::SHA256.hexdigest(digestable_instance_variables)}"
+          end
+
+          # Returns a string of all instance variable values that are not nil, empty, or excluded
+          def digestable_instance_variables
+            instance_vars = instance_variables.reject { |iv| @exclude_from_digest.include?(iv) }.sort_by!(&:to_s)
+            return 'empty' if instance_vars.empty?
+
+            var_vals = instance_vars.map { |iv| instance_variable_get(iv) }
+            var_vals.reject! { |v| v.nil? || v.empty? }
+            return 'empty' if var_vals.empty?
+
+            var_vals.join
+          end
+
+          # Compares two objects by their SHA256 digests
+          # and returns the degree to which they are similar
+          # as a percentage.
+          def digest_similarity(other, only_labels: [], label_weights: {})
+            digest_parts = sorted_digest_parts(digest)
+            number_compared = 0
+            cumulative_similarity = 0.0
+            digest_parts.each do |digest_part|
+              label, self_digest = split_labeled_digest(digest_part)
+              next unless only_labels.empty? || only_labels.include?(label)
+
+              label_weight = label_weights.key?(label) ? label_weights[label] : 1.0
+              sorted_digest_parts(other.digest).each do |other_digest_part|
+                other_label, other_digest = split_labeled_digest(other_digest_part)
+                next unless (label == other_label) && (self_digest == other_digest)
+
+                number_compared += 1
+                cumulative_similarity += 1.0 * label_weight
+                break # break when found
+              end
+            end
+            cumulative_similarity / (number_compared.zero? ? 1.0 : number_compared)
+          end
+
+          def sorted_digest_parts(dgst)
+            @sorted_digest_parts_cache = {} unless defined?(@sorted_digest_parts_cache)
+            return @sorted_digest_parts_cache[dgst] if @sorted_digest_parts_cache.key?(dgst)
+
+            @sorted_digest_parts_cache ||= {}
+            @sorted_digest_parts_cache[dgst] = dgst.split('|').sort_by { |part| split_labeled_digest(part).first }
+            @sorted_digest_parts_cache[dgst]
+          end
+
+          # If one of the digest parts is nil and the other is not, we can't compare
+          def non_compatible?(digest_part, other_digest_part)
+            (digest_part.nil? || other_digest_part.nil?) && digest_part != other_digest_part
+          end
+
+          # Splits a digest into a label and digest
+          def split_labeled_digest(digest_part)
+            @labeled_digest_part_cache = {} unless defined?(@labeled_digest_part_cache)
+            return @labeled_digest_part_cache[digest_part] if @labeled_digest_part_cache.key?(digest_part)
+
+            @labeled_digest_part_cache[digest_part] = digest_part.split(':')
+            @labeled_digest_part_cache[digest_part]
+          end
+        end
+      end
+    end
+  end
+end