Expressions

Traffic Policy module enables you to filter inbound and outbound traffic with Common Expression Language (CEL) expressions. Each policy rule expression must evaluate to true in order for the rule's actions to take effect against traffic. In addition to CEL's built-in functions and macros we provide additional variables for the connection along with custom macros.

Connection Variables

The following connection variables are available on the conn struct:

Name	Type	Description
conn.ClientIP	string	The source IP of the TLS connection to the ngrok endpoint.
conn.Geo.CountryCode	string	The two-letter ISO country code based on the client IP.
conn.Geo.Latitude	string	The approximate latitude based on the client IP.
conn.Geo.LatLongRadiusKm	string	The radius in kilometers around the latitude and longitude where the client IP is likely to originate.
conn.Geo.Longitude	string	The approximate longitude based on the client IP.
conn.TLS.CertCN	string	The subject common name of the leaf TLS certificate
conn.TLS.CipherSuite	string	The cipher suite negotiated on the connection.
conn.TLS.SNI	string	The Server Name Indication extension sent.
conn.TLS.Version	string	The TLS Version used on the connection.

conn.ClientIP

The source IP of the TLS connection to the ngrok endpoint as a string.

YAML

expressions:
  - conn.ClientIP in ['::1', '127.0.0.1']

JSON

{
  "expressions": [
    "conn.ClientIP in ['::1', '127.0.0.1']"
  ]
}

conn.Geo.CountryCode

The two-letter ISO country code based on the client IP.

YAML

expressions:
  - conn.Geo.CountryCode != 'US'

JSON

{
  "expressions": [
    "conn.Geo.CountryCode != 'US'"
  ]
}

conn.Geo.Latitude

The approximate latitude based on the client IP.

YAML

expressions:
  - double(conn.Geo.Latitude) >= 45.0

JSON

{
  "expressions": [
    "double(conn.Geo.Latitude) >= 45.0"
  ]
}

conn.Geo.LatLongRadiusKm

The radius in kilometers around the latitude and longitude where the client IP is likely to originate.

YAML

expressions:
  - conn.Geo.LatLongRadiusKm <= '20'

JSON

{
  "expressions": [
    "conn.Geo.LatLongRadiusKm <= '20'"
  ]
}

conn.Geo.Longitude

The approximate longitude based on the client IP.

YAML

expressions:
  - double(conn.Geo.Longitude) <= -93.0

JSON

{
  "expressions": [
    "double(conn.Geo.Longitude) <= -93.0"
  ]
}

conn.TLS.CertCN

The subject common name of the leaf TLS certificate.

YAML

expressions:
  - conn.TLS.CertCN.startsWith('example')

JSON

{
  "expressions": [
    "conn.TLS.CertCN.startsWith('example')"
  ]
}

conn.TLS.CipherSuite

The cipher suite negotiated on the connection.

YAML

expressions:
  - conn.TLS.CipherSuite.contains('SHA256')

JSON

{
  "expressions": [
    "conn.TLS.CipherSuite.contains('SHA256')"
  ]
}

conn.TLS.SNI

The Server Name Indication extension sent.

YAML

expressions:
  - conn.TLS.SNI.startsWith('domain')

JSON

{
  "expressions": [
    "conn.TLS.SNI.startsWith('domain')"
  ]
}

conn.TLS.Version

The TLS Version used on the connection.

YAML

expressions:
  - conn.TLS.Version.contains('1.3')

JSON

{
  "expressions": [
    "conn.TLS.Version.contains('1.3')"
  ]
}

---

Macros

CEL provides a set of predefined macros that can also be used in policy expressions. For convenience, the following custom macros are also supported:

Name	Return Type	Description
inCidrRange(ip string, cidr string)	bool	Returns true or false if the provided IP address falls within the provided CIDR range. Returns false if the provided CIDR range is invalid.
inCidrRanges(ip string, cidrs list)	bool	Returns true or false if the provided IP address falls within any of the provided CIDR ranges. Ignores any provided CIDR ranges that are invalid.

inCidrRange(ip string, cidr string)

Returns true or false if the provided IP address falls within the provided CIDR range. Returns false if the provided CIDR range is invalid.

YAML

expressions:
  - inCidrRange(conn.ClientIP, '66.249.66.1/24')

JSON

{
  "expressions": [
    "inCidrRange(conn.ClientIP, '66.249.66.1/24')"
  ]
}

inCidrRanges(ip string, cidrs list)

Returns true or false if the provided IP address falls within any of the provided CIDR ranges. Ignores any provided CIDR ranges that are invalid.

YAML

expressions:
  - inCidrRanges(conn.ClientIP, ['66.249.66.1/24', '2001:4860::/32'])

JSON

{
  "expressions": [
    "inCidrRanges(conn.ClientIP, ['66.249.66.1/24', '2001:4860::/32'])"
  ]
}