Developing and Understand Auxiliary Modules in Metasploit 3

This chapter covers the concept behind auxiliary modules, their structure and working examples on how to develop auxiliary modules. Most of the discussion in this chapter revolves around auxiliary modules development. Metasploit version 3 is written in the Ruby programming language. While going through this material without any Ruby programming knowledge will still give you good insights to the organization and capabilities of the framework; you will find this material most useful if you know Ruby language and have an intention of programming modules of metasploit.

Auxiliary Modules Overview

In metasploit any module that is not an exploit is an auxiliary module. Exploit modules always have a payload. Auxiliary modules are a fascinating feature of the framework allowing it to extend for a variety of purposes other than exploitation. You can create your own quick vulnerability scanners, port scanners, make MSF work as an FTP, HTTP or SMTP client and do a whole lot of other cool stuff. You have a ready to use code library at your disposal enabling quick development of such tools.

Throughout this chapter, we will look into various aspects and features of auxiliary modules and shall try to implement our own auxiliary module. This module will try to place files or delete files on web servers that allow the HTTP protocol's PUT and DELETE methods without any authentication. This is a good example of an auxiliary module since it isn't an exploit. It is just a simple tool to check web server mis-configurations.

Auxiliary Modules Placement and Structure

Auxiliary modules reside in the modules/auxiliary/ directory of the framework main directory. Given below is a basic definition of an auxiliary module.

require 'msf/core'

p "My Auxiliary Module"

class Metasploit3 < Msf::Auxiliary

end         # for the class definition

Place this code in a file any where under '$HOME/.msf/modules/auxiliary' folder.

All auxiliary modules inherit from their base class Msf::Auxiliary. The line p "My Auxiliary Module" prints a line when msf loads. Now your module is part of MSF and is available to you via various MSF user interfaces. Of course, as it is currently this module doesn't do anything other than printing a line (which no other module does).

The first thing we need to do is to add some information about this module. This can be done in the initialize constructor for the class. Lets include the initialize constructor in the class definition.

   def initialize(info = {})
       super(update_info(info,
           'Name'           => 'HTTP Put method exploiter',
           'Description'    => %q{
                   This module exploits faulty web server configurations
                   allowing HTTP PUT and DELETE methods without any user validation.
           },
           'Author'         => [ 'Kashif [at] compulife.com.pk' ],
           'License'        => BSD_LICENSE,
           'Version'        => '$Revision: 4663 $',
           'Privileged'     => false,
           'Platform'       => [  ],
           'Arch'           => [ ARCH_X86, ARCH_PPC, ARCH_SPARC, ARCH_CMD ],
           'Targets'        => [ [ 'Wildcard Target', { } ] ],
           'DefaultTarget'  => 0,
           'Actions'        => [AuxiliaryAction.new('PUT_FILE', {}),
                                AuxiliaryAction.new('DELETE_FILE', {})],
           'DefaultAction'  => [ 'PUT_FILE' ]
           ))

       register_options(
           [
               OptString.new('PATH', [ true,  "path where to store the new file", '/']),
               OptString.new('DATA', [ false,  "Data to write into the file", ' ']),
           ], self.class
           )
       
   end

First thing the constructor does is that it calls the constructor of its base class by calling the super method. All your modules should contain this call. Note the call to update_info method within the constructor. This method is used to update information about a module be it an exploit module or an auxiliary module. The options that each type of module takes differ slightly, for example, exploit modules contain a payload option while auxiliary modules don't.

(Detailed description of the options update_info can take comes here)

register_options method

Second call is to the register_options method. This method adds options that the user can specify before running the module.

The datastore

The options set by a user are available via a predefined hash named datastore. For example:

 print_status("the contents of the DATA variable are: " + datastore['DATA'])

Auxiliary Mixins

Auxiliary module mixins provide useful features that you can use to enhance the auxiliary modules you create.

Metasploit/DevelopingAuxiliaryModules