10.1.

Introduction

10.2. ELS Echo Server

10.3. Architecture and Framework

10.4. Explore and write the ELS Echo module

10.5. Meterpreter scripting

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
You should know that Metasploit is a penetration testing
framework designed to quickly use and develop exploits, payloads,
encoders and much more.

We have already used Metasploit during the entire Penetration

Testing Professional course. We have mainly used msfconsole and
msfpayload as well as some other useful tools such as
patter_create or pattern_offset.
https://www.metasploit.com/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit is a great penetration testing framework and covering
all its features is not the purpose of this course.

Our goal is to teach you the correct methodology to follow when

you have to run exploitation tasks using Metasploit.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

During your penetration testing activities, you may need to test or
exploit a vulnerability that is not present in Metasploit. This may
happen especially when facing custom applications.

For example, we have discovered that the ELS Echo Server is

vulnerable to Buffer Overflow but as you can imagine, there is not
a Metasploit module to use to exploit it. Therefore, we have to
manually exploit it.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In this chapter, you will learn how to write your own Metasploit
modules so you can use them during you penetration testing
activities.

Before seeing how to write the module, we will show you the
exploitation process of the Els Echo Server using a custom
Metasploit module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

After, we will explore this module so you will get an idea of how
the Metasploit framework works and how to write custom
modules.

The most straightforward method to learn how to write (and

understand) Metasploit modules is to use the framework as well as
explore existing Metasploit modules.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you already know, Metasploit is written in Ruby. At this point,
you should be a master of Ruby; if you have properly studied the
previous modules, you should be able to quickly understand this
too.

If you do not feel ready, we suggest you go back in the previous

modules and review them. We strongly recommend you check
'Exploitation with Ruby' module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Do you remember how ELS Echo Server works?

It is a simple echo server that sends back what it receives.

In the following examples, our target is a Windows XP SP3 machine

(ip: 172.16.5.10) with an ELS Echo Server bound to 7707 port.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Interacting with the service is very easy. Let us see again how to
connect to ELS Echo Server.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We have already seen that it is a vulnerable service. If we send too
many characters, the service crashes and does not respond with
the echo.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We have seen how to identify and exploit the buffer overflow
vulnerability in the 'Exploitation with Ruby‘ module.

Now we want to automate the exploitation phase: this avoids

having to write a custom script (or a payload) each time we find an
ELS Echo Server.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

To do this, we have written a Metasploit module to automate the
ELS Echo Server exploitation. We will see how easy it is to exploit
the service.

Like many other modules available in Metasploit, we will have to

configure some module settings before launching it.

Please remember that this module is not available by default in

your Metasploit framework. We will see how to write and add it
soon.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The first thing to do is run the msfconsole interface and use the
echoserv module (available under the exploit/windows/els )
section.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Like any other Metasploit module,
we can display information by
running the info.

Let us run it and see what

happens.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

These is general information about the module: name, platform,
author, and so on.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We also have the available targets for this specific vulnerability
(Window XP SP3 or Windows 7) and some other options required
for the exploitation (since it is a remote exploit we usually have the
target service address and port).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Finally, Metasploit tells us that the payload avoids the usage of
one particular character (we will see that it is ‘\x00’) and then we
can see the description of the module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now that we have selected the module, we have to configure the
module options. RHOST obviously is the address of the target
172.16.5.10.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The show options command tells us that all the options are set.
The module has the port 7707 and the Windows XP SP3 target as
default options.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Let us see if the target is exploitable using the check command. As
you can see, Metasploit returns that the ELS Echo Server is
exploitable.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Since echoserv is an exploitation module, the last configuration to
set is the payload to use.

If you recall in the 'Exploitation with Ruby' module, we have

created two payloads using msfpayload:
• a calc.exe execution payload
• and a bind shell payload

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now we can select our preferred payload using the "set PAYLOAD"
command. For example, we will use a meterpreter/reverse_tcp
payload.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As we can see. some payload options are required. Moreover if we
run 'show', Metasploit will print the payload options too.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

