Metasploit - Loading External Modules

If you’re in the business of writing or collecting Metasploit modules that aren’t part of the standard distribution, then you need a convenient way to load those modules in Metasploit. Never fear, it’s pretty easy, using Metasploit’s default local module search path, $HOME/.msf4/modules, and there are just a couple caveats:

Mirror the “real” Metasploit module paths

You must first set up a directory structure that fits with Metasploit’s expectations of path names. What this typically means is that you should first create an “exploits” directory structure, like so:

mkdir -p $HOME/.msf4/modules/exploit

If you are using auxiliary or post modules, or are writing payloads you’ll want to mkdir those as well.

Create an appropriate category

Modules are sorted by (somewhat arbitrary) categories. These can be anything you like; I usually use test or private, but if you are developing a module with an eye toward providing it to the main Metasploit distribution, you will want to mirror the real module path. For example:

mkdir -p $HOME/.msf4/modules/exploits/windows/fileformat

… if you are developing a file format exploit for Windows.

Troubleshooting

That’s really all there is to it. The most common problems that people (including myself) run into are:

• Attempting to create a module in $HOME/.msf4/modules/. This won’t work because you need to specify if it’s an exploit or a payload or something. Check ls /opt/metasploit/apps/pro/msf3/modules/ (or where your install of Metasploit lives).

• Attempting to create a module in $HOME/.msf4/modules/auxiliary/. This won’t work because you need at least one level of categorization. It can be new, like auxiliary/0day/, or existing, like auxiliary/scanner/scada/.

• Attempting to create a module in $HOME/.msf4/exploit/ or$HOME/.msf4/posts/. Note the pluralization of the directory names; they’re different for different things. Exploits, payloads, encoders, and nops are plural, while auxiliary and post are singular.

New mixins and protocols

Any module that requires on changes to core library functions, such as new protocol parsers or other library mixins, aren’t going to work out for you this way – you’re going to end up spewing errors all over the place as your module tries to load these classes. It’s possible to write modules as completely self-contained in nearly all cases (thanks to Ruby’s open class architecture), but such modules nearly always get refactored later to make the protocol and other mixin bits available to other modules.

In this case, it would be better to work with modules like that using a proper GitHub checkout with a development branch – see the dev environment setup docs for tons more on that.

A final warning

If you are loading new and exciting Metasploit modules, know that these things will tend to have access to anything you have access to; doubly so if you’re dropping them in root. Metasploit modules are plain text Ruby, so you can read them – but please be careful, and only add external modules from trusted sources; don’t just go grabbing any old thing you see on the Internet, because you may find yourself backdoored (or worse) in short order.

Demo

[nixawk@core ~]$ mkdir -p $HOME/.msf4/modules/auxiliary/scanner/http/
[nixawk@core ~]$ ls -l $HOME/.msf4/modules/auxiliary/scanner/http/
total 4
-rw-r--r-- 1 nixawk nixawk 2505 Feb 11 14:28 cn_caidao_php_backdoor.rb
[nixawk@core metasploit-framework]$ msfconsole
[*] Starting the Metasploit Framework console.../
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%     %%%         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  %%  %%%%%%%%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  %  %%%%%%%%   %%%%%%%%%%% http://metasploit.pro %%%%%%%%%%%%%%%%%%%%%%%%%
%%  %%  %%%%%%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  %%%%%%%%%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%  %%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%    %%   %%%%%%%%%%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%  %%%%%
%%%%  %%  %%  %      %%      %%    %%%%%      %    %%%%  %%   %%%%%%       %%
%%%%  %%  %%  %  %%% %%%%  %%%%  %%  %%%%  %%%%  %% %%  %% %%% %%  %%%  %%%%%
%%%%  %%%%%%  %%   %%%%%%   %%%%  %%%  %%%%  %%    %%  %%% %%% %%   %%  %%%%%
%%%%%%%%%%%% %%%%     %%%%%    %%  %%   %    %%  %%%%  %%%%   %%%   %%%     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  %%%%%%% %%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%          %%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


       =[ metasploit v4.11.0-dev [core:4.11.0.pre.dev api:1.0.0]]
+ -- --=[ 1399 exploits - 793 auxiliary - 229 post        ]
+ -- --=[ 356 payloads - 37 encoders - 8 nops             ]
+ -- --=[ Free Metasploit Pro trial: http://r-7.co/trymsp ]

msf > use auxiliary/scanner/http/cn_caidao_php_backdoor 
msf auxiliary(cn_caidao_php_backdoor) > info

       Name: Chinese Caidao Bruteforce - PHP
     Module: auxiliary/scanner/http/cn_caidao_php_backdoor
    License: Metasploit Framework License (BSD)
       Rank: Normal

Provided by:
  nixawk

Basic options:
  Name         Current Setting                                                                        Required  Description
  ----         ---------------                                                                        --------  -----------
  HTTP_METHOD  POST                                                                                   yes       HTTP Methods to use, GET or POST (accepted: GET, POST)
  PASS_FILE    /home/notfound/sectools/metasploit-framework/data/wordlists/CN_backdoor_passwords.txt  yes       File containing passwords, one per line
  Proxies                                                                                             no        A proxy chain of format type:host:port[,type:host:port][...]
  RHOSTS                                                                                              yes       The target address range or CIDR identifier
  RPORT        80                                                                                     yes       The target port
  TARGETURI    /                                                                                      yes       The URI to authenticate against
  THREADS      1                                                                                      yes       The number of concurrent threads
  VHOST                                                                                               no        HTTP server virtual host

Description:
  This module attempts to brute chinese caidao backdoor in php.

References:
  http://blog.csdn.net/nixawk/article/details/40430329

[1].https://github.com/rapid7/metasploit-framework/wiki/Loading-External-Modules