permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/services/security_audit/conditions_check.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # Activation conditions and field rows whose read-time meaning is not
+      # what the row looks like: conditions the validation would refuse
+      # today (ActivationConditions: nobody can judge them, so a muting set
+      # applies to every request and a granting set never passes) and
+      # resources holding both a row and an explicit row for one of its
+      # variants (the explicit row decides since 0.15).
+      class ConditionsCheck < BaseCheck
+        LEVEL_LABELS = { 'hidden' => 'Hidden', 'masked' => 'Masked', 'read' => 'Read-only', 'edit' => 'Editable' }.freeze
+        # ActivationConditions#condition_problems kind => its sentence (the value, the set).
+        PROBLEMS = {
+          ip_entry: ->(value, _set) { "IP entry “#{value}” is not an IP address or CIDR range" },
+          ip_empty: ->(_value, _set) { 'IP list has no entry' },
+          flag_unusable: ->(value, _set) { "session flag #{value.inspect} holds a control character no request carries" },
+          hours_equal: ->(_value, set) { "start hour #{set.allowed_hours_start} equals end hour #{set.allowed_hours_end}" },
+          hours_incomplete: ->(_value, set) { set.allowed_hours_start.nil? ? 'start hour missing' : 'end hour missing' },
+          hours_range: ->(_value, _set) { 'hour outside 0–23' }
+        }.freeze
+
+        def call
+          [incomplete_conditions, variant_rows_conflict].compact
+        end
+
+        private
+
+        def incomplete_conditions
+          sets = PermissionForge::PermissionSet.with_broken_conditions # Home's card reads the same
+          return if sets.empty?
+
+          finding(:medium, :incomplete_conditions, 'Activation conditions nobody can judge',
+                  'These rows hold a condition the validation refuses today: an IP entry that is not an IP address or ' \
+                  'CIDR range, a list with no entry, a session flag with a control character, the same start and end ' \
+                  'hour, one hour of the two, or an hour outside ' \
+                  '0–23. Such a condition cannot be judged, so a muting set applies to every request and a granting set ' \
+                  'never passes, with or without a request context: it grants nothing. Fix the condition on the ' \
+                  'set\'s Conditions tab (the admin and the API normalise the list; newline or comma lists and arrays ' \
+                  'are accepted).',
+                  items: sets.map { |set| condition_item(set) })
+        end
+
+        def condition_item(set)
+          what = set.condition_problems.map { |kind, value| describe_problem(kind, value, set) }.join('; ')
+          effect = set.is_muting ? 'applies to every request' : 'never passes, grants nothing'
+          "#{set.name}#{' (muting)' if set.is_muting}: #{what} — #{effect} · #{people(set.id)}"
+        end
+
+        def describe_problem(kind, value, set)
+          PROBLEMS.fetch(kind).call(value, set)
+        end
+
+        # Granting resources in effect: a muting resource's rows and variants
+        # all mute (deny direction), so two rows there never disagree.
+        def variant_rows_conflict
+          resources = PermissionForge::Resource.in_effect.merge(PermissionForge::PermissionSet.granting)
+                                               .includes(:permission_set, :resource_fields).order(:id)
+          items = resources.flat_map { |resource| conflicts_of(resource) }
+          return if items.empty?
+
+          finding(:info, :variant_rows_conflict, 'Field rows next to an explicit row for their variant',
+                  'Since 0.15 an explicit row for a name decides that name: the variant derived from the other row ' \
+                  '(owner_id → owner_uuid) no longer widens it. Check that each explicit row says what you mean.',
+                  items: items)
+        end
+
+        def conflicts_of(resource)
+          rows = resource.resource_fields.select(&:is_active)
+          by_name = rows.index_by(&:name)
+          variants = PermissionForge::FieldVariants.new(resource.name, configuration)
+          rows.flat_map do |row|
+            variants.call(row.name).filter_map do |variant|
+              explicit = by_name[variant]
+              conflict_item(resource, row, explicit) if explicit
+            end
+          end
+        end
+
+        def conflict_item(resource, row, explicit)
+          "#{resource.permission_set.name} › #{resource.name}: #{row.name} (#{level(row)}) → " \
+            "#{explicit.name} (#{level(explicit)}): the #{explicit.name} row decides"
+        end
+
+        def level(row)
+          LEVEL_LABELS.fetch(PermissionForge::Admin::FieldLevel.level_of(row, muting: false))
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/config_check.rb

