How to Write a Metasploit Post Module

by {"login"=>"averagesecurityguy", "email"=>"stephen@averagesecurityguy.info", "display_name"=>"averagesecurityguy", "first_name"=>"", "last_name"=>""}

I have written a couple of post exploitation modules for Metasploit and have had fun doing it. I thought I would share a few tips for anyone else who wanted to write a post module.

Start with a Template

There are a number of good post exploitation modules available in the modules/post directory within the framework directory. Your best bet is to find one you like and then modify it. You need to pay particular attention to the initialize method of your post module. Here is an example:

def initialize(info={})
  super( update_info( info,
    'Name'          => 'Gather Linux System Information Enumeration',
    'Description'   => %q{
	This module gathers basic system information from Linux systems.
	Enumerates users, hashes, services, network config, routing table, installed packages, 
	,screenshot, and bash_history
	},
    'License'       => MSF_LICENSE,
    'Author'        =>
	[
	  'Stephen Haywood ',
	  'sinn3r',  #Modified the original, and more testing
	  'Carlos Perez ', # get_packages and get_services
	],
    'Version'       => '$Revision: 12842 $',
    'Platform'      => [ 'linux' ],
    'SessionTypes'  => [ "shell" ]
  ))

  register_options(
    [
      OptBool.new('VERBOSE', [false, 'Show detailed status messages', false]),
    ], self.class)

end

You need to modify the Name, Description, Author, Platform, and SessionTypes. You can also add options using the register_options method.

Registering Options

These are the options that are listed when you type show options at the msfconsole prompt. If you look at the option definition the first argument is the name of the option. The second argument is an array of values, the first says whether the option is required, the second is the description of the option, the third is the default value of the option. You do not have to define a default value.

SessionTypes

After you exploit a box you will have one of two types of sessions, either a meterpreter session or a shell session. When you define your post module you need to determine whether it will work with meterpreter or shell sessions or both. Keep in mind that meterpreter is not stable for all platforms and shell is not as capable as meterpreter. This means your module may run in only one session type. The best thing to do is test your module.

Don't Reinvent the Wheel

If you look in the lib/msf/core/post directory in the framework directory you will find a number of ruby modules that define methods that can be used in your post module by using the require statement. Here is an example:

require 'msf/core/post/common'
require 'msf/core/post/file'

The common.rb file defines the cmd_exec method, which can be used to execute commands on your target whether you are using a meterpreter session or a shell session. The file.rb module defines methods to allow you to read, write, and append to files on the target machine. Use these methods.

Always Store your Loot

If your module is designed to gather data you should always store the data in the loot using the store_loot method. The store_loot method saves data in a unique file in your ~/.msf3/loot folder and adds indexing information to the metasploit database, if you are using it, to allow you to quickly find data stored in your loot folder. Here is a quick rundown of the store_loot method.

loot = store_loot(ltype, ctype, session, data, nil, info)

The ltype is the loot type, you can make this anything relevant. If you are gathering linux passwords it might be "linux.passwords". The ctype is the file or mime type. The session variable is already defined, it represents the session (meterpreter or shell) that you are currently in. The data variable holds the data you want to write to the file. Next is the filename, which you can leave as nil, and finally you have info, which is stored in the database and can be used to help you identify the data in the loot file. The store_loot method will return the full path of the loot file that was created.

Don't Forget to Run it

Metasploit uses the run method as the starting point to your module so make sure you define the run method. You can use as many other methods as you like but the run method is where you start.

This tutorial is over for now. Go have fun and create some cool post modules. One more thing, if you have questions the #metasploit channel on irc.freenode.net is an excellent place to ask.