This is a guide for setting up an environment for effectively **contributing to the Metasploit Framework**. If you just want to use Metasploit for legal, authorized hacking, we recommend instead you either [download the commercial Metasploit binary installer](http://metasploit.com/download), or the [open-source packages](https://github.com/rapid7/metasploit-framework/wiki/Nightly-Installers) which will take care of all the dependencies for you. The commercial installers also include the option for upgrading to Metasploit Pro and are updated semi-weekly, while the open-source installers are updated every night.
If you are using Kali Linux, Metasploit is already pre-installed. [Follow the instructions](http://docs.kali.org/general-use/starting-metasploit-framework-in-kali) provided by Kali on how to use the provided metasploit-framework package and setup a database.
If you want to develop on and [contribute] to Metasploit, read on! This guide should get you going on pretty much any Debian-based Linux system, but it is written for Kali Linux in particular, since many, many Metasploit Users are also Kali Linux users, and why spin up a different VM?
For this guide, the example user is "YOUR_USERNAME," and the sample password in this document is "YOUR_PASSWORD." Anywhere you see those strings, use your own username and password. Obviously, they should be hard.
Each section will have a **TLDR** code snippet, suitable for copy-pasting, if you just want to speed through things, then a more complete explination of what's going on with the TLDR broken down into more of a step-by-step. Keep in mind that as written, many of these can overwrite any local customization you might have, may have less secure defaults than you'd like, and other surprises. Use them only if you are impatient, have done this all before, and understand the risks.
This guide assumes you already have an installation of the Kali-Rolling distribution. Because this distribution is constantly updating, it is likely that this document will become stale rapidly. It assumes Kali 2016.1, which is the latest version at the time of this writing.
There are many ways to install Kali Linux, outlined in [Kali Linux's extensive documentation](http://docs.kali.org/category/installation). You can also install a [pre-built VM image](https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/), which can save a lot of time compared to fiddling with VM drivers. Just be sure to regenerate your SSH host keys and set the root password if you use these.
Kali Linux by default ships without a firewall enabled. This step is optional, but is a nice preventative measure to take. The 'ufw' package provides a simplified interface to the Linux firewall subsystem.
Often, you need to have remote access back to your Kali machine; a typical use case is for reverse shells. You might also want to use ssh and scp to write code and copy files, from elsewhere -- this is especially useful if you're running Kali as a guest OS and don't want to install VMWare Tools. To enable the most common ports you will likely use while hacking with Metasploit, run the following commands.
ufw allow 4444:4464/tcp # For default reverse shells
ufw allow 8080:8090/tcp # For browser exploits
ufw allow ssh && service ssh start # If you want to shell in from elsewhere
```
# Create a Dev User
You will want to create a non-root user. In this example, the user is `msfdev`. Neither Git nor RVM likes you to be root, since weird things can easily happen with your filesystem permissions.
Once this is complete, switch to this user by logging out of `root` and logging back in as `msfdev`. While some steps down the line will still require sudoer access, you should resist the temptation to keep being root. You will invariably forget to switch and start getting mystery errors about unable to read critical resources that RVM and Git need.
The TLDR here is all you should need to stage up Kali (or any other Debian-based distro) for a proper dev environment. Note, there's no Ruby or editor -- we'll get to those next.
Kali, like most operating system distributions, does not ship with the latest Ruby with any predictable frequency. So, we'll use RVM, the Ruby Version Manager. You can read up on it here: https://rvm.io/, and discover it's pretty swell. Some people prefer rbenv, and those instructions [are here][rbenv]. For our purposes, though, we're going to stick to RVM.
I like gvim, and many others do, too. I also like [Janus](https://github.com/carlhuda/janus), a collection of plugins that
supports a bunch of different languages, including Ruby. The TLDR above will install both of these. Again, if you don't like piping curl output straight to bash, do it your saner, slower way.
Many choices of editor exist, of course. An informal straw poll shows that many Metasploit developers use
[Rubymine](https://www.jetbrains.com/ruby/), a few use [emacs](http://i.imgur.com/dljEqtL.gif), and still others use [Sublime Text](http://www.sublimetext.com/) with some helpful [plugins](https://gist.github.com/kernelsmith/5308291).
One you have a fork on GitHub, it's time to pull it down to your local dev machine. Again, you'll want to follow the [cloning] instructions at GitHub, except instead of using `https://github.com/username/repo`, you'll be using your ssh
On Kali Linux, postgresql (and any other listening service) isn't enabled by default. This is a fine security and resource precaution, but if you're expecting it there all the time, feel free to auto-start it:
Now, you have a branch that points to upstream (the `rapid7` fork) that's different from your own fork (the original `master` branch that points to `origin/master`). You might find having `upstream-master` and `master` being different branches handy (especially if you are a [Metasploit committer][metasploit-committer], since this makes it less likely to accidentally push to `rapid7/master`).
Note: Kali ships with git 1.7.10, so you might consider updating to something more recent, as there are a few missing features between then and now. Doing so involves adding a Debian ppa, though, which is frowned upon in Kali.
Also note, to speed things up on your initial fetches, you might consider using `git fetch --depth=10` or so, espeically if you don't plan on tracking older pull requests individually. If this last sentence made no sense to you, go ahead and use the `--depth` option. You're not missing anything important.
If you'd like to get easy access to upstream pull requests on your command line -- and who wouldn't -- you need to add the appropriate fetch reference to your `.git/config`. This is done easily with the following:
All this lets you check out someone else's pull request (PR), make changes, and publish to your own branch on your own fork. This will, in turn, allow you to help out on other people's PRs with fixes or additions.
You pretty much **never** want to commit to master directly. Always make changes in a branch, and then merge those changes. This makes it easy to keep in sync with upstream and never lose any local changes.
Do the same for `upstream-master`, if you have one of those branches as well. This also will work for keeping pull requests in sync with master, but unless you're running into merge conflicts, you shouldn't need to do this often. When you do end up resolving merge conflicts, you'll want to use `--force` when pushing the re-synced branch, since your commit history will be different after the rebase.
In order to lint-check any new modules you're writing, you'll want a pre-commit and a post-merge hook to run our lint-checker, `msftidy.rb`. So, symlink like so:
If you want this to be your default identity for any other git repo you use, just use the `--global` option to `git config`. Your e-mail address must match your GitHub-registered e-mail.
We love signing commits, mainly because we're [terrified of the alternative][git-horror]. The procedure is [detailed
here][signing-howto]. Note that the name and e-mail address must match the information on the signing key exactly. Contributors are encouraged to sign commits, while Metasploit committers are required to sign their merge commits when they [land pull requests][landing-prs].
As the development user, you might accidentally try to use the installed Metasploit `msfconsole`. This won't work for a variety of reasons around how RVM handles different ruby versions and gemsets. So, create this alias:
Git has its own way of handling aliases -- either in `$HOME/.gitconfig` or `repo-name/.git/config` -- seperate from regular shell aliases. Below are some of the handier ones.
That's it! It's still on you to set up your [aliases](#handy-aliases) and PGP key for [signing commits](#signing-commits) if you ever care to land pull requests, but other than that, you're good to go.
Again, if there are any errors, omissions, or better ways to do any of these things, by all means, open an [issue][issues] and we'll see about updating this HOWTO.
Thanks especially to [@kernelsmith](https://github.com/kernelsmith) and [@corelanc0d3r](https://github.com/corelanc0d3r) for their invaluable help and feedback on this dev environment documentation guide.
