Expressions

A policy is written with Common Expression Language (CEL) expressions to determine on which connections it is applicable. Each policy expression must evaluate to true in order for the policy's actions to take effect against a connection.

Variables

Attributes of the connection are exposed on the conn struct. The following variables are available using this struct:

Name	Type	Description
`conn.ClientIP`	string	The source IP of the client 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.ClientIP`

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

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

`conn.Geo.CountryCode`

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

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

`conn.Geo.Latitude`

The approximate latitude based on the client IP.

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.

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

`conn.Geo.Longitude`

The approximate longitude based on the client IP.

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

Attributes of the request are exposed on the req struct. The following variables are available using this struct:

Name	Type	Description
`req.ClientTLS.CertCN`	string	The subject common name of the client's leaf TLS certificate.
`req.ClientTLS.CipherSuite`	string	The cipher suite negotiated on the connection.
`req.ClientTLS.SNI`	string	The Server Name Indication extension sent by the client.
`req.ClientTLS.Version`	string	The TLS Version used on the connection.
`req.ContentLength`	int	The length of the content associated with the request.
`req.Cookies`	list	The list of http cookie objects provided in the request.
`req.Form`	map	The url-encoded form data of the request wherein a string key maps to a list of string values.
`req.Method`	string	The request method.
`req.URL`	string	The URL of the request.
`req.Params`	map	The query parameters of the request URL wherein a string key maps to a list of string values.
`req.Protocol`	string	The protocol version of the request.
`req.Host`	string	The host of the request.
`req.Location`	string	The 'Location' header of the request.
`req.Headers`	map	The headers of the request wherein a string key maps to a list of string values.
`req.Trailers`	map	The trailers of the request wherein a string key maps to a list of string values.

`req.ClientTLS.CertCN`

The subject common name of the client's leaf TLS certificate.

expressions:
  - "req.ClientTLS.CertCN.startsWith('example')"

`req.ClientTLS.CipherSuite`

The cipher suite negotiated on the connection.

expressions:
  - "req.ClientTLS.CipherSuite.contains('SHA256')"

`req.ClientTLS.SNI`

The Server Name Indication extension sent by the client.

expressions:
  - "req.ClientTLS.SNI.startsWith('domain')"

`req.ClientTLS.Version`

The TLS Version used on the connection.

expressions:
  - "req.ClientTLS.Version.contains('1.3')"

`req.ContentLength`

The length of the content associated with the request.

expressions:
  - "req.ContentLength > 10000000"

`req.Method`

The request method.

expressions:
  - "req.Method == 'POST' || req.Method == 'PUT'"

`req.Cookies`

The list of http cookie objects provided in the request.

expressions:
  - "size(req.Cookies) > 0"

`req.Form`

The url-encoded form data of the request wherein a string key maps to a list of string values.

expressions:
  - "'val' in req.Form['key']"

`req.URL`

The URL of the request.

expressions:
  - "req.URL.contains('/admin')"

`req.Params`

The query parameters of the request URL wherein a string key maps to a list of string values.

expressions:
  - "'bar' in req.Params['foo']"

`req.Protocol`

The protocol version of the request.

expressions:
  - "`req.Protocol == 'HTTP/1.1'"

`req.Host`

The host of the request.

expressions:
  - "req.Host.contains(':8080')"

`req.Location`

The 'Location' header of the request.

expressions:
  - "req.Location == '/index.html'"

`req.Headers`

The headers of the request wherein a string key maps to a list of string values.

expressions:
  - "'fizz' in req.Headers['baz']"

`req.Trailers`

The trailers of the request wherein a string key maps to a list of string values.

expressions:
  - "'fizz' in req.Trailers['baz']"

Attributes of the response are exposed on the res struct. The following variables are available for use on outbound policy expressions using this struct:

