Land rapid7#18169, Add centralized Metasploit plugin documentation

docs/metasploit-framework.wiki/How-To-Use-Plugins.md

@@ -0,0 +1,155 @@
+Metasploit plugins can change the behavior of Metasploit framework by adding new features, new user interface commands, and more.
+They are designed to have a very loose definition in order to make them as useful as possible.
+
+Plugins are not available by default, they need to be loaded:
+
+```msf
+msf6 > load plugin_name
+```
+
+Plugins can be automatically loaded and configured on msfconsole's start up by configuring a custom `~/.msf4/msfconsole.rc` file:
+
+```
+load plugin_name
+plugin_name_command --option
+```
+
+## Available Plugins
+
+The current available plugins for Metasploit can be found by running the `load -l` command, or viewing Metasploit's [plugins](https://github.com/rapid7/metasploit-framework/tree/master/plugins) directory:
+
+| name             | Description                                                                                         |
+|------------------|-----------------------------------------------------------------------------------------------------|
+| aggregator       | Interacts with the external Session Aggregator                                                      |
+| alias            | Adds the ability to alias console commands                                                          |
+| auto_add_route   | Adds routes for any new subnets whenever a session opens                                            |
+| beholder         | Capture screenshots, webcam pictures, and keystrokes from active sessions                           |
+| besecure         | Integrates with the beSECURE - open source vulnerability management                                 |
+| capture          | Start all credential capture and spoofing services                                                  |
+| db_credcollect   | Automatically grab hashes and tokens from Meterpreter session events and store them in the database |
+| db_tracker       | Monitors socket calls and updates the database backend                                              |
+| event_tester     | Internal test tool used to verify the internal framework event subscriber logic works               |
+| ffautoregen      | This plugin reloads and re-executes a file-format exploit module once it has changed                |
+| ips_filter       | Scans all outgoing data to see if it matches a known IPS signature                                  |
+| lab              | Adds the ability to manage VMs                                                                      |
+| libnotify        | Send desktop notification with libnotify on sessions and db events                                  |
+| msfd             | Provides a console interface to users over a listening TCP port                                     |
+| msgrpc           | Provides a MessagePack interface over HTTP                                                          |
+| nessus           | Nessus Bridge for Metasploit                                                                        |
+| nexpose          | Integrates with the Rapid7 Nexpose vulnerability management product                                 |
+| openvas          | Integrates with the OpenVAS - open source vulnerability management                                  |
+| pcap_log         | Logs all socket operations to pcaps (in /tmp by default)                                            |
+| request          | Make requests from within Metasploit using various protocols.                                       |
+| rssfeed          | Create an RSS feed of events                                                                        |
+| sample           | Demonstrates using framework plugins                                                                |
+| session_notifier | This plugin notifies you of a new session via SMS                                                      |
+| session_tagger   | Automatically interacts with new sessions to create a new remote TaggedByUser file                  |
+| socket_logger    | Log socket operations to a directory as individual files                                            |
+| sounds           | Automatically plays a sound when various framework events occur                                     |
+| sqlmap           | sqlmap plugin for Metasploit                                                                        |
+| thread           | Internal test tool for testing thread usage in Metasploit                                          |
+| token_adduser    | Attempt to add an account using all connected Meterpreter session tokens                            |
+| token_hunter     | Search all active Meterpreter sessions for specific tokens                                          |
+| wiki             | Outputs stored database values from the current workspace into DokuWiki or MediaWiki format         |
+| wmap             | Web assessment plugin                                                                               |
+
+## Examples
+
+### Alias Plugin
+
+The Alias plugin adds the ability to alias console commands:
+
+```
+msf6 > load alias
+[*] Successfully loaded plugin: alias
+msf6 > alias -h
+Usage: alias [options] [name [value]]
+
+OPTIONS:
+
+    -c   Clear an alias (* to clear all).
+    -f   Force an alias assignment.
+    -h   Help banner.
+```
+
+Register an alias such as `proxy_enable`:
+
+```msf
+msf6 > alias proxy_enable "set Proxies http:localhost:8079"
+```
+
+Now when running the aliased `proxy_enable` command, the proxy datastore value will be set for the current module:
+
+```msf
+msf6 auxiliary(scanner/http/title) > proxy_enable
+Proxies => http:localhost:8079
+```
+
+Viewing registered aliases:
+
+```
+msf6 > alias
+
+Current Aliases
+===============
+
+       Alias Name    Alias Value
+       ----------    -----------
+alias  proxy_enable  set Proxies http:localhost:8079
+
+```
+
+To automatically load and configure the alias plugin on startup of Metasploit, create a custom `~/.msf4/msfconsole.rc` file:
+
+```
+load alias
+alias proxy_enable "set Proxies http:localhost:8079"
+alias proxy_disable "unset Proxies"
+alias routes "route print"
+```
+
+### Capture Plugin
+
+Capturing credentials is a critical and early phase in the playbook of many offensive security testers. Metasploit has
+facilitated this for years with protocol-specific modules all under the `modules/auxiliary/server/capture` directory. Users can start and configure
+each of these modules individually, but now the capture plugin can streamline the process. The capture plugin can easily start 13
+different services (17 including SSL enabled versions) on the same listening IP address including remote interfaces via Meterpreter.
+A configuration file can be used to select individual services to start and once finished, all services can easily be stopped
+using a single command.
+
+To use the plugin, it must first be loaded. That will provide the `captureg` command (for Capture-Global) which then offers start
+and stop subcommands. In the following example, the plugin is loaded, and then all default services are started on the 192.168.159.128 interface.
+
+```msf
+msf6 > load capture
+[*] Successfully loaded plugin: Credential Capture
+msf6 > captureg start --ip 192.168.159.128
+Logging results to /home/smcintyre/.msf4/logs/captures/capture_local_20220325104416_589275.txt
+Hash results stored in /home/smcintyre/.msf4/loot/captures/capture_local_20220325104416_612808
+[+] Authentication Capture: DRDA (DB2, Informix, Derby) started
+[+] Authentication Capture: FTP started
+[+] HTTP Client MS Credential Catcher started
+[+] HTTP Client MS Credential Catcher started
+[+] Authentication Capture: IMAP started
+[+] Authentication Capture: MSSQL started
+[+] Authentication Capture: MySQL started
+[+] Authentication Capture: POP3 started
+[+] Authentication Capture: PostgreSQL started
+[+] Printjob Capture Service started
+[+] Authentication Capture: SIP started
+[+] Authentication Capture: SMB started
+[+] Authentication Capture: SMTP started
+[+] Authentication Capture: Telnet started
+[+] Authentication Capture: VNC started
+[+] Authentication Capture: FTP started
+[+] Authentication Capture: IMAP started
+[+] Authentication Capture: POP3 started
+[+] Authentication Capture: SMTP started
+[+] NetBIOS Name Service Spoofer started
+[+] LLMNR Spoofer started
+[+] mDNS Spoofer started
+[+] Started capture jobs
+msf6 >
+```
+
+This content was originally posted on the [Rapid7 Blog](https://www.rapid7.com/blog/post/2022/03/25/metasploit-weekly-wrap-up-154/).

docs/navigation.rb

@@ -272,7 +272,7 @@ def without_prefix(prefix)
           {
             path: 'How-to-use-msfvenom.md',
             nav_order: 7
-          },
+          }
         ]
       },
       {
@@ -303,6 +303,10 @@ def without_prefix(prefix)
             path: 'Metasploit-Database-Support.md',
             title: 'Database Support'
           },
