compliance_engine 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5129c30257114df1399ae314ff6a0fb5d383de5bd4782b8b31dc060ea274870
-  data.tar.gz: 8dfaa1d2feaf1a43ea6551851eac5a586f2d4e2b4148efcd14cad21c32c93cba
+  metadata.gz: 9f8203b0a0381216d9a1a91c318f0f162bde1d4835bc7731c954156371b6f9b8
+  data.tar.gz: 784264cbb1aba5772bbf97dafdd952c3b8823fa404236c372af87f1d6dad885b
 SHA512:
-  metadata.gz: b4839e2648adfc6c1ea91d16c45a5494a6ad4da6521d816e16b9d0b3127b80d696d6f0cbb5249294cf6e0f21177809fbe9b8efd6c3665e3aae1bee6a02570134
-  data.tar.gz: 68a0a04f93e3c007eec4287a92d6d19ace0ba37e9a739200474802ef28c6cb24b01257cec5e23f8b8e2cb8f29cf397641ac1e2fc5a1c117ca1db43f1932c2c3d
+  metadata.gz: 1026ff097b4e46f31b59b2a584e9d25b94baa986014564fa6a0196d70224306956fd0499d923fa19b0c1035d248c490a3ffaaa1bbcf8f55bd222e7726fb25157
+  data.tar.gz: 588997e4f32f95f7d1edef560a16a09399c59d1b7aba4677ca6cf0bf9d97f38568d9d14c9349a5e489288d16dffe0abc2abc0147cecc9beb5127701270d3594a

data/AGENTS.md

@@ -91,6 +91,8 @@ A component can have multiple **fragments** (one per source file), which are dee
 | CE→Control overlap | Any of `check.ces`' CEs has a control that also appears in `profile.controls` |
 | Direct reference | `profile.checks[check_key]` is truthy |
 
