# Conditions

|     |     |
| --- | --- |
|   | This documentation is for<br>a previous<br>version of Cerbos. Choose 0.53.0 from the version picker at the top right or navigate to [https://docs.cerbos.dev](https://docs.cerbos.dev/) for the latest version. |

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)](https://github.com/google/cel-spec/blob/master/doc/intro.md).

|     |     |
| --- | --- |
|   | 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](https://docs.cerbos.dev/cerbos/0.40.0/cli/cerbos#repl) for more information. |

Every condition expression must evaluate to a boolean true/false value. A condition block in a policy can contain either a single condition expression, or multiple expressions combined using the `all`, `any`, or `none` operators. These logical operators may be nested.

Condition block

```yaml
condition:
  match:
    all:
      of:
        - expr: request.resource.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in request.resource.attr.geographies
```

## Top-level identifiers

Within a condition expression, you have access to several top-level identifiers:

`request`

Data provided in the check or plan request (principal, resource, and auxiliary data).

`runtime`

Additional data computed while evaluating the policy.

`variables`

Variables declared in the [`variables` section of the policy](https://docs.cerbos.dev/cerbos/0.40.0/policies/variables#variables).

`constants`

Variables declared in the [`constants` section of the policy](https://docs.cerbos.dev/cerbos/0.40.0/policies/variables#constants).

`globals`

Global variables declared in the [policy engine configuration](https://docs.cerbos.dev/cerbos/0.40.0/configuration/engine#globals).

There are also single-letter aliases available to allow you to write terser expressions:

`P`

`request.principal`

`R`

`request.resource`

`V`

`variables`

`C`

`constants`

`G`

`globals`

The `request` object

```yaml
request:
  principal: (1)
    id: alice (2)
    roles: (3)
      - employee
    attr: (4)
      geography: GB

resource: (5)
    kind: leave_request (6)
    id: XX125 (7)
    attr: (8)
      owner: alice

auxData: (9)
    jwt: (10)
      iss: acme.corp
```

|     |     |
| --- | --- |
| **1** | The principal whose permissions are being checked. |
| **2** | ID of the principal. |
| **3** | Static roles that are assigned to the principal by your identity management system. |
| **4** | Free-form context data about the principal. |
| **5** | The resource on which the principal is performing actions. |
| **6** | Resource kind. |
| **7** | ID of the resource instance. |
| **8** | Free-form context data about the resource instance. |
| **9** | [Auxiliary data sources](https://docs.cerbos.dev/cerbos/0.40.0/configuration/auxdata). |
| **10** | JWT claims. |

The `runtime` object

```yaml
runtime:
  effectiveDerivedRoles: (1)
    - owner
    - gb_employee
```

|     |     |
| --- | --- |
| **1** | [Derived roles](https://docs.cerbos.dev/cerbos/0.40.0/policies/derived_roles) that were assigned to to the principal by Cerbos while evaluating the policy. This is only populated in expressions in resource policies, and only includes derived roles that are referenced in at least one policy rule. |

## Expressions and blocks

Single boolean expression

```yaml
condition:
  match:
    expr: P.id.matches("^dev_.*")
```

`all` operator: all expressions must evaluate to true (logical AND)

```yaml
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)

```yaml
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)

```yaml
condition:
  match:
    none:
      of:
        - expr: R.attr.status == "PENDING_APPROVAL"
        - expr: >
            "GB" in R.attr.geographies
        - expr: P.attr.geography == "GB"
```

Nesting operators

```yaml
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:

```yaml
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))
```

Quotes in expressions

Single and double quotes have special meanings in YAML. To avoid parsing errors when your expression contains quotes, use the YAML block scalar syntax or wrap the expression in parentheses.

```yaml
expr: >
  "GB" in R.attr.geographies
```

```yaml
expr: ("GB" in R.attr.geographies)
```

## Policy variables

To avoid duplication in condition expressions, you can define [variables and constants in policies](https://docs.cerbos.dev/cerbos/0.40.0/policies/variables).

## Auxiliary data

If you have [auxiliary data sources configured](https://docs.cerbos.dev/cerbos/0.40.0/configuration/auxdata), they can be accessed using `request.auxData`.

Accessing JWT claims

```yaml
"cerbie" in request.auxData.jwt.aud && request.auxData.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](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 |
| `? :` | Ternary condition (if-then-else) |

## Durations

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

```json
...
"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

```json
...
"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` |

## IP addresses

|     |     |
| --- | --- |
|   | The IP address functions are Cerbos-specific extensions to CEL. |

Test data

```json
...
"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

```json
...
"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

```json
...
"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.charAt(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](https://github.com/google/re2/wiki/Syntax) 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

```json
...
"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

```yaml
timestamp(R.attr.lastUpdateTime) - timestamp(R.attr.lastAccessed) > duration("36h")
```

Example: Add a duration to a timestamp

```yaml
timestamp(R.attr.lastUpdateTime) + duration("24h") == timestamp("2021-05-02T13:34:12.024Z")
```