entitlements 0.1.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e129c20434bdad80c9fb7395a3a18f787f3a6c3c7c5579254a2bcd1b422e2715
+  data.tar.gz: eee34c03695d06d79c5eec2dc8e98627a0c66e5f9c4425c60d1ba247f9541f22
+SHA512:
+  metadata.gz: fc823d7ff8a6c1c6cdc582526e5bd4f3fa67d48ae6acc9940c37e15073c6661ca33469b85e5e12e4e6dee7981b4ef3022225c0697b1e449b1c8f4a98f524f9cf
+  data.tar.gz: 44724ff2988f4a7ca36b20489ace98d0af6351e8214d2975a1e256cfc088a5a4070c91524ed49342e684d5edc7bc7eb41d59dba8788000dfefef8566b653d3bb

data/VERSION

@@ -0,0 +1 @@
+0.1.7

data/bin/deploy-entitlements

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+ENV["BUNDLE_GEMFILE"] = File.expand_path("../Gemfile", File.dirname(__FILE__))
+require "bundler/setup"
+require "contracts"
+
+# We don't need Contract outside of normal development
+VALID = [true, nil]
+class Contract
+  def self.valid?(arg, contract)
+    VALID
+  end
+end
+
+require "entitlements"
+exitcode = Entitlements::Cli.run
+exitcode ||= 0
+exit exitcode

data/lib/entitlements/auditor/base.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# This class provides common methods and is intended to be inherited by other audit providers.
+
+module Entitlements
+  class Auditor
+    class Base
+      include ::Contracts::Core
+      C = ::Contracts
+
+      attr_reader :description, :provider_id
+
+      # ---------
+      # Interface
+      # ---------
+
+      # Constructor.
+      #
+      # config - A Hash with configuration options
+      Contract Logger, C::HashOf[String => C::Any] => C::Any
+      def initialize(logger, config)
+        @logger = logger
+        @description = config["description"] || self.class.to_s
+        @provider_id = config["provider_id"] || self.class.to_s.split("::").last
+        @config = config
+      end
+
+      # Setup. This sets up the audit provider before any action takes place. This may be
+      # declared in the child class.
+      #
+      # Takes no arguments.
+      #
+      # Returns nothing.
+      Contract C::None => nil
+      def setup
+        # :nocov:
+        nil
+        # :nocov:
+      end
+
+      # Commit. This takes the entirety of group objects and actions and records them in
+      # whatever methodology the audit provider uses.
+      #
+      # actions            - Array of Entitlements::Models::Action (all requested actions)
+      # successful_actions - Array of Entitlements::Models::Action (successfully applied actions)
+      # provider_exception - Exception raised by a provider when applying (hopefully nil)
+      #
+      # Returns nothing.
+      Contract C::KeywordArgs[
+        actions: C::ArrayOf[Entitlements::Models::Action],
+        successful_actions: C::ArrayOf[Entitlements::Models::Action],
+        provider_exception: C::Or[nil, Exception]
+      ] => nil
+      def commit(actions:, successful_actions:, provider_exception:)
+        # :nocov:
+        nil
+        # :nocov:
+      end
+
+      # Set up a logger class that wraps incoming messages with the prefix and (if meaningful) the
+      # provider ID. Messages are then sent with the requested priority to the actual logger object.
+      class CustomLogger
+        def initialize(underlying_object, underlying_logger)
+          @underlying_object = underlying_object
+          @underlying_logger = underlying_logger
+        end
+
+        def prefix
+          @prefix ||= begin
+            if @underlying_object.provider_id == @underlying_object.class.to_s.split("::").last
+              @underlying_object.class.to_s
+            else
+              "#{@underlying_object.class}[#{@underlying_object.provider_id}]"
+            end
+          end
+        end
+
+        def method_missing(m, *args, &block)
+          args[0] = "#{prefix}: #{args.first}"
+          @underlying_logger.send(m, *args, &block)
+        end
+      end
+
+      private
+
+      attr_reader :config
+
+      # Intercept calls to logger to wrap through the custom class.
+      def logger
+        @logger_class ||= CustomLogger.new(self, @logger)
+      end
+
+      # Raise a configuration error message.
+      #
+      # message - A String with the error message to be logged and raised.
+      #
+      # Returns nothing because it raises an error.
+      Contract String => C::Any
+      def configuration_error(message)
+        provider = self.class.to_s.split("::").last
+        error_message = "Configuration error for provider=#{provider} id=#{provider_id}: #{message}"
+        logger.fatal "Configuration error: #{message}"
+        raise ArgumentError, error_message
+      end
+
+      # Require the the configuration contain certain keys (no validation is performed on the
+      # values - just make sure the key exists).
+      #
+      # required_keys - An Array of Strings with the required keys.
+      #
+      # Returns nothing.
+      Contract C::ArrayOf[String] => nil
+      def require_config_keys(required_keys)
+        missing_keys = required_keys - config.keys
+        return unless missing_keys.any?
+        configuration_error "Not all required keys are defined. Missing: #{missing_keys.join(',')}."
+      end
+
+      # Convert a distinguished name (cn=something,ou=foo,dc=example,dc=net) to a file
+      # path (dc=net/dc=example/ou=foo/cn=something).
+      #
+      # dn - A String with the distinguished name.
+      #
+      # Returns a String with the path.
+      Contract String => String
+      def path_from_dn(dn)
+        File.join(dn.split(",").reverse)
+      end
+
+      # Convert a path (dc=net/dc=example/ou=foo/cn=something) to a distinguished name
+      # (cn=something,ou=foo,dc=example,dc=net).
+      #
+      # path - A String with the path name.
+      #
+      # Returns a String with the distinguished name.
+      Contract String => String
+      def dn_from_path(path)
+        path.split("/").reject { |i| i.empty? }.reverse.join(",")
+      end
+
+      # From a list of actions, return only the ones that have a net change in membership.
+      # In other words, filter out the ones where only metadata / description / etc. has changed.
+      #
+      # actions - Incoming array of Entitlements::Models::Action
+      #
+      # Returns an array of Entitlements::Models::Action
+      Contract C::ArrayOf[Entitlements::Models::Action] => C::ArrayOf[Entitlements::Models::Action]
+      def actions_with_membership_change(actions)
+        actions.select do |action|
+          if action.updated.is_a?(Entitlements::Models::Person) || action.existing == :none
+            # MemberOf or other modification to the person itself, not handled by this auditor
+            false
+          elsif action.updated.nil? || action.existing.nil?
+            # Add/remove group always triggers a commit
+            true
+          else
+            action.updated.member_strings_insensitive != action.existing.member_strings_insensitive
+          end
+        end
+      end
+    end
+  end
+end