@@ -6,11 +6,15 @@ module PermissionForge
       # Configuration hardening: who can reach the admin, whether the cache is
       # shared, fail-closed flags, GDPR and audit settings, and the JSON API.
       class ConfigCheck < BaseCheck
+        include MaskingWithoutUser
+
         RULES = %i[
           admin_ui_exposed process_local_cache unconfigured_fields_pass write_protection_off nested_parent_fallback
-          nil_user_bypass masked_nil_user_bypass gdpr_defaults_off log_filtering_off audit_trail_off conditional_sets_lenient
-          detection_raises_in_production api_without_auth api_mutations_unguarded api_sequential_ids
-          api_rule_values_exposed tenantless_admin strict_overrides
+          unconfigured_actions_allowed
+          nil_user_bypass masked_nil_user_bypass middleware_above_web_request gdpr_defaults_off log_filtering_off audit_trail_off
+          conditional_sets_lenient
+          detection_raises_in_production api_without_auth api_mutations_unguarded api_authorization_unset
+          api_sequential_ids api_rule_values_exposed tenantless_admin strict_overrides
         ].freeze
 
         def call
@@ -29,12 +33,18 @@ module PermissionForge
                   'a controller that authenticates and authorizes admins, or turn HTTP Basic back on.')
         end
 
+        # The one definition of "process-local" is the store's own
+        # (Cache::Base#process_local?: `cache_backend = :memory`, or
+        # `Rails.cache` a `:memory_store`), asked of the store the reviewed
+        # configuration builds.
         def process_local_cache
-          return unless production? && configuration.cache_backend.to_s == 'memory'
+          return unless production? && configuration.cache_store.process_local?
 
           finding(:high, :process_local_cache, 'Permission cache is local to each process',
-                  'cache_backend is :memory in production: a revoked permission stays cached in other Puma ' \
-                  'workers until their TTL expires. Use :rails_cache with a shared store.')
+                  'The permission cache store lives in each process in production (cache_backend :memory, or ' \
+                  'Rails.cache a :memory_store): a revoked permission stays cached in the other Puma workers until ' \
+                  'cache_ttl, and an invalidation from a console, runner or rake task never reaches the servers. ' \
+                  'Use :rails_cache with a shared store (Redis, Memcached, Solid Cache).')
         end
 
         def unconfigured_fields_pass
@@ -64,6 +74,18 @@ module PermissionForge
                   'it back to false (the default).')
         end
 
+        # Closed by default since 0.15: :allow is the host's explicit opt-out.
+        def unconfigured_actions_allowed
+          return unless configuration.allow_unconfigured_actions?
+
+          finding(:medium, :unconfigured_actions_allowed, 'Controller actions no Permission Set manages are allowed',
+                  'unconfigured_action_strategy is :allow (the opt-out from the :block default): a guarded ' \
+                  'controller action that maps to a Resource runs for every signed-in user until a Permission Set ' \
+                  'manages it, so a new action is open before anyone decides who may run it. ' \
+                  'unmanaged_actions_allowed lists the actions open now. Manage them, then remove the setting ' \
+                  '(:block refuses them with 403).')
+        end
+
         def nil_user_bypass
           strategies = { nil_user_strategy: configuration.nil_user_strategy,
                          response_filter_nil_user_strategy: configuration.response_filter_nil_user_strategy }
@@ -75,18 +97,6 @@ module PermissionForge
                   'that touches protected models is authenticated first, or use :deny / :raise.')
         end
 