Name	Type	Description
`res.ContentLength`	int	The length of the content associated with the response.
`res.Cookies`	list	The list of http cookie objects provided in the response.
`res.Headers`	map	The headers of the response wherein a string key maps to a list of string values.
`res.Location`	string	The 'Location' header of the response.
`res.ServerTLS.CertCN`	string	The subject common name of the leaf TLS certificate.
`res.ServerTLS.CipherSuite`	string	The cipher suite negotiated on the connection.
`res.ServerTLS.SNI`	string	The Server Name Indication extension sent by the client.
`res.ServerTLS.Version`	string	The TLS Version used on the connection.
`res.StatusCode`	string	The status code of the response.
`res.Trailers`	map	The trailers of the response wherein a string key maps to a list of string values.

`res.ContentLength`

The length of the content associated with the response.

expressions:
  - "res.ContentLength != 0"

`res.Cookies`

The list of http cookie objects provided in the response.

expressions:
  - "size(req.Cookies) > 0"

`res.Headers`

The headers of the response wherein a string key maps to a list of string values.

expressions:
  - "'fizz' in res.Headers['baz']"

`res.Location`

The 'Location' header of the response.

expressions:
  - "res.Location == '/index.html'"

`res.ServerTLS.CertCN`

The subject common name of the leaf TLS certificate.

expressions:
  - "res.ClientTLS.CertCN.startsWith('example')"

`res.ServerTLS.CipherSuite`

The cipher suite negotiated on the connection.

expressions:
  - "res.ClientTLS.CipherSuite.contains('SHA256')"

`res.ServerTLS.SNI`

The Server Name Indication extension sent by the client.

expressions:
  - "res.ClientTLS.SNI.startsWith('domain')"

`res.ServerTLS.Version`

The TLS Version used on the connection.

expressions:
  - "res.ClientTLS.Version.contains('1.3')"

`res.StatusCode`

The status code of the response.

expressions:
  - "res.StatusCode >= '300'"

`res.Trailers`

The trailers of the response wherein a string key maps to a list of string values.

expressions:
  - "'fizz' in res.Trailers['baz']"

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
`hasReqHeader(string)`	bool	Returns true or false if the provided header key is present on the request.
`getReqHeader(string)`	list	Returns a list of header values for the provided key on the request.
`hasQueryParam(string)`	bool	Returns true or false if the specified query parameter key is part of the request URL.
`getQueryParam(string)`	list	Returns a list of the query parameter values from the request URL for the specified key.
`hasReqCookie(string)`	bool	Returns true or false if a cookie exists on the request with the specified name.
`getReqCookie(string)`	bool	Returns the cookie struct for the specified cookie name, if it exists on the request.
`hasResHeader(string)`	bool	Returns true or false if the provided header key is present on the response.
`getResHeader(string)`	list	Returns a list of header values for the provided key on the response.
`hasResCookie(string)`	bool	Returns true or false if a cookie exists on the response with the specified name.
`getResCookie(string)`	bool	Returns the cookie struct for the specified cookie name, if it exists on the response.

`hasReqHeader(string)`

Returns true or false if the provided header key is present on the request.

expressions:
  - "hasReqHeader('x-version-id')"

`getReqHeader(string)`

Returns a list of header values for the provided key on the request.

expressions:
  - "getReqHeader('User-Agent').exists(v, v.matches('(?i)google-images'))"

Expressions

Variables​

conn.ClientIP​

conn.Geo.CountryCode​

conn.Geo.Latitude​

conn.Geo.LatLongRadiusKm​

conn.Geo.Longitude​

req.ClientTLS.CertCN​

req.ClientTLS.CipherSuite​

req.ClientTLS.SNI​

req.ClientTLS.Version​

req.ContentLength​

req.Method​

req.Cookies​

req.Form​

req.URL​

req.Params​

req.Protocol​

req.Host​

req.Location​

req.Headers​

req.Trailers​

res.ContentLength​

res.Cookies​

res.Headers​

res.Location​

res.ServerTLS.CertCN​

res.ServerTLS.CipherSuite​

res.ServerTLS.SNI​

res.ServerTLS.Version​

res.StatusCode​

res.Trailers​

Macros​

hasReqHeader(string)​

getReqHeader(string)​