Writing your first Metasploit module can be a daunting task, especially if one does not code in Ruby on a regular basis. Fortunately the language’s syntax is intuitive enough, for anyone with prior programming and scripting knowledge, to make the transition (from Python for example) to Ruby.

Before taking the plunge into module construction and development, let’s take a quick look at the some of the modules currently in place. These files can be used as our base for re-creating an attack on several different supported protocols, or crafting ones own custom module.

root@kali:/usr/share/metasploit-framework/lib/msf/core/exploit# ls
afp.rb                    dect_coa.rb      mixins.rb          smb
arkeia.rb                 dhcp.rb          mssql_commands.rb  smb.rb
browser_autopwn.rb        dialup.rb        mssql.rb           smtp_deliver.rb
brute.rb                  egghunter.rb     mssql_sqli.rb      smtp.rb
brutetargets.rb           exe.rb           mysql.rb           snmp.rb
capture.rb                file_dropper.rb  ndmp.rb            sunrpc.rb
cmdstager_bourne.rb       fileformat.rb    ntlm.rb            tcp.rb
cmdstager_debug_asm.rb    fmtstr.rb        omelet.rb          telnet.rb
cmdstager_debug_write.rb  ftp.rb           oracle.rb          tftp.rb
cmdstager_echo.rb         ftpserver.rb     pdf_parse.rb       tns.rb
cmdstager_printf.rb       http             pdf.rb             udp.rb
cmdstager.rb              imap.rb          php_exe.rb         vim_soap.rb
cmdstager_tftp.rb         ip.rb            pop2.rb            wbemexec.rb
cmdstager_vbs_adodb.rb    ipv6.rb          postgres.rb        wdbrpc_client.rb
cmdstager_vbs.rb          java.rb          powershell.rb      wdbrpc.rb
db2.rb                    kernel_mode.rb   realport.rb        web.rb
dcerpc_epm.rb             local            remote             winrm.rb
dcerpc_lsa.rb             local.rb         riff.rb
dcerpc_mgmt.rb            lorcon2.rb       ropdb.rb
dcerpc.rb                 lorcon.rb        seh.rb

Here we see several modules of interest, such as prepackaged protocols for Microsoft’s SQL, HTTP, TCP, FTP, SMTP, SNMP, Oracle, and many more. These files undergo constant changes and updates, adding new functionalities over time.

Let’s start with a very simple program, navigate to /usr/share/metasploit-framework/modules/auxiliary/scanner/mssql and create the required Metasploit folder structure under your home directory to store your custom module. Metasploit automatically looks in this folder structure so no extra steps are required for your module to be found.

root@kali:/usr/share/metasploit-framework/modules/auxiliary/scanner/mssql# mkdir -p ~/.msf4/modules/auxiliary/scanner/mssql

Then do a quick cp mssql_ping.rb ~/.msf4/modules/auxiliary/scanner/mssql/ihaz_sql.rb

root@kali:/usr/share/metasploit-framework/modules/auxiliary/scanner/mssql# cp mssql_ping.rb ~/.msf4/modules/auxiliary/scanner/mssql/ihaz_sql.rb

Open the newly-created file using your favourite editor and we’ll begin crafting our example module, walking through each line and what it means:

# $Id: ihaz_sql.rb 7243 2009-12-04 21:13:15Z rel1k $   >--- automatically gets set for us when we check in

# This file is part of the Metasploit Framework and may be subject to           >---- licensing agreement, keep standard
# redistribution and commercial restrictions. Please see the Metasploit
# Framework web site for more information on licensing and terms of use.
# http://metasploit.com/framework/

require 'msf/core'  >--- use the msf core library

class MetasploitModule < Msf::Auxiliary >---- its going to be an auxiliary module

include Msf::Exploit::Remote::MSSQL   >----- we are using remote MSSQL right?
include Msf::Auxiliary::Scanner  >----------- it use to be a SQL scanner

def initialize >---- initialize the main section
          'Name' => 'I HAZ SQL Utility',   >------- name of the exploit
          'Version' => '$Revision: 7243 $', >------- svn number
          'Description' => 'This just prints some funny stuff.', >------------ description of the exploit
          'Author' => 'THE AUTHOR', >--- thats you
          'License' => MSF_LICENSE >---- keep standard

    deregister_options('RPORT', 'RHOST')    >---- do not specify RPORT or RHOST

def run_host(ip) >--- define the main function

begin >---begin the function
puts "I HAZ SQL!!!!"  >---- print to screen i haz SQL!!!
end >--- close
end >---- close
end >---- close

Now that you have a basic idea of the module, save the above code (without the >—— comment strings) and let’s run it in msfconsole.

msf > search ihaz
[*] Searching loaded modules for pattern 'ihaz'...


Name Description
---- -----------
scanner/mssql/ihaz_sql MSSQL Ping Utility

msf > use scanner/mssql/ihaz_sql
msf auxiliary(ihaz_sql) > show options

Module options:

Name        Current Setting                                     Required Description
----        ---------------                                     -------- -----------
HEX2BINARY /pentest/exploits/framework3/data/exploits/mssql/h2b no       The path to the hex2binary script on the disk
MSSQL_PASS                                                      no       The password for the specified username
MSSQL_USER sa                                                   no       The username to authenticate as
RHOSTS                                                          yes      The target address range or CIDR identifier
THREADS    1                                                    yes      The number of concurrent threads

msf auxiliary(ihaz_sql) > set RHOSTS doesntmatter
RHOSTS => doesntmatter
msf auxiliary(ihaz_sql) > exploit

[*] Scanned 1 of 1 hosts (100% complete)
[*] Auxiliary module execution completed

Success! Our module has been added! Now that we have a basic understanding of how to add a module, let’s take a closer look at the MSSQL module written for the Metasploit framework.

X Close


Certified Pentesting

course starting at
$800 USD

Take Penetration Testing with Kali Linux to gain invaluable penetration testing skills and earn your OSCP.

  • Self-paced, online course
  • Includes certification exam fee
  • Access innovative virtual labs
  • Hands-on experience
  • Become an OSCP

Certified Pentesting

course starting at
$1200 USD

Take Cracking the Perimeter to take your penetration testing skills to expert levels and earn your OSCE.

  • Self-paced, online course
  • Includes certification exam fee
  • Access innovative virtual labs
  • Hands-on experience
  • Become an OSCE


Certified Pentesting
Web Expert

course starting at
$1400 USD

Take Advanced Web Attacks and Exploitation, to deep dive into web apps to earn your OSWE.

  • Self-paced, online course
  • Includes certification exam fee
  • Access innovative virtual labs
  • Hands-on experience
  • Become an OSWE

Certified Pentesting
Wireless Professional

course starting at
$450 USD

Take Offensive Security Wireless Attacks to acquire knowledge about Wi-Fi attacks and earn your OSWP.

  • Self-paced, online course
  • Includes certification exam fee
  • Access innovative virtual labs
  • Hands-on experience
  • Become an OSWP

Certified Exploitation

course starting at
Live Schedule

Take Advanced Windows Exploitation to develop exploits for Windows systems and earn your OSEE.

  • Live training course
  • Includes certification exam fee
  • Maximum instructor interaction
  • Highly challenging
  • Become an OSEE