+          {
+            path: 'How-To-Use-Plugins.md',
+            title: 'Metasploit Plugins',
+          }
         ]
       },
       {
@@ -623,10 +627,6 @@ def without_prefix(prefix)
                 path: 'How-to-use-the-Git-mixin-to-write-an-exploit-module.md',
                 title: 'Git Mixin'
               },
-              {
-                path: 'How-To-Use-The-Capture-Plugin.md',
-                title: 'Capture Plugin'
-              },
               {
                 title: 'HTTP',
                 folder: 'http',

lib/msf/ui/console/command_dispatcher/core.rb

@@ -967,7 +967,7 @@ def list_plugins
       items = Dir.entries(plugin_directory).keep_if { |n| n.match(/^.+\.rb$/)}
       next if items.empty?
       print_status("Available #{type} plugins:")
-      items.each do |item|
+      items.sort.each do |item|
         print_line("    * #{item.split('.').first}")
       end
       print_line

plugins/db_credcollect.rb

@@ -101,7 +101,7 @@ def name
     end
 
     def desc
-      'Automatically grabs hashes and tokens from meterpreter session events and stores them in the db'
+      'Automatically grab hashes and tokens from Meterpreter session events and store them in the database'
     end
 
   end

plugins/event_tester.rb

@@ -15,6 +15,10 @@ def name
       'event_tester'
     end
 
+    def desc
+      'Internal test tool used to verify the internal framework event subscriber logic works'
+    end
+
     def initialize(framework, opts)
       super
       @subscriber = Subscriber.new

plugins/ffautoregen.rb

@@ -91,7 +91,7 @@ def name
     end
 
     def desc
-      'FileFormat AutoRegen Plugin'
+      'This plugin reloads and re-executes a file-format exploit module once it has changed'
     end
 
   end

plugins/libnotify.rb

@@ -86,7 +86,7 @@ def name
     end
 
     def desc
-      'Send desktop notification with libnotify on sessions & db events'
+      'Send desktop notification with libnotify on sessions and db events'
     end
   end
 end

plugins/msfd.rb

@@ -85,7 +85,7 @@ def name
     # Returns the msfd plugin description.
     #
     def desc
-      'Provides a console interface to users over a listening TCP port.'
+      'Provides a console interface to users over a listening TCP port'
     end
 
     #

plugins/session_notifier.rb

@@ -400,7 +400,7 @@ def cleanup
     end
 
     def desc
-      'This plugin notifies you a new session via SMS.'
+      'This plugin notifies you of a new session via SMS'
     end
 
   end

plugins/session_tagger.rb

@@ -48,7 +48,7 @@ def name
     end
 
     def desc
-      'Automatically interacts with new sessions'
+      'Automatically interacts with new sessions to create a new remote TaggedByUser file'
     end
 
   end

plugins/thread.rb

@@ -102,7 +102,7 @@ def name
     # more than 60 characters, but there are no hard limits.
     #
     def desc
-      'Thread testing plugin'
+      'Internal test tool for testing thread usage in Metasploit'
     end
 
   end

plugins/token_adduser.rb

@@ -103,7 +103,7 @@ def name
     end
 
     def desc
-      'Attempt to add an account using all connected meterpreter session tokens'
+      'Attempt to add an account using all connected Meterpreter session tokens'
     end
   end
 end

plugins/token_hunter.rb

@@ -15,7 +15,7 @@ def name
 
       def commands
         {
-          'token_hunt_user' => 'Scan all connected meterpreter sessions for active tokens corresponding to one or more users'
+          'token_hunt_user' => 'Scan all connected Meterpreter sessions for active tokens corresponding to one or more users'
         }
       end
 
@@ -140,7 +140,7 @@ def name
     end
 
     def desc
-      'Search all active meterpreter sessions for specific tokens'
+      'Search all active Meterpreter sessions for specific tokens'
     end
   end
 end

plugins/wiki.rb

@@ -476,7 +476,7 @@ def name
     # more than 60 characters, but there are no hard limits.
     #
     def desc
-      'Adds output to wikitext'
+      'Outputs stored database values from the current workspace into DokuWiki or MediaWiki format'
     end
 
     #