IP Restrictions

Overview

The IP Restrictions module enables you to allow or deny traffic based on the source IP of the connection that was initiated to your ngrok endpoints. You define rules which allow or deny connections from IPv4 or IPv6 CIDR blocks.

A connection is allowed only if its source IP matches at least one rule with an 'allow' action and does not match any rule with a 'deny' action.

Example Usage

Allow TCP connections from 110.0.0.0/8 and 220.12.0.0/16 but not from 110.2.3.4/32.

Agent CLI

ngrok tls 443 \
  --cidr-allow 110.0.0.0/8 \
  --cidr-allow 220.12.0.0/16 \
  --cidr-deny 110.2.3.4/32

Agent Config

tunnels:
  example:
    proto: tls
    addr: 443
    ip_restriction:
      allow_cidrs: [110.0.0.0/8, 220.12.0.0/16]
      deny_cidrs: [110.2.3.4/32]

SSH

ssh -R 443:localhost:443 v2@connect.ngrok-agent.com tls \
  --cidr-allow 110.0.0.0/8 \
  --cidr-allow 220.12.0.0/16 \
  --cidr-deny 110.2.3.4/32

Go

import (
	"context"
	"net"

	"golang.ngrok.com/ngrok"
	"golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	return ngrok.Listen(ctx,
		config.TLSEndpoint(
			config.WithAllowCIDRString("110.0.0.0/8", "220.12.0.0/16"),
			config.WithDenyCIDRString("110.2.3.4/32"),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithAllowCIDRString
• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithDenyCIDRString

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		ip_restriction_allow_cidrs: ["110.0.0.0/8", "220.12.0.0/16"],
		ip_restriction_deny_cidrs: "110.2.3.4/32",
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#ip_restriction_allow_cidrs
• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#ip_restriction_deny_cidrs
• https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#allowCidr
• https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#denyCidr

Python

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    proto="tls",
    ip_restriction_allow_cidrs=["110.0.0.0/8", "220.12.0.0/16"],
    ip_restriction_deny_cidrs="110.2.3.4/32")

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/tls_listener_builder.html#ngrok.TlsListenerBuilder.allow_cidr
• https://ngrok.github.io/ngrok-python/tls_listener_builder.html#ngrok.TlsListenerBuilder.deny_cidr
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;
    let tun = sess
        .tls_endpoint()
        .allow_cidr("110.0.0.0/8"),
        .allow_cidr("220.12.0.0/16"),
        .deny_cidr("110.2.3.4/32"),
        .listen()
        .await?;
    println!("Listening on URL: {:?}", tun.url());
    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.TlsTunnelBuilder.html#method.allow_cidr
• https://docs.rs/ngrok/latest/ngrok/config/struct.TlsTunnelBuilder.html#method.deny_cidr

Kubernetes Controller

info

TLS endpoints are not supported by the Kubernetes Ingress Controller

Behavior

Rule Evaluation

A connection is allowed only if its source IP matches at least one rule with an 'allow' action and does not match any rule with a 'deny' action.

When using Edges and the Kubernetes Ingress Controller, if the IP Restrictions module references multiple IP Policies, then the rules of all referenced IP Policies are unioned together for evaluation.

IPv6

ngrok supports IPv6 addresses for all IP rules. You may use standard abbreviated notations.

ngrok tls 443 --allow-cidr "::/0" --deny-cidr "2600:1f16:d83:1202::6e:2/128"

Don't forget to create IPv6 rules. It's easy to test only with IPv4 and then suddenly things don't work when your software starts using IPv6 because you've forgotten to create rules to allow traffic from IPv6 addresses.

Reference

Configuration

Agent Configuration

Parameter	Description
Allow CIDRs	A set of IPv4 and IPv6 CIDRs to allow.
Deny CIDRs	A set of IPv4 and IPv6 CIDRs to deny.

Edge Configuration

Parameter	Description
IP Policy IDs	A set of IP policies that will be used to check if a source IP is allowed access. See the TLS Edge IP Restrictions Module API Resource for additional details.

Errors

If a connection is disallowed by IP Restrictions then the connection is closed.

Events

When the IP Restrictions module is enforced, it populates the following fields in the tcp_connection_closed.v0 event.

Fields
ip_policy.decision

Edges

IP Restrictions is a supported module for TLS Edges. When using IP Restrictions via Edges, you specify a set of references to one or more IP Policy objects, each of which contains a list of IP Policy Rule objects.

IP Restrictions and the IP Policy and IP Policy Rule objects they reference can be configured via the ngrok dashboard or API.

• TLS Edge IP Restrictions Module API Resource
• IP Policy API Resource
• IP Policy Rule API Resource

Pricing

This module is available on the Pro and Enterprise plans.

Try it out

First, grab your IPv4 and IPv6 addresses:

curl -4 icanhazip.com
curl -6 icanhazip.com

Then run ngrok with IP Restrictions with the IPv4 and IPv6 addresses you got in the previous step:

ngrok tls 443 \
  --url your-domain.ngrok.app \
  --allow-cidr 2600:8c00::a03c:91ee:fe69:9695/32 \
  --allow-cidr 78.227.75.230/32

Then make requests to your ngrok domain using the -4 and -6 flags to test both IPv4 and IPv6:

curl -4 https://your-domain.ngrok.app
curl -6 https://your-domain.ngrok.app