compliance_engine 0.1.0

data/TODO.md

@@ -0,0 +1,19 @@
+Unimplemented features, in no particular order:
+
+- [x] Limit ces/checks/controls based on selected profile
+- [x] Correlation between ces/controls and checks
+- [ ] Test merge of profiles (ordering of settings)
+- [ ] Test malformed data
+- [ ] Storage and resolution of facts
+- [ ] Confinement
+- [ ] Enforcement tolerance
+- [ ] Hiera backend functionality
+- [ ] Add missing documentation
+- [ ] Reset state when files are updated
+- [ ] Shared state between multiple objects (store file data)
+- [ ] Command-line tools for examining compliance data
+- [ ] Lint support (replace `scelint`)
+- [ ] Resolve oval ids to CEs
+- [ ] Puppet environment support
+    - [ ] Read/store metadata
+    - [ ] Load compliance data from a module path

data/exe/compliance_engine

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'compliance_engine/cli'
+
+ComplianceEngine::CLI.start(ARGV)

data/lib/compliance_engine/ce.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A compliance engine data CE
+class ComplianceEngine::Ce < ComplianceEngine::Component
+end

data/lib/compliance_engine/ces.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A collection of compliance engine data CEs
+class ComplianceEngine::Ces < ComplianceEngine::Collection
+  # A Hash of CEs by OVAL ID
+  #
+  # @return [Hash]
+  def by_oval_id
+    return @by_oval_id unless @by_oval_id.nil?
+
+    @by_oval_id ||= {}
+
+    each do |k, v|
+      v.oval_ids&.each do |oval_id|
+        @by_oval_id[oval_id] ||= {}
+        @by_oval_id[oval_id][k] = v
+      end
+    end
+
+    @by_oval_id
+  end
+
+  private
+
+  # Returns the key of the collection in compliance engine source data
+  #
+  # @return [String]
+  def key
+    'ce'
+  end
+
+  # Returns the class to use for the collection
+  #
+  # @return [Class]
+  def collected
+    ComplianceEngine::Ce
+  end
+end

data/lib/compliance_engine/check.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A compliance engine data check
+class ComplianceEngine::Check < ComplianceEngine::Component
+  # Returns the settings of the check
+  #
+  # @return [Hash] the settings of the check
+  def settings
+    element['settings']
+  end
+
+  # Returns the Puppet class parameters of the check
+  #
+  # @return [Hash] the Puppet class parameters of the check
+  def hiera
+    return @hiera unless @hiera.nil?
+
+    return @hiera = nil unless type == 'puppet-class-parameter'
+
+    @hiera = { settings['parameter'] => settings['value'] }
+  end
+
+  # Returns the type of the check
+  #
+  # @return [String] the type of the check
+  def type
+    element['type']
+  end
+
+  # Returns the remediation data of the check
+  #
+  # @return [Hash] the remediation data of the check
+  def remediation
+    element['remediation']
+  end
+end

data/lib/compliance_engine/checks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A collection of compliance engine data checks
+class ComplianceEngine::Checks < ComplianceEngine::Collection
+  private
+
+  # Returns the key of the collection in compliance engine source data
+  #
+  # @return [String]
+  def key
+    'checks'
+  end
+
+  # Returns the class to use for the collection
+  #
+  # @return [Class]
+  def collected
+    ComplianceEngine::Check
+  end
+end

