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.

• Operators

• Functions

• Loops / iterators

Eval Operators

• == - Equal to

• != - Not equal to

• > - Greater than

• < - Less than

• and

• or

• not

• in

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.

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

len(obj)

Accepts an object and returns its length

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

round(num,pos)

Returns a num rounded to pos digits

round(2.1)
// 2

coalesce(*args)

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

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

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.

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

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

dedup(list)

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

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.

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

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

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

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

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

strptime(str,format)

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

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

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

to_json(obj)

Accepts and object and returns a JSON formatted string

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

to_str(obj)

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

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

to_num('123')
// 123

url_decode(url_string)

Accepts a url quoted string and returns a unquoted version

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

url_encode(str)

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

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.

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.

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

// 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':'[e-mail]','count':55},
//  {'account':'[e-mail]','count':1},
// ] 

[i['account'] for i in senders if i['count'] > 50]
// returns ['[e-mail]']

Dictionary Comprehension

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

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

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

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

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

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

Eval Use Cases

• match actions
• webhook actions
• alert filters

• alert parsing