data/lib/entitlements/backend/base_controller.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# To add a new backend, make its "Controller" class inherit from Entitlements::Backend::BaseController.
+# Consider using dummy/controller.rb as a template for a brand new class.
+
+# Needed to register backends
+require_relative "../cli"
+require_relative "../util/util"
+
+module Entitlements
+  class Backend
+    class BaseController
+      include ::Contracts::Core
+      C = ::Contracts
+
+      # Upon loading of the class itself, register the class in the list of available
+      # backends that is tracked in the Entitlements class.
+      def self.register
+        Entitlements.register_backend(identifier, self, priority)
+      end
+
+      # Default priority is 10 - override by defining this method in the child class.
+      def self.priority
+        10
+      end
+
+      # :nocov:
+      def priority
+        self.class.priority
+      end
+      # :nocov:
+
+      # Default identifier is the de-camelized name of the class - override by defining this method in the child class.
+      def self.identifier
+        classname = self.to_s.split("::")[-2]
+        Entitlements::Util::Util.decamelize(classname)
+      end
+
+      COMMON_GROUP_CONFIG = {
+        "allowed_methods" => { required: false, type: Array },
+        "allowed_types"   => { required: false, type: Array },
+        "dir"             => { required: false, type: String }
+      }
+
+      # Constructor. Generic constructor that takes a hash of configuration options.
+      #
+      # group_name - Name of the corresponding group in the entitlements configuration file.
+      # config     - Optionally, a Hash of configuration information (configuration is referenced if empty).
+      Contract String, C::Maybe[C::HashOf[String => C::Any]] => C::Any
+      def initialize(group_name, config = nil)
+        @group_name = group_name
+        @config = config ? config.dup : Entitlements.config["groups"].fetch(group_name).dup
+        @config.delete("type")
+        @actions = []
+        @logger = Entitlements.logger
+        validate_config!(@group_name, @config)
+      end
+
+      attr_reader :actions
+
+      # Print difference array.
+      #
+      # key           - String with the key identifying the OU
+      # added         - Array[Entitlements::Models::Action]
+      # removed       - Array[Entitlements::Models::Action]
+      # changed       - Array[Entitlements::Models::Action]
+      # ignored_users - Optionally a Set of Strings with usernames to ignore
+      #
+      # Returns nothing (this just prints to logger).
+      Contract C::KeywordArgs[
+        key: String,
+        added:   C::ArrayOf[Entitlements::Models::Action],
+        removed: C::ArrayOf[Entitlements::Models::Action],
+        changed: C::ArrayOf[Entitlements::Models::Action],
+        ignored_users: C::Maybe[C::SetOf[String]]
+      ] => C::Any
+      def print_differences(key:, added:, removed:, changed:, ignored_users: Set.new)
+        added_array   = added.map   { |i| [i.dn, :added,   i] }
+        removed_array = removed.map { |i| [i.dn, :removed, i] }
+        changed_array = changed.map { |i| [i.dn, :changed, i] }
+
+        combined = (added_array + removed_array + changed_array).sort_by { |i| i.first.to_s.downcase }
+        combined.each do |entry|
+          identifier = entry[0]
+          changetype = entry[1]
+          obj        = entry[2]
+
+          if changetype == :added
+            members = obj.updated.member_strings.map { |i| i =~ /\Auid=(.+?),/ ? Regexp.last_match(1) : i }
+            Entitlements.logger.info "ADD #{identifier} to #{key} (Members: #{members.sort.join(',')})"
+          elsif changetype == :removed
+            Entitlements.logger.info "DELETE #{identifier} from #{key}"
+          else
+            ignored_users.merge obj.ignored_users
+            existing_members = obj.existing.member_strings
+            Entitlements::Util::Util.remove_uids(existing_members, ignored_users)
+
+            proposed_members = obj.updated.member_strings
+            Entitlements::Util::Util.remove_uids(proposed_members, ignored_users)
+
+            added_to_group = (proposed_members - existing_members).map { |i| [i, "+"] }
+            removed_from_group = (existing_members - proposed_members).map { |i| [i, "-"] }
+
+            # Filter out case-only differences. For example if "bob" is in existing and "BOB" is in proposed,
+            # we don't want to show this as a difference.
+            downcase_proposed_members = proposed_members.map { |m| m.downcase }
+            downcase_existing_members = existing_members.map { |m| m.downcase }
+            duplicated = downcase_proposed_members & downcase_existing_members
+            added_to_group.reject! { |m| duplicated.include?(m.first.downcase) }
+            removed_from_group.reject! { |m| duplicated.include?(m.first.downcase) }
+
+            # What's left is actual changes.
+            combined_group = (added_to_group + removed_from_group).sort_by { |i| i.first.downcase }
+            if combined_group.any?
+              Entitlements.logger.info "CHANGE #{identifier} in #{key}"
+              combined_group.each do |item, item_changetype|
+                Entitlements.logger.info ".  #{item_changetype} #{item}"
+              end
+            end
+
+            if obj.existing.description != obj.updated.description && obj.ou_type == "ldap"
+              Entitlements.logger.info "METADATA CHANGE #{identifier} in #{key}"
+              Entitlements.logger.info "- Old description: #{obj.existing.description.inspect}"
+              Entitlements.logger.info "+ New description: #{obj.updated.description.inspect}"
+            end
+          end
+        end
+      end
+
+      # Get count of changes.
+      #
+      # Takes no arguments.
+      #
+      # Returns an Integer.
+      Contract C::None => Integer
+      def change_count
+        actions.size
+      end
+
+      # Stub methods
+      # :nocov:
+      def prefetch
+        # Can be left undefined
+      end
+
+      def validate
+        # Can be left undefined
+      end
+
+      def calculate
+        raise "Must be defined in child class"
+      end
+
+      def preapply
+        # Can be left undefined
+      end
+
+      def apply(action)
+        raise "Must be defined in child class"
+      end
+
+      def validate_config!(key, data)
+        # Can be left undefined (but really shouldn't)
+      end
+
+      private
+
+      attr_reader :config, :group_name, :logger
+    end
+  end
+end

