2014-04-18 23:01:54 +08:00
|
|
|
# Hello, World!
|
2012-11-07 10:18:58 +08:00
|
|
|
|
2015-03-31 01:04:15 +08:00
|
|
|
Thanks for your interest in making Metasploit -- and therefore, the
|
|
|
|
|
world -- a better place!
|
2014-04-18 23:01:54 +08:00
|
|
|
|
2015-03-31 01:04:15 +08:00
|
|
|
Are you about to report a bug? Sorry to hear it. Here's our [Issue tracker].
|
2015-03-29 09:11:05 +08:00
|
|
|
Please try to be as specific as you can about your problem; include steps
|
|
|
|
|
to reproduce (cut and paste from your console output if it's helpful) and
|
2014-09-11 04:21:47 +08:00
|
|
|
what you were expecting to happen.
|
|
|
|
|
|
|
|
|
|
Are you about to report a security vulnerability in Metasploit itself?
|
2014-09-11 07:26:09 +08:00
|
|
|
How ironic! Please take a look at Rapid7's [Vulnerability
|
2014-09-11 04:21:47 +08:00
|
|
|
Disclosure Policy](https://www.rapid7.com/disclosure.jsp), and send
|
2015-01-31 04:28:39 +08:00
|
|
|
your report to security@rapid7.com using our [PGP key].
|
2014-04-18 23:01:54 +08:00
|
|
|
|
|
|
|
|
Are you about to contribute some new functionality, a bug fix, or a new
|
|
|
|
|
Metasploit module? If so, read on...
|
|
|
|
|
|
|
|
|
|
# Contributing to Metasploit
|
|
|
|
|
|
2015-03-29 09:11:05 +08:00
|
|
|
What you see here in CONTRIBUTING.md is a bullet point list of the do's
|
2014-04-18 23:01:54 +08:00
|
|
|
and don'ts of how to make sure *your* valuable contributions actually
|
|
|
|
|
make it into Metasploit's master branch.
|
2014-02-25 01:57:38 +08:00
|
|
|
|
2014-03-04 04:39:40 +08:00
|
|
|
If you care not to follow these rules, your contribution **will** be
|
2015-01-31 05:09:47 +08:00
|
|
|
closed. Sorry!
|
2014-02-25 01:57:38 +08:00
|
|
|
|
2015-01-31 04:28:39 +08:00
|
|
|
This is intended to be a **short** list. The [wiki] is much more
|
2014-03-05 04:06:34 +08:00
|
|
|
exhaustive and reveals many mysteries. If you read nothing else, take a
|
2015-03-29 09:11:05 +08:00
|
|
|
look at the standard [development environment setup] guide
|
2015-01-31 04:28:39 +08:00
|
|
|
and Metasploit's [Common Coding Mistakes].
|
2014-02-25 01:57:38 +08:00
|
|
|
|
|
|
|
|
## Code Contributions
|
|
|
|
|
|
2015-01-31 04:28:39 +08:00
|
|
|
* **Do** stick to the [Ruby style guide].
|
|
|
|
|
* **Do** get [Rubocop] relatively quiet against the code you are adding or modifying.
|
|
|
|
|
* **Do** follow the [50/72 rule] for Git commit messages.
|
|
|
|
|
* **Don't** use the default merge messages when merging from other branches.
|
2016-02-23 06:29:13 +08:00
|
|
|
* **Do** license your code as BSD 3-clause, BSD 2-clause, or MIT.
|
2018-05-09 06:54:14 +08:00
|
|
|
* **Do** create a [topic branch] to work on instead of working directly on `master`.
|
|
|
|
|
If you do not send a PR from a topic branch, the history of your PR will be
|
|
|
|
|
lost as soon as you update your own master branch. See
|
|
|
|
|
https://github.com/rapid7/metasploit-framework/pull/8000 for an example of
|
|
|
|
|
this in action.
|
|
|
|
|
|
2014-02-25 01:57:38 +08:00
|
|
|
|
|
|
|
|
### Pull Requests
|
|
|
|
|
|
2014-04-06 11:21:44 +08:00
|
|
|
* **Do** target your pull request to the **master branch**. Not staging, not develop, not release.
|
2014-03-05 02:44:12 +08:00
|
|
|
* **Do** specify a descriptive title to make searching for your pull request easier.
|
2015-01-31 04:28:39 +08:00
|
|
|
* **Do** include [console output], especially for witnessable effects in `msfconsole`.
|
|
|
|
|
* **Do** list [verification steps] so your code is testable.
|
2018-01-16 11:32:44 +08:00
|
|
|
* **Do** [reference associated issues] in your pull request description.
|
|
|
|
|
* **Do** write [release notes] once a pull request is landed.
|
2014-03-04 04:39:40 +08:00
|
|
|
* **Don't** leave your pull request description blank.
|
|
|
|
|
* **Don't** abandon your pull request. Being responsive helps us land your code faster.
|
2014-02-25 01:57:38 +08:00
|
|
|
|
2015-01-31 04:28:39 +08:00
|
|
|
Pull requests [PR#2940] and [PR#3043] are a couple good examples to follow.
|
2014-03-04 16:38:47 +08:00
|
|
|
|
2014-02-25 01:57:38 +08:00
|
|
|
#### New Modules
|
|
|
|
|
|
2016-01-22 03:30:55 +08:00
|
|
|
* **Do** run `tools/dev/msftidy.rb` against your module and fix any errors or warnings that come up.
|
2015-03-29 09:11:05 +08:00
|
|
|
- It would be even better to set up `msftidy.rb` as a [pre-commit hook].
|
2015-03-31 01:04:15 +08:00
|
|
|
* **Do** use the many module mixin [API]s. Wheel improvements are welcome; wheel reinventions, not so much.
|
2014-03-04 04:39:40 +08:00
|
|
|
* **Don't** include more than one module per pull request.
|
2018-01-16 11:32:44 +08:00
|
|
|
* **Do** include instructions on how to setup the vulnerable environment or software.
|
|
|
|
|
* **Do** include [Module Documentation](https://github.com/rapid7/metasploit-framework/wiki/Generating-Module-Documentation) showing sample run-throughs.
|
2016-06-10 04:23:32 +08:00
|
|
|
|
|
|
|
|
|
2014-02-25 01:57:38 +08:00
|
|
|
|
2015-01-31 04:28:39 +08:00
|
|
|
#### Scripts
|
|
|
|
|
|
|
|
|
|
* **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.
|
|
|
|
|
|
2014-02-25 01:57:38 +08:00
|
|
|
#### Library Code
|
|
|
|
|
|
2015-01-31 04:28:39 +08:00
|
|
|
* **Do** write [RSpec] tests - even the smallest change in library land can thoroughly screw things up.
|
|
|
|
|
* **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.
|
2014-04-06 11:21:44 +08:00
|
|
|
* **Don't** fix a lot of things in one pull request. Small fixes are easier to validate.
|
2014-02-25 01:57:38 +08:00
|
|
|
|
|
|
|
|
#### Bug Fixes
|
|
|
|
|
|
2014-03-04 04:39:40 +08:00
|
|
|
* **Do** include reproduction steps in the form of verification steps.
|
2015-01-31 04:28:39 +08:00
|
|
|
* **Do** include a link to any corresponding [Issues] in the format of
|
|
|
|
|
`See #1234` in your commit description.
|
2014-02-25 01:57:38 +08:00
|
|
|
|
|
|
|
|
## Bug Reports
|
|
|
|
|
|
2014-04-18 23:01:54 +08:00
|
|
|
* **Do** report vulnerabilities in Rapid7 software directly to security@rapid7.com.
|
2014-03-05 03:16:55 +08:00
|
|
|
* **Do** write a detailed description of your bug and use a descriptive title.
|
2014-03-04 04:39:40 +08:00
|
|
|
* **Do** include reproduction steps, stack traces, and anything else that might help us verify and fix your bug.
|
2015-03-29 09:11:05 +08:00
|
|
|
* **Don't** file duplicate reports; search for your bug before filing a new report.
|
2014-03-05 02:19:34 +08:00
|
|
|
|
2014-03-04 04:39:40 +08:00
|
|
|
If you need some more guidance, talk to the main body of open
|
2015-03-29 09:11:05 +08:00
|
|
|
source contributors over on the [Freenode IRC channel],
|
|
|
|
|
or e-mail us at the [metasploit-hackers] mailing list.
|
2014-02-25 01:57:38 +08:00
|
|
|
|
2014-03-04 04:39:40 +08:00
|
|
|
Also, **thank you** for taking the few moments to read this far! You're
|
|
|
|
|
already way ahead of the curve, so keep it up!
|
2015-01-31 04:28:39 +08:00
|
|
|
|
|
|
|
|
[Issue Tracker]:http://r-7.co/MSF-BUGv1
|
|
|
|
|
[PGP key]:http://pgp.mit.edu:11371/pks/lookup?op=vindex&search=0x2380F85B8AD4DB8D
|
|
|
|
|
[wiki]:https://github.com/rapid7/metasploit-framework/wiki
|
2015-03-29 09:11:05 +08:00
|
|
|
[scripts]:https://github.com/rapid7/metasploit-framework/tree/master/scripts
|
2015-01-31 04:28:39 +08:00
|
|
|
[development environment setup]:http://r-7.co/MSF-DEV
|
|
|
|
|
[Common Coding Mistakes]:https://github.com/rapid7/metasploit-framework/wiki/Common-Metasploit-Module-Coding-Mistakes
|
|
|
|
|
[Ruby style guide]:https://github.com/bbatsov/ruby-style-guide
|
|
|
|
|
[Rubocop]:https://rubygems.org/search?query=rubocop
|
2015-11-10 03:13:45 +08:00
|
|
|
[50/72 rule]:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
|
2015-01-31 04:28:39 +08:00
|
|
|
[topic branch]:http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches
|
|
|
|
|
[console output]:https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks
|
|
|
|
|
[verification steps]:https://help.github.com/articles/writing-on-github#task-lists
|
2016-07-01 04:14:59 +08:00
|
|
|
[reference associated issues]:https://github.com/blog/1506-closing-issues-via-pull-requests
|
2016-08-23 04:15:00 +08:00
|
|
|
[release notes]:https://github.com/rapid7/metasploit-framework/wiki/Adding-Release-Notes-to-PRs
|
2015-01-31 04:28:39 +08:00
|
|
|
[PR#2940]:https://github.com/rapid7/metasploit-framework/pull/2940
|
|
|
|
|
[PR#3043]:https://github.com/rapid7/metasploit-framework/pull/3043
|
|
|
|
|
[pre-commit hook]:https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/pre-commit-hook.rb
|
2015-03-29 09:11:05 +08:00
|
|
|
[API]:https://rapid7.github.io/metasploit-framework/api
|
|
|
|
|
[RSpec]:http://rspec.info
|
|
|
|
|
[Better Specs]:http://betterspecs.org
|
|
|
|
|
[YARD]:http://yardoc.org
|
2015-01-31 04:28:39 +08:00
|
|
|
[Issues]:https://github.com/rapid7/metasploit-framework/issues
|
|
|
|
|
[Freenode IRC channel]:http://webchat.freenode.net/?channels=%23metasploit&uio=d4
|
2017-08-21 02:23:54 +08:00
|
|
|
[metasploit-hackers]:https://groups.google.com/forum/#!forum/metasploit-hackers
|
