This is a guide for setting up a developer environment to contribute modules, documentation, and fixes to the Metasploit Framework. If you just want to use Metasploit for legal, authorized hacking, we recommend instead you:
3. If you encounter a "permission denied" error on the above command, research the error message. If there isn't an explicit reason given, confirm that your [Github SSH key is configured correctly][github-ssh-instructions].
4. To receive updates, you will create an `upstream-master` branch to track the Rapid7 remote repository, alongside your `master` branch which will point to your personal repository's fork:
5. Configure your Github username, email address, and username. Ensure your `user.email` matches the email address you registered with your Github account.
Linux distributions do not ship with the latest Ruby, nor are package managers routinely updated. Additionally, if you are working with multiple Ruby projects, each one has dependencies and Ruby versions which can start to conflict. For these reasons, it is advisable to use a Ruby manager.
You could just install Ruby directly (eg. `sudo apt install ruby-dev`), but you may likely end up with the incorrect version and no way to update. Instead, consider using one of the many different [Ruby environment managers] available. The Metasploit team prefers [rbenv] and [rvm] (note that [rvm] does require a re-login to complete).
Regardless of your choice, you'll want to make sure that, when inside the `~/git/metasploit-framework` directory, you are running the correct version of Ruby:
Note: the Ruby version is likely to change over time, so don't rely on the output in the above example. Instead, confirm your `ruby -v` output with the version number listed in the `.ruby-version` file.
If the two versions don't match, restart your terminal. If that does not work, consult the troubleshooting documentation for your Ruby environment manager. Unfortunately, troubleshooting the Ruby environment is beyond the scope of this document, but feel free to reach out for community support using the links at the bottom of this document.
If you encounter an error with the above command, refer to the `bundle` output and search for the error message along with the name of the gem that failed. Likely, you'll need to `apt get install` a dependency that is required by that particular gem.
Congratulations! You have now set up a development environment and the latest version of the Metasploit Framework. If you followed this guide step-by-step, and you ran into any problems, it would be super great if you could open a [new issue] so we can either help you, or, more likely, update the docs.
<details><summary>The following optional section describes how to manually install PostgreSQL and set up the Metasploit database. Alternatively, use our Omnibus installer which handles this more reliably. Click to expand.</summary>
4. If you receive an error about a component not being installed, confirm that the binaries shown are in your path using the [which] and [find] commands, then modifying your [$PATH] environment variable. If it was something else, open a [new issue] to let us know what happened.
- Consider generating a GPG key to sign your commits. Read about [why][git-horror] and [how][signing-howto]. Once you have done this, consider enabling automatic signing of all your commits with the following command:
We're excited to see your upcoming contributions of new modules, documentation, and fixes! Check out our [wiki documentation][wiki-documentation] and, if you're looking for inspiration, keep an eye out for [newbie-friendly pull requests and issues][newbie-friendly-prs-issues]. Please [submit your new pull requests][howto-PR] and reach out to us on [Slack] for community help.
Finally, we welcome your feedback on this guide, so feel free to reach out to us on [Slack] or open a [new issue]. For their significant contributions to this guide, we would like to thank [@kernelsmith], [@corelanc0d3r], and [@ffmike].