data/lib/entitlements/backend/base_provider.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Entitlements
+  class Backend
+    class BaseProvider
+      include ::Contracts::Core
+      C = ::Contracts
+
+      # Dry run of committing changes. Returns a list of users added or removed.
+      # Takes a group; looks up that same group in the appropriate backend.
+      #
+      # group         - An Entitlements::Models::Group object.
+      # ignored_users - Optionally, a Set of lower-case Strings of users to ignore.
+      #
+      # Returns added / removed hash.
+      Contract Entitlements::Models::Group, C::Maybe[C::SetOf[String]] => Hash[added: C::SetOf[String], removed: C::SetOf[String]]
+      def diff(group, ignored_users = Set.new)
+        existing_group = read(group.cn.downcase)
+        return diff_existing_updated(existing_group, group, ignored_users)
+      end
+
+      # Dry run of committing changes. Returns a list of users added or removed.
+      # Takes an existing and an updated group object, avoiding a lookup in the backend.
+      #
+      # existing_group - An Entitlements::Models::Group object.
+      # group          - An Entitlements::Models::Group object.
+      # ignored_users  - Optionally, a Set of lower-case Strings of users to ignore.
+      Contract Entitlements::Models::Group, Entitlements::Models::Group, C::Maybe[C::SetOf[String]] => Hash[added: C::SetOf[String], removed: C::SetOf[String]]
+      def diff_existing_updated(existing_group, group, ignored_users = Set.new)
+        # The comparison needs to be done case-insensitive because some backends (e.g. GitHub organizations or teams)
+        # may report members with different capitalization than is used in Entitlements. Keep track of correct capitalization
+        # of member names here so they can be applied later. Note that `group` (from Entitlements) overrides `existing_group`
+        # (from the backend).
+        member_with_correct_capitalization = existing_group.member_strings.map { |ms| [ms.downcase, ms] }.to_h
+        member_with_correct_capitalization.merge! group.member_strings.map { |ms| [ms.downcase, ms] }.to_h
+
+        existing_members = existing_group.member_strings.map { |u| u.downcase }
+        Entitlements::Util::Util.remove_uids(existing_members, ignored_users)
+
+        proposed_members = group.member_strings.map { |u| u.downcase }
+        Entitlements::Util::Util.remove_uids(proposed_members, ignored_users)
+
+        added_members = proposed_members - existing_members
+        removed_members = existing_members - proposed_members
+
+        {
+          added: Set.new(added_members.map { |ms| member_with_correct_capitalization[ms] }),
+          removed: Set.new(removed_members.map { |ms| member_with_correct_capitalization[ms] })
+        }
+      end
+    end
+  end
+end

