Getting Started Using CEL
Common Expression Language (CEL) is a simple expression language used by Secureworks® Taegis™ Automation. CEL provides simple, consistent, and powerful functionality to manipulate data in Connectors, Templates, Playbook triggers, and Playbook inputs. For more information, see the official Google CEL documentation.
Usage ⫘
An expression is always supported by using the ${}
syntax. The ${}
syntax can be omitted, if preferred, when using expressions within a playbook template or trigger filter for convenience. Note that the ${}
syntax must be used when authoring connector definitions.
Example:
Expression:
${'Hello World'}
Output:
Hello World
Find further examples at Common Expression Language Examples.
Tip
The CEL Helper displays where applicable to provide common CEL expressions for use in automation configurations.
CEL Helper
You can also use CEL Explorer to test CEL expressions against a specific type of input so that you can see the outcome of the expression while completing your configuration. For more information, see CEL Explorer.
Data Types ⫘
CEL is strongly-typed and supports the following data types:
Data Type | Description | Example |
---|---|---|
int |
64-bit signed integers | |
uint |
64-bit unsigned integers | |
double |
64-bit IEEE floating-point numbers | |
bool |
Booleans (true or false ) |
|
string |
Strings of Unicode code points | |
bytes |
Byte sequences | |
list |
Lists of values | [1,2,3] |
map |
Associative arrays with int , uint , bool , or string keys |
{'key':'value'} |
null_type |
The value null | |
message names | Protocol buffer messages | |
type |
Values representing the types in the first column | string |
In many cases, a data type can be converted using built-in macros: int()
, uint()
, double()
, string()
, list()
, map()
, bool()
, bytes()
. For example, to convert a number to a string:
Expression:
${ string(8) }
Output:
8
Expression:
${ type(string(8)) }
Output:
string
In most cases, defining the value of a variable also sets the data type:
Expression:
${ {'key':'value'} }
Output:
a map data type, with a single key called "key" and a value of "value"
Expression:
${ [1,2,3] }
Output:
a list data type, with the values 1, 2, and 3
Expression:
${ [] }
Output:
an empty list
Expression:
${ 'this is a string' }
Output:
this is a string
Accessing Data ⫘
Data can be accessed by referencing the variable name:
Expression:
${myvar}
Data in a map can be accessed via one of the following methods (the expressions return the same result):
Expression:
${map_var.map_key}
Expression:
${map_var['map_key']}
Output:
the value associated with the key map_key in the map_var map variable
List elements can be accessed if you know the element order (zero-based):
Expression:
${mylist[0]}
Output:
the value of the first element in the mylist list variable
Conditionals ⫘
CEL does not support a traditional if
, then
, else
syntax, but it does support a ternary conditional. A ternary is a shortened if
, then
, else
that has the following structure: <if> ? <then> : <else>
. Where <if>
is any expression that evaluates to a true/false boolean value. <then>
can be any expression and will be returned if the condition is true. <else>
can be any expression and will be returned if the condition is false. Note that the data type of the <then>
and <else>
values must match.
Expression:
${ int_val > 3 ? 'int_val is greater than 3' : 'int_val is less than 3' }
Output (int_val=4):
int_val is greater than 3
Output (int_val=2):
int_val is less than 3
Macros ⫘
A number of macros are supported which extend the functionality of language. Macros typically only apply to and accept specific data types. For example, the toLower()
macro applies to a string or a list.
Expression:
${'Hello World'.toLower()}
Output:
hello world
Expression:
${toLower(['Hello World'])}
Output:
[
hello world
]
Many of the supported macros are documented at Common Expression Language Macros.
Avoiding Errors ⫘
Attempting to access a variable that is not defined will result in a no_such_field
error. This can be avoided by using the has()
macro along with a ternary conditional:
Expression:
${ has(map_var, 'map_key') ? map_var.map_key : '' }
Output:
the value of map_var.map_key if it exists, else an empty string
Another common error is due to mismatched type values. Converting the data in a variable to a specific data type may be necessary to prevent this issue. For example:
Expression:
${ int(int_val) }
Output:
the value of int_val as an integer type