So let us set LHOST with 172.16.5.100 (it is our interface IP
address) and then the port to receive and accept the reverse
connection: 4321 (LPORT).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now all of the options are set. We are ready to launch the exploit.
As you can see, Metasploit sends the malicious payload to the
target and then it opens a meterpreter connection!

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We have a meterpreter session. Therefore we can use all of the
meterpreter commands and scripts that you have already seen
during the PTP course.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Before exploring the ELS Echo module, we want to give you an
overview of the Metasploit Architecture and Framework.

Metasploit is a very huge framework and we will not cover all of its
features and functions. Rather, we will give you a starting point to
learn how to use and develop modules in Metasploit.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will not bore you with many of the theoretical concepts but if
you want more information, we suggest you keep close the official
Metasploit Developer Guide.

It is an old reference guide but it covers all the Metasploit

framework fundamental development concepts.

https://github.com/rapid7/metasploit-framework/wiki#metasploit-development

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This is the Metasploit framework Architecture.
LIBRARIES
INTERFACES
TOOLS Rex
Console

MSF CORE
CLI

PLUGINS MSF BASE

WEB

MODULES
Payloads Exploits Encoders Post-Modules Auxiliary

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see from the previous diagram, the Metasploit
framework has a modular structure.

This structure allows the framework to be as flexible as possible in

order to make possible code and functionality reuse.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will see in the following slide how to use all of the interfaces
provided by Metasploit.

You should know how to use the console (msfconsole command)

but the Metasploit CLI and Metasploit web interface are probably
new for you.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Then we will show some concepts related to the Metasploit
Libraries and Modules that will help you in writing your own
custom module.

We will mainly explain how to use the Metasploit API and how to
find all the information that you need for you custom module. This
is because it is not good to write a lot of library structure concepts
when the best way to learn to develop modules is to explore them
and reuse the code you find.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In Kali OS, the Metasploit Framework directory is
/usr/share/metasploit-framework. As you can see, it contains all
the Metasploit filesystem.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Taking a look at the architecture diagram again, we can identify the
respective directories while the framework interfaces are the msf*
commands.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will briefly see all of them (their content) in the following
sections.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Another useful directory is ~/.msf4/ . It is suitable for local user
modules and plugins. Putting them here you will allow you to have
them in the Metasploit framework too. We will see it better when
we explore the ELS Echo Server exploitation modules.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The Metasploit framework can be used using different interfaces
for its modules, services and features.

We will briefly see the major points of each in the following slides.

The use of them depends of your needs.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The msfconsole interface is the most used one. It gives you a real
console for the framework features.

You have already used it during the entire PTP course therefore we
will not explain its basic concepts. The only thing we want you to
notice is that msfconsole is a complex interface and a shell
command too.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Therefore using -h option, you can have a lot of interesting usage
information.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Msfcli is a very useful command-line interface into the Metasploit
framework. You can use it to launch exploits or handler quickly.

With msfcli, you have to know a bit about the framework. For
example, you have to know an exploit to launch it. It is the best
choice if you already know what you have to do and you do not
want to use the msfconsole.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Using the -h command option you can have some information
about its usage.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Let us see a simple example of exploiting the ELS Echo Server
quickly with msfcli. As you can see, RPORT, TARGET and payloads
options are taken as default.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit has a web interface too. To use it in Kali Linux, the first
thing to do is start the Metasploit service.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Then you can find the interface at the address localhost:3790. To
use it, a registration is required, but it is free and quick.

Once registered, you can create a user and password to login and
use the interface.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Once logged in. you should
see something like:

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You can build your own projects and perform the same things you
can do with msfconsole.

For some users (especially beginners), the web interface is a better

starting point to use the Metasploit framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

For example, let us exploit the ELS Echo Server vulnerability. First,
we have to select the echoserv module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now you have a graphical interface to set all of the module options. Fill
them.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

After you run the exploit, you have the meterpreter session available in
the sessions section.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Selecting the session, you
have a high level interface
to interact with
meterpreter features.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit web interface may be useful if you have to automate a
lot of tasks.

Unfortunately, some features are not available in the community

version (for example auto-exploitation feature).

If you need them, take consider upgrading your Metasploit to the

Pro version.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

There are some other interfaces to the Metasploit framework. You
already know some of them (msfpayload and msfencode for
example).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You may never need some of them. For more information, please
use the help option (-h).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We have already seen that you can find all of the libraries used by
the Metasploit framework in the lib directory of the Metasploit file
system.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Here we will give you some information related to the main
libraries used by the Framework: Rex, Msf::Core and Msf::Base.

