Metasploit is a pentesting framework that encompasses everything from target/service reconnaissance to the development of complete exploits. In this article, I will explain how to program a basic module that will connect to a port, read a string, and write another string to that same socket.

We create the necessary directory structure:

NOTE: Modules without payloads (scanners) are auxiliary.

We write a basic port scanner that will send a string and read another when the connection is made:

require 'msf/core'

class MetasploitModule < Msf::Auxiliary

      include Msf::Exploit::Remote::Tcp
      include Msf::Auxiliary::Scanner

      def initialize(info = {})
                super(update_info(info,
                        'Name'           => 'TCP Scanner',
                        'Description'    => %q{
                                        Simple TCP Scanner coded by kr0m
                                             },
                        'Author'         => [ 'Kr0m' ],
                        'Version'        => '$Revision: 0.1 $',
                        ))

                        register_options(
                        [
                                Opt::RPORT(12345)
                        ], self.class)
       end

        def run_host(ip)
                connect()
                greeting = "HELLO SERVER"
                sock.puts(greeting)
                data = sock.recv(1024)
                print_status("Received: #{data} from #{ip}")
                disconnect()
        end
end

We put the string in a file and listen with netcat with that file:

We launch our scanner from Metasploit:

msf > search simple_tcp

Matching Modules
================

   Name                          Disclosure Date  Rank    Description
   ----                          ---------------  ----    -----------
   auxiliary/dos/tcp/synflood                     normal  TCP SYN Flooder
   auxiliary/scanner/simple_tcp                   normal  TCP Scanner

msf > use auxiliary/scanner/simple_tcp
msf auxiliary(simple_tcp) > set RHOSTS 192.168.20.27
RHOSTS => 192.168.20.27
msf auxiliary(simple_tcp) > run
[*] 192.168.20.27:12345   - Received: 123
 from 192.168.20.27
[*] Scanned 1 of 1 hosts (100% complete)
[*] Auxiliary module execution completed

We can see that 123 has been received in Metasploit and netcat has received HELLO SERVER:

listening on [any] 12345 ...
connect to [192.168.20.27] from (UNKNOWN) [192.168.20.27] 34155
HELLO SERVER

This is a very basic example, but as an introduction, it is very useful to have a base module from which to build more complex modules.