You are here: Home » Exploitation Tools » ngrok

ngrok

ngrok Description

The ngrok program makes local services available on the Internet even if the computer does not have a white IP address and is located behind NAT and firewalls. Using ngrok, any port on your local computer will be accessible through a secure tunnel from the Internet. For example, you can make your local web server accessible from the Internet through a direct link without additional configuration.

How the program works

You download and run the program on your machine and specify the network service port, usually a web server.

The program connects to the ngrok cloud service, which gives you the generated address (third-level domain). If you open this address in a web browser, the traffic will be redirected to your local network service or to any address that you specified.

What is ngrok suitable for?

  • Demonstration of web sites without deployment on real hosting
  • Create web hooks on your computer for software development
  • Testing mobile applications connected to a locally running backend
  • Stable addresses for connected devices deployed in the field
  • Launching personal cloud services from your home

Homepage: https://ngrok.com/

Author: Keith Rarick

License: Apache License

ngrok Help

Usage:

ngrok COMMAND OPTIONS

COMMANDS:

   authtoken	save authtoken to configuration file
   credits	prints author and licensing information
   http		start an HTTP tunnel
   start	start tunnels by name from the configuration file
   tcp		start a TCP tunnel
   tls		start a TLS tunnel
   update	update ngrok to the latest version
   version	print the version string
   help		Shows a list of commands or help for one command

authtoken Help

Name:

authtoken saves authtoken to configuration file.

Usage:

ngrok authtoken [command options] [arguments...]

Description:

The authtoken command modifies your configuration file to include the specified authtoken. By default, this configuration file is located at $HOME/.ngrok2/ngrok.yml.

The ngrok.com service requires that you sign up for an account to use many advanced service features. In order to associate your client with an account, it must pass a secret token to the ngrok.com service when it starts up. Instead of passing this authtoken on every invocation, you may use this command to save it into your configuration file so that your client always authenticates you properly.

Example:

ngrok authtoken BDZIXnhJt2HNWLXyQ5PM_qCaBq0W2sNFcCa0rfTZd

Options:

   --config 		save in this config file, default: ~/.ngrok2/ngrok.yml
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level

credits Help

Name:

credits prints author and licensing information.

Usage:

ngrok credits [arguments...]

Description:

Displays program credits and license information.

http Help

Name:

http starts an HTTP tunnel.

Usage:

ngrok http [command options] [arguments...]

Description:

Starts a tunnel listening for HTTP/HTTPS traffic with a specific hostname. The HTTP Host header on incoming public requests is inspected to determine which tunnel it matches.

HTTPS endpoints terminate TLS traffic at the ngrok server using the ngrok.io certificates. The decrypted, HTTP traffic is then forwarded through the secure tunnel and then to your local server. If you don't want your TLS traffic to terminate at the ngrok server, use a TLS or TCP tunnel.

Example:

Forward ngrok.io subdomain to port 80:

ngrok http 8080

Forward traffic to example.com:9000:

ngrok http example.com:9000

Request subdomain name: 'bar.ngrok.io':

ngrok http -subdomain=bar 80

Request tunnel 'ex.com' (DNS CNAME):

ngrok http -hostname=ex.com 1234

Enforce basic auth on tunnel endpoint:

ngrok http -auth='falken:joshua' 80

Rewrite the Host header to 'ex.com':

ngrok http -host-header=ex.com 80

Serve local files in /var/log:

ngrok http file:///var/log

Forward to a local https server:

ngrok http https://localhost:8443

Options:

   --auth 		enforce basic auth on tunnel endpoint, 'user:password'
   --authtoken 		ngrok.com authtoken identifying a user
   --bind-tls "both"	listen for http, https or both: true/false/both
   --config		path to config files; they are merged if multiple
   --host-header 	set Host header; if 'rewrite' use local address hostname
   --hostname 		host tunnel on custom hostname (requires DNS CNAME)
   --inspect		enable/disable http introspection
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level
   --region 		ngrok server region [us, eu, au, ap, sa, jp, in] (default: us)
   --subdomain 		host tunnel on a custom subdomain

start Help

Name:

start starts tunnels by name from the configuration file.

Usage:

ngrok start [command options] [arguments...]

Description:

Starts tunnels by name from the configuration file. You may specify any number of tunnel names. You may start all tunnels in the configuration file with the --all switch.

Examples:

Start tunnel named 'dev' in the configuration file:

ngrok start dev

Start tunnels named 'web' and 'blog':

ngrok start web blog

Start all tunnels defined in the config file:

ngrok start --all

Options:

   --all		start all tunnels in the configuration file
   --authtoken 		ngrok.com authtoken identifying a user
   --config		path to config files; they are merged if multiple
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level
   --none		start running no tunnels
   --region 		ngrok server region [us, eu, au, ap, sa, jp, in] (default: us)

tcp Help

Name:

tcp starts a TCP tunnel.

Usage:

ngrok tcp [command options] [arguments...]

Description:

