Conditions

A powerful feature of Cerbos policies is the ability to define conditions that are evaluated against the data provided in the request. Conditions are written using the Common Expression Language (CEL).

Cerbos ships with an interactive REPL that can be used to experiment with writing CEL conditions. It can be started by running cerbos repl. See the REPL documentation for more information.
CEL condition
condition:
  match:
    all:
      of:
        - expr: request.resource.attr.status == "PENDING_APPROVAL"
        - expr: "GB" in request.resource.attr.geographies

Within a condition block you have access to serveral special variables:

request

The entire request object containing data provided about the resource and the principal. Use dots to access nested fields. For example, the expression to get the principal’s department attribute is request.principal.attr.department.

variables

Access variables declared in the variables section of the policy.

P

An alias for request.principal for accessing the principal object.

R

An alias for request.resource for accessing the resource object.

V

An alias for variables for accessing the policy variables object.

Every condition expression must evaluate to a boolean true/false value. You can combine complex expressions together in a single condition block by using the all, any, or none operators.

Single boolean expression
condition:
  match:
    expr: matches(P.id, "^dev_.*")
all operator: all expressions must evaluate to true (logical AND)
condition:
  match:
    all:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"
any operator: only one of the expressions has to evaluate to true (logical OR)
condition:
  match:
    any:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"
none operator: none of the expressions should evaluate to true (logical negation)
condition:
  match:
    none:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"
Nesting operators
condition:
  match:
    all:
      of:
        - expr: R.attr.status == "DRAFT"
        - any:
            of:
              - expr: R.attr.dev == true
              - expr: matches(R.attr.id, "^[98][0-9]+")
        - none:
            of:
              - expr: R.attr.qa == true
              - expr: R.attr.canary == true

The above nested block is equivalent to the following:

condition:
  match:
    expr: |-
      (R.attr.status == "DRAFT" &&
        (R.attr.dev == true || matches(R.attr.id, "^[98][0-9]+")) &&
        !(R.attr.qa == true || R.attr.canary == true))

Policy variables

If your policy repeats the same expression in multiple conditions, you can declare it in the variables section of a policy and refer in the conditions to avoid a repeat.

---
apiVersion: "api.cerbos.dev/v1"
variables:
  is_dev_record: request.resource.attr.dev_record == true
principalPolicy:
  principal: daffy_duck
  version: "dev"
  rules:
    - resource: leave_request
      actions:
        - name: dev_record_wildcard
          action: "*"
          condition:
            match:
              expr: variables.is_dev_record
          effect: EFFECT_ALLOW
    - resource: employee_profile
      actions:
        - name: view_employee_profile
          action: "*"
          condition:
            match:
              all:
                of:
                  - expr: V.is_dev_record
                  - expr: request.resource.attr.public == true
          effect: EFFECT_ALLOW
    - resource: salary_record
      actions:
        - action: "*"
          effect: EFFECT_DENY

Auxiliary Data

If you have auxiliary data sources configured, they can be accessed using request.aux_data.

Accessing JWT claims
"cerbie" in request.aux_data.jwt.aud && request.aux_data.jwt.iss == "cerbos"

Operators

CEL has many builtin functions and operators. The fully up-to-date list can be found at https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions.
Operator Description

!

Logical negation (NOT)

-

Subtraction/numeric negation

!=

Unequals

%

Modulo

&&

Logical AND

||

Logical OR

*

Multiplication

+

Addition/concatenation

/

Division

⇐

Less than or equal to

<

Less than

==

Equals

>=

Greater than or equal to

>

Greater than

in

Membership in lists or maps

Durations

Test data
...
"resource": {
  "kind": "leave_request",
  "attr": {
    "cooldownPeriod": "3750s",
    "lastAccessed": "2021-04-20T10:00:20.021-05:00"
  }
}
...
Function Description Example

duration

Convert a string to a duration. The string must contain a valid duration suffixed by one of ns, us, ms, s, m or h. E.g. 3750s

duration(R.attr.cooldownPeriod).getSeconds == 3750

getHours

Get hours from a duration

duration(R.attr.cooldownPeriod).getHours() == 1

getMilliseconds

Get milliseconds from a duration

duration(R.attr.cooldownPeriod).getMilliseconds() == 3750000

getMinutes

Get minutes from a duration

duration(R.attr.cooldownPeriod).getMinutes() == 62

getSeconds

Get seconds from a duration

duration(R.attr.cooldownPeriod).getSeconds() == 3750

timeSince

