Aristotle as a Module

If the module is installed, Aristotle can be invoked from the command line and run like a script, e.g.:

python3 -m aristotle -r examples/example.rules --stats

Of course, Aristotle can be imported and used like a normal module:

import aristotle

For logging and/or output, attach to the logger named aristotle and add desired Handler(s), e.g.:

logger = logging.getLogger("aristotle")
logger.addHandler(logging.StreamHandler())

To use, create a Ruleset object and pass it a string containing the ruleset or a filename of a ruleset, along with a filter string. Then call the Ruleset object’s filter_ruleset() function to get a list of SIDs matching the filter string.

Example:

import aristotle

a = aristotle.Ruleset("examples/example.rules")
a.set_metadata_filter("examples/example1.filter")
sids = a.filter_ruleset()

Ruleset class and functions:

class aristotle.Ruleset(rules, metadata_filter=None, enable_all_rules=False, summary_max=16, output_disabled_rules=False, ignore_classtype_keyword=False, ignore_filename=False, normalize=False, enhance=False, modify_metadata=False, pfmod_file=None)

Class for ruleset data structures, filter string, and ruleset operations.

Parameters:

• rules (string, required) – a string containing a ruleset or a filename of a ruleset file

• metadata_filter (string, optional) – A string or a filename of a file that defines the desired outcome based on Boolean logic, and uses the metadata key-value pairs as values in the Boolean algebra. Defaults to None (can be set later with set_metadata_filter()).

• enable_all_rules (bool, optional) – enable all valid rules, including those disabled/commented out in the given rules file(s), when applying the filter; defaults to False

• summary_max (int, optional) – the maximum number of rules to print when outputting summary/truncated filtered ruleset, defaults to 16.

• output_disabled_rules (bool, optional) – include disabled rules in the output as commented out lines, defaults to False

• ignore_classtype_keyword (bool, optional) – don’t incorporate the ‘classtype’ keyword and value into the metadata structure for filtering and reporting

• ignore_filename (bool, optional) – don’t incorporate the filename of the rules file into the metadata structure for filtering and reporting

• normalize (bool, optional) – try to convert and normalize date and CVE related metadata values into the schema defined by BETTER. Dates are normalized to the format YYYY-MM-DD and CVEs to YYYY-<num>. Also, ‘sid’ is removed from the metadata. Defaults to False

• enhance (bool, optional) – enhance metadata by adding additional key-value pairs based on the rules, defaults to False

• modify_metadata (bool, optional) – modify the rule metadata keyword value on output to contain the internally tracked and normalized metadata data, defaults to False

• pfmod_file (string, optional) – A filename of a YAML file of directives to apply actions on post-filtered rules based on filter strings.

Raises:

AristotleException

add_metadata(sid, key, value)

Update self.metadata_dict and self.keys_dict data structures for the given sid, adding the passed in key and value.

Parameters:

• sid (int, required) – sid to update

• key (string, required) – key to add or update

• value (string, required) – value corresponding to given key

cve_compare(left_val, right_val, cmp_operator)

Compare CVE values given comparison operator.

May have unexpected results if CVE values (left_val, right_val) not formatted as CVE numbers. Returns boolean.

delete_metadata(sid, key, value=None)

Update self.metadata_dict and self.keys_dict data structures for the given sid, deleting the passed in key and value. If value is not provided (or None), delete all references involving the given key.

Parameters:

• sid (int, required) – sid to update

• key (string, required) – key to add or update

• value (string, optional) – value corresponding to given key

evaluate(myobj)

Recursive evaluation function that deals with BooleanAlgebra elements from boolean.py.

filter_ruleset(metadata_filter=None)

Applies boolean filter against the ruleset and returns list of matching SIDs.

Parameters:

metadata_filter (string, optional) – A string that defines the desired outcome based on Boolean logic, and uses the metadata key-value pairs as values in the Boolean algebra. Defaults to self.metadata_filter which must be set if this parameter is not set.

Returns:

list of matching SIDs

Return type:

list

Raises:

AristotleException

get_all_sids()

Returns a list of all SIDs, enabled and disabled.

Returns:

list of all enabled SIDs, enabled and disabled.

Return type:

list

get_disabled_sids()

Returns a list of all disabled SIDs.

Returns:

