|
1 | | -# $Id$ |
| 1 | +HACKING |
| 2 | +======= |
2 | 3 |
|
3 | | -This file contains some brief instructions on contributing to the |
4 | | -Metasploit Framework. |
| 4 | +(Last updated: 2014-03-04) |
5 | 5 |
|
6 | | -Code Style |
7 | | -========== |
| 6 | +This document almost entirely deprecated by: |
8 | 7 |
|
9 | | -In order to maintain consistency and readability, we ask that you |
10 | | -adhere to the following style guidelines: |
| 8 | +CONTRIBUTING.md |
11 | 9 |
|
12 | | - - Standard Ruby two-space soft tabs, not hard tabs. |
13 | | - - Try to keep your lines under 100 columns (assuming two-space tabs) |
14 | | - - do; end instead of {} for a block |
15 | | - - Always use str[0,1] instead of str[0] |
16 | | - (This avoids a known ruby 1.8/1.9 incompatibility.) |
17 | | - - Method names should always be lower_case and words separated by "_" |
18 | | - - Variable names should be lower case with words separated by "_" |
19 | | - - Don't depend on any external gems or libraries without talking to |
20 | | - todb to resolve packaging and licensing issues |
| 10 | +in the same directory as this file, and to a lesser extent: |
21 | 11 |
|
22 | | -You can use the the "./tools/msftidy.rb" script to do some rudimentary |
23 | | -checking for various violations. |
24 | | - |
25 | | - |
26 | | -Code No-Nos |
27 | | -=========== |
28 | | - |
29 | | -1. Don't print to standard output. Doing so means that users of |
30 | | -interfaces other than msfconsole, such as msfrpc and msfgui, won't see |
31 | | -your output. You can use print_line to accomplish the same thing as |
32 | | -puts. |
33 | | - |
34 | | -2. Don't read from standard input, doing so will make your code |
35 | | -lock up the entire module when called from other interfaces. If you |
36 | | -need user input, you can either register an option or expose an |
37 | | -interactive session type specific for the type of exploit. |
38 | | - |
39 | | -3. Always use Rex sockets, not ruby sockets. This includes |
40 | | -third-party libraries such as Net::Http. There are several very good |
41 | | -reasons for this rule. First, the framework doesn't get notified on |
42 | | -the creation of ruby sockets and won't know how to clean them up in |
43 | | -case your module raises an exception without cleaning up after itself. |
44 | | -Secondly, non-Rex sockets do not know about routes and therefore can't |
45 | | -be used through a meterpreter tunnel. Lastly, regular sockets miss |
46 | | -out on msf's proxy and SSL features. Msf includes many protocols |
47 | | -already implemented with Rex and if the protocol you need is missing, |
48 | | -porting another library to use them is straight-forward. See our |
49 | | -Net::SSH modifications in lib/net/ssh/ for an example. |
50 | | - |
51 | | -4. When opening an IO stream, always force binary with "b" mode (or |
52 | | -using IO#binmode). This not only helps keep Windows and non-Windows |
53 | | -runtime environments consistent with each other, but also guarantees |
54 | | -that files will be treated as ASCII-8BIT instead of UTF-8. |
55 | | - |
56 | | -5. Don't use String#[] for a single character. This returns a Fixnum in |
57 | | -ruby 1.8 and a String in 1.9, so it's safer to use the following idiom: |
58 | | - str[idx,1] |
59 | | -which always returns a String. If you need the ASCII byte, unpack it like |
60 | | -so: |
61 | | - tr[idx,1].unpack("C")[0] |
62 | | - |
63 | | -6. Whenever possible, avoid using '+' or '+=' to concatenate strings. |
64 | | -The '<<' operator is significantly faster. The difference will become |
65 | | -even more apparent when doing string manipulation in a loop. The |
66 | | -following table approximates the underlying implementation: |
67 | | - |
68 | | - Ruby Pseudo-C |
69 | | - ----------- ---------------- |
70 | | - a = b + c a = malloc(b.len+c.len+1); |
71 | | - strcpy(a, b); |
72 | | - memcpy(a+b.len, c, c.len); |
73 | | - a[b.len + c.len] = '\0'; |
74 | | - a = b a = b; |
75 | | - a << c a = realloc(a, a.len+c.len+1); |
76 | | - memcpy(a+a.len, c, c.len); |
77 | | - a[a.len + c.len] = '\0'; |
78 | | - |
79 | | -Note that the original value of 'b' is lost in the second case. Care |
80 | | -must be taken to duplicate strings that you do not want to modify. |
81 | | - |
82 | | -7. For other Ruby 1.8.x/1.9.x compat issues, please see Sam Ruby's |
83 | | -excellent slide show at <http://slideshow.rubyforge.org/ruby19.html> |
84 | | -for an overview of common and not-so-common Ruby version related gotchas. |
85 | | - |
86 | | -8. Never, ever use $global variables. This applies to modules, mixins, |
87 | | -and libraries. If you need a "global" within a specific class, you can |
88 | | -use @@class_variables, but most modules should use @instance variables |
89 | | -to store information between methods. |
90 | | - |
91 | | -9. Don't craft your XML document raw or by using Nokogiri, the current |
92 | | -preferred way is REXML. |
93 | | - |
94 | | -Creating New Modules |
95 | | -==================== |
96 | | - |
97 | | -When creating a new module, the simplest way to start is to copy |
98 | | -another module that uses the same protocol and modify it to your |
99 | | -needs. If you're creating an exploit module, generally you'll want |
100 | | -to edit the exploit() method. Auxiliary Scanner modules use one of |
101 | | -run_host(), run_range(), or run_batch() instead of exploit(). |
102 | | -Non-scanner aux modules use run(). |
103 | | - |
104 | | - |
105 | | -Submitting Your Code |
106 | | -==================== |
107 | | - |
108 | | -To get started with a Metasploit Framework source clone, simply: |
109 | | - |
110 | | - - Fork rapid7/metasploit-framework to your GitHub account |
111 | | - - git clone git://github.com/YourName/metasploit-framework.git |
112 | | - - gem install bundler |
113 | | - - bundle install |
| 12 | +The Metasploit Development Environment |
| 13 | +https://github.com/rapid7/metasploit-framework/wiki/Metasploit-Development-Environment |
114 | 14 |
|
115 | | -More detailed documentation regarding the process for submitting new |
116 | | -modules via GitHub is documented here: |
| 15 | +Common Coding Mistakes |
| 16 | +https://github.com/rapid7/metasploit-framework/wiki/Common-Metasploit-Module-Coding-Mistakes |
117 | 17 |
|
118 | | -https://github.com/rapid7/metasploit-framework/wiki/Metasploit-Development-Environment |
| 18 | +The Ruby Style Guide |
| 19 | +https://github.com/bbatsov/ruby-style-guide |
119 | 20 |
|
120 | | -This describes the process of forking, editing, and generating a |
121 | | -pull request, and is the preferred method for bringing new modules |
122 | | -and framework enhancements to the attention of the core Metasploit |
123 | | -development team. Note that this process requires a GitHub account. |
| 21 | +Ruby 1.9: What to Expect |
| 22 | +http://slideshow.rubyforge.org/ruby19.html |
124 | 23 |
|
125 | | -For Git commits, please adhere to 50/72 formatting: your commits should |
126 | | -start with a line 50 characters or less, followed by a blank line, |
127 | | -followed by one or more lines of explanatory text wrapped at at 72 |
128 | | -characters Pull requests with commits not formatted this way will |
129 | | -be rejected without review. |
| 24 | +You can use the the "./tools/msftidy.rb" script against your new and |
| 25 | +changed modules to do some rudimentary checking for various style and |
| 26 | +syntax violations. |
130 | 27 |
|
131 | | -For modules, note that Author field is not automatic, and should be |
132 | | -filled in in the format of 'Your Name <user[at]domain.tld>' so future |
133 | | -developers can contact you with any questions. |
| 28 | +Licensing for Your New Content |
| 29 | +============================== |
134 | 30 |
|
135 | | -Licensing |
136 | | -========= |
137 | 31 | By submitting code contributions to the Metasploit Project it is |
138 | 32 | assumed that you are offering your code under the Metasploit License |
139 | | -or similar 3-clause BSD-compatible license. MIT and Ruby Licenses |
| 33 | +or similar 3-clause BSD-compatible license. MIT and Ruby Licenses |
140 | 34 | are also fine. We specifically cannot include GPL code. LGPL code |
141 | | -is accepted on a case by case basis for libraries only and is never |
| 35 | +is accepted on a case by case basis for libraries only and is never |
142 | 36 | accepted for modules. |
143 | 37 |
|
144 | | -When possible, such as aux and exploit modules, be sure to include |
145 | | -your license designation in the file in the appropriate place. |
146 | 38 |
|
0 commit comments