Time elapsed since the given timestamp to current time on the server. This is a Cerbos extension to CEL

timestamp(R.attr.lastAccessed).timeSince() > duration("1h")

Hierarchies

The hierarchy functions are Cerbos-specific extensions to CEL.
Test data
...
"principal": {
  "id": "john",
  "roles": ["employee"],
  "attr": {
    "scope": "foo.bar.baz.qux",
  }
},
"resource": {
  "kind": "leave_request",
  "attr": {
    "scope": "foo.bar",
  }
}
...
Function Description Example

hierarchy

Convert a dotted string or a string list to a hierarchy

hierarchy("a.b.c") == hierarchy(["a","b","c"])

hierarchy

Convert a delimited string representation to a hierarchy

hierarchy("a:b:c", ":").size() == 3

ancestorOf

Returns true if the first hierarchy shares a common prefix with the second hierarchy

hierarchy("a.b").ancestorOf(hierarchy("a.b.c.d")) == true

commonAncestors

Returns the common ancestor hierarchy

hierarchy(R.attr.scope).commonAncestors(hierarchy(P.attr.scope)) == hierarchy("foo.bar")

descendentOf

Mirror function of ancestorOf

hierarchy("a.b.c.d").descendentOf(hierarchy("a.b")) == true

immediateChildOf

Returns true if the first hierarchy is a first-level child of the second hierarchy

hierarchy("a.b.c").immediateChildOf(hierarchy("a.b")) == true && hierarchy("a.b.c.d").immediateChildOf(hierarchy("a.b")) == false

immediateParentOf

Mirror function of immediateChildOf

hierarchy("a.b").immediateParentOf(hierarchy("a.b.c")) == true && hierarchy("a.b").immediateParentOf(hierarchy("a.b.c.d")) == false

overlaps

Returns true if one of the hierarchies is a prefix of the other

hierarchy("a.b.c").overlaps(hierarchy("a.b.c.d.e")) == true && hierarchy("a.b.x").overlaps(hierarchy("a.b.c.d.e")) == false

siblingOf

Returns true if both hierarchies share the same parent

hierarchy("a.b.c").siblingOf(hierarchy("a.b.d")) == true

size

Returns the number of levels in the hierarchy

hierarchy("a.b.c").size() == 3

[]

Access a level in the hierarchy

hierarchy("a.b.c.d")[1] == "b"

IP Addresses

The IP address functions are Cerbos-specific extensions to CEL.
Test data
...
"principal": {
  "id": "elmer_fudd",
  "attr": {
    "ipv4Address": "192.168.0.10",
    "ipv6Address": "2001:0db8:0000:0000:0000:0000:1000:0000"
  }
}
...
Function Description Example

inIPAddrRange

Check whether the IP address is in the range defined by the CIDR

P.attr.ipv4Address.inIPAddrRange("192.168.0.0/24") && P.attr.ipv6Address.inIPAddrRange("2001:db8::/48")

Lists and maps

Test data
...
"principal": {
  "id": "elmer_fudd",
  "attr": {
    "id": "125",
    "teams": ["design", "communications", "product", "commercial"],
    "clients": {
      "acme": {"active": true},
      "bb inc": {"active": true}
    }
  }
}
...
Operator/Function Description Example

+

Concatenates lists

P.attr.teams + ["design", "engineering"]

[]

Index into a list or a map

P.attr.teams[0] == "design" && P.attr.clients["acme"]["active"] == true

all

Check whether all elements in a list match the predicate

P.attr.teams.all(t, size(t) > 3)

except

Produces the set difference of two lists

P.attr.teams.except(["design", "engineering"]) == ["communications", "product", "commercial"]

exists

Check whether at least one element matching the predicate exists

P.attr.teams.exists(t, t.startsWith("comm"))

exists_one

Check that only one element matching the predicate exists

P.attr.teams.exists_one(t, t.startsWith("comm")) == false

filter

Filter a list using the predicate

size(P.attr.teams.filter(t, t.matches("^comm"))) == 2

hasIntersection

Checks whether the lists have at least one common element

hasIntersection(["design", "engineering"], P.attr.teams)

in

Check whether the given element is contained in the list or map

("design" in P.attr.teams) && ("acme" in P.attr.clients)

intersect

Produces the set intersection of two lists

intersect(["design", "engineering"], P.attr.teams) == ["design"]

isSubset

Checks whether the list is a subset of another list

["design", "engineering"].isSubset(P.attr.teams) == false

map

Transform each element in a list

"DESIGN" in P.attr.teams.map(t, t.upperAscii())

