How to get started with writing an auxiliary module

Metasploit is known for its free, open-source exploits - modules that pop shells. But in reality, penetration testers rely more on auxiliary modules, and often a successful pentest can be done without firing a single exploit. They're just more handy, and the punishment for a failed attempt is generally much lower. Professionals actually love auxiliary modules.

Another interesting fact about auxiliary modules is that some of them aren't so different from being exploits. The main difference is how it's defined in Metasploit: if a module pops a shell, it's an exploit. If not, even though it takes advantage of a vulnerability, it still belongs to the auxiliary category.

So you see, if you're an auxiliary module addict, you are on the right track.

Plan your module

Just like writing a software, before you start coding you should have a clear and specific goal for what your auxiliary module does. It's never a good idea to have multiple functionalities in a single module. You should break it down into multiple modules instead.

You should also think about how your module will perform in different situations. For example, if it's meant to test against a Tomcat server, what happens if you use it against Nginx? Will it error out and leave a backtrace? If it does, you should handle that properly. Does your module require specific settings/conditions from the target machine? What happens if it doesn't? Will it error out again?

Most importantly, make sure to test your module thoroughly. It's always ugly to find out problems in the middle of an important engagement, that just might cost you.

Main categories of auxiliary modules

Generally speaking, auxiliary modules are categorized based on their behavior, but this is somewhat inconsistent so you'll just have to use your best judgement and find the most appropriate one. Here's a list of the common ones:

• admin - Modules that modify, operate, or manipulate something on target machine.
• analyze - We initially created this folder for password-cracking modules that require analysis time.
• client - We initially created this folder for an SMTP module for social-engineering purposes.
• crawler - If you have a web-spider (crawler), put it here.
• dos - Pretty self-explanatory: denial-of-service modules.
• fuzzers - If your module is a fuzzer, this is where it belongs. Make sure to place it in the correct sub-directory based on the protocol.
• gathers - Modules that gather, collect, or enumerates data from a single target.
• scanner - Modules that use the Msf::Auxiliary::Scanner mixin almost always go here. Make sure to place yours in the correct sub-directory based on the protocol.
• server - Modules that are servers.
• sniffer - Modules that are sniffers.

There are actually a few more directories in auxiliary, but that's kind of where the gray area is. You are more than welcome to see if yourself.

The Msf::Auxiliary::Scanner mixin

The Msf::Auxiliary::Scanner mixin is heavily used in auxiliary modules, so we might as well talk about it right here. The mixin allows you to be able to test against a range of hosts, and it's multi-threaded. To use it, first off you need to include the mixin under the scope of your Metasploit3 class:

include Msf::Auxiliary::Scanner

A couple of new things will be added to your module when you include this mixin. You will have a new datastore option named "RHOSTS", which allows the user to specify multiple hosts. There's a new "THREADS" option, which allows the number of threads to run during execution. There's also "ShowProgress" and "ShowProgressPercent" for tracking scan progress.

Typically, the main function for an auxiliary module is "def run". But when you use the Msf::Auxiliary::Scanenr mixin, you need to be using def run_host(ip). The IP parameter is the target machine.

Templates

Here's the most basic example of an auxiliary module. We'll explain a bit more about the fields that need to be filled:

##
# This module requires Metasploit: http//metasploit.com/download
# Current source: https://github.com/rapid7/metasploit-framework
##

require 'msf/core'

class Metasploit3 < Msf::Auxiliary

  def initialize(info = {})
    super(update_info(info,
      'Name'           => 'Module name',
      'Description'    => %q{
        Say something that the user might want to know.
      },
      'Author'         => [ 'Name' ],
      'License'        => MSF_LICENSE
    ))
  end

  def run
    # Main function
  end

end

The Name field can begin with the vendor name, but optional. Followed by the software name. And then a few words that basically describe what it's for. For example: "Dolibarr ERP/CRM Login Utility"

The Description field should explain what the module does, things to watch out for, specific requirements, the more the better. The goal is to let the user understand what he's using without the need to actually read the module's source and figure things out. And trust me, most of them don't.

The Author field is where you put your name. The format should be "Name ". If you want to have your Twitter handle there, leave it as a comment, for example: "Name # handle"

Because the Msf::Auxiliary::Scanner mixin is so popular, we figured you want a template for it, too. And here you go:

##
# This module requires Metasploit: http//metasploit.com/download
# Current source: https://github.com/rapid7/metasploit-framework
##

require 'msf/core'

class Metasploit3 < Msf::Auxiliary

  include Msf::Auxiliary::Scanner

  def initialize(info = {})
    super(update_info(info,
      'Name'           => 'Module name',
      'Description'    => %q{
        Say something that the user might want to know.
      },
      'Author'         => [ 'Name' ],
      'License'        => MSF_LICENSE
    ))
  end

  def run_host(ip)
    # Main function
  end

end

References

https://github.com/rapid7/metasploit-framework/tree/master/modules/auxiliary

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/auxiliary.rb

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/auxiliary/scanner.rb