Policies

Overview

The Policy module allows you to configure a series of inbound and outbound policies that can be used to influence and control traffic to and from your upstream service.

Policies are composed of zero-to-many expressions that filter the traffic on which they apply and one-to-many actions which will be taken against the traffic.

Example Usage

Agent CLI

ngrok http 80 --policy-config /path/to/policy-config.yml

Agent Config

tunnels:
  example:
    proto: http
    addr: 80
    policies:
      inbound:
        - name: FooBarParamNotFound
          expressions:
            - "'bar' in getQueryParam('foo')"
          actions:
            - type: "custom-response"
              config:
                status_code: 404
                content_type: text/plain
                content: not found
            - type: "log"
              config:
                metadata:
                  message: "foobar request was made"
        - name: "BazCookieForLargeRequests"
          expressions:
            - "!hasReqCookie('baz')"
            - "req.ContentLength > 5000"
          actions:
            - type: deny
      outbound:
        - name: "RemoveTraceHeader"
          actions:
            - type: remove-headers
              config:
                headers:
                  - internal-trace-id

Behavior

Policies are evaluated sequentially in the order they are configured with inbound policies taking effect before the upstream server is reached and outbound policies taking effect after the upstream server responds. Whether or not a policy's actions are performed is determined at runtime.

Expression Evaluation

Policy expressions are a set of Common Expression Language (CEL) expressions that must evaluate to true in order for a policy actions to take effect. There is no behavioral difference between adding multiple expressions to a policy or having one single expression with multiple statements logically conjoined (&&) together.

If no expressions are specified on a policy, the actions will always take effect.

Action Execution

If a policy's expressions are evaluated as a match against a connection, the policy's actions will be executed. If multiple actions are defined on a policy, the actions will execute sequentially.

Edges

Policies is an HTTPS Edge module which can be applied to Routes.

Policies can be configured vai the ngrok dashboard or API.

//todo add api reference