compliance_engine 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 739c21f5b10c86e4ec22f8fdbe5e86175a69f1bfd15af9d064a2fec3c6b11d7b
-  data.tar.gz: e142e74b1b28997ead592c6c358cc160cd094d307f162adc5f0edf77b3e22f68
+  metadata.gz: 9f8203b0a0381216d9a1a91c318f0f162bde1d4835bc7731c954156371b6f9b8
+  data.tar.gz: 784264cbb1aba5772bbf97dafdd952c3b8823fa404236c372af87f1d6dad885b
 SHA512:
-  metadata.gz: f99f46c33175af5a2bc879ab5254fe4cc91334c11edf334c4809063063fd82279458de34e296d0af4dcc619cd9caa5342f3412f40aded8a73e629137716ea090
-  data.tar.gz: 0ff070e539cb02ef974de2b2c7de752a79b7e0e0e89f3306bd26780dabe91c836a347f12e8c6e1fe32c4fe0cd2b97c0eefd267ada51a6b22aff64cc5c8151f0f
+  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,8 @@
+### 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)

data/lib/compliance_engine/data.rb

@@ -125,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
@@ -439,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 }
 
@@ -457,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/environment_loader/zip.rb

@@ -7,23 +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 input [String, ::Zip::File] either a filesystem path to a zip file,
-  #   or an already-opened ::Zip::File (e.g. from Zip::File.open_buffer); when
-  #   a ::Zip::File is passed, the caller owns its lifecycle
+  # @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
   # @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 zip's #name (the path on disk, or "-" for
-  #   buffer-opened zips). Pass an explicit value when loading a buffer-opened
-  #   zip to keep cache keys unique and logs informative.
+  #   cache keys; defaults to the full path string passed as +input+.
   def initialize(input, root: '/'.dup, load_dotfiles: true, name: nil)
-    zipfile = input.is_a?(::Zip::File) ? input : ::Zip::File.open(input)
-    @modulepath = name || zipfile.name
+    raise ArgumentError, "input must be a String path, got #{input.class}" unless input.is_a?(String)
+
+    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 if zipfile && !input.is_a?(::Zip::File)
+    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/sce-schema.json

@@ -51,7 +51,7 @@
     },
     "controlsMap": {
       "type": "object",
-      "title": "References to top-level controls entries. Enforced when value is true.",
+      "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",
@@ -132,7 +132,7 @@
             "ces": {
               "type": "object",
               "default": {},
-              "title": "CEs to include in this profile. Enforced when value is true.",
+              "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",
@@ -151,7 +151,7 @@
             "checks": {
               "type": "object",
               "default": {},
-              "title": "Checks to include in this profile. Enforced when value is true.",
+              "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",

data/lib/compliance_engine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ComplianceEngine
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compliance_engine
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Steven Pritchard
@@ -145,6 +145,7 @@ files:
 - 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
@@ -158,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.5.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: