Contributing to Metasploit

Want to get your feet wet? Start here.

Every so often, we'll get a request on the Metasploit Developer's mailing list, metasploit-hackers@sourceforge.net, along the lines of, "Hey, I'm new to Metasploit, and I want to help!" The usual answer is something like, "Great! Here's our framework bug tracker, get crackin!"

However, tackling core Metasploit Framework bugs or particularly squirrelly exploits probably isn't the right place for the new contributor. Believe me, everyone was a newbie once, there's no shame in that. Those bugs and vulns are usually complicated, nuanced, and there's so many to choose from, it's hard to get started.

This page will attempt to keep a set of links for straightforward, fresh vulns, and decent search terms for bugs on the Redmine bug tracker.

Server exploits

Server exploits are always in demand; why bother with complicated social engineering campaigns when you can go straight to the pain point of a vulnerable network. Here are some search queries to get you started:

• Remote exploits from Exploit-DB
• Remote exploits from OSVDB

Client Exploits

Client exploits generally run as an "evil service" that a remote client will connect to. They nearly always require some kind of user interaction to trigger, such a viewing a web page, downloading a file, or otherwise connecting to the service controlled by the attacker.

• Client Vulns from OSVDB
• [Browser Vulns](site:securityfocus.com (("Firefox" OR "Internet Explorer" OR "Chrome" OR "Safari" OR "Opera") -"Retired")) from SecurityFocus via Google search terms

Local and Privilege Escalation Exploits

Privilege escalation exploits tend to require the attacker already have an account on a target computer. They are nearly always going to be implemented as Metasploit exploit modules under the local tree.

• Local Vulns from Exploit-DB
• Local VUlns from OSVDB

Framework bugs and features

If exploit dev isn't your thing, but more straightforward Ruby development is, then here are some good places to get started:

• Recent Bugs, which tend to be either very easy or very hard to fix (not a lot of middle ground).
• Somewhat recent feature requests, which is often in the same boat.
• Next version bugs, which are targeted specifically for turnaround before the next version of Metasploit.

Along these same lines is a perennial need for better automated testing, down in the spec directory. If you have a talent for exploring strange and wonderful code bases, pick out a chunk of the Metasploit core code and define out what you expect for working behavior. This search is an ideal place to start; describe the bug as a pending Rspec test, reference the bug, and then we'll have a test that works once it gets fixed.

Non-code

Hey, we could always use better documentation. Those guys over at Offensive Security do a great job with Metasploit Unleashed, but as with all complex bodies of work, there are surely bugs to be found. If you have ideas on how to make the documentation on Metasploit clear and more accessible to more people, go nuts.

Write wiki articles in your fork (hint, Gollum is excellent for this) and let someone know about them, we'll be happy to reflect them here and maintain your credit.

Ditto with YouTube screencasts of particular common tasks. Narration while you do it is great, please seem to love YouTube videos of this stuff -- there are over 40,000 of the things out there, and we'd love for someone to step up and curate a top 10 or top 100 of those that we can promote here for new and experienced users.

Again, there's always room on #metasploit on Freenode. Be helpful with the questions there, and people are more likely to help you in the future.

The Usual Warnings

You probably shouldn't run proof of concept exploit code you find on the Internet on a machine you care about in a network you care about. That is generally considered a Bad Idea. You also probably shouldn't use your usual computer as a target for exploit development, since you are intentionally inducing unstable behavior.

Our preferred method of module submission is via a git pull request from a feature branch on your own fork of Metasploit. You can learn how to create one here: https://github.com/rapid7/metasploit-framework/wiki/Landing-a-Pull-Request

Also, please take a peek at our guides on using git and our acceptance guidelines for new modules in case you're not familiar with them: https://github.com/rapid7/metasploit-framework/wiki

We also have a pair of guideline text files that you should be familiar with in order to avoid the most common mistakes. They are CONTRIBUTING.md and HACKING.

If you get stuck, try to explain your specific problem as best you can on our Freenode IRC channel, #metasploit (joining requires a registered nick). Someone should be able to lend a hand. Apparently, some of those people never sleep. Alternatively, we have the metasploit-hackers mailing list if that's more your speed.

Thank you

In case nobody's said it yet: Thanks for your interest and support! Exploit developers from the open source community are the soul of Metasploit, and by contributing your time and talent, you are helping advance the state of the art for intelligent IT defense. We simply couldn't do all of this without you.