-        # The one nil-user setting that is about the getters themselves.
-        def masked_nil_user_bypass
-          return if configuration.hide_masked_attributes_without_user?
-
-          finding(:medium, :masked_nil_user_bypass, 'Masked attributes are readable with no current user',
-                  'masked_attributes_nil_user_strategy is :bypass: when nobody is signed in (a job, a mailer, the ' \
-                  'console, a resolver that returns nil) the getters, attributes and as_json of a masked model return ' \
-                  'the stored values, whatever nil_user_strategy says. Set it to :hide (the user model stays readable, as ' \
-                  'sign-in needs), and set the current user in ' \
-                  'the jobs and mailers that read masked data.')
-        end
-
         def gdpr_defaults_off
           return if configuration.gdpr_defaults
 
@@ -149,6 +159,19 @@ module PermissionForge
                   'to refuse changes until they are set.')
         end
 
+        # Fails closed (each refusal is a 403 naming the option): a note, so
+        # that the missing lambda is found before a caller is refused.
+        def api_authorization_unset
+          lines = PermissionForge::ApiAuthorizations.lines(configuration)
+          return if lines.empty?
+
+          finding(:info, :api_authorization_unset, 'The JSON API refuses what no authorization lambda guards',
+                  'The API is on and api_auth admits callers, but an authorization lambda it needs is not set: it ' \
+                  'answers 403 (naming the option) to everything that lambda guards. Set each one listed, or turn ' \
+                  'the API off if nothing calls it.',
+                  items: lines)
+        end
+
         # Tenancy on, and an admin base controller that sets no tenant.
         def tenantless_admin
           defaults = configuration.default_admin_controllers_under_tenancy

data/lib/permission_forge/services/security_audit/integrity_check.rb

@@ -4,7 +4,8 @@ module PermissionForge
   module Services
     module SecurityAuditChecks
       # Rows the models' validations would refuse but the database holds
-      # anyway (written by SQL, an older version, or another app).
+      # anyway (written by SQL, an older version, or another app), and field
+      # rows that name nothing on their model.
       class IntegrityCheck < BaseCheck
         RESOURCE_RULES = {
           'edit without read' => ->(r) { r.edit_access && !r.read_access },
@@ -18,7 +19,8 @@ module PermissionForge
         }.freeze
 
         def call
-          [duplicate_fields, duplicate_actions, dependency_violations, unknown_models].compact
+          [duplicate_fields, duplicate_actions, dependency_violations, unknown_models, unknown_fields,
+           unknown_mask_strategies].compact
         end
 
         private
@@ -95,9 +97,74 @@ module PermissionForge
                   'shares these tables it may still use them — check there before deleting.', items: names)
         end
 
