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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

filter_ruleset(metadata_filter=None)[source]

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()[source]

Returns a list of all SIDs, enabled and disabled.

Returns:list of all enabled SIDs, enabled and disabled.
Return type:list
get_disabled_sids()[source]

Returns a list of all disabled SIDs.

Returns:list of all disabled SIDs.
Return type:list
get_enabled_sids()[source]

Returns a list of all enabled SIDs.

Returns:list of all enabled SIDs.
Return type:list
get_sids(kvpair, negate=False)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]
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)[source]

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