Implementing the Encoder

The encoder portion is made up of code that runs on an attacker's machine prior to exploiting a target. It converts the actual payload that will be executed into the encoded format and then transmits the encoded form as the payload. Once the target begins executing code, the decoder, as described in chapter , converts the encoded payload back into its raw form and then executes it.

For the purposes of this document, the client-side encoder was implemented in the 3.0 version of the Metasploit Framework as an encoder module for x86. This chapter will describe what was actually involved in implementing the encoder module for the Metasploit Framework.

The very first step involved in implementing the encoder is to create the appropriate file and set up the class so that it can be loaded into the framework. This is accomplished by placing the encoder module's file in the appropriate directory, which in this case is modules/encoders/x86. The name of the module's file is important only in that the module's reference name is derived from the filename. For example, this encoder can be referenced as x86/avoid_utf8_tolower based on its filename. In this case, the module's filename is avoid_utf8_tolower.rb. Once the file is created in the appropriate location, the next step is to define the class and provide the framework with the appropriate module information.

To define the class, it must be placed in the appropriate namespace that reflects where it is at on the filesystem. In this case, the module is placed in the Msf::Encoders::X86 namespace. The name of the class itself is not important so long as it is unique within the namespace. When defining the class, it is important that it inherit from the Msf::Encoder base class at some level. This ensures that it implements all the required methods for an encoder to function when the framework is interacting with it.

At this point, the class definition should look something like this:

require 'msf/core'

module Msf
module Encoders
module X86

class AvoidUtf8 < Msf::Encoder

end

end
end
end

With the class defined, the next step is to create a constructor and to pass the appropriate module information down to the base class in the form of the info hash. This hash contains information about the module, such as name, version, authorship, and so on. For encoder modules, it also conveys information about the type of encoder that's being implemented as well as information specific to the encoder, like block size and key size. For this module, the constructor might look something like this:

def initialize
   super(
      'Name'             => 'Avoid UTF8/tolower',
      'Version'          => '$Revision: 1.3 $',
      'Description'      => 'UTF8 Safe, tolower Safe Encoder',
      'Author'           => 'skape',
      'Arch'             => ARCH_X86,
      'License'          => MSF_LICENSE,
      'EncoderType'      => Msf::Encoder::Type::NonUpperUtf8Safe,
      'Decoder'          =>
         {
            'KeySize'    => 4,
            'BlockSize'  => 4,
         })
end

With all of the boilerplate code out of the way, it's time to finally get into implementing the actual encoder. When implementing encoder modules in the 3.0 version of the Metasploit Framework, there are a few key methods that can overridden by a derived class. These methods are described in detail in the developer's guide[2], so an abbreviated explanation of only those useful to this encoder will be given here. Each method will be explained in its own individual section.

• decoder_stub
• encode_block
• encode_end