diff --git a/Navigating-Metasploit's-Codebase.md b/Navigating-and-Understanding-Metasploit's-Codebase.md similarity index 70% rename from Navigating-Metasploit's-Codebase.md rename to Navigating-and-Understanding-Metasploit's-Codebase.md index 0f83e8cdeb..86aee972e8 100644 --- a/Navigating-Metasploit's-Codebase.md +++ b/Navigating-and-Understanding-Metasploit's-Codebase.md @@ -28,7 +28,11 @@ A great outline of Metasploit's code structure can be found at https://www.offen GitHub Code Navigation ------------------------ +You can search through the code of Metasploit using GitHub with searches such as https://github.com/rapid7/metasploit-framework/search?l=Ruby&q=%22payload.arch%22&type=code. Note that double quotes are required to match specifically on a certain term; in the previous example this term was `payload.arch`. You can also set the `type=code` parameter to specifically match only on code results, however this can be set to `commits` or `issues` if you want to search commits or issues instead. Finally notice that when searching code, its important to also specify the language of the files you want to match. In the case above I made it so that my results would only match on files deemed by GitHub to contain Ruby code, however you can also specify other languages such as Batch, or C if you want those languages instead. You can even remove the language restriction if you find your search results are too narrow. +Another incredibly useful feature of GitHub is the ability to search across all repositories that an organization owns. This is especially useful in Metasploit as certain components, such as Rex code and payload code, may be contained in repositories other than `metasploit-framework`. To search across the public repositories that Rapid7 owns, use a search such as https://github.com/search?q=org%3Arapid7+%22payload.arch%22&type=code. Note the presence of the `org:rapid7` tag within the previous URL: this tells GitHub to look through all repositories that Rapid7 owns for the term `payload.arch` within any code files. + +Experiment with these results and play around with GitHub searches more. Over time you will learn where it is useful and where it has its limitations and will be able to determine when it might be better to use an IDE to help understand a piece of code more. IDE Code Navigation ------------------------ @@ -36,4 +40,8 @@ One of the best ways to navigate the codebase within Metasploit is to use RubyMi For a cheaper option one can also use VS Code. Note however that VS Code does not have the best autotab completion and will not allow you to trace references, however if your willing to put up with this, it is a much faster and more lightweight product than RubyMine, which makes it great for those times when you just need to edit a piece of code without loading a bunch of related files that you don't need to reference or edit. It also has great regex search features that work much faster than RubyMine, allowing you to search for items within the codebase a lot quicker than you can with RubyMine, which will often seem to stutter at times due to its larger overhead. -Ultimately though the tool that you pick should be up to you. Some may prefer to work with vim/nano/emacs or some other command line editor over a GUI interface. Use whatever you can afford and feels comfortable to you! \ No newline at end of file +Ultimately though the tool that you pick should be up to you. Some may prefer to work with vim/nano/emacs or some other command line editor over a GUI interface. Use whatever you can afford and feels comfortable to you! + +Pry Debugging +------------------------ +Occasionally, simply reading through Metasploit code may not be helpful. You need to actually get into the weeds and learn what a piece of code is doing. In these cases, it may be helpful to use `pry`, a Ruby Debugger that can be launched at a specific place within your code and which allows you to view the state of the program at that time, make adjustments as needed, and then either step through the program or continue to let it run. A full tutorial on Pry will not be provided here, instead readers are encouraged to read up on the various guides on Pry available online, such as https://learn.co/lessons/debugging-with-pry \ No newline at end of file