Starts a tunnel which forwards all TCP traffic on a public port to a local address. This is extremely useful for exposing services that run non-HTTP traffic (ssh, sip, rdp, game servers, etc).

A TCP tunnel binds a public address on the remote ngrok server. Any services which require a stable public address should use the --remote-addr option. ngrok.com requires that you reserve a TCP tunnel address for your account before you can use it.

Examples:

Forward a port to your local ssh server:

ngrok tcp 22

Expose an RDP server on a specific public address that you reserved:

ngrok tcp --remote-addr=1.tcp.ngrok.io:27210 3389

Options:

   --authtoken 		ngrok.com authtoken identifying a user
   --config		path to config files; they are merged if multiple
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level
   --region 		ngrok server region [us, eu, au, ap, sa, jp, in] (default: us)
   --remote-addr 	bind remote address (requires you reserve an address)

tls Help

Name:

tls starts a TLS tunnel.

Usage:

ngrok tls [command options] [arguments...]

Description:

Starts a tunnel listening for TLS traffic on port 443 with a specific hostname. The TLS SNI (Server Name Indication) extension field in the TLS connection is inspected to determine which tunnel it matches.

The ngrok server does not terminate TLS connections forwarded with this command. Any underlying protocol may be used. You may optionally specify a TLS key/cert pair which will be used to terminate the traffic client-side before it is forwarded. If not specified, the traffic will be forwarded still encrypted.

Using this command is only recommended with the -hostname option. Other uses will work, but will always result in certificate mismatch warnings.

Examples:

Forward TLS traffic for example.com to port 443 (requires CNAME):

ngrok tls -hostname=example.com 443

Forward TLS traffic on subdomain (mismatch certificate warning):

ngrok tls 1234

Terminate TLS traffic for t.co before forwarding:

ngrok tls -hostname=t.co -crt=/path/to/t.co.crt -key=/path/to/t.co.key 443

Options:

   --authtoken 		ngrok.com authtoken identifying a user
   --client-cas 	path to TLS certificate authority to verify client certs
   --config		path to config files; they are merged if multiple
   --crt 		path to a TLS certificate for TLS termination
   --hostname 		tunnel on a custom hostname (requires CNAME of your DNS)
   --key 		path to a TLS key for TLS termination
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level
   --region 		ngrok server region [us, eu, au, ap, sa, jp, in] (default: us)
   --subdomain 		host tunnel on a custom subdomain

update Help

Name:

update updates ngrok to the latest version.

Usage:

ngrok update [command options] [arguments...]

Description:

Updates ngrok to the latest version. This command checks the ngrok web service for a newer versions of the ngrok client. If a newer version is available, it will download it an replace the ngrok binary with the new version after cryptographically verifying the update is safe to apply.

In order to update successfully, the ngrok binary must be in a directory that is writable by your current user. If you placed ngrok in a system path, you may need to run this with root or Administrator privileges.

Examples:

Update ngrok to the latest stable version:

ngrok update

Update ngrok to the latest beta version:

ngrok update -channel=beta

Options:

   --channel "stable"	update channel (stable, beta)
   --log "false"	path to log file, 'stdout', 'stderr' or 'false'
   --log-format "term"	log record format: 'term', 'logfmt', 'json'
   --log-level "info"	logging level

version Help

Name:

version prints the version string.

Usage:

ngrok version [arguments...]

help command Help

Name:

help - Shows a list of commands or help for one command

Usage:

ngrok help [arguments...]

Usage Example ngrok

Create a tunnel from the generated subdomain accessible via a public link to the local port 80 (web server):

ngrok http 80

Create a tunnel to the specified HOST:PORT (foo.dev:80) instead of localhost:

ngrok http foo.dev:80

Make the local HTTPS server accessible from the Internet:

ngrok http https://localhost

Tunneling arbitrary TCP traffic on port 22:

ngrok tcp 22

Creating a tunnel (http) to the hackware.ru site using the https protocol (https://hackware.ru) with replacing the Host HTTP header with hackware.ru (-host-header=hackware.ru):

ngrok http https://hackware.ru -host-header=hackware.ru

How to install ngrok

Installation on Kali Linux and any Linux distribution

wget `curl -s https://ngrok.com/download | grep -o -E 'https://bin.equinox.io/c/[A-Za-z0-9]{4,}/ngrok-stable-linux-amd64.zip'`
unzip ngrok-stable-linux-amd64.zip
chmod +x ./ngrok
./ngrok -h

Installation on BlackArch

The program is preinstalled in BlackArch

sudo pacman -S ngrok

Installation on Windows

Go to the official website page and download ngrok for Windows: https://ngrok.com/download

Unzip the downloaded archive, open the command line and go to the folder with the executable file using cd, for example, my program is placed in the folder C:\Users\MiAl\Downloads\:

cd C:\Users\MiAl\Downloads\

To check, display help with the command:

.\ngrok -h

ngrok Screenshots

ngrok Tutorials

Related tools