metasploit-framework/CONTRIBUTING.md

Hello, World!

Thanks for your interest in making Metasploit -- and therefore, the world -- a better place! Before you get started, review our Code of Conduct. There are mutliple ways to help beyond just writing code:

• Submit bugs and feature requests with detailed information about your issue or idea.
• Help fellow users with open issues or [help fellow committers test recent pull requests].
• Report a security vulnerability in Metasploit itself to Rapid7.
• Submit an updated or brand new module! We are always eager for exploits, scanners, and new integrations or features. Don't know where to start? Set up a development environment, then head over to ExploitDB to look for proof-of-concept exploits that might make a good module.

Contributing to Metasploit

Here's a short list of do's and don'ts to make sure your valuable contributions actually make it into Metasploit's master branch. If you do not care to follow these rules, your contribution will be closed. Sorry!

Code Contributions

• Do stick to the Ruby style guide and use Rubocop to find common style issues.
• Do follow the 50/72 rule for Git commit messages.
• Do license your code as BSD 3-clause, BSD 2-clause, or MIT.
• Do create a topic branch to work on instead of working directly on master. This helps protect the process, ensures users are aware of commits on the branch being considered for merge, allows for a location for more commits to be offered without mingling with other contributor changes, and allows contributors to make progress while a PR is still being reviewed.

Pull Requests

• Do target your pull request to the master branch.
• Do specify a descriptive title to make searching for your pull request easier.
• Do include console output, especially for witnessable effects in msfconsole.
• Do list verification steps so your code is testable.
• Do reference associated issues in your pull request description.
• Don't leave your pull request description blank.
• Don't abandon your pull request. Being responsive helps us land your code faster.

Pull request PR#9966 is a good example to follow.

New Modules

• Do set up msftidy to fix any errors or warnings that come up as a pre-commit hook.
• Do use the many module mixin APIs.
• Don't include more than one module per pull request.
• Do include instructions on how to setup the vulnerable environment or software.
• Do include Module Documentation showing sample run-throughs.
• Don't submit new scripts. Scripts are shipped as examples for automating local tasks, and anything "serious" can be done with post modules and local exploits.

Library Code

• Do write RSpec tests - even the smallest change in a library can break existing code.
• Do follow Better Specs - it's like the style guide for specs.
• Do write YARD documentation - this makes it easier for people to use your code.
• Don't fix a lot of things in one pull request. Small fixes are easier to validate.

Bug Fixes

• Do include reproduction steps in the form of verification steps.
• Do link to any corresponding Issues in the format of See #1234 in your commit description.

Bug Reports

Please report vulnerabilities in Rapid7 software directly to security@rapid7.com. For more on our disclosure policy and Rapid7's approach to coordinated disclosure, head over here.

When reporting Metasploit issues:

• Do write a detailed description of your bug and use a descriptive title.
• Do include reproduction steps, stack traces, and anything that might help us fix your bug.
• Don't file duplicate reports; search for your bug before filing a new report.

If you need some more guidance, talk to the main body of open source contributors over on our Metasploit Slack or #metasploit on Freenode IRC.

Finally, thank you for taking the few moments to read this far! You're already way ahead of the curve, so keep it up!