Skip to content
This repository
Newer
Older
100644 136 lines (108 sloc) 5.719 kb
f3359c34 » jduck
2010-06-16 adjust a couple $Id: outliers
1 # $Id$
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
2
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
3 This file contains some brief instructions on contributing to the
4 Metasploit Framework.
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
5
6 Code Style
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
7 ==========
8
e20b4705 » jlee-r7
2010-08-14 typo fixes, thanks enaqx
9 In order to maintain consistency and readability, we ask that you
10 adhere to the following style guidelines:
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
11
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
12 - Hard tabs, not spaces
13 - Try to keep your lines under 100 columns (assuming four-space tabs)
14 - do; end instead of {} for a block
9c95c0ac » jduck
2010-08-23 add note about string indexing
15 - Always use str[0,1] instead of str[0]
b50ecdad » Jonathan Cran
2011-07-30 minor tweaks to the HACKING file, primarily updating to the current r…
16 (This avoids a known ruby 1.8/1.9 incompatibility.)
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
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
9bbb1041 » todb-r7
2011-10-12 Adding minor edits to HACKING: License language, updating contact inf…
20 todb to resolve packaging and licensing issues
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
21
688d66f9 » jduck
2010-12-03 add a sentence about msftidy.rb
22 You can use the the "./tools/msftidy.rb" script to do some rudimentary
23 checking for various violations.
24
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
25
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
26 Code No-Nos
27 ===========
28
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
29 1. Don't print to standard output. Doing so means that users of
a0dac2db » scriptjunkie
2011-03-06 Because msfweb doesn't really exist anymore.
30 interfaces other than msfconsole, such as msfrpc and msfgui, won't see
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
31 your output. You can use print_line to accomplish the same thing as
32 puts.
33
5afdc234 » rootman
2012-06-18 corrected a typo, "from from" to "from"
34 2. Don't read from standard input, doing so will make your code
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
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 interactve session type specific for the type of exploit.
38
39 3. Don't use "sleep". It has been known to cause issues with
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
40 multi-threaded programs on various platforms. Instead, we use
41 "select(nil, nil, nil, <time>)" throughout the framework. We have
42 found this works around the underlying issue.
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
43
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
44 4. Always use Rex sockets, not ruby sockets. This includes
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
45 third-party libraries such as Net::Http. There are several very good
46 reasons for this rule. First, the framework doesn't get notified on
47 the creation of ruby sockets and won't know how to clean them up in
48 case your module raises an exception without cleaning up after itself.
49 Secondly, non-Rex sockets do not know about routes and therefore can't
50 be used through a meterpreter tunnel. Lastly, regular sockets miss
51 out on msf's proxy and ssl features. Msf includes many protocols
52 already implemented with Rex and if the protocol you need is missing,
53 porting another library to use them is straight-forward. See our
54 Net::SSH modifications in lib/net/ssh/ for an example.
55
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
56 5. When opening an IO stream, always force binary with "b" mode (or
f2423b06 » todb-r7
2010-06-23 Add note about binmode
57 using IO#binmode). This not only helps keep Windows and non-Windows
58 runtime environments consistent with each other, but also guarantees
59 that files will be treated as ASCII-8BIT instead of UTF-8.
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
60
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
61 6. Don't use String#[] for a single character. This returns a Fixnum in
1b8c84d4 » jlee-r7
2010-06-25 mention the String#[] differences in 1.8 and 1.9, show example workar…
62 ruby 1.8 and a String in 1.9, so it's safer to use the following idiom:
63 str[idx,1]
64 which always returns a String. If you need the ASCII byte, unpack it like
65 so:
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
66 str[idx,1].unpack("C")[0]
1b8c84d4 » jlee-r7
2010-06-25 mention the String#[] differences in 1.8 and 1.9, show example workar…
67
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
68 7. Whenever possible, avoid using '+' or '+=' to concatenate strings.
5d4d225a » jduck
2010-07-09 add blurb about += vs <<
69 The '<<' operator is significantly faster. The difference will become
70 even more apparent when doing string manipulation in a loop. The
71 following table approximates the underlying implementation:
72 Ruby Pseudo-C
73 ----------- ----------------
74 a = b + c a = malloc(b.len+c.len+1);
75 strcpy(a, b);
76 memcpy(a+b.len, c, c.len);
77 a[b.len + c.len] = '\0';
78 a = b a = b;
79 a << c a = realloc(a, a.len+c.len+1);
80 memcpy(a+a.len, c, c.len);
81 a[a.len + c.len] = '\0';
82 Note that the original value of 'b' is lost in the second case. Care
83 must be taken to duplicate strings that you do not want to modify.
84
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
85 8. For other Ruby 1.8.x/1.9.x compat issues, please see Sam Ruby's
58ba9c79 » todb-r7
2011-03-02 Adding a pointer to Sam Ruby's slideshow on Ruby 1.8/1.9 changes to H…
86 excellent slide show at <http://slideshow.rubyforge.org/ruby19.html>
87 for an overview of common and not-so-common Ruby version related gotchas.
1b8c84d4 » jlee-r7
2010-06-25 mention the String#[] differences in 1.8 and 1.9, show example workar…
88
cbce0e2c » hmoore-r7
2011-04-25 Update hacking with some other gotchas
89 9. Never, ever use $global variables. This applies to modules, mixins,
90 and libraries. If you need a "global" within a specific class, you can
91 use @@class_variables, but most modules should use @instance variables
92 to store information between methods.
93
94 10. Do not define CONSTANTS within individual modules. This can lead to
95 warning messages when the module is reloaded. Try to keep constants
96 inside libraries and mixins instead.
97
98
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
99 Creating New Modules
100 ====================
101
102 When creating a new module, the simplest way to start is to copy
103 another module that uses the same protocol and modify it to your
104 needs. If you're creating an exploit module, generally you'll want
105 to edit the exploit() method. Auxiliary Scanner modules use one of
106 run_host(), run_range(), or run_batch() instead of exploit().
107 Non-scanner aux modules use run().
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
108
109
30caf824 » jlee-r7
2010-11-30 add a section about submitting patches
110 Submitting Your Code
111 ====================
112
e75d1cad » todb
2011-11-10 Updating HACKING to point developers to GitHub
113 The process for submitting new modules via GitHub is documented here:
9bbb1041 » todb-r7
2011-10-12 Adding minor edits to HACKING: License language, updating contact inf…
114
0be83dae » todb
2012-05-21 Replaces a dead link in HACKING
115 https://github.com/rapid7/metasploit-framework/wiki/Metasploit-Development-Environment
e75d1cad » todb
2011-11-10 Updating HACKING to point developers to GitHub
116
117 This describes the process of forking, editing, and generating a
118 pull request, and is the preferred method for bringing new modules
119 and framework enhancements to the attention of the core Metasploit
120 development team. Note that this process requires a GitHub account.
121
122 For modules, note that Author field is not automatic, and should be
123 filled in in the format of 'Your Name <user[at]domain.tld>' so future
124 developers can contact you with any questions.
30caf824 » jlee-r7
2010-11-30 add a section about submitting patches
125
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
126 Licensing
127 =========
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
128 By submitting code contributions to the Metasploit Project it is
9bbb1041 » todb-r7
2011-10-12 Adding minor edits to HACKING: License language, updating contact inf…
129 assumed that you are offering your code under the Metasploit License
130 or similar 3-clause BSD-compatible license. MIT and Ruby Licenses
131 are also fine. We specifically cannot include GPL code. LGPL code
132 is accepted on a case by case basis for libraries only and is never
133 accepted for modules.
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
134
a487ce07 » jduck
2010-06-18 add "sleep" rule, restructure
135 When possible, such as aux and exploit modules, be sure to include
e20b4705 » jlee-r7
2010-08-14 typo fixes, thanks enaqx
136 your license designation in the file in the appropriate place.
8f161576 » jlee-r7
2010-05-09 first stab at a HACKING file. fixes #821
137
Something went wrong with that request. Please try again.