Add some documentation for the methods

Author: zeroSteiner

lib/msf/core/exploit/remote/ldap/active_directory.rb

@@ -16,6 +16,8 @@ module ActiveDirectory
       DACL_SECURITY_INFORMATION = 0x4
       SACL_SECURITY_INFORMATION = 0x8
 
+      # Match an ACE when *any* of the specified permissions are allowed or *all* of the specified permissions are
+      # denied.
       class ACEMatcherAllowAll
         attr_reader :permissions
 
@@ -24,22 +26,23 @@ def initialize(permissions)
         end
 
         def call(ace)
-          access_mask = ace.body.access_mask.snapshot
-          target_permissions = access_mask.select { |flag, value| @permissions.include?(flag) }
+          target_permissions = ace.body.access_mask.permissions
 
           if target_permissions.empty?
             return false
           elsif Rex::Proto::MsDtyp::MsDtypAceType.allowed?(ace.header.ace_type)
-            return target_permissions.all? { |flag, value| value == 1 }
+            return @permissions.all? { |perm| target_permissions.include?(perm) }
           elsif Rex::Proto::MsDtyp::MsDtypAceType.denied?(ace.header.ace_type)
             # if any target permission is denied, then all of them can't be allowed
-            return target_permissions.any? { |flag, value| value == 0 }
+            return @permissions.any? { |perm| target_permissions.include?(perm) }
           end
 
           false
         end
       end
 
+      # Match an ACE when *all* of the specified permissions are allowed or *any* of the specified permissions are
+      # denied.
       class ACEMatcherAllowAny
         attr_reader :permissions
 
@@ -48,16 +51,15 @@ def initialize(permissions)
         end
 
         def call(ace)
-          access_mask = ace.body.access_mask.snapshot
-          target_permissions = access_mask.select { |flag, value| @permissions.include?(flag) }
+          target_permissions = ace.body.access_mask.permissions
 
           if target_permissions.empty?
             return false
           elsif Rex::Proto::MsDtyp::MsDtypAceType.allowed?(ace.header.ace_type)
-            return target_permissions.any? { |flag, value| value == 1 }
+            return @permissions.any? { |perm| target_permissions.include?(perm) }
           elsif Rex::Proto::MsDtyp::MsDtypAceType.denied?(ace.header.ace_type)
             # if all target permissions are denied, then none of them can be allowed
-            return target_permissions.all? { |flag, value| value == 0 }
+            return @permissions.all? { |perm| target_permissions.include?(perm) }
           end
 
           false
@@ -84,6 +86,10 @@ def is_active_directory?(ldap)
         true
       end
 
+      # Build a control blob that will fetch all security descriptor data but the SACL. This often enables reading a
+      # security descriptor's DACL without the need for elevated permissions.
+      #
+      # @rtype String
       def adds_build_ldap_sd_control
         # Set the value of LDAP_SERVER_SD_FLAGS_OID flag so everything but
         # the SACL flag is set, as we need administrative privileges to retrieve
@@ -103,6 +109,13 @@ def adds_build_ldap_sd_control
         [LDAP_SERVER_SD_FLAGS_OID.to_ber, true.to_ber, control_values].to_ber_sequence
       end
 
+      # Query LDAP and obtain all members of a particular group. In this context, "members" are either users or groups.
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [String] group_dn The DN of the group to obtain members for.
+      # @param [String] base_dn An optional base search DN.
+      # @param [Boolean] inherited Whether or not to include entities that are members by inheritance.
+      # @param [String] object_class An optional object class for filtering. This is typically either 'user' or 'group'.
       def adds_query_group_members(ldap, group_dn, base_dn: nil, inherited: true, object_class: nil)
         return enum_for(:adds_query_group_members, ldap, group_dn, base_dn: base_dn, inherited: inherited, object_class: object_class) unless block_given?
         results = 0
@@ -138,6 +151,12 @@ def adds_query_group_members(ldap, group_dn, base_dn: nil, inherited: true, obje
         results
       end
 
+      # Query LDAP and obtain all groups a particular entity is a member of. In this context, "members" are either users or groups.
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [String] member_dn The DN of the member to obtain groups for.
+      # @param [String] base_dn An optional base search DN.
+      # @param [Boolean] inherited Whether or not to include groups that are inherited.
       def adds_query_member_groups(ldap, member_dn, base_dn: nil, inherited: true)
         return enum_for(:adds_query_member_groups, ldap, member_dn, base_dn: base_dn, inherited: inherited) unless block_given?
         results = 0
@@ -174,6 +193,12 @@ def adds_query_member_groups(ldap, member_dn, base_dn: nil, inherited: true)
         results
       end
 
+      # Obtain a particular entity by its distinguished name (DN).
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [String] object_dn The full distinguished name of the object to retrieve.
+      # @return Returns nil when the object was not found.
+      # @rtype [Net::LDAP::Entry,nil]
       def adds_get_object_by_dn(ldap, object_dn)
         object = ldap_entry_cache.get_by_dn(object_dn)
         return object if object
@@ -185,6 +210,12 @@ def adds_get_object_by_dn(ldap, object_dn)
         object
       end
 
+      # Obtain a particular entity by its sAMAccountName.
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [String] object_samaccountname The sAMAccountName of the object to retrieve.
+      # @return Returns nil when the object was not found.
+      # @rtype [Net::LDAP::Entry,nil]
       def adds_get_object_by_samaccountname(ldap, object_samaccountname)
         object = ldap_entry_cache.get_by_samaccountname(object_samaccountname)
         return object if object
@@ -197,6 +228,12 @@ def adds_get_object_by_samaccountname(ldap, object_samaccountname)
         object
       end
 
+      # Obtain a particular entity by its SID.
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [String] object_sid The SID of the object to retrieve.
+      # @return Returns nil when the object was not found.
+      # @rtype [Net::LDAP::Entry,nil]
       def adds_get_object_by_sid(ldap, object_sid)
         object_sid = Rex::Proto::MsDtyp::MsDtypSid.new(object_sid)
         object = ldap_entry_cache.get_by_sid(object_sid)
@@ -319,6 +356,24 @@ def adds_sd_grants_permissions?(ldap, security_descriptor, matcher, test_sid: ni
 
         false
       end
+
+      # Determine if a security descriptor will grant the permissions identified by *matcher* to the
+      # *test_sid*.
+      #
+      # @param [Net::LDAP::Connection] ldap The LDAP connection to use for querying.
+      # @param [Net::LDAP::Entry] obj The LDAP object to test. The security descriptor will be taken from the
+      #   nTSecurityDescriptor attribute.
+      # @param [#call] matcher An object that will match ACEs that allow or deny the desired permissions.
+      # @param [Rex::Proto::MsDtyp::MsDtypSid] test_sid The SID to check for access.
+      def adds_obj_grants_permissions?(ldap, obj, matcher, test_sid: nil)
+        security_descriptor = Rex::Proto::MsDtyp::MsDtypSecurityDescriptor.read(obj[:nTSecurityDescriptor].first)
+        self_sid = nil
+        if obj[:objectSid]&.first
+          self_sid = Rex::Proto::MsDtyp::MsDtypSid.read(obj[:objectSid].first)
+        end
+
+        adds_sd_grants_permissions?(ldap, security_descriptor, matcher, test_sid: test_sid, self_sid: self_sid)
+      end
     end
   end
 end