list of all disabled SIDs.

Return type:

list

get_enabled_sids()

Returns a list of all enabled SIDs.

Returns:

list of all enabled SIDs.

Return type:

list

get_sids(kvpair, negate=False)

Get a list of all SIDs for passed in key-value pair.

Parameters:

• kvpair (string, required) – key-value pair

• negate (bool, optional) – returns the inverse of the result (i.e. all SIDs not matching the kvpair), defaults to False

Returns:

list of matching SIDs

Return type:

list

Raises:

AristotleException

get_stats(key, keyonly=False, sids=None, include_empty_substat=False)

Returns string of statistics (total, enabled, disabled) for specified key and its values.

Parameters:

• key (string, required) – key to print statistics for

• keyonly (bool, optional) – only print stats for the key itself and not stats for all possible key-value pairs, defaults to False

• sids (list, optional) – list of SIDs to consider. If not provided, global list is used.

• include_empty_substat – includes cases where substat (key-value pair) has zero results

Parap include_empty_substat:

bool, optional

Returns:

string contaning stats, suitable for printing to stdout

Return type:

string

Raises:

AristotleException

normalize_better(k, v, sid=None)

Try to convert date, MITRE ATT&CK, and cve related metadata values to conform to the BETTER schema for filtering and statistics. Currently applies to keys ‘cve’, ‘mitre_tactic_id’, ‘mitre_technique_id’ and those ending with ‘_at’ or “-at”.

Parameters:

• k (string, required) – key name of a metadata key-value pair

• v (string, required) – value of a metadata key-value pair

• sid (int, optional) – SID related to the passed in key-value pair. Used only for enriching logging.

Returns:

list of all key/value pairs to add to metadata structure

Return type:

list

output_rules(sid_list, outfile=None, modify_metadata=None)

Output rules, given a list of SIDs.

Parameters:

• sid_list (list, required) – list of SIDs of the rules to output

• outfile (string or None, optional) – filename to output to; if None, output to stdout; defaults to None

• modify_metadata (bool, optional) – modify the rule metadata keyword value on output to contain the internally tracked and normalized metadata data.

Returns:

None

Return type:

NoneType

Raises:

AristotleException

parse_rules(rules, filename=None)

Parses the given rules and builds/updates necessary data structures.

Parameters:

• rules (string, required) – rules (one per line) to parse and build/update the necessary data structures

• filename (string, optional) – if the passed in rules came from a file, the filename of that file

print_header(sids=None)

Prints vanity header and stats.

Parameters:

sids (list, optional) – list of SIDs to consider. If not provided, global list is used.

print_ruleset_summary(sids, pfmod_sids=None)

Prints summary/truncated filtered ruleset to stdout.

Parameters:

• sids (list, optional) – list of SIDs.

• pfmod_sids – list of SID modified by PFMod.

Raises:

AristotleException

print_stats(key, keyonly=False, sids=None)

Print statistics (total, enabled, disabled) for specified key and its values.

Parameters:

• key (string, required) – key to print statistics for.

• keyonly (bool, optional) – only print stats for the key itself and not stats for all possible key-value pairs, defaults to False.

• sids (list, optional) – list of SIDs to scope stats to. If None, global list will be used downstream.

reduce_ipval(ipval)

Take an “IP” value (raw IP, list, ipvar) and reduce it to one of the following:

• any

• $HOME_NET

• $EXTERNAL_NET

• UNDETERMINED

Assumptions:

• ipval doesn’t contain any nested lists

  • (could recurse on nested lists but once we start reducing, we loose accuraccy pretty fast.)

  • (most 3rd party rulesets should rarely, if ever, need to include rules that require nested IPs/ranges.)

Parameters:

ipval (string, required) – IP part of a rule, e.g. $HOME_NET, 10.0.0.0/8, [192.168.1.0/24,192.168.2.0/24], etc.

Returns:

‘any’, ‘$HOME_NET’, ‘$EXTERNAL_NET’, or ‘UNDETERMINED’

Return type:

string

set_metadata_filter(metadata_filter)

Sets the metadata filter to use.

Parameters:

metadata_filter (string, required) – A string or a filename of a file that defines the desired outcome based on Boolean logic, and uses the metadata key-value pairs as values in the Boolean algebra.

Raises:

AristotleException