Adding new functionality via an Auxiliary module is an easy way to take advantage of a lot of the Metasploit library features with out having to duplicate code. Most of the function-ality needed to do things like socket communications is already included, and if the Metasploit API is used, the only real task is fashioning the code to carry out whatever task you want to add.The best way to learn is by doing; that’s why in this section a working aux-iliary module will be developed and included.The example that best illustrates this is adding a new family type of auxiliary module and a tool to take advantage of them.The function-ality that will be added is Voice over Internet Protocol (VoIP).The result is a simple module that allows a researcher to spoof VoIP phone calls and callerID.The module is designed to send out an SIP invite request to every address in a given range.The invite request will cause the SIP device to begin ringing and display information about the caller that is read from the packet.
Adding a new Auxiliary module begins in the Metasploit core.This is how the new functionality will be announced to other parts of Metasploit and will allow selection and use while running Metasploit.The heart of Metasploit can be found at lib/msf/core. Work begins by adding a line in lib/msf/core/auxiliary.rb.The auxiliary script is the base all mod-ules in that class start with (see Figure 5.11). Under the Auxiliary, add a line like the fol-lowing: msf/core.auxiliary/voip.
Figure 5.11 An Auxiliary Script for Metasploit Showing Where to Add a Line in auxiliary.rb for the New voip mixin
After this, go into the auxiliary directory and create a file called voip.rb.This is empty now, but as the functionality of voip modules increases, the more code can be added here.
For now, we will just declare a base module that is empty.
module Msf
###
#
# This module provides methods for VoIP attacks
#
###
module Auxiliary::Voip
end end
Once the Metasploit core is aware of the new class, the actual auxiliary plugin can be developed.The plugin code will reside in modules/auxiliary. Create a VoIP directory to con-tain this new family and then enter it. Not much is required for a base module, and with the only necessary features being the basic skeleton of the new tool, it will look like the fol-lowing example:
end
end end
This template provides a great foundation with which to start the module.The first thing to do is fill in the initialize function.These fields in the initialize function will be dis-played when a user requests more detailed information.These fields are disdis-played by script, which can be found at lib/msf/base/serializer/readable_text.rb. A quick review of
readable_text.rb will familiarize you with what the valid options are and how they are dis-played. Something to remember is that, in the author section, if you want to include an e-mail address, enclose it between < and >, otherwise the entire field will be included.
Now that a skeleton module will show up when Metasploit is run, check and see if it works with the show auxiliarycommand and the info voip/sip_invite_spoofcommand (see Figures 5.12 and 5.13).
Figure 5.12Output of the show auxiliary Command
Figure 5.13Output of Running Info on voip/sip_invite_spoof
The first two new lines are the include Exploit::Remote::Udp and include Auxiliary::Scanner mixins.This is the equivalent of adding header files in a C program.This lets the module know where to find code you will be calling later.
require 'msf/core'
include Exploit::Remote::Udp include Auxiliary::Scanner
module Msf
class Auxiliary::Voip::SipSpoof < Msf::Auxiliary
def initialize
super(
'Name' => '',
'Version' => '', 'Description' => '',
'Author' => '', 'License' => MSF_LICENSE
)
register_options(
[
], self.class) end
end end
Next, you must decide what options will be used. Since this works on a range,
RHOSTS will be used instead of RHOST (see Figure 5.14). In order to remove the options not being used, the deregister_options function is employed. Now when show optionsis used after selecting the module, RHOST, SSL, and Proxies will not show up. RPORT, or the port that the UDP packet will be sent to, is set by default to port 5060.The user can over-ride this if a SIP implementation is found running on a nonstandard port.The expected options and default values are added between the brackets in the register_options() function.
require 'msf/core'
module Msf
class Auxiliary::Voip::SipSpoof < Msf::Auxiliary
include Exploit::Remote::Udp include Auxiliary::Scanner
def initialize super(
'Name' => 'SIP Invite Spoof', 'Version' => '$Revision: 3624 $',
'Description' => 'This module will create a fake SIP invite request making the targeted device ring and display fake caller id information.',
'Author' => 'David Maynor <dave@erratasec.com>', 'License' => MSF_LICENSE
)
deregister_options('Proxies','SSL','RHOST')
register_options(
[
Opt::RPORT(5060),
OptString.new('SRCADDR', [true, "The sip address the spoofed call is coming from",'192.168.1.1']),
OptString.new('MSG', [true, "The spoofed caller id to send","The Metasploit has you"])
], self.class) end
end end
Figure 5.14Options from the VoIP SIP Spoof Module
Some options were added to make things more robust.The option MSG will be dis-played in the phone’s callerID when it rings. SCRADDR allows the user to configure where the call appears to be coming from.
Since this module uses the scanner mixin, this allows a user to set a range like 192.168.1.1/24, and a copy of the SIP invite will be sent to every address in the given
range.The default function for an auxiliary module is run_host(), so this is the first part of the module to be executed. In this example, the run_host function accepts a single argu-ment,ip. Since this module uses the scanner mixin every time run_host() is invoked, it will be a different address from the range supplied to RHOSTS. As a developer, which address is currently being targeted is not a concern.Your code should just perform an action on the ip argument.This is demonstrated with the print line that informs the user what IP the SIP invite is currently being sent to.
require 'msf/core'
'Name' => 'SIP Invite Spoof', 'Version' => '$Revision: 3624 $',
'Description' => 'This module will create a fake SIP invite request making the targeted device ring and display fake caller id information.',
'Author' => 'David Maynor <dave@erratasec.com>', 'License' => MSF_LICENSE
OptString.new('SRCADDR', [true, "The sip address the spoofed call is coming from",'192.168.1.1']),
OptString.new('MSG', [true, "The spoofed caller id to send","The Metasploit has you"])
], self.class) end
def run_host(ip)
begin
name=datastore['MSG']
src=datastore['SRCADDR']
connect_udp
print_status("Sending Fake SIP Invite to: #{ip}")
end end
end end
The actual invite request is pretty simple.The following code is the entire module, which resides in modules/auxiliary/voip/sip_invite_spoof.rb.This is easy to construct since SIP is a text-based protocol. SIP parsers look for the end of a line by finding a linefeed and carriage return so they have to be included when building the packet. Ruby makes building this packet simple as newlines just append the next line to the previous ones (see Figure 5.15).
Figure 5.15Output of the Module with RHOSTS Set to 192.168.1.10/27
Using the UDP subsystem is trivial.The connect_udp function initializes the system, data are sent using the udp_sock.put() function, and everything is cleaned up using discon-nect_udp.The whole module is 53 lines and took less than an hour to write (see Figures 5.16 and 5.17).
Figure 5.16The VoIP SIP Invite Spoof Module Making a Softphone Ring
Figure 5.17The SIP Invite Actually Looks As If It Were Being Sent to Hosts in Wireshark