data/lib/entitlements/backend/dummy/controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Entitlements
+  class Backend
+    class Dummy
+      class Controller < Entitlements::Backend::BaseController
+        register
+
+        # :nocov:
+        include ::Contracts::Core
+        C = ::Contracts
+
+        # Pre-fetch the existing group membership in each OU.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing. (Populates cache.)
+        Contract C::None => C::Any
+        def prefetch
+          # This does nothing.
+        end
+
+        # Validation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing. (Populates cache.)
+        Contract C::None => C::Any
+        def validate
+          # This does nothing.
+        end
+
+        # Get count of changes.
+        #
+        # Takes no arguments.
+        #
+        # Returns an Integer.
+        Contract C::None => Integer
+        def change_count
+          super
+        end
+
+        # Calculation routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing (populates @actions).
+        Contract C::None => C::Any
+        def calculate
+          # No point in calculating anything. Any references herein will be calculated automatically.
+          @actions = []
+        end
+
+        # Pre-apply routines.
+        #
+        # Takes no arguments.
+        #
+        # Returns nothing.
+        Contract C::None => C::Any
+        def preapply
+          # This does nothing.
+        end
+
+        # Apply changes.
+        #
+        # action - Action array.
+        #
+        # Returns nothing.
+        Contract Entitlements::Models::Action => C::Any
+        def apply(caction)
+          # This does nothing.
+        end
+
+        # Validate configuration options.
+        #
+        # key  - String with the name of the group.
+        # data - Hash with the configuration data.
+        #
+        # Returns nothing.
+        Contract String, C::HashOf[String => C::Any] => nil
+        def validate_config!(key, data)
+          # Do nothing to validate. Pass whatever arguments you want, and this will just ignore them!
+        end
+
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/entitlements/backend/dummy.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dummy/controller"