+An entry on the **profile side** with value `false` is treated as an **explicit exclusion** that overrides positive matches: `profile.checks[X] = false` hard-excludes check `X` from every route, and `profile.ces[X] = false` prevents CE `X` from being used as either a direct CE match or as a CE→Control bridge. On the **check side**, `false` is local-only (e.g. `check.controls[X] = false` simply means the check is not associated with control `X`); `check.ces` is an array, so no `false` handling applies.
+
 `check_mapping` can also be called with CE objects (in addition to profiles). Results are cached by `"#{object.class}:#{object.key}"`.
 
 ### Loading Pipeline

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+### 0.6.0 / 2026-05-05
+* Honor explicit `false` in profile `checks` and `ces` mappings as exclusions that override positive matches (#117)
+* Coerce non-String `zipfile.name` to `-` for buffer-opened zips (#121)
+* Replace `Zip::File` handoff with `open_environment_zip_bytes` (#124)
+
+### 0.5.0 / 2026-04-29
+* Add JSON Schema for SCE data, exposed via `ComplianceEngine.schema` (#49)
+* Add `ComplianceEngine::Tolerance` constants for enforcement tolerance levels (#107)
+* Drop stale file data on environment rescan (#108)
+* Handle malformed compliance data gracefully instead of raising (#111)
+* Make dotfile loading opt-in (defaults to off) (#112)
+* Accept `::Zip::File` objects directly in `EnvironmentLoader::Zip` (#114)
+* Support `compliance_markup`-style parameter knockout prefixes
+* Split `version.rb`: separate gem `VERSION` from data format validator (#104)
+
 ### 0.4.0 / 2026-04-20
 * Route Puppet Hiera backend log messages through Puppet's logging system (#96)
 * Fix JRuby compatibility: convert internal requires to require_relative so the library loads correctly inside Puppet Server / OpenVox Server when installed as a Puppet module rather than a standalone gem

data/compliance_engine.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.metadata['bug_tracker_uri'] = 'https://github.com/simp/rubygem-simp-compliance_engine/issues'
 
   # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.glob(['*.gemspec', '*.md', 'LICENSE', 'exe/*', 'lib/**/*.rb']).reject { |f| f.start_with?('lib/puppet/') }
+  spec.files = Dir.glob(['*.gemspec', '*.md', 'LICENSE', 'exe/*', 'lib/**/*.rb', 'lib/**/*.json']).reject { |f| f.start_with?('lib/puppet/') }
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

data/lib/compliance_engine/collection.rb

@@ -12,7 +12,21 @@ class ComplianceEngine::Collection
     @collection ||= {}
     hash_key = key
     data.files.each do |file|
-      data.get(file)[hash_key]&.each do |k, v|
+      file_data = data.get(file)
+      unless file_data.is_a?(Hash)
+        ComplianceEngine.log.debug "Skipping #{file}: expected Hash content, got #{file_data.class}"
+        next
+      end
+
+      entries = file_data[hash_key]
+      next if entries.nil?
+
+      unless entries.is_a?(Hash)
+        ComplianceEngine.log.error "Expected '#{hash_key}' in #{file} to be a Hash, got #{entries.class}"
+        next
+      end
+
+      entries.each do |k, v|
         @collection[k] ||= collected.new(k, data: self)
         @collection[k].add(file, v)
       end

data/lib/compliance_engine/data.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+require 'set'
 require_relative '../compliance_engine'
-require_relative 'version'
+require_relative 'data_version'
 require_relative 'component'
 require_relative 'ce'
 require_relative 'check'
@@ -124,13 +125,29 @@ class ComplianceEngine::Data
     nil
   end
 
-  # Scan a Puppet environment from a zip file
-  # @param path [String] The Puppet environment archive file
+  # Scan a Puppet environment from a zip file on disk
+  # @param path [String] filesystem path to the zip archive
+  # @param name [String, nil] stable string identifier used as the modulepath
+  #   and cache-key prefix; defaults to the full path string passed as +path+.
   # @return [NilClass]
-  def open_environment_zip(path)
+  def open_environment_zip(path, name: nil)
     require 'compliance_engine/environment_loader/zip'
 
-    environment = ComplianceEngine::EnvironmentLoader::Zip.new(path)
+    environment = ComplianceEngine::EnvironmentLoader::Zip.new(path, name: name)
+    self.modulepath = environment.modulepath
+    open(environment)
+  end
+
+  # Scan a Puppet environment from a raw zip byte string
+  #
+  # @param bytes [String] raw binary zip data (e.g. from File.binread or an HTTP body)
+  # @param name [String, nil] stable string identifier used as the modulepath
+  #   and cache-key prefix; defaults to "-" when no filename is available.
+  # @return [NilClass]
+  def open_environment_zip_bytes(bytes, name: nil)
+    require 'compliance_engine/environment_loader/zip_bytes'
+
+    environment = ComplianceEngine::EnvironmentLoader::ZipBytes.new(bytes, name: name)
     self.modulepath = environment.modulepath
     open(environment)
   end
@@ -161,9 +178,17 @@ class ComplianceEngine::Data
 
       if path.is_a?(ComplianceEngine::ModuleLoader)
         modules[path.name] = path.version unless path.name.nil?
-        path.files.each do |file_loader|
-          update(file_loader)
-        end
+        new_keys = path.files.to_set(&:key)
+        module_root = if path.zipfile_path
+                        ::File.join(path.zipfile_path, '.', path.path.sub(%r{^/+}, ''))
+                      else
+                        path.path
+                      end
+        module_prefix = ::File.join(module_root, '')
+        stale_keys = data.keys.select { |k| (k == module_root || k.start_with?(module_prefix)) && !new_keys.include?(k) }
+        stale_keys.each { |k| data.delete(k) }
+        path.files.each { |file_loader| update(file_loader) }
+        reset_collection if path.files.empty? && !stale_keys.empty?
         next
       end
 
@@ -221,7 +246,7 @@ class ComplianceEngine::Data
       loader.add_observer(self, :update)
       data[key] = {
         loader: loader,
-        version: ComplianceEngine::Version.new(loader.data['version']),
+        version: ComplianceEngine::DataVersion.new(loader.data['version']),
         content: loader.data,
       }
     else
@@ -237,7 +262,7 @@ class ComplianceEngine::Data
         data[filename.key][:loader] = filename
         data[filename.key][:loader].add_observer(self, :update)
       end
-      data[filename.key][:version] = ComplianceEngine::Version.new(filename.data['version'])
+      data[filename.key][:version] = ComplianceEngine::DataVersion.new(filename.data['version'])
       data[filename.key][:content] = filename.data
     end
 
@@ -306,7 +331,8 @@ class ComplianceEngine::Data
         v.to_a.each do |component|
           next unless component.key?('confine')
 
-          @confines = DeepMerge.deep_merge!(component['confine'], @confines)
+          confine = component['confine'].transform_values { |val| val.is_a?(Array) ? val.dup : Array(val) }
+          @confines = DeepMerge.deep_merge!(confine, @confines, knockout_prefix: '--')
         end
       end
     end
@@ -348,10 +374,24 @@ class ComplianceEngine::Data
 
     valid_profiles.reverse_each do |profile|
       check_mapping(profile).each_value do |check|
-        parameters = DeepMerge.deep_merge!(check.hiera, parameters)
+        hiera_data = check.hiera
+        next if hiera_data.nil?
+
+        parameters = DeepMerge.deep_merge!(Marshal.load(Marshal.dump(hiera_data)), parameters)
       end
     end
 
+    # deep_merge does not support hash-key knockout via knockout_prefix.
+    # Handle parameter-name knockout explicitly: any key starting with '--'
+    # signals that the matching key without the prefix should be suppressed
+    # (mirrors compliance_markup behavior).
+    parameters.each_key do |key|
+      next unless key.start_with?('--')
+
+      parameters.delete(key.delete_prefix('--'))
+      parameters.delete(key)
+    end
+
     @hiera[cache_key] = parameters
   end
 
@@ -415,6 +455,9 @@ class ComplianceEngine::Data
     cache_key = [check.key, "#{profile_or_ce.class}:#{profile_or_ce.key}"].to_s
     return @mapping[cache_key] if @mapping.key?(cache_key)
 
+    # An explicit `false` on the profile side hard-excludes the check, regardless of any other route.
+    return @mapping[cache_key] = false if profile_or_ce.is_a?(ComplianceEngine::Profile) && profile_or_ce.checks&.dig(check.key) == false
+
     # Correlate based on controls
     controls = check.controls&.select { |_, v| v }&.map { |k, _| k }
 
@@ -433,9 +476,10 @@ class ComplianceEngine::Data
     # Correlate based on CEs
     return @mapping[cache_key] = true if correlate(check.ces, profile_or_ce.ces)
 
-    # Correlate based on CEs and controls
-    return @mapping[cache_key] = true if profile_or_ce.ces&.any? { |k, _| correlate(controls, ces[k]&.controls) }
-    return @mapping[cache_key] = true if check.ces&.any? { |ce| ces[ce]&.controls&.any? { |k, v| v && profile_or_ce.controls&.dig(k) } }
+    # Correlate based on CEs and controls. A CE explicitly set to `false` in the profile
+    # cannot be used as a bridge; absence (nil) still allows the bridge.
+    return @mapping[cache_key] = true if profile_or_ce.ces&.any? { |k, v| v && correlate(controls, ces[k]&.controls) }
+    return @mapping[cache_key] = true if check.ces&.any? { |ce| profile_or_ce.ces&.dig(ce) != false && ces[ce]&.controls&.any? { |k, v| v && profile_or_ce.controls&.dig(k) } }
 
     @mapping[cache_key] = false
   end

data/lib/compliance_engine/data_version.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../compliance_engine'
+
+# Validates the version field found in compliance data files.
+# Currently only version 2.0.0 of the data format is supported.
+class ComplianceEngine::DataVersion
+  # @param version [String] the version string from a compliance data file
+  # @raise [ComplianceEngine::Error] if version is nil or not '2.0.0'
+  def initialize(version)
+    raise ComplianceEngine::Error, 'Missing version' if version.nil?
+    raise ComplianceEngine::Error, "Unsupported version '#{version}'" unless version == '2.0.0'
+
+    @version = version
+  end
+
+  # @return [String]
+  def to_s
+    @version
+  end
+end

data/lib/compliance_engine/environment_loader/zip.rb

@@ -7,18 +7,21 @@ require 'zip/filesystem'
 # Load compliance engine data from a zip file containing a Puppet environment
 class ComplianceEngine::EnvironmentLoader::Zip < ComplianceEngine::EnvironmentLoader
   # Initialize a ComplianceEngine::EnvironmentLoader::Zip object from a zip
-  # file and an optional root directory.
+  # file path and an optional root directory.
   #
-  # @param path [String] the path to the zip file containing the Puppet environment
+  # @param input [String] filesystem path to a zip file
   # @param root [String] a directory within the zip file to use as the root of the environment
-  def initialize(path, root: '/'.dup)
-    @modulepath = path
+  # @param load_dotfiles [Boolean] whether to load dotfiles; defaults to true to
+  #   preserve the historical zip-loader behaviour of including all files
+  # @param name [String, nil] identifier used for modulepath and downstream
+  #   cache keys; defaults to the full path string passed as +input+.
+  def initialize(input, root: '/'.dup, load_dotfiles: true, name: nil)
+    raise ArgumentError, "input must be a String path, got #{input.class}" unless input.is_a?(String)
 
-    ::Zip::File.open(path) do |zipfile|
-      dir = zipfile.dir
-      file = zipfile.file
-
-      super(root, fileclass: file, dirclass: dir, zipfile_path: path)
-    end
+    zipfile = ::Zip::File.open(input)
+    @modulepath = name || input.to_s
+    super(root, fileclass: zipfile.file, dirclass: zipfile.dir, zipfile_path: @modulepath, load_dotfiles: load_dotfiles)
+  ensure
+    zipfile&.close
   end
 end

data/lib/compliance_engine/environment_loader/zip_bytes.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../../compliance_engine'
+require_relative '../environment_loader'
+# zip/filesystem must be required before any Zip::File instance is opened so
+# that the per-instance dir/file accessors are wired up at open time.
+require 'zip/filesystem'
+require 'zip'
+
+# Load compliance engine data from a raw zip byte string containing a Puppet environment
+class ComplianceEngine::EnvironmentLoader::ZipBytes < ComplianceEngine::EnvironmentLoader
+  # @param bytes [String] raw binary zip data (e.g. from File.binread or an HTTP body)
+  # @param root [String] a directory within the zip file to use as the root of the environment
+  # @param load_dotfiles [Boolean] whether to load dotfiles; defaults to true to
+  #   preserve the historical zip-loader behaviour of including all files
+  # @param name [String, nil] identifier used for modulepath and downstream
+  #   cache keys; defaults to "-" when no filename is available.
+  def initialize(bytes, root: '/'.dup, load_dotfiles: true, name: nil)
+    raise ArgumentError, "bytes must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+    zipfile = ::Zip::File.open_buffer(bytes)
+    @modulepath = name || '-'
+    super(root, fileclass: zipfile.file, dirclass: zipfile.dir, zipfile_path: @modulepath, load_dotfiles: load_dotfiles)
+  ensure
+    zipfile&.close
+  end
+end

data/lib/compliance_engine/environment_loader.rb

@@ -11,7 +11,9 @@ class ComplianceEngine::EnvironmentLoader
   # @param fileclass [File] the class to use for file operations (default: `File`)
   # @param dirclass [Dir] the class to use for directory operations (default: `Dir`)
   # @param zipfile_path [String, nil] the path to the zip file if loading from a zip archive
-  def initialize(*paths, fileclass: File, dirclass: Dir, zipfile_path: nil)
+  # @param load_dotfiles [Boolean] whether to load dotfiles; passed through to
+  #   each ModuleLoader (default: false)
+  def initialize(*paths, fileclass: File, dirclass: Dir, zipfile_path: nil, load_dotfiles: false)
     raise ArgumentError, 'No paths specified' if paths.empty?
 
     @modulepath ||= paths
@@ -26,7 +28,7 @@ class ComplianceEngine::EnvironmentLoader
       []
     end
     modules.flatten!
-    @modules = modules.map { |path| ComplianceEngine::ModuleLoader.new(path, fileclass: fileclass, dirclass: dirclass, zipfile_path: @zipfile_path) }
+    @modules = modules.map { |path| ComplianceEngine::ModuleLoader.new(path, fileclass: fileclass, dirclass: dirclass, zipfile_path: @zipfile_path, load_dotfiles: load_dotfiles) }
   end
 
   attr_reader :modulepath, :modules, :zipfile_path

data/lib/compliance_engine/module_loader.rb

@@ -12,12 +12,18 @@ class ComplianceEngine::ModuleLoader
   # @param fileclass [File] the class to use for file operations (default: `File`)
   # @param dirclass [Dir] the class to use for directory operations (default: `Dir`)
   # @param zipfile_path [String, nil] the path to the zip file if loading from a zip archive
-  def initialize(path, fileclass: File, dirclass: Dir, zipfile_path: nil)
+  # @param load_dotfiles [Boolean] whether to load files whose relative path contains
+  #   a component (directory or filename) beginning with '.'. Defaults to false so that
+  #   dotfiles are skipped during normal module scanning, matching the behavior of
+  #   Ruby's Dir.glob on real filesystems. Set to true only when the caller explicitly
+  #   needs dotfile support (e.g. zip-based environment loading).
+  def initialize(path, fileclass: File, dirclass: Dir, zipfile_path: nil, load_dotfiles: false)
     raise ComplianceEngine::Error, "#{path} is not a directory" unless fileclass.directory?(path)
 
     @name = nil
     @version = nil
     @files = []
+    @path = path.to_s
     @zipfile_path = zipfile_path
 
     # Read the Puppet module's metadata.json
@@ -34,30 +40,42 @@ class ComplianceEngine::ModuleLoader
 
     # In this directory, we want to look for all yaml and json files
     # under SIMP/compliance_profiles and simp/compliance_profiles.
-    globs = ['SIMP/compliance_profiles', 'simp/compliance_profiles']
-            .select { |dir| fileclass.directory?(File.join(path, dir)) }
-            .map { |dir|
-      ['yaml', 'json'].map { |type| File.join(path, dir, '**', "*.#{type}") }
-    }.flatten
-    # Using .each here to make mocking with rspec easier.
-    globs.each do |glob|
-      dirclass.glob(glob).sort.each do |file|
-        key = if @zipfile_path
-                File.join(@zipfile_path, '.', file.to_s)
-              else
-                file.to_s
-              end
-        loader = if File.extname(file.to_s) == '.json'
-                   ComplianceEngine::DataLoader::Json.new(file.to_s, fileclass: fileclass, key: key)
-                 else
-                   ComplianceEngine::DataLoader::Yaml.new(file.to_s, fileclass: fileclass, key: key)
-                 end
-        @files << loader
-      rescue StandardError => e
-        ComplianceEngine.log.warn "Could not load #{file}: #{e.message}"
+    # The loops are structured this way (rather than building a flat globs
+    # array first) so that each glob result can be checked against its
+    # base directory for dotfile filtering.
+    ['SIMP/compliance_profiles', 'simp/compliance_profiles'].each do |dir|
+      base = File.join(path, dir)
+      next unless fileclass.directory?(base)
+
+      # Using .each here to make mocking with rspec easier.
+      ['yaml', 'json'].each do |type|
+        dirclass.glob(File.join(base, '**', "*.#{type}")).sort.each do |file|
+          unless load_dotfiles
+            # Skip any file whose path (relative to the compliance_profiles
+            # base) contains a component beginning with '.', e.g. hidden
+            # files (.profile.yaml) or files inside hidden directories
+            # (.hidden/profile.yaml).
+            relative = file.to_s.delete_prefix("#{base}/")
+            next if relative.split('/').any? { |part| part.start_with?('.') }
+          end
+
+          key = if @zipfile_path
+                  File.join(@zipfile_path, '.', file.to_s)
+                else
+                  file.to_s
+                end
+          loader = if File.extname(file.to_s) == '.json'
+                     ComplianceEngine::DataLoader::Json.new(file.to_s, fileclass: fileclass, key: key)
+                   else
+                     ComplianceEngine::DataLoader::Yaml.new(file.to_s, fileclass: fileclass, key: key)
+                   end
+          @files << loader
+        rescue StandardError => e
+          ComplianceEngine.log.warn "Could not load #{file}: #{e.message}"
+        end
       end
     end
   end
 
-  attr_reader :name, :version, :files, :zipfile_path
+  attr_reader :name, :version, :files, :path, :zipfile_path
 end

data/lib/compliance_engine/sce-schema.json

@@ -0,0 +1,517 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://simp-project.com/docs/sce/schema.json",
+  "type": "object",
+  "default": {},
+  "title": "Compliance Engine data",
+  "description": "Data for the Sicura Compliance Engine",
+  "required": [
+    "version"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "confine": {
+      "type": "object",
+      "title": "Conditions that confine this entry to specific environments",
+      "description": "Keys are dot-notation Puppet fact paths (e.g. os.release.major) or the special keys module_name and module_version. Values may be a single scalar (exact match; strings may be prefixed with ! to negate) or an array of scalars (any match).",
+      "patternProperties": {
+        "^\\w+(?:[.\\-]\\w+)*$": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "integer"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": ["string", "boolean", "integer"]
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "os.release.major": ["8"],
+          "os.name": "RedHat"
+        },
+        {
+          "ipv6_enabled": true
+        },
+        {
+          "module_name": "simp-compliance_engine",
+          "module_version": ">=1.0.0 <2.0.0"
+        }
+      ]
+    },
+    "controlsMap": {
+      "type": "object",
+      "title": "References to top-level controls entries. Enforced when value is true; explicitly excluded when value is false.",
+      "patternProperties": {
+        "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "nist_800_53:rev4:AU-2": true
+        }
+      ]
+    },
+    "identifiers": {
+      "title": "External framework identifiers",
+      "description": "Preferred form: an object whose keys are framework names (e.g. nist_800_53:rev4, disa_stig) and whose values are arrays of identifier strings or numbers within that framework. A plain array of identifier strings is also accepted.",
+      "oneOf": [
+        {
+          "type": "object",
+          "patternProperties": {
+            "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+              "type": "array",
+              "items": {
+                "type": ["string", "number"]
+              }
+            }
+          },
+          "examples": [
+            {
+              "nist_800_53:rev4": ["AU-2", "AU-3"],
+              "disa_stig": ["RHEL-07-021820", "CCI-000293"]
+            }
+          ]
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": ["string", "number"]
+          },
+          "examples": [
+            ["ID1.1", "ID1.2"]
+          ]
+        }
+      ]
+    }
+  },
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "2.0.0",
+      "title": "The SCE data format version"
+    },
+    "profiles": {
+      "type": "object",
+      "default": {},
+      "title": "Collection of compliance profiles",
+      "description": "Each profile is a named checklist of Checks, CEs, and Controls to enforce.",
+      "patternProperties": {
+        "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+          "type": "object",
+          "default": {},
+          "title": "A compliance profile",
+          "properties": {
+            "title": {
+              "type": "string",
+              "title": "Short description of the profile",
+              "examples": [
+                "Level 1 - Server"
+              ]
+            },
+            "description": {
+              "type": "string",
+              "title": "Longer description of the profile",
+              "examples": [
+                "Items in this profile intend to: be practical and prudent; provide a clear security benefit; and not inhibit the utility of the technology beyond acceptable means. This profile is intended for servers."
+              ]
+            },
+            "ces": {
+              "type": "object",
+              "default": {},
+              "title": "CEs to include in this profile. Enforced when value is true; explicitly excluded when value is false (overrides any positive mapping route).",
+              "patternProperties": {
+                "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+                  "type": "boolean",
+                  "default": false
+                }
+              },
+              "examples": [
+                {
+                  "oval:simp.cis.el8.1.6.2_Ensure_ASLR_is_enabled:def:1": true
+                }
+              ]
+            },
+            "controls": {
+              "$ref": "#/$defs/controlsMap"
+            },
+            "checks": {
+              "type": "object",
+              "default": {},
+              "title": "Checks to include in this profile. Enforced when value is true; hard-excluded when value is false (overrides any positive mapping route).",
+              "patternProperties": {
+                "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+                  "type": "boolean",
+                  "default": false
+                }
+              },
+              "examples": [
+                {
+                  "widget_spinner_audit_logging": true
+                }
+              ]
+            },
+            "confine": {
+              "$ref": "#/$defs/confine"
+            }
+          },
+          "examples": [
+            {
+              "title": "Level 1 - Server",
+              "description": "Items in this profile intend to: be practical and prudent; provide a clear security benefit; and not inhibit the utility of the technology beyond acceptable means. This profile is intended for servers.",
+              "controls": {
+                "cis:el8:l1": true
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "cis:el8:l1:server": {
+            "title": "CIS Level 1 - Server",
+            "controls": {
+              "cis:el8:l1": true
+            }
+          }
+        }
+      ]
+    },
+    "ce": {
+      "type": "object",
+      "default": {},
+      "title": "Collection of Compliance Elements (CEs)",
+      "description": "Each CE names a single compliance capability and bridges profiles to checks via a shared vocabulary.",
+      "patternProperties": {
+        "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+          "type": "object",
+          "default": {},
+          "title": "A Compliance Element",
+          "properties": {
+            "title": {
+              "type": "string",
+              "title": "Short title of the compliance element",
+              "examples": [
+                "Ensure address space layout randomization (ASLR) is enabled"
+              ]
+            },
+            "description": {
+              "type": "string",
+              "title": "Detailed description of the compliance element",
+              "examples": [
+                "Address space layout randomization (ASLR) is an exploit mitigation technique which randomly arranges the address space of key data areas of a process."
+              ]
+            },
+            "controls": {
+              "$ref": "#/$defs/controlsMap"
+            },
+            "identifiers": {
+              "$ref": "#/$defs/identifiers"
+            },
+            "oval-ids": {
+              "type": "array",
+              "default": [],
+              "title": "OVAL identifiers associated with this CE",
+              "items": {
+                "type": "string"
+              },
+              "examples": [
+                [
+                  "xccdf_org.cisecurity.benchmarks_rule_1.6.2_Ensure_ASLR_is_enabled"
+                ]
+              ]
+            },
+            "imported_data": {
+              "type": "object",
+              "default": {},
+              "title": "Data imported from external benchmark sources",
+              "properties": {
+                "fixtext": {
+                  "type": "string",
+                  "title": "Remediation instructions from the source benchmark"
+                }
+              },
+              "additionalProperties": true
+            },
+            "confine": {
+              "$ref": "#/$defs/confine"
+            }
+          },
+          "examples": [
+            {
+              "controls": {
+                "cis:el8:v1.0.0.1": true
+              },
+              "identifiers": {
+                "cis": ["1.6.2"],
+                "nist_800_53:rev4": ["SC-39"]
+              },
+              "title": "Ensure address space layout randomization (ASLR) is enabled",
+              "description": "Address space layout randomization (ASLR) is an exploit mitigation technique which randomly arranges the address space of key data areas of a process.",
+              "confine": {
+                "os.release.major": ["8"],
+                "os.name": ["RedHat"]
+              }
+            }
+          ]
+        }
+      }
+    },
+    "checks": {
+      "type": "object",
+      "default": {},
+      "title": "Collection of compliance checks",
+      "description": "Each check is a verifiable assertion about a system setting. Currently only type puppet-class-parameter is supported; it carries a parameter and value that become Hiera data.",
+      "patternProperties": {
+        "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+          "type": "object",
+          "default": {},
+          "title": "A compliance check",
+          "properties": {
+            "type": {
+              "type": "string",
+              "const": "puppet-class-parameter",
+              "title": "The type of check"
+            },
+            "settings": {
+              "type": "object",
+              "title": "Settings for the check",
+              "required": ["parameter", "value"],
+              "properties": {
+                "parameter": {
+                  "type": "string",
+                  "title": "The fully-qualified Puppet class parameter name. Prefix with -- to knock out an existing parameter.",
+                  "examples": [
+                    "simp::sysctl::kernel__randomize_va_space",
+                    "--simp::sysctl::kernel__randomize_va_space"
+                  ]
+                },
+                "value": {
+                  "title": "The value to enforce for the parameter",
+                  "type": ["boolean", "integer", "number", "string", "array", "object", "null"],
+                  "examples": [
+                    2,
+                    true,
+                    "weekly",
+                    ["item1", "item2"]
+                  ]
+                }
+              },
+              "examples": [
+                {
+                  "parameter": "simp::sysctl::kernel__randomize_va_space",
+                  "value": 2
+                }
+              ]
+            },
+            "ces": {
+              "type": "array",
+              "default": [],
+              "title": "CEs that this check satisfies",
+              "items": {
+                "type": "string"
+              },
+              "examples": [
+                [
+                  "oval:simp.cis.el8.1.6.2_Ensure_ASLR_is_enabled:def:1"
+                ]
+              ]
+            },
+            "controls": {
+              "$ref": "#/$defs/controlsMap"
+            },
+            "identifiers": {
+              "$ref": "#/$defs/identifiers"
+            },
+            "confine": {
+              "$ref": "#/$defs/confine"
+            },
+            "remediation": {
+              "type": "object",
+              "title": "Remediation metadata used to filter checks by enforcement tolerance",
+              "properties": {
+                "risk": {
+                  "type": "array",
+                  "title": "Risk entries describing the potential impact of enforcing this check",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "level": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 100,
+                        "title": "Numeric risk level (1-100). Checks are skipped when this value is >= the enforcement_tolerance setting."
+                      },
+                      "reason": {
+                        "type": "string",
+                        "title": "Human-readable explanation of the risk"
+                      }
+                    }
+                  },
+                  "examples": [
+                    [
+                      {
+                        "level": 41,
+                        "reason": "Depending on the system being scanned, aide could cause system sluggishness during the period it performs its scan."
+                      }
+                    ]
+                  ]
+                },
+                "disabled": {
+                  "type": "array",
+                  "title": "Entries indicating this check is disabled. Disabled checks are always skipped when enforcement_tolerance is set.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "reason": {
+                        "type": "string",
+                        "title": "Human-readable explanation of why this check is disabled"
+                      }
+                    }
+                  },
+                  "examples": [
+                    [
+                      {
+                        "reason": "This check is not applicable to containerized environments."
+                      }
+                    ]
+                  ]
+                }
+              }
+            }
+          },
+          "if": {
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["settings"]
+          },
+          "examples": [
+            {
+              "type": "puppet-class-parameter",
+              "settings": {
+                "parameter": "simp::sysctl::kernel__randomize_va_space",
+                "value": 2
+              },
+              "controls": {
+                "nist_800_53:rev4:SC-39": true
+              },
+              "confine": {
+                "os.family": "RedHat",
+                "os.release.major": ["7", "8", "9"]
+              }
+            }
+          ]
+        }
+      }
+    },
+    "controls": {
+      "type": "object",
+      "default": {},
+      "title": "Collection of compliance controls",
+      "description": "Controls are cross-reference labels from external frameworks (e.g. nist_800_53:rev4:AU-2, disa_stig). Profiles and checks annotate themselves with controls to express alignment. Control entries carry optional metadata; an empty object {} is valid.",
+      "patternProperties": {
+        "^\\w(?:[\\w.-]*[\\w-])?(?::\\w(?:[\\w.-]*[\\w-])?)*$": {
+          "type": "object",
+          "default": {},
+          "title": "A compliance control",
+          "properties": {
+            "title": {
+              "type": "string",
+              "title": "Short title of the control"
+            },
+            "description": {
+              "type": "string",
+              "title": "Description of the control"
+            },
+            "identifiers": {
+              "$ref": "#/$defs/identifiers"
+            },
+            "confine": {
+              "$ref": "#/$defs/confine"
+            }
+          },
+          "examples": [
+            {},
+            {
+              "title": "Audit Events",
+              "identifiers": {
+                "nist_800_53:rev4": ["AU-2"]
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "nist_800_53:rev4": {},
+          "disa_stig": {},
+          "nist_800_53:rev4:AU-2": {
+            "title": "Audit Events"
+          }
+        }
+      ]
+    }
+  },
+  "examples": [
+    {
+      "version": "2.0.0",
+      "profiles": {
+        "cis:el8:l1:server": {
+          "title": "CIS Level 1 - Server",
+          "controls": {
+            "cis:el8:l1": true
+          }
+        }
+      },
+      "ce": {
+        "oval:simp.cis.el8.1.6.2_Ensure_ASLR_is_enabled:def:1": {
+          "controls": {
+            "cis:el8:l1": true
+          },
+          "identifiers": {
+            "cis": ["1.6.2"],
+            "nist_800_53:rev4": ["SC-39"]
+          },
+          "title": "Ensure address space layout randomization (ASLR) is enabled",
+          "description": "ASLR is an exploit mitigation technique which randomly arranges the address space of key data areas of a process.",
+          "confine": {
+            "os.release.major": ["8"],
+            "os.name": ["RedHat"]
+          }
+        }
+      },
+      "checks": {
+        "oval:com.puppet.forge.simp.cis.simp.sysctl.kernel__randomize_va_space": {
+          "type": "puppet-class-parameter",
+          "settings": {
+            "parameter": "simp::sysctl::kernel__randomize_va_space",
+            "value": 2
+          },
+          "controls": {
+            "cis:el8:l1": true
+          },
+          "confine": {
+            "os.family": "RedHat"
+          }
+        }
+      },
+      "controls": {
+        "cis:el8:l1": {}
+      }
+    }
+  ]
+}

data/lib/compliance_engine/tolerance.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ComplianceEngine
+  # Named constants for enforcement tolerance levels.
+  #
+  # The enforcement tolerance controls which remediation risk levels are
+  # enforced. A check whose risk level is greater than or equal to the
+  # tolerance value is filtered out. For example, setting
+  # +enforcement_tolerance+ to +ComplianceEngine::Tolerance::MODERATE+
+  # enforces checks with risk levels below 60 while skipping anything
+  # rated MODERATE (60) or higher.
+  module Tolerance
+    # Enforce only checks with no meaningful risk (risk < 20).
+    NONE = 20
+
+    # Enforce checks below low-risk remediations; skip SAFE (40) and above (risk < 40).
+    SAFE = 40
+
+    # Enforce checks below moderate-risk remediations; skip MODERATE (60) and above (risk < 60).
+    MODERATE = 60
+
+    # Enforce checks below remediations that affect access; skip ACCESS (80) and above (risk < 80).
+    ACCESS = 80
+
+    # Enforce all checks, including those that may cause breaking changes (risk < 100).
+    BREAKING = 100
+  end
+end

data/lib/compliance_engine/version.rb

@@ -1,25 +1,5 @@
 # frozen_string_literal: true
 
 module ComplianceEngine
-  VERSION = '0.4.0'
-
-  # Handle supported compliance data versions
-  class Version
-    # Verify that the version is supported
-    #
-    # @param version [String] The version to verify
-    def initialize(version)
-      raise 'Missing version' if version.nil?
-      raise "Unsupported version '#{version}'" unless version == '2.0.0'
-
-      @version = version
-    end
-
-    # Convert the version to a string
-    #
-    # @return [String]
-    def to_s
-      @version
-    end
-  end
+  VERSION = '0.6.0'
 end

data/lib/compliance_engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'compliance_engine/version'
+require_relative 'compliance_engine/tolerance'
 require_relative 'compliance_engine/data'
 require 'logger'
 
@@ -42,6 +43,44 @@ module ComplianceEngine
     @log = value
   end
 
+  # Return the path to the bundled JSON schema for SCE data files
+  #
+  # @return [String] absolute path to sce-schema.json
+  def self.schema_path
+    File.expand_path(File.join(__dir__, 'compliance_engine', 'sce-schema.json'))
+  end
+
+  # Return the parsed JSON schema for SCE data files
+  #
+  # @return [Hash] the parsed JSON schema
+  def self.schema
+    require 'json'
+    @schema ||= begin
+      path = schema_path
+      deep_freeze(JSON.parse(File.read(path, encoding: 'UTF-8')))
+    rescue Errno::ENOENT, JSON::ParserError => e
+      raise Error, "Failed to load schema from #{path}: #{e.class}: #{e.message}"
+    end
+  end
+
+  # Recursively freeze a Hash, Array, and all nested objects.
+  #
+  # @param obj [Object] the object to freeze
+  # @return [Object] the frozen object
+  def self.deep_freeze(obj)
+    case obj
+    when Hash
+      obj.each do |k, v|
+        deep_freeze(k)
+        deep_freeze(v)
+      end
+    when Array
+      obj.each { |v| deep_freeze(v) }
+    end
+    obj.freeze
+  end
+  private_class_method :deep_freeze
+
   # Install a PuppetLogger unless a logger has already been explicitly configured.
   # Extracted so the behaviour can be unit-tested without reloading enforcement.rb.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compliance_engine
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Steven Pritchard
@@ -142,12 +142,16 @@ files:
 - lib/compliance_engine/data_loader/file.rb
 - lib/compliance_engine/data_loader/json.rb
 - lib/compliance_engine/data_loader/yaml.rb
+- lib/compliance_engine/data_version.rb
 - lib/compliance_engine/environment_loader.rb
 - lib/compliance_engine/environment_loader/zip.rb
+- lib/compliance_engine/environment_loader/zip_bytes.rb
 - lib/compliance_engine/module_loader.rb
 - lib/compliance_engine/profile.rb
 - lib/compliance_engine/profiles.rb
 - lib/compliance_engine/puppet_logger.rb
+- lib/compliance_engine/sce-schema.json
+- lib/compliance_engine/tolerance.rb
 - lib/compliance_engine/version.rb
 homepage: https://simp-project.com/docs/sce/
 licenses:
@@ -155,7 +159,7 @@ licenses:
 metadata:
   homepage_uri: https://simp-project.com/docs/sce/
   source_code_uri: https://github.com/simp/rubygem-simp-compliance_engine
-  changelog_uri: https://github.com/simp/rubygem-simp-compliance_engine/releases/tag/0.4.0
+  changelog_uri: https://github.com/simp/rubygem-simp-compliance_engine/releases/tag/0.6.0
   bug_tracker_uri: https://github.com/simp/rubygem-simp-compliance_engine/issues
 rdoc_options: []
 require_paths: