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.
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 thanand
or
not
in
1 == 0
// False
'potato' in ['apple','orange','banana']
// False
'potato' not in ['apple','orange','banana']
// True
Eval Functions
Accepts a logical string, and returns True or False. This function can be used to assess truthiness.
// field1 == None
bool(field1)
// False
Accepts an object and returns its length
len([3,2,1])
// 3
Returns a num rounded to pos digits
round(2.1)
// 2
Accepts any number of inputs and returns the first non null value
// field1 == None
// field3 == "hello"
coalesce(None, field1, field2, field3)
// hello
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
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
Returns a string comprised of the list values concatenated by the value of str
join(['I','love','Salem'],'_')
// I_love_Salem
Accepts a list of strings, and returns a list with duplicate values removed
dedup(['1', '1', '3', '5'])
// ['1', '3', '5']
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
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)
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')
// ''
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]
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
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)
Accepts a JSON formatted string and returns an object
from_json('{"veg":"potato"}')
// {'veg': 'potato'}
Accepts and object and returns a JSON formatted string
to_json({'veg': 'potato'})
// '{"veg":"potato"}'
Accepts an object and returns a str formatted version of that object
to_str(now())
// 2024-11-22 19:13:15.750714
Accepts a string and returns a number formatted version of that string
to_num('123')
// 123
Accepts a url quoted string and returns a unquoted version
url_encode('https%3A//salemcyber.com')
// https://salemcyber.com
Accepts a string and returns a url quoted version of that string
url_encode('https://salemcyber.com')
// https%3A//salemcyber.com
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'}
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
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':'[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).
// 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'
// }
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 = ['[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
// 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
alert filters
Last updated