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