Eval String Reference

Logical Operations

User-entered logical operations are a key component of Salem's learning architecture and are referred to in the Salem nomenclature as "eval strings." These operations are created by users to inform Salem actions related to context-building workloads, alert categorization, and other logic-based evaluations.

eval strings

Definition: Eval strings are logical operations used by Salem to add and apply context to alerts based on their details. Salem can be taught to evaluate complex Boolean expressions using the and and or operators and the match() function. These expressions can be used to filter alerts, extract relevant information, and generate new context.

Eval Operators

== - Equal to
!= - Not equal to
> - Greater than
< - Less than
and
or
not
in

Copy

1 == 0
// False

'potato' in ['apple','orange','banana']
// False

'potato' not in ['apple','orange','banana']
// True

Eval Functions

bool(exp)

Accepts a logical string, and returns True or False. This function can be used to assess truthiness.

Copy

// field1 == None
bool(field1)
// False

len(obj)

Accepts an object and returns its length

Copy

len([3,2,1])
// 3

round(num,pos)

Returns a num rounded to pos digits

Copy

round(2.1)
// 2

coalesce(*args)

Accepts any number of inputs and returns the first non null value

Copy

// field1 == None
// field3 == "hello"
coalesce(None, field1, field2, field3)
// hello

if_then(bool,true,false)

If the bool statement evaluates to true, the value of the true case is returned, otherwise the value of the false case is returned

Copy

if_then(1 == 0,'fruit','veg')
// veg

case(bool,value,bool,value,default)

The first bool value that returns true will return the next value. If no bools return true, then the default value is returned.

Copy

case(1 == 0, 'fruit', 1==1, 'veg', True, 'potato', 'salmon')
// veg

join(list,str)

Returns a string comprised of the list values concatenated by the value of str

Copy

join(['I','love','Salem'],'_')
// I_love_Salem

dedup(list)

Accepts a list of strings, and returns a list with duplicate values removed

Copy

dedup(['1', '1', '3', '5'])
// ['1', '3', '5']

match(type,match_exp,match_field)

Returns True or False based on the evaluation of the match expression.

Match types:

in <list>: Returns true if the test is contained in the object.
is <str>: Returns true if the test is equal to the object.
beginsWith <str> : Returns true if the object starts with the test.
endsWith <str>: Returns true if the object ends with the test.
contains <str>: Returns true if the object contains the test.
regex <str>: Returns true if the object matches the test regular expression.
CIDR <str>: Returns true if the object’s IP address is within the CIDR range specified by the test.

Copy

match('endsWith','.com',src)
// src == 'example.com'
// True

match('CIDR','192.168.0.0/24',ip)
// ip == 192.168.0.1
// True

now(seconds)

Returns a date object that is the current UTC time offset by the value of seconds

Copy

now()
// datetime.datetime(2024, 11, 22, 18, 58, 6, 976369)

now().isoformat()
// 2024-11-22T18:58:54.366710

now(-86400)
// datetime object representing yesterday
// datetime.datetime(2024, 11, 21, 19, 0, 2, 106986)

rex(exp,str)

returns a match value based on the regex exp evaluated over str

Copy

// customer_code == "UC_3452"

rex('\d+',customer_code)
// 3452

rex('^UC_(\d+)$',customer_code)
// 3452

rex('^UC_(\d+)$', '202-123-4567')
// ''

split(str,exp)

Accepts a string and returns a list of str components split by the value of exp

Copy

split('10.0.0.1','.')
// [10,0,0,1]

strftime(time,format)

Accepts a datetime object and a time format string. Returns a str representing time in the format provided

Copy

strftime(now(),'%m-%d-%Y')
// 11-22-2024

strptime(str,format)

Accepts a time str and format, and returns a datetime object

Copy

strptime('11-22-2024','%m-%d-%Y')
// datetime.datetime(2024, 11, 22, 0, 0)

from_json(json_str)

Accepts a JSON formatted string and returns an object

Copy

from_json('{"veg":"potato"}')
// {'veg': 'potato'}

to_json(obj)

Accepts and object and returns a JSON formatted string

Copy

to_json({'veg': 'potato'})
// '{"veg":"potato"}'

to_str(obj)

Accepts an object and returns a str formatted version of that object

Copy

to_str(now())
// 2024-11-22 19:13:15.750714

to_num(str)

Accepts a string and returns a number formatted version of that string

Copy

to_num('123')
// 123

url_decode(url_string)

Accepts a url quoted string and returns a unquoted version

Copy

url_encode('https%3A//salemcyber.com')
// https://salemcyber.com

url_encode(str)

Accepts a string and returns a url quoted version of that string

Copy

url_encode('https://salemcyber.com')
// https%3A//salemcyber.com

zip(iterator1, iterator2, iterator3 ... )

Accepts a series of iterators and returns a zip object, which is an iterator of tuples where the nth position value of each input iterator is paired together.

Copy

zip(['name', 'location'],['Jan','Washington DC'])

// ex. use zip to create a dictionary

{k:v for k, v in zip(['name', 'location'],['Jan','Washington DC'])}
// {'name': 'Jan', 'location': 'Washington DC'}

bag_of_fields

A dictionary that allows you to access the set of variables accessable by an eval. Most commonly, bag_of_fields would contain the fields from an alert.

Copy

bag_of_fields.keys()
// dict_keys(['field1', 'field2'])

bag_of_fields['field1']
// value1

Loops and Iterators

Salem eval supports loop and iterator operations. This can be useful when you want to extract, manipulate or test data from a list or dictionary.

List Comprehension

List Comprehension creates a new list by looping through an iterator. This can be useful if you want to construct a new list based on the values of another list or dictionary. This implementation is similar to the implementation in Python (doc).

Copy

// Example 1, create a list of domain names based on the input variable entities
// entities = [{'domain':'google.com'},{'domain':'salemcyber.com'}]

[i['domain'] for i in entities]
// returns ['gooogle.com','salemcyber.com']


// Example 2, create a list of account names, if the count is greater than 50
// senders = [
//  {'account':'[email protected]','count':55},
//  {'account':'[email protected]','count':1},
// ] 

[i['account'] for i in senders if i['count'] > 50]
// returns ['[email protected]']

Dictionary Comprehension

Dictionary Comprehension creates a new dictionary by looping through an iterator. This implementation is similar to the implementation in Python (doc).

Copy

// Example 1, filter a dictionary to a subset of keys
// details = 
//  {
//   'src':'10.0.0.1',
//   'user': 'jan.bragg',
//   'app': 'internal_db_123'
//  }

{k, v for k, v in details.items() if k in ['user', 'src']}
//   'src':'10.0.0.1',
//   'user': 'jan.bragg'
//  }

// Example 2, create a dictionary from string of key values pairs
// details = "src=10.0.0.1 user=jan.bragg app=internal_db_123"

{k: v for k, v in (item.split('=') for item in details.split())}
// {
//   'src':'10.0.0.1',
//   'user': 'jan.bragg',
//   'app': 'internal_db_123'
// }

Any

The any() function can be used to return True if any of the values in the iterator treturn True for the given test

Copy

// Example: return True if any of the users are on the salemcbyer.com domain
// users = ['[email protected]', '[email protected]']

any('@salemcyber.com' in user for user in users)
// Tr

All

The all() function can be used to return True if all of the values in the iterator treturn True for the given test

Copy

// Example: return False if any of the users are not on the salemcbyer.com domain
// users = ['[email protected]', '[email protected]']

all('@salemcyber.com' in user for user in users)
// False

Eval Use Cases

PreviousReference NextConf Spec Files

Last updated 2 months ago