+        # Field rows in effect whose name is nothing their model has
+        # (PermissionForge::FieldNames): a typo such as `emial`. Saving does
+        # not refuse them — a key only a serializer computes is filtered by
+        # a row of its name — so they are reported here. Low when a muting
+        # set holds one (it mutes nothing it was meant to), otherwise info (a
+        # granting row grants nothing on the model).
+        def unknown_fields
+          fields = unknown_field_rows
+          return if fields.empty?
+
+          muting = fields.any? { |field| field.resource.permission_set.is_muting }
+          finding(muting ? :low : :info, :unknown_fields, 'Fields naming nothing on their model',
+                  'No column, attribute, alias, public method, declared or discovered virtual field, or configured ' \
+                  'variant of the model has these names, so the rows configure nothing on it: a muting row mutes ' \
+                  'nothing (a typo such as emial leaves email as it was), a granting row grants nothing. Correct ' \
+                  'or remove the row; for a key only a serializer computes (filtered by FiltersResponseAttributes) ' \
+                  'declare it in the model\'s extra_fields_for_permissions (see "Extra Virtual Fields" in ' \
+                  'docs/field-filtering.md).',
+                  items: fields.map { |field| unknown_field_item(field) })
+        end
+
+        def unknown_field_rows
+          fields = PermissionForge::ResourceField.in_effect.includes(resource: :permission_set).order(:resource_id, :id)
+          fields.group_by(&:resource).flat_map do |resource, rows|
+            names = PermissionForge::FieldNames.for(resource.name, siblings: rows.map(&:name), configuration: configuration)
+            names ? rows.reject { |field| names.include?(field.name) } : []
+          end
+        end
+
+        def unknown_field_item(field)
+          resource = field.resource
+          set = resource.permission_set
+          "#{set.name}#{' (muting)' if set.is_muting} › #{resource.name}.#{field.name} · #{people(set.id)}"
+        end
+
+        # Field rows in effect that mask with a strategy this app does not
+        # know (Services::MaskValue.known?): written past the model, or a
+        # custom strategy since removed from config.custom_mask_strategies.
+        # Their values are masked fully until the row or the configuration is
+        # fixed — medium, high when people hold the set (they read ********
+        # where a lighter mask was meant, and nobody is told why).
+        def unknown_mask_strategies
+          fields = unknown_strategy_rows
+          return if fields.empty?
+
+          held = fields.any? { |field| people_counts.fetch(field.resource.permission_set_id, 0).positive? }
+          finding(held ? :high : :medium, :unknown_mask_strategies, 'Fields masked with a strategy this app does not know',
+                  'No built-in mask strategy and no entry of config.custom_mask_strategies has these names — a row ' \
+                  'written past the model, or a custom strategy since removed. Such a field is masked fully ' \
+                  '(********) until the row or the configuration is fixed: pick a strategy in the field drawer, or ' \
+                  'add the custom strategy back.',
+                  items: fields.map { |field| unknown_strategy_item(field) })
+        end
+
+        # The reading Home's card takes too (ResourceField.with_unknown_mask_strategy).
+        def unknown_strategy_rows
+          PermissionForge::ResourceField.with_unknown_mask_strategy
+        end
+
+        def unknown_strategy_item(field)
+          resource = field.resource
+          "#{resource.permission_set.name} › #{resource.name}.#{field.name}: #{field.mask_strategy.inspect} · " \
+            "#{people(resource.permission_set_id)}"
+        end
+
+        # The one definition of "a model with a table" (PermissionForge::ModelLookup).
         def model?(name)
-          klass = name.safe_constantize
-          klass.is_a?(Class) && klass < ActiveRecord::Base
+          PermissionForge::ModelLookup.model?(name)
         end
       end
     end