size

Number of elements in a list or map

size(P.attr.teams) == 4 && size(P.attr.clients) == 2

Strings

Test data
...
"resource": {
  "kind": "leave_request",
  "attr": {
    "id": "125",
    "department": "marketing"
  }
}
...
Function Description Example

base64.encode

Encode as base64

base64.encode(bytes("hello")) == "aGVsbG8="

base64.decode

Decode base64

base64.decode("aGVsbG8=") == bytes("hello")

charAt

Get the character at given index

R.attr.department.chartAt(1) == 'a'

contains

Check whether a string contains the given substring

R.attr.department.contains("arket")

endsWith

Check whether a string has the given suffix

R.attr.department.endsWith("ing")

indexOf

Index of the first occurrence of the given character

R.attr.department.indexOf('a') == 1

lastIndexOf

Index of the last occurrence of the given character

R.attr.department.lastIndexOf('g') == 8

lowerAscii

Convert ASCII characters to lowercase

"MARKETING".lowerAscii() == R.attr.department

matches

Check whether a string matches a RE2 regular expression

R.attr.department.matches("^[mM].*g$")

replace

Replace all occurrences of a substring

R.attr.department.replace("market", "engineer") == "engineering"

replace

Replace with limits. Limit 0 replaces nothing, -1 replaces all.

"engineering".replace("e", "a", 1) == "angineering" && "engineering".replace("e", "a", -1) == "anginaaring"

size

Get the length of the string

size(R.attr.department) == 9

split

Split a string using a delimiter

"a,b,c,d".split(",")[1] == "b"

split

Split a string with limits. Limit 0 returns an empty list, 1 returns a list containing the original string.

"a,b,c,d".split(",", 2)[1] == "b,c,d"

startsWith

Check whether a string has the given prefix

R.attr.department.startsWith("mark")

substring

Selects a substring from the string

R.attr.department.substring(4) == "eting" && R.attr.department.substring(4, 6) == "et"

trim

Remove whitespace from beginning and end

" marketing ".trim() == "marketing"

upperAscii

Convert ASCII characters to uppercase

R.attr.department.upperAscii() == "MARKETING"

Timestamps

Test data
...
"resource": {
  "kind": "leave_request",
  "attr": {
    "lastAccessed": "2021-04-20T10:00:20.021-05:00",
    "lastUpdateTime": "2021-05-01T13:34:12.024Z",
  }
}
...
Function Description Example

timestamp

Convert an RFC3339 formatted string to a timestamp

timestamp(R.attr.lastAccessed).getFullYear() == 2021

getDate

Get day of month from a timestamp

timestamp(R.attr.lastAccessed).getDate() == 20

getDayOfMonth

Get day of month from a timestamp. Returns a zero-based value

timestamp(R.attr.lastAccessed).getDayOfMonth() == 19

getDayOfWeek

Get day of week from a timestamp. Returns a zero-based value where Sunday is 0

timestamp(R.attr.lastAccessed).getDayOfWeek() == 2

getDayOfYear

Get day of year from a timestamp. Returns a zero-based value

timestamp(R.attr.lastAccessed).getDayOfYear() == 109

getFullYear

Get full year from a timestamp

timestamp(R.attr.lastAccessed).getFullYear() == 2021

getHours

Get hours from a timestamp

timestamp(R.attr.lastAccessed).getHours() == 10

getMilliseconds

Get milliseconds from a timestamp

timestamp(R.attr.lastAccessed).getMilliseconds() == 21

getMinutes

Get minutes from a timestamp

timestamp(R.attr.lastAccessed).getMinutes() == 5

getMonth

Get month from a timestamp. Returns a zero-based value where January is 0

timestamp(R.attr.lastAccessed).getMonth() == 3

getSeconds

Get seconds from a timestamp

timestamp(R.attr.lastAccessed).getSeconds() == 20

now

Current time on the server. This is a Cerbos extension to CEL

now() > timestamp(R.attr.lastAccessed)

timeSince

Time elapsed since the given timestamp to current time on the server. This is a Cerbos extension to CEL

timestamp(R.attr.lastAccessed).timeSince() > duration("1h")
Example: Assert that more than 36 hours has elapsed between last access time and last update time
timestamp(R.attr.lastUpdateTime) - timestamp(R.attr.lastAccessed) > duration("36h")
Example: Add a duration to a timestamp
timestamp(R.attr.lastUpdateTime) + duration("24h") == timestamp("2021-05-02T13:34:12.024Z")