CEL matcher language reference

Stay organized with collections Save and categorize content based on your preferences.

Common Expression Language (CEL) is an open source non-Turing complete language that implements common semantics for expression evaluation. Cloud SWG uses a subset of CEL conditions to make boolean authorization decisions based on attribute data. In general, a condition expression consists of one or more statements that are joined by logical operators (&&, ||, or !). Each statement expresses an attribute-based control rule that applies to the role binding and ultimately determines whether access is allowed.

Attributes

Session attributes and application attributes are used when defining Cloud SWG policies to describe either the session attributes or the application attributes that a policy applies to.

Session attributes, described by SessionMatcher, apply to session-specific attributes, such as the source or destination IP address, hosts, or IP range. Application attributes, described by ApplicationMatcher, apply to application attributes, such as request headers, HTTP request method, or request path.

Available attributes in SessionMatcher and ApplicationMatcher

The following table describes attributes that apply to both SessionMatcher and ApplicationMatcher.

Attribute Attribute type Description
source.ip string The IP address of the client that sent the request.
source.port integer The client port that sent the request.
destination.port integer The upstream port that the gateway is sending traffic to.
host() string The host value used for DNS resolution and upstream connections. This does not include the port. The value is determined by the following:
  • Raw HTTP requests: the Host header
  • Proxy tunnel HTTP CONNECT requests: The CONNECT target
connectHost() string The HTTP CONNECT target for the explicit proxy tunnel. We recommend using host() in most cases. This does not include the port.
inUrlList(HOST_OR_URL, NAMED_LIST) boolean True if HOST_OR_URL is present in the provided named list NAMED_LIST—for example:
  • inUrlList(host(), 'projects/1234/locations/us-east1/urlLists/allowed-repos')
  • inUrlList(request.url(), 'projects/1234/locations/us-east1/urlLists/allowed-repos')
inIpRange(IP_ADDRESS,
IP_RANGE)
boolean True if IP_ADDRESS is contained within the IP_RANGE such as inIpRange(source.ip, '1.2.3.0/24'). Subnet masks for IPv6 addresses cannot be larger than /64.

Attributes available only to ApplicationMatcher

The following table describes attributes that apply only to ApplicationMatcher.

Attribute Attribute type Description
request.headers map A string-to-string map of the HTTP request headers. If a header contains multiple values, the value in this map is a comma-separated string of all of the values of the header. The keys in this map are all lowercase.
request.method string The HTTP Request method, such as GET or POST.
request.host string

Convenience equivalent to request.headers['host'].

We recommend using host() in most cases.

request.path string The requested HTTP URL path.
request.query string

The HTTP URL query in the format of name1=value&name2=value2, as it appears in the first line of the HTTP request.

No decoding is performed.

request.scheme string The HTTP URL scheme, such as HTTP or HTTPS. Values for this attribute are all lowercase.
request.url() string

Convenience for host() + request.path.

This doesn't include the port and uses a host value that might differ from the host header.

request.useragent() string Convenience equivalent to request.headers['user-agent'].

Operators

Cloud SWG supports several operators that can be used to build complex logic expressions from simple expression statements. Cloud SWG supports logical operators, such as &&, ||, and !, and string manipulation operators, such as x.contains('y').

The logical operators let you verify multiple variables in a conditional expression. For example, request.method == 'GET' && host().matches('.*\.example.com') joins two statements, and requires both statements to be True in order to produce an overall result of True.

The string manipulation operators match strings or substrings that you define, and let you develop rules to control access to resources without listing every possible combination.

Logical operators

The following table describes the logical operators that Cloud SWG supports.

Example expression Description
x == "foo" Returns True if x is equal to the constant string literal argument.
x == R"fo'o" Returns True if x is equal to the given raw string literal that does not interpret escape sequences. Raw string literals are convenient for expressing strings that the code must use to escape sequence characters.
x == y Returns True if x is equal to y.
x != y Returns True if x is not equal to y.
x + y Returns the concatenated string xy.
x && y Returns True if both x and y are True.
x || y Returns True if x, y, or both are True.
!x Returns True if the boolean value x is False, or returns False if the boolean value x is True.
x.lower() Returns the lowercase value of the string x.
x.upper() Returns the uppercase value of the string x.
m['k'] If key k is present, returns the value at key k in the string-to-string map m. If key k is not present, returns an error that causes the rule under evaluation to not match.
int(x) Converts the string result of x to an int type. The converted string can be used for integer comparison with standard arithmetic operators such as > and <=. This works only for values that can be integers.

String manipulation operators

The following table describes the string manipulation operators that Cloud SWG supports.

Expression Description
x.contains(y) Returns True if the string x contains the substring y.
x.startsWith(y) Returns True if the string x begins with the substring y.
x.endsWith(y) Returns True if the string x ends with the substring y.
x.matches(y)

Returns True if the string x matches the specified RE2 pattern y.

The RE2 pattern is compiled using the RE2::Latin1 option that disables Unicode features.