Merge pull request rapid7#20003 from zeroSteiner/feat/cmd/ldap-uris

Add support for RHOSTS using LDAP URIs

Author: adfoster-r7

docs/metasploit-framework.wiki/Metasploit-Guide-LDAP.md

@@ -34,6 +34,13 @@ use auxiliary/gather/ldap_query
 run rhost=192.168.123.13 [email protected] password=p4$$w0rd action=ENUM_ACCOUNTS
 ```
 
+Alternatively, the URI syntax can be used:
+
+```
+use auxiliary/gather/ldap_query
+run ldap://domain.local;Administrator:[email protected]/dc=domain,dc=local action=ENUM_ACCOUNTS
+```
+
 Example output:
 
 ```msf

docs/metasploit-framework.wiki/Metasploit-Guide-Setting-Module-Options.md

@@ -124,6 +124,8 @@ The following protocols are currently supported, and described in more detail be
 - file - Load a series of RHOST values separated by newlines from a file. This file can also include URI strings
 - http
 - https
+- ldap
+- ldaps
 - mysql
 - postgres
 - smb

lib/msf/core/rhosts_walker.rb

@@ -15,6 +15,8 @@ class RhostsWalker
       file
       http
       https
+      ldap
+      ldaps
       mysql
       postgres
       smb
@@ -251,6 +253,45 @@ def parse_http_uri(value, datastore)
     end
     alias parse_https_uri parse_http_uri
 
+    # Parses a uri string such as ldap://user:[email protected] into a hash which can safely be
+    # merged with a [Msf::DataStore] datastore for setting ldap options.
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc4516
+    #
+    # @param value [String] the ldap string
+    # @return [Hash] A hash where keys match the required datastore options associated with
+    #   the uri value
+    def parse_ldap_uri(value, datastore)
+      uri = ::Addressable::URI.parse(value)
+      result = {}
+
+      result['RHOSTS'] = uri.hostname
+      is_ssl = %w[ssl ldaps].include?(uri.scheme)
+      result['RPORT'] = uri.port || (is_ssl ? 636 : 389)
+      result['SSL'] = is_ssl
+
+      if uri.path.present?
+        base_dn = uri.path.delete_prefix('/').split('?', 2).first
+        result['BASE_DN'] = base_dn if base_dn.present?
+      end
+
+      set_hostname(datastore, result, uri.hostname)
+
+      if uri.user && uri.user.include?(';')
+        domain, user = uri.user.split(';')
+        result['LDAPDomain'] = domain
+        set_username(datastore, result, user)
+      elsif uri.user
+        result['LDAPDomain'] = ''
+        set_username(datastore, result, uri.user)
+      end
+
+      set_password(datastore, result, uri.password) if uri.password
+
+      result
+    end
+    alias parse_ldaps_uri parse_ldap_uri
+
     # Parses a uri string such as mysql://user:[email protected] into a hash
     # which can safely be merged with a [Msf::DataStore] datastore for setting mysql options.
     #
@@ -353,7 +394,7 @@ def set_hostname(datastore, result, hostname)
     def set_username(datastore, result, username)
       # Preference setting application specific values first
       username_set = false
-      option_names = %w[SMBUser FtpUser Username user USER USERNAME username]
+      option_names = %w[SMBUser FtpUser LDAPUsername Username user USER USERNAME username]
       option_names.each do |option_name|
         if datastore.options.include?(option_name)
           result[option_name] = username
@@ -372,7 +413,7 @@ def set_username(datastore, result, username)
     def set_password(datastore, result, password)
       # Preference setting application specific values first
       password_set = false
-      password_option_names = %w[SMBPass FtpPass Password pass PASSWORD password]
+      password_option_names = %w[SMBPass FtpPass LDAPPassword Password pass PASSWORD password]
       password_option_names.each do |option_name|
         if datastore.options.include?(option_name)
           result[option_name] = password

spec/lib/msf/core/rhosts_walker_spec.rb

@@ -22,7 +22,8 @@ def http_options_for(datastores)
     mysql_keys = %w[RHOSTS RPORT USERNAME PASSWORD]
     postgres_keys = %w[RHOSTS RPORT USERNAME PASSWORD DATABASE]
     ssh_keys = %w[RHOSTS RPORT USERNAME PASSWORD]
-    required_keys = dynamic_keys + http_keys + smb_keys + mysql_keys + postgres_keys + ssh_keys
+    ldap_keys = %w[RHOSTS RPORT SSL LDAPDomain LDAPUsername LDAPPassword BASE_DN]
+    required_keys = dynamic_keys + http_keys + smb_keys + mysql_keys + postgres_keys + ssh_keys + ldap_keys
     datastores.map do |datastore|
       # Workaround: Manually convert the datastore to a hash ourselves as `datastore.to_h` coerces all datatypes into strings
       # which prevents this test suite from validating types correctly. i.e. The tests need to ensure that RPORT is correctly
