Creating an Auxiliary Module

Background

wXf currently has two types of protocols that an auxiliary module will want to develop for, HTTP(s) and SOAP. The auxiliary modules have a specific format to follow. If the format is not followed the framework will not load the module. wXf developers have identified three use cases thus far to build an auxiliary module. These three use cases are enumeration, fuzzing and scanning. Should a module developer find another purposes outside of these use cases, the module developer can contact wXf developers to add a folder under modules/auxiliary/"new folder and the module can be placed accordingly.

Brief overview of the auxiliary module types:

Scanner => Module performs an intrusive function such as sending potentially malicious data like SQL Injection strings
Fuzzing => Module sends fuzzing strings or data and reviews response.
Enum    => If the module performs an action or sends data that is considered harmless, much like the user_agent_tester,      
           then it is considered an enum module. The user_agent_tester tests an application’s responses to the same       
           request utilizing various valid user agents

Always place the auxiliary module in the directory which matches the module's purpose or type. For example, if creating an enumeration module, place this module under auxiliary/enum/your_module.rb and ensure to give it the .rb extension.

The format is as follows

class WebXploit < WXf::WXfmod_Factory::Auxiliary

def initialize
  super(
   'Name'        => 'Name Example',
   'Version'     => '1.0',
   'Description' => %q{
    Description Example, here we demonstrate what an example description would look like.
    Thank you for participating in wXf development!
                    },
   'References'  =>
    [
    ['URL', 'http://www.example.com']
    ],
   'Author'      => [ 'Your Name' ],
   'License'     => WXF_LICENSE
  )
  
  init_opts([
   OptString.new('EXAMPLE', [true, "Example Description of the Option", "default"]),
  ])
  
end

def run
  Your Code Here. When a user types `run` from the console, this method will be called (initiated)
end

end

Auxiliary Module Explained

Every wXf module whether auxiliary, exploit or otherwise must include the following class definition. The portion that specifies this as an auxiliary module is < WXf::WXfmod_Factory::Auxiliary. Append the 'end' tag to close the class and finalize the module. The rest of the code discussed on this page goes between the 'class' and 'end' markers.

class WebXploit < WXf::WXfmod_Factory::Auxiliary

end

If the module is to perform an HTTP(s) or SOAP action, then an assist module must be included. Assist modules are discussed in depth under the Assists Page on this wiki. For now, if you would like to utilize the methods you must include them.

To include the MechReq (HTTPs(s)) assist module:

include WXf::WXfassists::General::MechReq

To include the SavonReq (SOAP) assist module:

include WXf::WXfassists::General::SavonReq

Additionally, every wXf module must initialize and create values that are utilized elsewhere in the framework. This is the 'initialize' method and every module must use it. The values specified within super() are very self-explanatory.

 def initialize 
   super(
   'Name'        => 'Name Example',
   'Version'     => '1.0',
   'Description' => %q{
    Description Example, here we demonstrate what an example description would look like.
    Thank you for participating in wXf development!
                    },
   'References'  =>
    [
    ['URL', 'http://www.example.com']
    ],
   'Author'      => [ 'Your Name' ],
   'License'     => WXF_LICENSE
  )

To add another reference append a comma after the last reference. Create the next reference by following the format: ['ReferenceType', 'Reference']

'References'  =>
[
 ['URL', 'http://www.example.com'],
 ['URL', 'http://another.example.com]
],

To add an additional Author, append a comma to the last Author's name and enclose the new author's name in single or double quotes (all within one bracket). Notice that because the second author's name has a single quote (') within it, we've encapsulated the entire name in double quotes.

Author => [ 'Your Name', "Second Author's Name" ]

Before finishing the initialize function and closing it with the end tag, we need to specify any additional options that the module developer wishes to expose to the user. By default, when an assist module is included, default options are already available. An example of a default option, which is included in every assist module, would be the RURL. You can find which options will be displayed to the users on the Assists Page.

To expose additional options, use init_opts([]) (the 'end' marker closes the initialize function NOT init_opts([]):

init_opts([
   OptString.new('EXAMPLE', [true, "Example Description of the Option", "default"]),
])
  
end

The portion between init_opts([]) is the option the user will see when typing show options. Additionally, this will allow the user to set the option and the module to call it. A wiki page exists to explain the Opt classes (example shown above is OptString) and how to use them in modules. The basic premise is that the 'EXAMPLE' item (shown above) is the name of the option. The first item in the brackets specifies if it is a required option (true or false) , the second is the description and the final item is the default option as shown to the user.

Finally we need to specify the 'run' method and place code within it. When a user types 'run' from the console this is the method they will invoke and the code within it will be execute.

The following is an example of printing (to the console), the value associated with the 'EXAMPLE' option created in the previous init_opts([]) demo code.

def run
  prnt_plus(datahash['EXAMPLE'])
end

To retrieve values associated with the init_opts([]), use datahash['']. If calling a default assit option, you can call it by its lowercase equivalent. For example,

def run
  prnt_plus(rurl)
end

When printing output to the console, the developer may wish to prepend a colored symbol. We've provided the follow options:

prnt_gen()  => This is a blue -{*}-
prnt_err()  => This is a red -{-}-
prnt_plus() => This is a green -{+}-
prnt_dbg()  => This is a yellow -{!}-

Whatever is sent to the symbol method will be converted to a string and printed to the console.

This is the conclusion, if you feel we've omitted an important detail please contact the wXf developers: wXfdev[at]gmail.com.