If you want a deep knowledge on them, we suggest you read the

Metasploit Developer’s Guide available here.

https://github.com/rapid7/metasploit-framework/blob/master/documentation/developers_guide.pdf

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You should always remember that Metasploit is an open source
framework, therefore its code is fully available to you.

You can explore its modules, classes, utilities etc. You can also use
its libraries in your scripts without using any Metasploit interface
(as reported in the Metasploit Developer’s Guide Appendix).

https://github.com/rapid7/metasploit-framework/wiki#metasploit-development

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit provides very good API documentation that shows you
the code of each method you want to know.

It is available here. We suggest you consult it often during this

course, especially when we will explore the Metasploit elsecho
custom module.

https://rapid7.github.io/metasploit-framework/api/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Rex library (Ruby extension Library) is probably one of the most
important of the entire framework.

It provides a collection of basic classes and modules useful for

almost all of the framework tasks: protocols, sockets, services,
encoders, text transformations and so on.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Its full path in Kali is the following:
/usr/share/metasploit-framework/lib/rex/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You can explore its classes, modules and files but we suggest you
read the Metasploit Developer’s Guide if you want further
information.

It contains some examples that show you how to use its features in
your external scripts and tools by loading the Rex library (or some
parts of it).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Moreover, you can see that the
API documentation may help
you to understand all of the
features of Rex.

http://rapid7.github.io/metasploit-framework/api/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

If you take a look at the architecture diagram, you can visualize
what we said. Indeed tools usually use Rex features (we will see
soon).
LIBRARIES

TOOLS Rex

MSF CORE

MSF BASE

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The core library implements the set of classes and utilities that can
be used as an interface to the framework modules and plugins.

From this moment on, we will refer to modules as Metasploit

modules such as exploits, auxiliary, payloads, etc. Please do not be
confused with Ruby module syntax structure.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The library is under the
/usr/share/metasploit-framework/lib/msf/core

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will not inspect it very deeply but an important thing to know
is that the core part of the framework can be used with an
instance based approach.

The instance contains the entire framework state and you can
create it using the Msf::Framework class framework =
Msf::Framework.new

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Using the core instance, you can manage modules, plugins,
sessions, jobs and so on.

If you want to explore them, a good starting point is the Metasploit

Developer’s Guide (here).

For our purposes, we will not directly use the Framework Core.

https://github.com/rapid7/metasploit-framework/wiki#metasploit-development

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

One of the things we want to show you is the
LIBRARIES
core library effectively uses the features
provided by Rex library. Rex

MSF CORE

For example, if you take a look at the

MSF BASE
payload.rb file, you can see that it uses the
rex/payload as a mixin.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You can also use the API
documentation too (Msf node in
this case).

But pay attention; Msf also

contains classes defined in the
Base Library.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Base library is the last of the three big libraries that build up the
Metasploit framework.

It is a library developed on top of the Core library and it makes

easier to interact with the framework structure. Its purpose is to
provide simplified and more user-friendly APIs to improve and
speed up the development.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will not explore it deeply but in the same way as others
libraries, it can be found in the Metasploit file system under:
/usr/share/metasploit-framework/lib/msf/base

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

If you want more information, you can read up on Base library in
the Metasploit Developer’s Guide.

In the Appendix, you can find a comparison between Core and

Base library which is used to interact with the framework. You can
use what you prefer in your scripts.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Here we can see the modular structure of the framework. Base
library is developed using the features and classes provided by the
Core library.
LIBRARIES

Rex
You can use the API documentation
under the Msf namespace as we MSF CORE
have seen for Core.
MSF BASE

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Modules are the part of the framework that the user uses to
perform exploitations and penetration testing activities.

As we will see later, the framework is designed to facilitate the

development of different types of modules. For example, if a new
payload module is developed, all of the exploits can automatically
use it thanks to the framework structure.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Pay attention: during the course, we will use the term 'module' to
refer to Metasploit Modules, not the module syntactic (and
semantic) structure of Ruby.

In Kali, they are available here: /usr/share/metasploit-

