diff --git a/app/README.md b/app/README.md new file mode 100644 index 0000000000..9bdde79262 --- /dev/null +++ b/app/README.md @@ -0,0 +1 @@ +This directory contains ActiveRecord concerns, models and validators. \ No newline at end of file diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000000..431188811c --- /dev/null +++ b/config/README.md @@ -0,0 +1,3 @@ +Contains various files that help configure Metasploit. Most files here you'll never have to deal with, though +`database.yml.example` might be useful for those looking to configure their database, and `openssl.conf` +might be helpful for those trying to troubleshoot OpenSSL issues in Metasploit. \ No newline at end of file diff --git a/data/README.md b/data/README.md new file mode 100644 index 0000000000..979cc5b96c --- /dev/null +++ b/data/README.md @@ -0,0 +1,7 @@ +This folder contains various data files used for a variety of purposes, including but not limited to banners for the +console, exploit source code for exploits (under `data/exploits`), template code and binaries, wordlists and shellcode. + +As a general rule of thumb this folder will most often be used when you are using compiled binaries or source code from +other exploits for cases such as local privilege escalation exploits and need to provide the exploit code and compiled +binaries so that maintainers can verify the binary and compile it themselves, as so that modules can find the R7 compiled +version of the resulting binary for use during exploitation. \ No newline at end of file diff --git a/db/README.md b/db/README.md new file mode 100644 index 0000000000..d164fb9c46 --- /dev/null +++ b/db/README.md @@ -0,0 +1,2 @@ +Contains `modules_metadata_base.json` which contains information about all modules within Metasploit, as well as +`schema.rb` which describes current state of the database schema maintained by Rails ActiveRecord. \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index f84b6820ce..e6dd6caa58 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,3 +1,6 @@ +# Folder Purpose +This folder contains files related to running Metasploit inside Docker. + # Metasploit in Docker ## Getting Started diff --git a/docs/metasploit-framework.wiki/Metasploit-Filesystem-Explained.md b/docs/metasploit-framework.wiki/Metasploit-Filesystem-Explained.md deleted file mode 100644 index 33304d3dff..0000000000 --- a/docs/metasploit-framework.wiki/Metasploit-Filesystem-Explained.md +++ /dev/null @@ -1,86 +0,0 @@ -# Understanding Metasploit's Filesystem -The file system of Metasploit can be a little confusing at times. The following is a guide that should help -to explain some of the common folders that you might use. Keep in mind that on Kali Linux your root install directory -will likely be `/usr/share/metasploit-framework`. For Omnibus installers downloaded from https://downloads.metasploit.com/ -or a similar location, it will be `/opt/metasploit` on Linux devices, or `C:\metasploit-framework` or `D:\metasploit-framework` -by default for Windows devices. - -The following are some of the most important folders. Note this isn't a complete list, but should help you get acquainted -with the file system of Metasploit for most use cases. - -## app -This directory contains ActiveRecord concerns, models and validators. - -## config -Contains various files that help configure Metasploit. Most files here you'll never have to deal with, though -`database.yml.example` might be useful for those looking to configure their database, and `openssl.conf` -might be helpful for those trying to troubleshoot OpenSSL issues in Metasploit. - -## data -This folder contains various data files used for a variety of purposes, including but not limited to banners for the -console, exploit source code for exploits (under `data/exploits`), template code and binaries, wordlists and shellcode. - -As a general rule of thumb this folder will most often be used when you are using compiled binaries or source code from -other exploits for cases such as local privilege escalation exploits and need to provide the exploit code and compiled -binaries so that maintainers can verify the binary and compile it themselves, as so that modules can find the R7 compiled -version of the resulting binary for use during exploitation. - -## db -Contains `modules_metadata_base.json` which contains information about all modules within Metasploit, as well as -`schema.rb` which describes current state of the database schema maintained by Rails ActiveRecord. - -## docker -Contains files related to running Metasploit inside Docker. - -## docs -This contains all the documentation files that are on https://docs.metasploit.com as well as the associated server files -so that you can run a local copy of this site offline. - -## documentation -This folder is primarily used to hold documentation for Metasploit's various modules, as well as the developers guide -at `developers_guide.pdf`. - -## external -This folder contains files to assist in using Metasploit with other tools such as `burp-proxy`, `vscode` and `zsh`. -It also contains `serialport`, which is a Rapid7 fork of the original `ruby-serialport` project provided by -RubyForge.org. Most importantly though, it contains the `source` directory, which contains source code for all -compiled binaries in Metasploit Framework so that users can verify the code being used. - -## kubernetes -Contains files related to deploying Metasploit in Kubernetes for Kubernetes testing, using a `meterpreter` helm chart. - -## lib -This is where all of the libraries and mixins of Metasploit live. Generally speaking any code that will be reused -across multiple modules will be placed into a library or mixin which will then be placed under this folder. - -## modules -This is the folder where all of Metasploit's modules live. These modules are scripts in Ruby that interface with -Metasploit itself to perform some specific task. There are various types of modules, such as `exploit` modules to -exploit a vulnerability and gain a shell, `auxiliary` to perform a non-shell gaining activity, `payloads` for -Metasploit's various payloads (which are also modules), and `post` for post exploitation modules. - -## plugins -This is where plugins for Metasploit live, which allow Metasploit to interface with other tools and services. - -## script -This contains the `rails.rb` file which will automatically be run when the command `rails` is run from -the root of Metasploit itself, and allows Rails to populate its list of additional commands -that are available for users to use. - -## scripts -This folder contains all resource, shell, and Meterpreter scripts in Metasploit. Note that Metasploit no longer supports -Meterpreter scripts, so the `meterpreter/` folder should be treated as deprecated and is likely to be removed in the -future. - -## spec -All RSpec related unit test files reside under this directory. - -## test -Contains files related to integration tests for things such as payload testing, -modules used in sanity testing, as well as tests that can be exercised using -https://github.com/rapid7/geppetto. - -## tools -This folder contains standalone scripts that can help developers and users with various tasks, such as `msftidy.rb` -which checks modules to make sure they conform to our linting rules, and `msftidy_docs.rb` which does the same for -documentation files. \ No newline at end of file diff --git a/docs/navigation.rb b/docs/navigation.rb index 7fdf837ecd..6556105a06 100644 --- a/docs/navigation.rb +++ b/docs/navigation.rb @@ -243,35 +243,30 @@ NAVIGATION_CONFIG = [ nav_order: 2, children: [ { - path: 'Metasploit-Filesystem-Explained.md', - title: "Metasploit's Filesystem Explained", + path: 'Using-Metasploit.md', + title: 'Running modules', nav_order: 2 }, { - path: 'Using-Metasploit.md', - title: 'Running modules', + path: 'How-to-use-a-Metasploit-module-appropriately.md', nav_order: 3 }, { - path: 'How-to-use-a-Metasploit-module-appropriately.md', + path: 'How-payloads-work.md', nav_order: 4 }, { - path: 'How-payloads-work.md', + path: 'Module-Documentation.md', nav_order: 5 }, { - path: 'Module-Documentation.md', + path: 'How-to-use-a-reverse-shell-in-Metasploit.md', nav_order: 6 }, { - path: 'How-to-use-a-reverse-shell-in-Metasploit.md', + path: 'How-to-use-msfvenom.md', nav_order: 7 }, - { - path: 'How-to-use-msfvenom.md', - nav_order: 8 - } ] }, { diff --git a/documentation/README.md b/documentation/README.md index 105fc74618..47892d45f8 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,3 +1,7 @@ +# Folder Purpose +This folder is primarily used to hold documentation for Metasploit's various modules, as well as the developers guide +at `developers_guide.pdf`. + # Metasploit Developer Documentation Metasploit is actively supported by a community of hundreds of @@ -19,7 +23,7 @@ treasures there, such as: ## API Documentation If you are looking for API documentation, you may run `rake yard` to -generate a navigatable view of the comment documentation used throughout +generate a navigable view of the comment documentation used throughout Metasploit, or visit https://rapid7.github.io/metasploit-framework/api for a recently generated online version. diff --git a/external/README.md b/external/README.md new file mode 100644 index 0000000000..03a642f9f0 --- /dev/null +++ b/external/README.md @@ -0,0 +1,4 @@ +This folder contains files to assist in using Metasploit with other tools such as `burp-proxy`, `vscode` and `zsh`. +It also contains `serialport`, which is a Rapid7 fork of the original `ruby-serialport` project provided by +RubyForge.org. Most importantly though, it contains the `source` directory, which contains source code for all +compiled binaries in Metasploit Framework so that users can verify the code being used. \ No newline at end of file diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000000..29424dbdee --- /dev/null +++ b/lib/README.md @@ -0,0 +1,2 @@ +This is where all of the libraries and mixins of Metasploit live. Generally speaking any code that will be reused +across multiple modules will be placed into a library or mixin which will then be placed under this folder. \ No newline at end of file diff --git a/modules/README.md b/modules/README.md new file mode 100644 index 0000000000..e93420ec2d --- /dev/null +++ b/modules/README.md @@ -0,0 +1,4 @@ +This is the folder where all of Metasploit's modules live. These modules are scripts in Ruby that interface with +Metasploit itself to perform some specific task. There are various types of modules, such as `exploit` modules to +exploit a vulnerability and gain a shell, `auxiliary` to perform a non-shell gaining activity, `payloads` for +Metasploit's various payloads (which are also modules), and `post` for post exploitation modules. \ No newline at end of file diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000000..0f79b3677b --- /dev/null +++ b/plugins/README.md @@ -0,0 +1 @@ +This is where plugins for Metasploit live, which allow Metasploit to interface with other tools and services. \ No newline at end of file diff --git a/script/README.md b/script/README.md new file mode 100644 index 0000000000..af9545dde2 --- /dev/null +++ b/script/README.md @@ -0,0 +1,3 @@ +This contains the `rails.rb` file which will automatically be run when the command `rails` is run from +the root of Metasploit itself, and allows Rails to populate its list of additional commands +that are available for users to use. \ No newline at end of file diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000000..083a5112a4 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,3 @@ +This folder contains all resource, shell, and Meterpreter scripts in Metasploit. Note that Metasploit no longer supports +Meterpreter scripts, so the `meterpreter/` folder should be treated as deprecated and is likely to be removed in the +future. \ No newline at end of file diff --git a/spec/README.md b/spec/README.md new file mode 100644 index 0000000000..b8444ed184 --- /dev/null +++ b/spec/README.md @@ -0,0 +1 @@ +All RSpec related unit test files reside under this directory. \ No newline at end of file diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000000..907f5e6070 --- /dev/null +++ b/test/README.md @@ -0,0 +1,3 @@ +Contains files related to integration tests for things such as payload testing, +modules used in sanity testing, as well as tests that can be exercised using +https://github.com/rapid7/geppetto. \ No newline at end of file diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000000..eac0fcf120 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,3 @@ +This folder contains standalone scripts that can help developers and users with various tasks, such as `msftidy.rb` +which checks modules to make sure they conform to our linting rules, and `msftidy_docs.rb` which does the same for +documentation files. \ No newline at end of file