ROOT:partial$attributes.adoc

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).

Tip	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 several 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: P.id.matches("^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: R.attr.id.matches("^[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 || R.attr.id.matches("^[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

Note	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

Note

Duration values must be specified in one of the following units. Larger units like days, weeks or years are not supported because of ambiguity around their meaning due to factors such as daylight saving time transitions.

Suffix	Unit
`ns`	Nanoseconds
`us`	Microseconds
`ms`	Milliseconds
`s`	Seconds
`m`	Minutes
`h`	Hours

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

Note	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

Note	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`

Math

Function	Description	Example
`math.greatest`	Get the greatest valued number present in the arguments	`math.greatest([1, 3, 5]) == 5`
`math.least`	Get the least valued number present in the arguments	`math.least([1, 3, 5]) == 1`

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")`
`format`	Format a string with the given arguments	`"department_%s_%d".format(["marketing", 1])`
`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")

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

conditions.adoc

conditions.adoc

Conditions

Policy variables

Auxiliary Data

Operators

Durations

Hierarchies

IP Addresses

Lists and maps

Math

Strings

Timestamps

Files

conditions.adoc

Latest commit

History

conditions.adoc

File metadata and controls

Conditions

Policy variables

Auxiliary Data

Operators

Durations

Hierarchies

IP Addresses

Lists and maps

Math

Strings

Timestamps