data/lib/permission_forge/services/security_audit/masking_without_user.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # ConfigCheck's findings about masking with nobody signed in
+      # (masked_attributes_nil_user_strategy) and about the request marker
+      # they depend on (WebRequest): included by ConfigCheck, which lists
+      # them in its RULES.
+      #
+      # @api private
+      module MaskingWithoutUser
+        private
+
+        # The one nil-user setting that is about the getters themselves.
+        # :bypass is reported with :hide_in_requests as the remedy; under
+        # :hide_in_requests what still reads as stored (jobs, the console) is
+        # an info; :hide reports nothing here (UserModelCheck notes the user
+        # model's exemption).
+        def masked_nil_user_bypass
+          case configuration.masked_attributes_nil_user_strategy
+          when :bypass then masked_nil_user_bypassed
+          when :hide_in_requests then masked_nil_user_outside_requests
+          end
+        end
+
+        def masked_nil_user_bypassed
+          finding(:medium, :masked_nil_user_bypass, 'Masked attributes are readable with no current user',
+                  'masked_attributes_nil_user_strategy is :bypass: when nobody is signed in the getters, attributes ' \
+                  'and as_json of a masked model return the stored values, whatever nil_user_strategy says — in a job, ' \
+                  'a mailer or the console, and also in a web request where nobody is signed in (a public page, a ' \
+                  'webhook, a controller that forgot authentication, a resolver that returns nil). Each such read in ' \
+                  'a web request is logged (once per model and process) and published as field.unmasked_without_user ' \
+                  '(stored when audit_runtime_events includes :bypass). Set it to :hide_in_requests: hidden in web ' \
+                  'requests with nobody signed in, the stored values kept for jobs, rake and the console. Trade-off: ' \
+                  'a page that reads a masked model before anyone signs in (a tenant lookup, a public page, a mail ' \
+                  'sent with deliver_now) then reads hidden values: sign the request in first, or read raw columns ' \
+                  'there. :hide hides everywhere (set the current user in jobs and mailers). The user model stays ' \
+                  'readable under both, as sign-in needs.')
+        end
+
+        def masked_nil_user_outside_requests
+          finding(:info, :masked_nil_user_outside_requests, 'Masked attributes are readable with no current user outside web requests',
+                  'masked_attributes_nil_user_strategy is :hide_in_requests: in a web request with nobody signed in ' \
+                  'every guarded attribute reads as hidden, but jobs, rake tasks, the runner and the console (and ' \
+                  'Action Cable channel actions) read the stored values. That code runs on your servers, not on a ' \
+                  'visitor\'s behalf; :hide hides there too, and then needs the current user set in those jobs and mailers.')
+        end
+
+        # Middlewares inserted above WebRequest::Middleware read outside the
+        # request: :hide_in_requests does not hide there, :bypass does not
+        # record (WebRequest::StackCheck, also a boot warning).
+        def middleware_above_web_request
+          return if configuration.masked_attributes_nil_user_strategy == :hide
+
+          above = PermissionForge::WebRequest::StackCheck.middlewares_above
+          return if above.blank?
+
+          finding(:info, :middleware_above_web_request, 'Middlewares run before requests are marked',
+                  "#{PermissionForge::WebRequest::StackCheck.message(above, 'are not hidden or recorded')} " \
+                  'Middlewares that read no masked model (CORS, profiling, static files) need nothing.', items: above)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/personal_data_check.rb

@@ -4,7 +4,8 @@ module PermissionForge
   module Services
     module SecurityAuditChecks
       # Personal data shown unmasked, from GdprFieldAuditor. Fields an admin
-      # marked "This is intended" in the privacy audit are left out.
+      # marked "This is intended" in the privacy audit are left out by the
+      # auditor itself (ResourceField.exposing_unacknowledged).
       class PersonalDataCheck < BaseCheck
         def call
           report = GdprFieldAuditor.call(configuration: configuration)
@@ -14,7 +15,7 @@ module PermissionForge
         private
 
         def unmasked(report)
-          rows = report.select { |row| row[:type] == :unmasked_field && acknowledged_ids.exclude?(row[:resource_field_id]) }
+          rows = report.select { |row| row[:type] == :unmasked_field }
           return if rows.empty?
 
           finding(:medium, :unmasked_personal_data, 'Personal data readable unmasked',
@@ -47,7 +48,10 @@ module PermissionForge
 
           finding(:medium, :cross_set_unmasking, 'One set unmasks what another masks',
                   'Masks combine with AND: anyone holding both sets sees the full value.',
-                  items: rows.map { |row| "#{row[:permission_set]} › #{row[:resource_name]}.#{row[:field_name]}" })
+                  items: rows.map do |row|
+                    "#{row[:permission_set]} › #{row[:resource_name]}.#{row[:field_name]} " \
+                      "(masked in #{Array(row[:masked_in]).join(', ').presence || 'another set'})"
+                  end)
         end
 
         def unmapped(report)
@@ -65,14 +69,6 @@ module PermissionForge
           finding(passes ? :high : :low, :unmapped_personal_data, 'Personal-data columns with no active field row', detail,
                   items: rows.map { |row| "#{row[:resource]}.#{row[:column]}" })
         end
-
-        def acknowledged_ids
-          @acknowledged_ids ||= if PermissionForge::Admin::AttentionItems.acknowledgement_supported?
-                                  PermissionForge::ResourceField.where.not(sensitive_acknowledged_at: nil).pluck(:id).to_set
-                                else
-                                  Set.new
-                                end
-        end
       end
     end
   end