framework/modules/.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Again, the entire framework is designed to make the usage and
interactions easier. You can see that the msfconsole interface
summarizes them each time you execute it.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now we will see what types of modules we can use (and develop)
in the Metasploit framework.

We will see them briefly but we will study them deeply when we
will explore the echoserv custom module.
MODULES
Payloads Exploits Encoders Post-Modules Auxiliary

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Exploit modules are probably the modules most used during the
whole PTP course. In Kali, you can find them in the following
directory:
• /usr/share/metasploit-framework/modules/exploits

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Note that there is also a local module directory where you can put
all of your custom modules you have developed.

We will analyze both the exploit and the local directory structure in
deep when we will explore the echoserv module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Exploits modules are not used only to perform exploitations
attacks. They are also used for other purposes such as executing
arbitrary sets of code depending on a selected payload.

Handlers are exploit modules too. For example, if we want to catch

the reverse connection of a particular exploit, we have to use a
suitable handler for that type of reverse connection.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the following example, we have created a handler that listens to
the port 4321 for a reverse meterpreter connection request.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the chapter 'Exploitation with Ruby‘, we used a payload to open
a bind shell. We could change our script in order to use a
meterpreter reverse payload; our handler will then catch the
connection started by the victim.

Note: reverse connections can be used to bypass NAT rules since it

is the victim that starts the handshake.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Here we can see that the echoS_reverseExpl.rb sends a reverse
meterpreter payload. Now it is the target machine to initiate the
connection. The handler catches the request and a meterpreter
session is created.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In order to avoid running two commands and multiple interfaces
(one that starts the handler and one that exploits the server), we
will see how to use Metasploit framework to parameterize the
entire exploitation process.

The Metasploit echoserv module that we are going to create step

by step encapsulates all of the previous steps.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Auxiliary modules are used to perform operations different from
exploitation. They are generally used when there is no need of a
payload or a target.

Some common auxiliary modules perform Denial of Service (DOS)

attacks while some other are used as scanners, information
collections and so on.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

They are generic modules that can be used when your module
does not the necessary requirements to become an exploitation
module.

As usual, if you want more information you should read up about

them in the Metasploit Developer’s Guide.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Payloads are another type of module that are very common. You
will always use a Payload module when you launch an exploit
(remember that you usually do a 'SET PAYLOAD' command).

They encapsulate the real malicious code that is going to be

executed if the exploitation succeeds (the raw instructions that
make it possible to take control of the target machine exploited).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can imagine, their default path is:
• /usr/share/metasploit-framework/modules/payloads/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see in the following screenshot, there are three types
of payloads: single, stagers and stages.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We have already used all of them.

A single payload has all of the necessary raw code to perform a

particular task. For example, a bind_shell is a single payload
because it does not require additional code.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

A meterpreter connection requires a stager and a staged payload.

The stager is used to setup the connection between the target and
the attacker machine.

Once established, a staged payload is sent to the target victim and

it is the real malicious raw code.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Taking a look at the Meterpreter session establishment, we can see
that a staged payload is sent after the stager initialize the
connection.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We will not deeply explore the payload module structure in this
course.

We suggest you take a look at the Ruby code of one of your mainly
used payloads in order to realize what they are.

We suggest you do that after you study all of this chapter (after
exploring the echoserv module) because it will be all more clear
for you.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Nops and Encoders are modules related to the exploitation phase.

Generally nops modules are used to generate instructions that

have no effect to the target machine. A typical nop instruction is
“\x90” (we used it in our scripts during the Exploitation with Ruby
chapter).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Note that sometimes, these type of nops are detected by antivirus;
therefore Metasploit provides some nops generator modules that
you can use to generate more sophisticated nops.

These are advanced concepts that are not strictly required for our
purposes but it is good to know that you can use these type of
modules.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Encoders are another type of module used to improve your
payload generation in order to make them undetectable from
antiviruses.

As usual, we will not deeply cover encoders and nops but you can
read about them in the Metasploit Developer’s Guide (here).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Encoders and nops can be respectively found in the following
paths:
• /usr/share/metasploit-framework/modules/encoders/
• /usr/share/metasploit-framework/modules/nops/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The last type of module offered by Metasploit framework is post.