data/lib/compliance_engine/cli.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+require 'thor'
+
+# Compliance Engine CLI
+class ComplianceEngine::CLI < Thor
+  class_option :facts, type: :string
+  class_option :enforcement_tolerance, type: :numeric
+  class_option :module, type: :array, default: []
+  class_option :modulepath, type: :array
+  class_option :modulezip, type: :string
+
+  desc 'hiera', 'Dump Hiera data'
+  option :profile, type: :array, required: true
+  def hiera
+    require 'yaml'
+    puts data.hiera(options[:profile]).to_yaml
+  end
+
+  desc 'lookup KEY', 'Look up a Hiera key'
+  option :profile, type: :array, required: true
+  def lookup(key)
+    require 'yaml'
+    puts data.hiera(options[:profile]).select { |k, _| k == key }.to_yaml
+  end
+
+  desc 'dump', 'Dump all compliance data'
+  def dump
+    require 'yaml'
+    data.files.each do |file|
+      puts({ file => data.get(file) }.to_yaml)
+    end
+  end
+
+  desc 'profiles', 'List available profiles'
+  def profiles
+    require 'yaml'
+    puts data.profiles.select { |_, value| value.ces&.count&.positive? || value.controls&.count&.positive? }.keys.to_yaml
+  end
+
+  desc 'inspect', 'Start an interactive shell'
+  def inspect
+    # Run the CLI with `data` as the object containing the compliance data.
+    require 'irb'
+    # rubocop:disable Lint/Debugger
+    binding.irb
+    # rubocop:enable Lint/Debugger
+  end
+
+  private
+
+  def data
+    return @data unless @data.nil?
+
+    @data = ComplianceEngine::Data.new(facts: facts, enforcement_tolerance: options[:enforcement_tolerance])
+    if options[:modulezip]
+      @data.open_environment_zip(options[:modulezip])
+    elsif options[:modulepath]
+      @data.open_environment(*options[:modulepath])
+    else
+      @data.open(*options[:module])
+    end
+
+    @data
+  end
+
+  def facts
+    return nil unless options[:facts]
+    return @facts unless @facts.nil?
+
+    require 'json'
+
+    @facts = JSON.parse(options[:facts])
+  end
+end

data/lib/compliance_engine/collection.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A generic compliance engine data collection
+class ComplianceEngine::Collection
+  # A generic compliance engine data collection
+  #
+  # @param data [ComplianceEngine::Data] the data to initialize the object with
+  def initialize(data)
+    context_variables.each { |var| instance_variable_set(var, data.instance_variable_get(var)) }
+    @collection ||= {}
+    hash_key = key
+    data.files.each do |file|
+      data.get(file)[hash_key]&.each do |k, v|
+        @collection[k] ||= collected.new(k, data: self)
+        @collection[k].add(file, v)
+      end
+    end
+  end
+
+  attr_accessor :collection, :facts, :enforcement_tolerance, :environment_data
+
+  # Invalidate the cache of computed data
+  #
+  # @param data [ComplianceEngine::Data, NilClass] the data to initialize the object with
+  # @return [NilClass]
+  def invalidate_cache(data = nil)
+    context_variables.each { |var| instance_variable_set(var, data&.instance_variable_get(var)) }
+    collection.each_value { |obj| obj.invalidate_cache(data) }
+    (instance_variables - (context_variables + [:@collection])).each { |var| instance_variable_set(var, nil) }
+    nil
+  end
+
+  # Converts the object to a hash representation
+  #
+  # @return [Hash] the hash representation of the object
+  def to_h
+    collection.reject { |k, _| k.is_a?(Symbol) }
+  end
+
+  # Returns the keys of the collection
+  #
+  # @return [Array] the keys of the collection
+  def keys
+    to_h.keys
+  end
+
+  # Return a single value from the collection
+  #
+  # @param key [String] the key of the value to return
+  # @return [Object] the value of the key
+  def [](key)
+    collection[key]
+  end
+
+  # Iterates over the collection
+  #
+  # @param block [Proc] the block to execute
+  def each(&block)
+    to_h.each(&block)
+  end
+
+  # Iterates over values in the collection
+  #
+  # @param block [Proc] the block to execute
+  def each_value(&block)
+    to_h.each_value(&block)
+  end
+
+  # Iterates over keys in the collection
+  #
+  # @param block [Proc] the block to execute
+  def each_key(&block)
+    to_h.each_key(&block)
+  end
+
+  # Return true if any of the values in the collection match the block
+  #
+  # @param block [Proc] the block to execute
+  # @return [TrueClass, FalseClass] true if any of the values in the collection match the block
+  def any?(&block)
+    to_h.any?(&block)
+  end
+
+  # Return true if all of the values in the collection match the block
+  #
+  # @param block [Proc] the block to execute
+  # @return [TrueClass, FalseClass] true if all of the values in the collection match the block
+  def all?(&block)
+    to_h.all?(&block)
+  end
+
+  # Select values in the collection
+  #
+  # @param block [Proc] the block to execute
+  # @return [Hash] the filtered hash
+  def select(&block)
+    to_h.select(&block)
+  end
+
+  # Filter out values in the collection
+  #
+  # @param block [Proc] the block to execute
+  # @return [Hash] the filtered hash
+  def reject(&block)
+    to_h.reject(&block)
+  end
+
+  private
+
+  # Get the context variables
+  #
+  # @return [Array<Symbol>]
+  def context_variables
+    [:@enforcement_tolerance, :@environment_data, :@facts]
+  end
+
+  # Returns the key of the object
+  #
+  # @return [NotImplementedError] This method is not implemented and should be overridden by subclasses.
+  def key
+    raise NotImplementedError
+  end
+
+  # Returns the class to use for the collection
+  #
+  # @return [NotImplementedError] This method is not implemented and should be overridden by subclasses.
+  def collected
+    raise NotImplementedError
+  end
+end

