Restrict IPs

Overview

The Restrict IPs Traffic Policy action enables you to allow or deny traffic based on the source IP of the connection that was initiated to your ngrok endpoints.

You can define rules in two ways, with allow and deny lists or with identifiers to existing ngrok IP Policies.

Configuration Reference

This is the Traffic Policy configuration reference for this action.

Action Type

restrict-ips

Configuration Fields

Parameter	Type	Description
enforce	bool	Default true. If false, continue to the next action even if the IP is not permitted.
allow	[]string	A list of of CIDRs that are allowed.
deny	[]string	A list of of CIDRs that are denied.
ip_policies	[]ref	List of IP Policy identifiers to be checked if the source IP is allowed access.

Supported Phases

• on_http_request
• on_http_response
• on_tcp_connect

Behavior

Evaluation of Rules

This action evaluates the configured rules against the layer 4 source IP (conn.client_ip) of a connection. HTTP headers like X-Forwarded-For are never used.

Allow and Deny Conditions

A connection is allowed only if its source IP matches at least one of the allowed CIDRs and does not match any of the denied CIDRs.

Building CIDR Sets

The set of allowed and denied CIDRs are built from:

• The CIDRs specified in the allow and deny fields.
• The CIDRs belonging to the ngrok IP Policies specified in the ip_policies field.

Denied Connection Handling

If this action denies the connection:

• The connection is immediately closed.
• The upstream server is never reached.
• No further actions or policy rules in the policy configuration will be executed.

IPv6 Support

This action supports IPv6 addresses for all IP rules. You may use standard abbreviated notations such as "::/0".

Don't forget to create IPv6 rules. It is easy to test with only IPv4 and then suddenly things don't work as expected because you forgot to create IPv6 rules.

Examples

Restricting Access with Allow and Deny Lists

The following Traffic Policy configuration demonstrates how to restrict access to specific IP addresses using the restrict-ips action.

Example Traffic Policy Document

YAML

---
on_tcp_connect:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: true
          allow:
            - "1.1.1.1/32"
          deny:
            - "e680:5791:be4c:5739:d959:7b94:6d54:d4b4/128"

JSON

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": true,
            "allow": [
              "1.1.1.1/32"
            ],
            "deny": [
              "e680:5791:be4c:5739:d959:7b94:6d54:d4b4/128"
            ]
          }
        }
      ]
    }
  ]
}

This configuration will ensure that only requests from the IP 1.1.1.1 are allowed, while requests from the IP e680:5791:be4c:5739:d959:7b94:6d54:d4b4 are denied.

Example Request

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, the connection will be closed:

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.
Connection closed by foreign host.

Restricting Access with IP Policies

The following Traffic Policy configuration demonstrates how to restrict access using the restrict-ips action with IP Policies.

Example Traffic Policy Document

YAML

---
on_tcp_connect:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: true
          ip_policies:
            - "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"

JSON

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": true,
            "ip_policies": [
              "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
            ]
          }
        }
      ]
    }
  ]
}

This configuration will ensure that the IP Policies specified ipp_1yjqdrIBwgciY2I9zH2EelgBbJF are enforced against incoming traffic.

Example Request

If the request comes from an allowed IP, the response will proceed as normal. If the request comes from a denied IP, you will receive an HTTP 403 response:

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.
Connection closed by foreign host.

Test Restricting IPs

The following Traffic Policy configuration demonstrates how to test restricting IPs using the log action with the restrict-ips action and IP Policies.

Example Traffic Policy Document

YAML

---
on_tcp_connect:
  - actions:
      - type: "restrict-ips"
        config:
          enforce: false
          ip_policies:
            - "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
      - type: "log"
        config:
          metadata:
            message: "Restrict IPs action would be ${actions.ngrok.restrict_ips.action} for
              ${conn.client_ip}."
            matched_cidr: "${actions.ngrok.restrict_ips.matched_cidr}"
            error:
              code: "${actions.ngrok.restrict_ips.error.code}"
              message: "${actions.ngrok.restrict_ips.error.message}"

JSON

{
  "on_tcp_connect": [
    {
      "actions": [
        {
          "type": "restrict-ips",
          "config": {
            "enforce": false,
            "ip_policies": [
              "ipp_1yjqdrIBwgciY2I9zH2EelgBbJF"
            ]
          }
        },
        {
          "type": "log",
          "config": {
            "metadata": {
              "message": "Restrict IPs action would be ${actions.ngrok.restrict_ips.action} for ${conn.client_ip}.",
              "matched_cidr": "${actions.ngrok.restrict_ips.matched_cidr}",
              "error": {
                "code": "${actions.ngrok.restrict_ips.error.code}",
                "message": "${actions.ngrok.restrict_ips.error.message}"
              }
            }
          }
        }
      ]
    }
  ]
}

This configuration will test the incoming client IP against the specified IP Policy ipp_1yjqdrIBwgciY2I9zH2EelgBbJF without enforcing it, then log the result using the log action.

Example Request

The following request will be allowed and an event will be logged:

$ telnet 5.tcp.ngrok.io 22984

Trying...
Connected to 5.tcp.ngrok.io.

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

Name	Type	Description
actions.ngrok.restrict_ips.action	string	The resulting action for this action execution. Supported values are either allow or deny.
actions.ngrok.restrict_ips.matched_cidr	string	The CIDR that matched for the incoming client ip. This may be empty.
actions.ngrok.restrict_ips.error.code	string	Code for an error that occurred during the invocation of an action.
actions.ngrok.restrict_ips.error.message	string	Message for an error that occurred during the invocation of an action.