From their name, you can assume they are used to perform post
exploitation tasks and therefore they may require an active
meterpreter session to interact with as an option.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The framework allows to use them with the 'run' command.

When we type run post/*, we are just running a post module.

As usual, you can find post modules here (in Kali):

• /usr/share/metasploit-framework/modules/post/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We know these architecture slides and concepts may be boring.

The purpose of these concept is to give you an overview of what

the potentiality of the Metasploit framework is and how you can
use it to improve your penetration testing activities.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We did not deeply cover modules because a lot of theory is not
necessary right now but we believe that a basic knowledge of
these concept may help you in your future development activities;
you should now know the starting point for development of each
type of module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Plugins are used to extend framework capabilities.

They provide an easy way to augment the framework features and

commands and often they are developed to provide a bridge
between the Metasploit framework and other penetration testing
tools.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Default plugins are stored under the path (in Kali):
• /usr/share/metasploit-framework/plugins
As you can see, some plugin are related to other penetration
testing tools.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

If you take a look at the framework architecture, you can see that
Plugins use Msf Base library.

This means that the interaction with LIBRARIES

the framework is usually done using Rex
the simple Msf BASI API.
MSF CORE

PLUGINS MSF BASE

But nothing prevents directly
using the other libraries too.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit tools are particular scripts that mainly use the Ruby
Extension Library to perform some tasks that do not require any
framework interaction or structure.

LIBRARIES
If you want to use some Rex
TOOLS Rex
classes or features, you are
writing what is called a Metasploit MSF CORE
dependent tool and you have
MSF BASE
to include it the Rex library.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The default Metasploit tools are available at the path (in Kali):
• /usr/share/metasploit-framework/tools

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You have already used some of them during the PTP course. Take a
look at their code to better understand how they work.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Now you should have an overview of the Metasploit Framework. It
is time to explore the ELS Echo module seen in the beginning of
the chapter. We suggest you write the module by yourself during
the study of the following slides.

Note that you can download the module in the members area too.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Remember that ELS Echo is not a standard Metasploit Framework
Module.

It is developed by eLearnSecurity exclusively for educational

purposes.

In the next slides, we will analyze it step by step in order to learn

how a generic exploitation modules can be written using the
Metasploit Framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The first thing to do in writing a Metasploit module is to identify
the module type. In this case, the module that we are going to
develop is an exploitation module (since we want to exploit a
buffer overflow vulnerability of the ELS Echo Server).

When we used the module in the beginning of the chapter, we

selected it from the exploit section of the modules.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We know that it is a Windows platform exploit module (the target
application runs on Windows).

This consideration is very important because it tells us where the

real Ruby file module must be stored in order to make it
recognizable by the framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This is what we have done to use the echoserv module. We have
another section after exploit/windows that is called els
(eLearnSecurity section).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Where do we put the module? In Kali, we have two options:

In the framework file system:

• /usr/share/metasploit-framework/modules/exploits/windows

In the directory reserved to the private user modules and plugins:

• ~/.msf4/modules/exploits/windows/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Using the reserved directory is better. This choice avoids any
problems related to the framework updates and upgrades (for
example the overwrite of your custom or modified modules) . As
you can see, we have used it in our exploitation module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Pay attention. By default, the specific directories are not available
in the ~/.msf4/modules/ directory so you have to create them.

We have created exploits/windows/els directories.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

If you want to immediately test the module, you can download it
from the members area and put it in one of the right paths we
have seen (Metasploit file system or your local user msf4
directory).

To test it, you can download and start the Els Echo server on your
local machine or use the Hera Laboratory designed for that
(Exploitation with ruby and Metasploit).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the Hera Lab, you already have an exploitable machine running
the Els Echo Server.

Once tested, we suggest you erase it and write it again from the
contents in following the next slides; we will explore it thoroughly.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Adding the module script in the right path is not enough.

The script must follow the Metasploit framework module structure

(based on the type of the module) in order to be recognizable.
Otherwise, you will not able to use it. We will see in the next slides
how to setup the structure of our example echoserv module.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This is a very high level structure of a generic module. It will be more
clear soon.

Module type

Module
Requirements

Module information

Module Operations

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Since the goal of our module is to exploit a remote buffer overflow
vulnerability, the structure of the module is the following. Take a
look at the full module code available in the members area. You
should have already downloaded it.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The msf/core library is almost always required for Metasploit
module. It is the first row of our module code.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Since our module will try to exploit a vulnerability against targets
other than the local machine, we need to extend the
Msf::Exploit::Remote class. The keyword Metasploit4 as a class
name is required. Metasploit3 can be used too.

http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Exploit/Remote

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

From the Msf::Exploit::Remote documentation, we see:

“The remote exploit class is a specialization of the exploit

module class that is geared toward exploits that are performed
against targets other than the local machine. This typically
implies exploiting other machines via a network connection,
though it is not limited to this scope.”

http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Exploit/Remote

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Taking a look at the documentation, we can see which are the
attributes to use in the module body and which are the methods
to use and redefine to specifically fit our purposes.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Since the connection that we want to establish with the vulnerable
target service is a TCP connection, we need to specialize the
echoserv module with the right methods (and options) suitable for
TCP.

It is the time to use the mixin Ruby feature. Therefore, we have to

include the specialized class Exploit::Remote::Tcp in the
Metasploit4 class.
http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Exploit/Remote/Tcp

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now we can use all of the methods and attributes provided by the
Exploit::Remote::Tcp class in the module body (take a look at the
documentation).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Particularly, we will use the connect method and the sock
attribute. Note that this class makes available RHOST and RPORT
options that will be used in the connect method. It will be more
clear soon.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

If you have decided to build the module step by step following the
course, it may be useful to know the reload command. It can be
used to reload the module you are using. It is useful because you
can modify the module and reload it to see the changes you have
made.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now that all of the classes and the libraries have been included,
we can build the module body. The first thing to do is initialize the
module with the information related to the module itself.

We suggest to keep close the full module code while you read the
following slides in order to have a global view of the module since
we will show the entire module by screen sections.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This is the information that will
be displayed when we run the
info command from the
Metasploit console.

Note that RHOST and RPORT are

available thanks to the TCP class
mixin.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the next slides, we are going
to see how to fill all of these
fields using the initialize
method.

Remember that initialize is the

constructor of every class in
Ruby.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The parameters you can specify in the initialize constructor vary
according to the module type (exploit, auxiliary, payload, etc…).

The best way to learn them is to explore the initialize constructor

of the modules available in Metasploit (we suggest you first see of
all the code of the modules you use a lot).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Another way to explore the Metasploit documentation is by taking
a look at the code shown by the initialize API for each class of the
class chain. For example, for Msf::Exploit::Remote
the class chain is the following.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

To set module information, we can use the following code. Note
the code in the rectangle is mandatory.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

It is a convention to start
setting information such
as Name, Description,
Author and so on.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see, the information is treated as a hash. Let us now
inspect these options more closely.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

DefaultOptions is a very important field because it allows us to set
some default options for the module. For example, in the following
code the RPORT default value is 7707 (as we have seen previously
from the msfconsole interface).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the following code, EXITFUNC => process means that when we
use a payload, its default EXITFUNC value is process. Remember
that process means that when you close the connection with the
specified payload (meterpreter, shell, etc..) the remote process
ends too; it is not available for further connections.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Let us see some other fields. Payload is used to specify information
about the payload generation (encoding, character to avoid, space and
so on).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

For our purposes, we only need to specify the unique character to
avoid - “\x00”.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This setting automatically tells Metasploit to create a payload that
does not contain the specified character. So when we use the SET
PAYLOAD command from our msfconsole, the payload
automatically avoids “\x00” characters.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Platform => win means that the target platform is Windows. When
you use the show payloads command, only Windows payloads will
be displayed.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Targets is used to specify information about the various type of
targets.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You should know that different OS’s have different return
addresses to use in the exploit (the address of a CALL ESP for
example). Therefore using Targets, you can parameterize the
script. We will see it more when we show the exploit method.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Finally, default target means that when you load the module (use
command) the TARGET value is already set to 0; in our case it is
Windows XP SP3 (the first value in the Targets array).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see, when we
load the module we have
some options already set
(like RPORT and TARGET).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now that our module has enough information, let us show how to
implement the check framework command.

Note that check is used to verify if the target is exploitable and it is

not a mandatory command (it is not so used by penetration
testers).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Before seeing the source code implemented, let us try to run it and
see what happens. In our case, we can see that the ELS Echo
Server of the target host 172.16.5.10 (default port 7707) is
vulnerable. Remember that you can try it in the Hera Lab.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

But what is the logic behind the check command? To identify if ELS
Echo Server is vulnerable, we can simply test its banner. You have
already seen that the first message the server sends to the client is
its banner "ELS Echo Server 1.1."

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Therefore if the banner is “ELS Echo Server 1.1”, we treat the target
service as vulnerable.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Check command corresponds to the check method.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Remember that check is a
method that we override from
the Msf::Exploit::Remote class.

You can use the class references

to get all of its methods.
Let us see the following code
step by step.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Connect is used to create a TCP
connection to the remote target.
Note that the target information
will be retrieved from RHOST
and RPORT parameters.

Remember that connect is a

method provided by
Remote::Tcp.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Exploit::Remote::Tcp tells us
that the attribute to interact
with the TCP connection is sock.

After the connection, we can use

sock.gets() to get the banner
sent by the server.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now that we have the banner,
we just need to verify its value.
The best way to return the
result of the test is using the
standard Metasploit return
values.

You can read more about check

return values here.
http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Exploit/CheckCode

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Exploit is the last method implemented in our module. As you can
imagine, it wraps the real exploitation logic code. Note that it uses
the parameters and options specified through the framework.

If you do not remember the exploitation phase, do not worry as

we will see it again in the following slides.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In order to successfully exploit the remote server, we need to set
the echoserv module with the required options.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Remember that some of
them are set by default.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see, after launching the exploitation (exploit command)
we get a meterpreter session.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The exploit command corresponds to the exploit method in our
module class. What is the logic behind it?

It is really simple. We have seen in the previous chapters how to

exploit the server through Ruby. Now we have to do the same
thing using methods, options and parameters provided by the
Metasploit framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This is how the exploit method looks. As you can see, we need to
define the exploitation code between 'def exploit…end'. We will
explain all of its parts in the following slides.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You already know that connect is used to establish a TCP
connection with the target RHOST and RPORT.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The print_status command simply outputs some information while
datastore is an array that contains the framework options.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The handler method is used to open a listening socket to the
LHOST and LPORT.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The listening socket is used to receive the request of connection by
the reverse_* PAYLOAD. Without it, we would not receive the
reverse connection.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The local variable buff stores our full payload. Do you remember
the Exploitation with Ruby chapter? We have done the same thing
using the attributes provided by the framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Target and payload are two attributes provided by the
Msf::Exploit::Remote class. Please take a look at the target and
payload references to have more info.

http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Module/Target
http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/Payload
Penetration Testing Professional 5.0 – Caendra Inc. © 2018
The first part of the payload simply set 44 nops at the very
beginning. Please refer to the previous chapter to check how we
calculated them.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

With the target attribute, you can get the selected target fields. In
our example, the target is Windows XP SP3 and with target.ret, we
have the return address specified in the initialize method.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Therefore the framework structure allows you to change targets
without changing the logic of the exploit method; target is a
parameter.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The pack(‘V’) method is used to convert the return address
(target.ret) into a binary sequence (32-bit little endian).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

After the return address, we simply add some nops.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Similar to target, payload.encoded stores the encoded payload. It
takes into account the parameter set in the module configuration.
This is an instance of the Msf::EncodedPayload class.

http://www.rubydoc.info/github/rapid7/metasploit-framework/Msf/EncodedPayload

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Finally, you already know the sock attribute provided by the TCP
inclusion can be used to interact with the service.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

So with sock.put(buff), we send the entire payload (buff) to the
server using the available socket. The last instruction (disconnect)
closes the connection.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now if the exploitation succeeds, we will obtain a meterpreter
session. Remember that thanks to the handler, the stream is
automatically opened.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Pay attention because we have deliberately used a non parametric
strategy to setup the buffer. Moreover we have used the usual
NOP instruction in the following red rectangles.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit Framework allows you to generate NOPs using the
make_nops instruction. The nops are not only ‘\x90’ instruction,
they are more sophisticated nops that avoid using the bad
characters specified in the initialize constructor.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We can parameterize the buffer generation using some Payload
parameters.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We can also parameterize the buffer generation using Target
Parameters.

It is a common situation where different targets requires different

offset or payload spaces to perform the exploitation.

Metasploit is very flexible and parametric framework; we suggest

you explore the code of some exploits to learn some common
parametric techniques.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You have probably noted that our module has two targets. The first
has been used in all of our examples (Windows XP SP3). The
second is a generic Windows 7.

Note: if you test the module with an XP machine, all should work
well while if you test the module with a different target OS (such as
Windows 7), it will certainly fail.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

This happens because Windows XP does not implement ASLR
(Address space layout randomization) like Windows 7 does.

From the system module, you should know what ASLR is and how
it works. Please refer to it if you do not recall.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the Hera Lab, you can use the module to exploit a Windows XP
target machine but if you want to test it in your private
environment (without using a Windows XP OS) you can simply
change the return address of your target with an appropriate one.

Remember that the instruction that we have to insert in the return

address is a CALL ESP or similar (JMP ESP for example).

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Obviously this is only for testing purpose because you have to find
a suitable return address of your target that is good only for you
and only if you do not restart the machine (remember the
presence of ASLR).

For example, let see how to find the address of a Windows 7

machine using the findjmp.exe tool.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Let us use the findjmp tool to find the address of a CALL ESP.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Now we can insert the found address in our module in the right
target.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Let us use the msfconsole interface to setup the exploitation
options.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see the target
is now Windows 7.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

As you can see, we have exploited the Windows 7 machine with
the right return value.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

At this point, you should understand all of the steps required to
write and test a custom module.

Obviously we have shown a very simple module and a very simple

exploit. We suggest you take a look at the code in Metasploit
modules (not only exploits module) in order to learn more about
the framework.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We know that writing a Metasploit module for the first time may
be difficult but if you spend enough time to learn the framework
structure, it will become very clear and easy.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You have a very good starting point now. You can become a
Metasploit guru and take part in the Metasploit framework
developing your modules and exploits.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

You have a very good starting point now. You can become a
Metasploit guru and take part in the Metasploit framework
developing your modules and exploits.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
 Exploitation with Ruby

Your goal is to find the vulnerable

application in the lab and then create
a Metasploit module for this specific
vulnerability.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
You already know that Meterpreter is one of the payloads available
in the Metasploit Framework.

It gives you a command line interface to execute different types of

penetration testing activities such as data harvesting, pivoting and
so on.

We have already seen some of its features during the PTP course.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

It is important to know that Meterpreter is a real framework that
provides APIs with which to interact.

You can write your own scripts using Meterpreter APIs and you can
use them in your penetration testing activities with the run
command.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

The best way to learn the Meterpreter API is to explore the code
available here:
/usr/share/metasploit-framework/lib/rex/post/meterpreter

Then you can test the APIs using the irb interpreter available in
each meterpreter session.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Default meterpreter scripts can be found here:
/usr/share/metasploit-framework/scripts/meterpreter

Some of the most known are hasdump, killav, migrate, scraper,

autoroute and so on.

They are called by the meterpreter framework using the run

command. We have seen some of them during the PTP course.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

We suggest exploring the default meterpreter scripts provided by
Metasploit in order to learn some of useful APIs and their
structure.

You can execute your own meterpreter scripts by putting them in

your local Metasploit directory:
.msf4/scripts/meterpreter/

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

In the next video, you can learn how to develop your own scripts
using features provided by the Meterpreter framework.

During the video, we will start to write a simple but powerful

information gathering tool from a template file provided by
Metasploit.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Penetration Testing Professional 5.0 – Caendra Inc. © 2018
Metasploit Developer’s Guide Metasploit Official API Documentation
https://github.com/rapid7/metasploit-
https://rapid7.github.io/metasploit-
framework/blob/master/documentation/dev
framework/api/
elopers_guide.pdf

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Metasploit: writing
Meterpreter API
custom modules

Meterpreter scripting

Penetration Testing Professional 5.0 – Caendra Inc. © 2018

Exploitation with Ruby
Your goal is to find the vulnerable
application in the lab and then create
a Metasploit module for this specific
vulnerability.

Penetration Testing Professional 5.0 – Caendra Inc. © 2018