Pentest Tools

Published on April 1st, 2016 📆 | 5231 Views ⚑


ngrok — Secure tunnels to localhost


 Secure tunnels to localhost: ngrok is a reverse proxy that creates a secure tunnel from a public endpoint to a locally running web service. ngrok captures and analyzes all traffic over the tunnel for later inspection and replay. ngrok allows you to expose a web server running on your local machine to the internet. Just tell ngrok what port your web server is listening on. It also provides a real-time web UI where you can introspect all of the HTTP traffic running over your tunnels. The ngrok project is composed of two components, the ngrok client (ngrok) and the ngrok server (ngrokd)


I want to expose a local server behind a NAT or firewall to the internet.


What can I do with ngrok?

  • Expose any http service behind a NAT or firewall to the internet on a subdomain of
  • Expose any tcp service behind a NAT or firewall to the internet on a random port of
  • Inspect all http requests/responses that are transmitted over the tunnel
  • Replay any request that was transmitted over the tunnel


What is ngrok useful for?

  • Temporarily sharing a website that is only running on your development machine
  • Demoing an app at a hackathon without deploying
  • Developing any services which consume webhooks (HTTP callbacks) by allowing you to replay those requests
  • Debugging and understanding any web service by inspecting the HTTP traffic
  • Running networked services on machines that are firewalled off from the internet


[adsense size='1']

ngrok features


Secure Tunnels

Instantly create a public HTTPS URL for a web site running locally on your development machine.
ngrok http 80



ngrok tunnels run using an optimized version of the technology that powers HTTP/2 so that your tunneled services load fast.


Password Protected

Set http auth credentials to protect access to your tunnel and those you share it with.
ngrok http -auth "user:password" 80


Websocket Support

Share your real-time web apps! ngrok tunnels websocket connections over HTTP tunnels without any changes.
ngrok http 8000


Replay Webhook Requests

Easily develop webhook integrations by simply ‘replaying’ webhook requests to your dev server.


Automate ngrok via API

Dynamically start, stop and query tunnel status all with a simple RESTful API.


Request Inspection

Use ngrok’s web inspection interface to understand the HTTP request and response traffic over your tunnel.


No more port forwarding

Don’t configure port forwarding on your router or waste time setting up dynamic DNS solutions. ngrok works everywhere with no changes, even when a device changes networks.


TCP Tunnels

Expose any networked service to the internet, even ones that don’t use HTTP like SSH.
ngrok tcp 22


Multiple Simultaneous Tunnels

Run multiple tunnels simultaneously with a single ngrok client.
ngrok start demo-site ssh admin-ui


Target virtual-host sites

Rewrite the Host header of tunneled requests to target a specific site in your WAMP/MAMP/Pow development environment.
ngrok http 80


Shared account access for teams

Accounts can share access to reserved domains and addresses allowing multiple developers to collaborate on a project while still having their own credentials.


 [adsense size='1']


Network protocol and tunneling

At a high level, ngrok’s tunneling works as follows:


Connection Setup and Authentication

  1. The client initiates a long-lived TCP connection to the server over which they will pass JSON instruction messages. This connection is called the Control Connection.
  2. After the connection is established, the client sends an Auth message with authentication and version information.
  3. The server validates the client’s Auth message and sends an AuthResp message indicating either success or failure.


Tunnel creation

  1. The client may then ask the server to create tunnels for it by sending ReqTunnel messages.
  2. When the server receives a ReqTunnel message, it will send 1 or more NewTunnel messages that indicate successful tunnel creation or indicate failure.


Tunneling connections

  1. When the server receives a new public connection, it locates the appropriate tunnel by examining the HTTP host header (or the port number for TCP tunnels). This connection from the public internet is called a Public Connection.
  2. The server sends a ReqProxy message to the client over the control connection.
  3. The client initiates a new TCP connection to the server called a Proxy Connection.
  4. The client sends a RegProxy message over the proxy connection so the server can associate it to a control connection (and thus the tunnels it’s responsible for).
  5. The server sends a StartProxy message over the proxy connection with metadata information about the connection (the client IP and name of the tunnel).
  6. The server begins copying the traffic byte-for-byte from the public connection to the proxy connection and vice-versa.
  7. The client opens a connection to the local address configured for that tunnel. This is called the Private Connection.
  8. The client begins copying the traffic byte-for-byte from the proxied connection to the private connection and vice-versa.


Detecting dead tunnels

  1. In order to determine whether a tunnel is still alive, the client periodically sends Ping messages over the control connection to the server, which replies with Pong messages.
  2. When a tunnel is detected to be dead, the server will clean up all of that tunnel’s state and the client will attempt to reconnect and establish a new tunnel.



How to run your own ngrokd server

Running your own ngrok server is really easy! The instructions below will guide you along your way!


1. Get an SSL certificate

ngrok provides secure tunnels via TLS, so you’ll need an SSL certificate. Assuming you want to create tunnels on *, buy a wildcard SSL certificate for * Note that if you don’t need to run https tunnels that you don’t need a wildcard certificate. (In fact, you can just use a self-signed cert at that point, see the section on that later in the document).


2. Modify your DNS

You need to use the DNS management tools given to you by your provider to create an A record which points * to the IP address of the server where you will run ngrokd.


3. Compile it

You can compile an ngrokd server with the following command:

make release-server

Make sure you compile it with the GOOS/GOARCH environment variables set to the platform of your target server. Then copy the binary over to your server.


4. Run the server

You’ll run the server with the following command.

./ngrokd -tlsKey="/path/to/tls.key" -tlsCrt="/path/to/tls.crt" -domain=""


Specifying your TLS certificate and key

ngrok only makes TLS-encrypted connections. When you run ngrokd, you’ll need to instruct it where to find your TLS certificate and private key. Specify the paths with the following switches:

-tlsKey="/path/to/tls.key" -tlsCrt="/path/to/tls.crt"


Setting the server’s domain

When you run your own ngrokd server, you need to tell ngrokd the domain it’s running on so that it knows what URLs to issue to clients.



5. Configure the client

In order to connect with a client, you’ll need to set two options in ngrok’s configuration file. The ngrok configuration file is a simple YAML file that is read from ~/.ngrok by default. You may specify a custom configuration file path with the -config switch. Your config file must contain the following two options.

trust_host_root_certs: true

Substitute the address of your ngrokd server for “”. The “trust_host_root_certs” parameter instructs ngrok to trust the root certificates on your computer when establishing TLS connections to the server. By default, ngrok only trusts the root certificate for


6. Connect with a client

Then, just run ngrok as usual to connect securely to your own ngrokd server!

ngrok 80


Secure tunnels to localhost with a self-signed SSL certificate

It’s possible to run ngrokd with a a self-signed certificate, but you’ll need to recompile ngrok with your signing CA. If you do choose to use a self-signed cert, please note that you must either remove the configuration value for trust_host_root_certs or set it to false:

trust_host_root_certs: false




Source && Download

Comments are closed.