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:
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:
If you already have msfconsole running, use a `reload_all` command to pick up your new modules. If not, just start msfconsole and they'll be picked up automatically. If you'd like to test with something generic, I have a module posted up as a gist, here: <https://gist.github.com/todb-r7/5935519>, so let's give it a shot:
* 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.
Note that the `$HOME` directory for Metasploit Community Edition is going to be `root` and not your own user directory, so if you are expecting modules to show up in the Metasploit Pro web UIs, you will want to stash your external modules in `/root/.msf4/modules`. Of course, this means you need root access to the machine in question, but hey, you're a l33t Metasploit user, so that shouldn't be too hard.
For Windows users, the above is all true, except for accessing the modules from the web GUI. Sadly, you're a little out of luck; the module load paths on Windows are a little more restrictive and don't allow for external modules. However, the Console2-based Metasploit Console (Start > Programs > Metasploit > Metasploit Console) will work out just fine.
### 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|./dev/Setting-Up-a-Metasploit-Development-Environment.md]] for tons more on that.
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.