@@ -154,6 +155,33 @@ def initialize
     mod
   end
 
+  let(:ldap_mod) do
+    mod_klass = Class.new(Msf::Auxiliary) do
+      include Msf::Exploit::Remote::LDAP
+      include Msf::Exploit::Remote::LDAP::Queries
+
+      def initialize
+        super(
+          'Name' => 'mock ldap module',
+          'Description' => 'mock ldap module',
+          'Author' => ['Unknown'],
+          'License' => MSF_LICENSE
+        )
+
+        register_options([
+          Msf::OptString.new('BASE_DN', [false, 'LDAP base DN if you already have it'])
+        ])
+      end
+    end
+
+    mod = mod_klass.new
+    datastore = Msf::ModuleDataStore.new(mod)
+    allow(mod).to receive(:framework).and_return(nil)
+    mod.send(:datastore=, datastore)
+    datastore.import_options(mod.options)
+    mod
+  end
+
   let(:mysql_mod) do
     mod_klass = Class.new(Msf::Auxiliary) do
       include Msf::Exploit::Remote::MYSQL
@@ -908,6 +936,74 @@ def create_tempfile(content)
         expect(each_host_for(ssh_mod)).to have_datastore_values(expected)
       end
     end
+
+    context 'when using the ldap scheme' do
+      it 'enumerates ldap schemes for scanners when no user or password are specified' do
+        ldap_mod.datastore['RHOSTS'] = 'ldap://example.com/ ldaps://example.com/'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => nil, 'LDAPUsername' => nil, 'LDAPPassword' => nil, 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 636, 'SSL' => true, 'LDAPDomain' => nil, 'LDAPUsername' => nil, 'LDAPPassword' => nil, 'BASE_DN' => nil }
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+
+      it 'enumerates ldap schemes for scanners when a port is specified' do
+        ldap_mod.datastore['RHOSTS'] = 'ldap://example.com:1389/ ldaps://example.com:1636/'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 1389, 'SSL' => false, 'LDAPDomain' => nil, 'LDAPUsername' => nil, 'LDAPPassword' => nil, 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 1636, 'SSL' => true, 'LDAPDomain' => nil, 'LDAPUsername' => nil, 'LDAPPassword' => nil, 'BASE_DN' => nil }
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+
+      it 'enumerates ldap schemes for scanners when no user or password are specified and uses the default option values instead' do
+        ldap_mod.datastore.import_options(
+          Msf::OptionContainer.new(
+            [
+              Msf::OptString.new('LDAPUsername', [true, 'The username to authenticate as', 'db2admin'], fallbacks: ['USERNAME']),
+              Msf::OptString.new('LDAPPassword', [true, 'The password for the specified username', 'db2admin'], fallbacks: ['PASSWORD']),
+            ]
+          ),
+          ldap_mod.class,
+          true
+        )
+        ldap_mod.datastore['RHOSTS'] = 'ldap://example.com/ ldap://[email protected]/ ldap://user:[email protected] ldap://:@example.com'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => nil, 'LDAPUsername' => 'db2admin', 'LDAPPassword' => 'db2admin', 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => 'db2admin', 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => 'password', 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => '', 'LDAPPassword' => '', 'BASE_DN' => nil }
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+
+      it 'enumerates ldap schemes for scanners when a user and password are specified' do
+        ldap_mod.datastore['RHOSTS'] = 'ldap://user:[email protected]/'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => 'pass', 'BASE_DN' => nil },
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+
+      it 'enumerates ldap schemes for scanners when a domain, user and password are specified' do
+        ldap_mod.datastore['RHOSTS'] = 'ldap://domain;user:[email protected]/'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => 'domain', 'LDAPUsername' => 'user', 'LDAPPassword' => 'pass', 'BASE_DN' => nil },
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+
+      it 'enumerates ldap schemes for when the module has BASE_DN available' do
+        ldap_mod.datastore['RHOSTS'] = 'ldap://[email protected] ldap://[email protected]/ ldap://[email protected]/dc=msflab,dc=local'
+        expected = [
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => nil, 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => nil, 'BASE_DN' => nil },
+          { 'RHOSTNAME' => 'example.com', 'RHOSTS' => '192.0.2.2', 'RPORT' => 389, 'SSL' => false, 'LDAPDomain' => '', 'LDAPUsername' => 'user', 'LDAPPassword' => nil, 'BASE_DN' => 'dc=msflab,dc=local' }
+        ]
+        expect(each_host_for(ldap_mod)).to have_datastore_values(expected)
+      end
+    end
+
     # TODO: Discuss adding a test for the datastore containing an existing TARGETURI,and running with a HTTP url without a path. Should the TARGETURI be overridden to '/', '', or unaffected, and the default value is used instead?
 
     it 'enumerates a combination of all syntaxes' do