data/lib/compliance_engine/component.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+require 'deep_merge'
+
+# A generic compliance engine data component
+class ComplianceEngine::Component
+  # A generic compliance engine data component
+  #
+  # @param [String] component The component key
+  # @param [ComplianceEngine::Data, ComplianceEngine::Collection, NilClass] data The data to initialize the object with
+  def initialize(name, data: nil)
+    context_variables.each { |var| instance_variable_set(var, data&.instance_variable_get(var)) }
+    @component ||= { key: name, fragments: {} }
+  end
+
+  attr_accessor :component, :facts, :enforcement_tolerance, :environment_data
+
+  # Invalidate the cache of computed data
+  #
+  # @param data [ComplianceEngine::Data, ComplianceEngine::Collection, NilClass] the data to initialize the object with
+  # @return [NilClass]
+  def invalidate_cache(data = nil)
+    context_variables.each { |var| instance_variable_set(var, data&.instance_variable_get(var)) }
+    cache_variables.each { |var| instance_variable_set(var, nil) }
+    nil
+  end
+
+  # Adds a value to the fragments array of the component.
+  #
+  # @param value [Object] The value to be added to the fragments array.
+  # @return [Object]
+  def add(filename, value)
+    component[:fragments][filename] = value
+  end
+
+  # Returns an array of fragments from the component
+  #
+  # @return [Array] an array of fragments
+  def to_a
+    component[:fragments].values
+  end
+
+  # Returns the merged data from the component
+  #
+  # @return [Hash] merged data
+  def to_h
+    element
+  end
+
+  # Returns the key of the component
+  #
+  # @return [String] the key of the component
+  def key
+    component[:key]
+  end
+
+  # Returns the title of the component
+  #
+  # @return [String] the title of the component
+  def title
+    element['title']
+  end
+
+  # Returns the description of the component
+  #
+  # @return [String] the description of the component
+  def description
+    element['description']
+  end
+
+  # Returns the oval ids of the component
+  #
+  # @return [Array] the oval ids of the component
+  def oval_ids
+    element['oval-ids']
+  end
+
+  # Returns the controls of the component
+  #
+  # @return [Hash] the controls of the component
+  def controls
+    element['controls']
+  end
+
+  # Returns the identifiers of the component
+  #
+  # @return [Hash] the identifiers of the component
+  def identifiers
+    element['identifiers']
+  end
+
+  # Returns the ces of the component
+  #
+  # @return [Array, Hash] the ces of the component
+  # @note This returns an Array for checks and a Hash for other components
+  def ces
+    element['ces']
+  end
+
+  # Return a single key from the component
+  #
+  # @param key [String] the key of the value to return
+  # @return [Object] the value of the key
+  def [](key)
+    element[key]
+  end
+
+  private
+
+  # Get the context variables
+  #
+  # @return [Array<Symbol>]
+  def context_variables
+    [:@enforcement_tolerance, :@environment_data, :@facts]
+  end
+
+  # Get the cache variables
+  #
+  # @return [Array<Symbol>]
+  def cache_variables
+    instance_variables - (context_variables + [:@component])
+  end
+
+  # Compare a fact value against a confine value
+  #
+  # @param [Object] fact The fact value
+  # @param [Object] confine The confine value
+  # @param [Integer] depth The depth of the recursion
+  # @return [TrueClass, FalseClass] true if the fact value matches the confine value
+  def fact_match?(fact, confine, depth = 0)
+    if confine.is_a?(String)
+      return fact != confine.delete_prefix('!') if confine.start_with?('!')
+
+      fact == confine
+    elsif confine.is_a?(Array)
+      if depth == 0
+        confine.any? { |value| fact_match?(fact, value, depth + 1) }
+      else
+        fact == confine
+      end
+    else
+      fact == confine
+    end
+  end
+
+  # Check if a fragment is confined
+  #
+  # @param [Hash] fragment The fragment to check
+  # @return [TrueClass, FalseClass] true if the fragment should be dropped
+  def confine_away?(fragment)
+    return false unless fragment.key?('confine')
+
+    fragment['confine'].each do |k, v|
+      if k == 'module_name'
+        unless environment_data.nil?
+          return true unless environment_data.key?(v)
+          module_version = fragment['confine']['module_version']
+          unless module_version.nil?
+            require 'semantic_puppet'
+            begin
+              return true unless SemanticPuppet::VersionRange.parse(module_version).include?(SemanticPuppet::Version.parse(environment_data[v]))
+            rescue => e
+              warn "Failed to compare #{v} #{environment_data[v]} with version confinement #{module_version}: #{e.message}"
+              return true
+            end
+          end
+        end
+      elsif k == 'module_version'
+        warn "Missing module name for #{fragment}" unless fragment['confine'].key?('module_name')
+      else
+        # Confinement based on Puppet facts
+        unless facts.nil?
+          fact = facts.dig(*k.split('.'))
+          if fact.nil?
+            return true
+          end
+          unless fact_match?(fact, v)
+            return true
+          end
+        end
+      end
+    end
+
+    false
+  end
+
+  # Returns the fragments of the component after confinement
+  #
+  # @return [Hash] the fragments of the component
+  def fragments
+    return @fragments unless @fragments.nil?
+
+    @fragments ||= {}
+
+    component[:fragments].each do |filename, fragment|
+      # If none of the confinable data is present in the object,
+      # ignore confinement data entirely.
+      if facts.nil? && enforcement_tolerance.nil? && environment_data.nil?
+        @fragments[filename] = fragment
+        next
+      end
+
+      # If no confine data is present in the fragment, include it.
+      if !fragment.key?('confine') && !fragment.key?('remediation')
+        @fragments[filename] = fragment
+        next
+      end
+
+      next if confine_away?(fragment)
+
+      # Confinement based on remediation risk
+      if enforcement_tolerance.is_a?(Integer) && is_a?(ComplianceEngine::Check) && fragment.key?('remediation')
+        if fragment['remediation'].key?('disabled')
+          message = "Remediation disabled for #{fragment}"
+          reason = fragment['remediation']['disabled']&.map { |value| value['reason'] }&.reject { |value| value.nil? }&.join("\n")
+          message += "\n#{reason}" unless reason.nil?
+          warn message
+          next
+        end
+
+        if fragment['remediation'].key?('risk')
+          risk_level = fragment['remediation']['risk']&.map { |value| value['level'] }&.select { |value| value.is_a?(Integer) }&.max
+          if risk_level.is_a?(Integer) && risk_level >= enforcement_tolerance
+            warn "Remediation risk #{risk_level} exceeds enforcement tolerance #{enforcement_tolerance} for #{fragment}"
+            next
+          end
+        end
+      end
+
+      @fragments[filename] = fragment
+    end
+
+    @fragments
+  end
+
+  # Returns a merged view of the component fragments
+  #
+  # @return [Object] the element of the component
+  def element
+    return @element unless @element.nil?
+
+    @element = {}
+
+    fragments.each_value do |fragment|
+      @element = @element.deep_merge!(fragment)
+    end
+
+    @element
+  end
+end

data/lib/compliance_engine/control.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A compliance engine data control
+class ComplianceEngine::Control < ComplianceEngine::Component
+end

data/lib/compliance_engine/controls.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'compliance_engine'
+
+# A collection of compliance engine data controls
+class ComplianceEngine::Controls < ComplianceEngine::Collection
+  private
+
+  # Returns the key of the collection in compliance engine source data
+  #
+  # @return [String]
+  def key
+    'controls'
+  end
+
+  # Returns the class to use for the collection
+  #
+  # @return [Class]
+  def collected
+    ComplianceEngine::Control
+  end
+end