Refactor EPM Functionality

[zeroSteiner]

This refactors the endpoint mapping (EPM) functionality defined in MS-RPCE to be more encapsulated, and thus reusable in isolation. An existing DCERPC client will now create a private DCERPC client instance specifically for the EPM service calls needed to map a service to a port for connection. This enables developers to also create their own DCERPC clients specifically for interacting with the EPM service, enabling them to control the exact parameters to the ept_map function when resolving services.

This also includes an example script to demonstrate the functionality for the two protocols that are currently supported.

Demo

In this case, the target system (192.168.159.10) is a Windows Server 2019 Domain Controller. The example script is used to resolve the GKDI and SAMR endpoints.

ruby examples/epm_client.rb --help
# MS-GKDI
ruby examples/epm_client.rb --max-towers 3 192.168.159.10 ncacn_ip_tcp b9785960-524f-11df-8b6d-83dcded72085
# MS-SAMR
ruby examples/epm_client.rb --max-towers 1 192.168.159.10 ncacn_ip_tcp 12345778-1234-abcd-ef00-0123456789ac
ruby examples/epm_client.rb --max-towers 1 192.168.159.10 ncacn_np     12345778-1234-abcd-ef00-0123456789ac
Usage: script.rb [options] TARGET PROTOCOL UUID
        --major-version N            Specify major version number (default: 1)
        --minor-version N            Specify minor version number ((default: 0)
        --max-towers N               Set the maximum number of towers (default: 1)
    -h, --help                       Prints this help
Tower: ncacn_ip_tcp:192.168.159.10[49673]
  port: 49673
  address: 192.168.159.10
Tower: ncacn_ip_tcp:192.168.159.10[49671]
  port: 49671
  address: 192.168.159.10
Tower: ncacn_ip_tcp:192.168.159.10[49667]
  port: 49667
  address: 192.168.159.10
Tower: ncacn_ip_tcp:192.168.159.10[49671]
  port: 49671
  address: 192.168.159.10
Tower: ncacn_np:\\DC[\pipe\78a0156af3d332e7]
  pipe: \pipe\78a0156af3d332e7
  host: \\DC

[jheysel-r7]

This has been tested with rapid7/metasploit-framework#20017 as well as with the epm_client.rb example script and looks good 👍

➜  ruby_smb git:(test/msf/20017) ruby examples/epm_client.rb --max-towers 3 172.16.199.130  ncacn_ip_tcp b9785960-524f-11df-8b6d-83dcded72085
Tower: ncacn_ip_tcp:172.16.199.130[57966]
  port: 57966
  address: 172.16.199.130
Tower: ncacn_ip_tcp:172.16.199.130[49668]
  port: 49668
  address: 172.16.199.130
Tower: ncacn_ip_tcp:172.16.199.130[49664]
  port: 49664
  address: 172.16.199.130
➜  ruby_smb git:(test/msf/20017) ruby examples/epm_client.rb --max-towers 1 172.16.199.130 ncacn_np   12345778-1234-abcd-ef00-0123456789ac
Tower: ncacn_np:\\DC3[\pipe\lsass]
  pipe: \pipe\lsass
  host: \\DC3
➜  ruby_smb git:(test/msf/20017) ruby examples/epm_client.rb --max-towers 3 172.16.199.130  ncacn_ip_tcp 12345778-1234-abcd-ef00-0123456789ac
Tower: ncacn_ip_tcp:172.16.199.130[49664]
  port: 49664
  address: 172.16.199.130
➜  ruby_smb git:(test/msf/20017) ruby examples/epm_client.rb --max-towers 1 172.16.199.130  ncacn_ip_tcp 12345778-1234-abcd-ef00-0123456789ac
Tower: ncacn_ip_tcp:172.16.199.130[49664]
  port: 49664
  address: 172.16.199.130
➜  ruby_smb git:(test/msf/20017)