Utilizing MSF Mixins For Exploit/Auxiliary Modules Development

Mixins are a handy mechanism in Ruby language to include functionality into a module. Although Ruby is a single-inheritance language, mixins provide a way to have multiple-inheritance of some sort. Metasploit makes good use of mixins. Understanding and efficiently using mixins is a vital part in the course of module development for MSF. This chapter aims to describe various mixins available, their purpose and functionality.

Please note that mixins are normally not tied to a specific module category (Exploit, Auxiliary etc), though they appear under the one which most closely suits them. This means that you can use Exploit module mixins in Auxiliary modules and vice versa.

The Auxiliary::Report Mixin

This mixin is used to save host, service and vulnerability info to a database. It provides two methods report_host and report_service that are used to indicate the status of a host (Up or Down etc) and a service. To use this module you need to include it into your classes by using: include Auxiliary::Report

After including the mixin, you can use its method to save info in the DB.

Please note if you haven't loaded a backend database, calling these methods won't do anything and will not raise an error.

Auxiliary::Report.report_host()

This method takes in a hash argument. To save the status of a host that is up, you can call this method as:

report_host(:host => datastore['RHOST'])

To specify that a host is not online (dead), pass the second parameter to the method that should be of type HostState.

report_host(:host => '127.0.0.1', Msf::HostState::Dead)

Auxiliary::Report.report_service()

Similar to the report_host method, this method also takes a hash argument containing various key-value pairs. The hash can contain values for the following keys:

addr (The hostname or address)
port (The numerical port number)
proto (Protocol can be 'tcp' or 'udp' )
name (Service name, like 'http', 'https', etc)
state (service state of type Msf::ServiceState)

The code snippet below reports TCP port 80 to be open for localhost. Notice that the default value for state is Msf::ServiceState::Up so we don't need to specify the state parameter.

report_service(:host => 'localhost',
               :port => 80,
               :name => 'HTTP'
              )

The Auxiliary::Scanner Mixin

The Scanner mixin allows modules to have the ability to perform operations on more than one host. The easiest and most common way to implement a scanner is to include the scanner mixin with a line like:

include Auxiliary::Scanner

and then implement the run_host(ip) method in your module

def run_host(ip)
   print_status("Processing IP #{ip}")
end

Each host/IP is automatically passed to this function and you just have to implement your logic as if you were working on a single host.

Including the scanner mixin removes the RHOST option from the module options and adds a RHOSTS option to the module. This option allows you to specify network address ranges (like: 192.168.10.0/24, 11.23.45.6-11.23.45.56, etc). This allows module users to specify the hosts to scan.

run_host()

called with a single IP, with THREADS concurrent threads. The best way to mass-test a range of addresses for a host-specific issue.

run_batch()

called with a group of IPs with the size defined by the run_batch_size() method, with THREADS concurrent threads. This means it will process multiple batches at the same time, so don't use this for single-host testing (its useful for a few edge cases basically).

run_range()

called *once* for the entire range of hosts. This is useful if you are going to be passing this range to another tool or doing some network-wide test. For example, calling the nmap program.

USING MULTIPLE THREADS FOR SCANNING

The scanner module now has an additional feature of using multiple threads to have multiple hosts scanned in parallel. Including the scanner mixin now adds an additional THREADS option to your module with a default value of 1. Module users and/or developers can change this value to anything greater than 1 to have multiple-threaded scanning.

Metasploit/UsingMixins