Contributing to Metasploit

Like hacking things? 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. Here are some ideas to get you started.

CONTRIBUTING.md

Metasploit is a tool by and for hackers, but the hackers that maintain it also happen to be software engineers. So, we have some hopefully easy-to-remember Do's and Don'ts in CONTRIBUTING.md. Read up on those.

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

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.

• Browser Vulns 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 one of the local trees (platform dependent), but sometimes they're better off as post modules. This is especially true for privilege escalation bugs.

• Local Vulns from Exploit-DB

Unstable modules

Want to pick up where someone else left off? Super! Just check the guide on rescuing Unstable Modules and push these poor, unloved modules over the finish line with decent testing and code cleanup.

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 want to be fixed 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.

For developer types: we are slowly but surely converting all of Metasploit to use standardized commenting using YARD, so we could always use more accurate and more comprehensive YARD documentation for pretty much anything found in lib. We will happily take pull requests that contain nothing but comment docs!

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-Pull-Requests

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

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.