Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Contributing to MetasploitJump to bottom Caitlin Condon edited this page Nov 8, 2018 · 38 revisions
Every so often, we'll get a request 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, and there are so many to choose from that it's hard to get started. Here are some ideas to get you started.
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 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 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
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
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.
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).
- Feature requests, which is often in the same boat.
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.
We can 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. If you're interested in working with us on documentation long-term, that's even better; reach out on Slack for info on how best to make changes.
Ditto with YouTube screencasts of particular common tasks. Narration while you do it is great. People 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. Same goes for the Metasploit Slack team, where all sorts of new and proficient users and devs are looking for help and camaraderie.
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: [github.com]
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: [github.com]
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.
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.
- 2017 Roadmap
- 2018 Roadmap
- Adding Release Notes to PRs
- Committer Keys
- Committer Rights
- Common Metasploit Module Coding Mistakes
- Contributing to Metasploit
- Creating Metasploit Framework LoginScanners
- Debugging Dead Meterpreter Sessions
- Decommissioning Redmine
- Definition of Module Reliability, Side Effects, and Stability
- Downloads by Version
- Evading Anti Virus
- Exploit Ranking
- Generating Module Documentation
- Git cheatsheet
- Git Gotchas
- Git Reference Sites
- GSoC 2017 Mentor Organization Application
- GSoC 2017 Project Ideas
- GSoC 2017 Student Proposal
- GSoC 2018 Project Ideas
- GSoC 2018 Student Proposal
- Guidelines for Accepting Modules and Enhancements
- How payloads work
- How to add and update gems in metasploit framework
- How to check Microsoft patch levels for your exploit
- How to clean up files using FileDropper
- How to decode Base64 with Metasploit::Framework::Compiler
- How to decrypt RC4 with Metasploit::Framework::Compiler
- How to deprecate a Metasploit module
- How to do reporting or store data in module development
- How to get Oracle Support working with Kali Linux
- How to get started with writing a Meterpreter script
- How to get started with writing a post module
- How to get started with writing an auxiliary module
- How to get started with writing an exploit
- How to log in Metasploit
- How to parse an HTTP response
- How to Send an HTTP Request Using HTTPClient
- How to send an HTTP request using Rex::Proto::Http::Client
- How to use a Metasploit module appropriately
- How to use a reverse shell in Metasploit
- How to use command stagers
- How to use datastore options
- How to use exim_gethostbyname_bof.rb (Exim GHOST Buffer Overflow)
- How to use Metasploit::Framework::Compiler::Windows to compile C code
- How to use Metasploit::Framework::Obfuscation::CRandomizer
- How to use Msf::Auxiliary::AuthBrute to write a bruteforcer
- How to use msfvenom
- How to use PhpEXE to exploit an arbitrary file upload bug
- How to use Powershell in an exploit
- How to use Railgun for Windows post exploitation
- How to Use the FILEFORMAT mixin to create a file format exploit
- How to use the Msf::Exploit::Remote::Tcp mixin
- How to use the Seh mixin to exploit an exception handler
- How to use WbemExec for a write privilege attack on Windows
- How to write a browser exploit using BrowserExploitServer
- How to write a browser exploit using HttpServer
- How to write a check() method
- How to write a HTTP LoginScanner Module
- How to write a module using HttpServer and HttpClient
- How to XOR with Metasploit::Framework::Compiler
- How to zip files with Msf::Util::EXE.to_zip
- How to zip files with Rex::Zip::Archive
- Indentation Standards
- Information About Unmet Browser Exploit Requirements
- Issue Labels
- Keeping in sync with rapid7 master
- Landing Pull Requests
- Loading External Modules
- Merging Metasploit Payload Gem Updates
- Metasploit Data Service Enhancements (Goliath)
- Metasploit development environment
- Metasploit Hackathons
- Metasploit Loginpalooza
- Metasploit module reference identifiers
- Metasploit Web Service
- Meterpreter Configuration
- Meterpreter HTTP Communication
- Meterpreter Paranoid Mode
- Meterpreter Reliable Network Communication
- Meterpreter Sleep Control
- Meterpreter Stageless Mode
- Meterpreter Timeout Control
- Meterpreter Transport Control
- Meterpreter Unicode Support
- Meterpreter Wishlist
- Nightly Installers
- Oracle Usage
- Payload Rename Justification
- Payload UUID
- Powershell Extension
- Python Extension
- Remote Branch Pruning
- Reporting a Bug
- Resuscitating Dead Pull Requests
- Rex Layout
- Rolling back merges
- Setting Up a Metasploit Development Environment
- Setting Up a Metasploit Development Environment Ubuntu 14.04
- Style Tips
- The ins and outs of HTTP and HTTPS communications in Meterpreter and Metasploit Stagers
- Unstable Modules
- Using Git
- Using Metasploit
- Using ReflectiveDll Injection
- Using Rubocop
- Weekly Wrapup
- What does my Rex::Proto::SMB Error mean?
- Why is a CVE Not Available?
- Why Ruby?
- Writing External Metasploit Modules
- Writing External Python Modules
- Writing Module Documentation
- Home Welcome to Metasploit!
- Using Metasploit A collection of useful links for penetration testers.
- Setting Up a Metasploit Development Environment From
- CONTRIBUTING.md What should your contributions look like?
- Landing Pull Requests Working with other people's contributions.
- Using Git All about Git and GitHub.
- Contributing to Metasploit Be a part of our open source community.
- Meterpreter All about the Meterpreter payload.