docs/metasploit-framework.wiki/Reporting-a-Bug.md
Metasploit gets hundreds of issue reports every year on our issue tracker. Some issues aren't bug reports at all, but instead requests for new features or questions about Metasploit usage. We appreciate feature or enhancement requests, and you should feel free to keep submitting those to our issue tracker. Some questions, such as whether an odd error or behavior is intended, are okay to submit to the issue tracker as well. Other questions, such as basic support requests or questions on beginning Framework usage, are better to ask the community on Slack. If you believe you have discovered a legitimate bug in Metasploit Framework, you should open a bug report on our issue tracker. The rest of this page will discuss how to submit detailed, useful bug reports so we can understand and triage your issue as quickly as possible.
But first...two important exceptions to bug/issue reports.
NOTE: There are two situations where, even if you have found what you know is a bug, you should not open a bug report on our public issue tracker.
If you are a Metasploit Pro customer, you can log in to Rapid7's customer support portal here. You are also able to reach out to your CSM or support representative if you prefer. To provide a consistent customer experience, Metasploit Framework community members, committers, and open-source developers do not offer support for commercial Rapid7 products. Rapid7's support resources and team members are well-equipped to handle your Metasploit Pro support needs!
If you have a security issue with Metasploit itself, you should email [email protected] or let us know here. Rapid7's disclosure policy is here. In general, our security teams are happy to give you credit, inform you about progress, and explore related issues with you if you'd like. They're also happy to keep you anonymous if that's what you prefer. All of this is significantly easier if you report security issues in a manner that lets our teams quickly work with you to understand the problem! Clear communication and coordinated disclosure give us the best chance of fixing any security issues quickly and protecting users.
Now on to the good stuff! The Metasploit development community has read thousands of bug reports over the past 15 years, and a well-written bug report makes fixing bugs much faster and easier. In fact, in our experience, how quickly we can understand and fix an issue has more to do with bug report quality than the complexity of the bug itself.
We ask for several different pieces of information when users report issues in Metasploit. As of June 2020, our core engineering team in Belfast is developing a debug command that will automatically give you all the information we require when you encounter an issue and then run the command in msfconsole. For now, the following information ensures that we can more effectively triage and address bugs. If you do not provide this information, it is likely that response time will be significantly longer!
What did you do to get the results you got? Can you give us step-by-step instructions to get the same results you got? Are you able to consistently reproduce the issue in your own environment?
Tell us which operating system you're using and any relevant information about your setup. If the module or feature you're having trouble with requires any external dependencies, check whether they are installed, and (if not) whether installing them could solve your problem.
If you're having problems with a target (victim), tell us the target operating system and service versions.(Please ensure you've redacted any private or sensitive data!) If the module or feature you're having trouble with requires any external dependencies, check whether that could solve your problem.
If you're testing a module in a lab or virtual environment, we would appreciate as much data about the target as you can provide. This means exact versions of the target including patch levels, pcaps if you can capture them, and any kind of logging inside or outside of Framework. We will often ask for the framework.log.
What should happen? If what you're trying to do used to work but no longer does, what was the behavior you encountered before you ran into a problem?
What happens now? Please give us as many technical details as possible. Once again, we also strongly recommend that you send us any relevant logs and/or stack traces. In case you haven't noticed by now, we absolutely love logs and screen captures, and your including them will make us happy.
Get this with the version command in msfconsole (or git log -1 --pretty=oneline for a source install).
Did you install Metasploit with...
This list isn't intended to be exhaustive - it's simply the bare minimum set of details we need to reproduce and diagnose your bug. You should feel free to include as much detailed information as you need to help us understand how you got the results you did.
You may not be the first person to notice the problem you're seeing as a Framework user, and the more bug reports we get, the more difficult it is to sort through them all for easy fixes or high-priority issues. Here are some ways to help a previously-reported bug get noticed more quickly and prioritized (if necessary).
If you're a superhero and you figured out the root cause of a bug AND found a way to fix it, you can send your Metasploit fixes and improvements our way! The best way to get your fix into Metasploit quickly is to patch your own fork and submit a pull request to Metasploit. You get extra gratitude from all of us when you do this, and you'll also get a shout-out in the weekly Metasploit wrap-up.
You can find a guide on setting up your own [[Metasploit Development Environment here|./dev/Setting-Up-a-Metasploit-Development-Environment.md]].
Some projects and companies don't like discussing bugs in the bug report itself. Some even have policies of not doing this. Metasploit is not one of those projects. We greatly prefer public communication over private communication because it makes community knowledge accessible and searchable to everyone. That said, if you have specific privacy or security concerns, we're always happy to speak privately. You can get in touch with us at [email protected].
Your bug should be considered "Resolved" once there's a fix landed in the Metasploit-Framework master branch. People who track that branch will have the fix available quickly. It may take other distributions that include Metasploit (e.g., Kali) a few days to pull in fixes, depending on their individual release cadences.
Thanks for helping us get to diagnoses and resolutions quickly and efficiently for all Framework users!