Usage¶
usage: aristotle.py [-h] -r RULES [-f METADATA_FILTER] [--summary]
[-o OUTFILE] [-s [STATS [STATS ...]]] [-i] [-q] [-d]
optional arguments:
-h, --help show this help message and exit
-r RULES, --rules RULES, --ruleset RULES
path to rules file or string containing the ruleset
(default: None)
-f METADATA_FILTER, --filter METADATA_FILTER
Boolean filter string or path to a file containing it
(default: None)
--summary output a summary of the filtered ruleset to stdout; if
an output file is given, the full, filtered ruleset
will still be written to it. (default: False)
-o OUTFILE, --output OUTFILE
output file to write filtered ruleset to (default:
<stdout>)
-s [STATS [STATS ...]], --stats [STATS [STATS ...]]
display ruleset statistics about specified key(s). If
no key(s) supplied, then summary statistics for all
keys will be displayed. (default: None)
-i, --include-disabled
include (effectively enable) disabled rules when
applying the filter (default: False)
-q, --quiet, --suppress_warnings
quiet; suppress warning logging (default: False)
-d, --debug turn on debug logging (default: False)
Example Files¶
The examples directory has .filter files that show examples of Boolean
filter strings.
Also in the examples directory is an example.rules file that has a dummy
Suricata ruleset that implements the BETTER Schema.
While the example
ruleset is syntactically correct, it is not a real ruleset
intended to be used by a Suricata sensor.
It is provided to assist in demonstrating the functionality of
Aristotle and to provide examples of rules with metadata keywords that
conform to the BETTER Schema.
Example Usage¶
Note
aristotle.py in the root of the repository is a symlink
to aristotle/aristotle.py. If the evironment in use does
not recognize symlinks, adjust the paths accordingly.
Show high level statistics on all the keys in the example.rules file:
python aristotle.py -r examples/example.rules -s
Show statistics on the protocols key in the example.rules file:
python aristotle.py -r examples/example.rules -s protocols
Apply the Boolean filter defined in the example1.filter file against the
rules in the example.rules file and output summary results to stdout:
python aristotle.py -r examples/example.rules -f examples/example1.filter --summary
Apply the Boolean filter defined in the example1.filter file against the
rules in the example.rules file and output the results to the file newrules.rules:
python aristotle.py -r examples/example.rules -f examples/example1.filter -o newrules.rules
Apply the Boolean filter defined specified on the command line against the
rules in the example.rules file and output the results to the file newrules.rules:
python aristotle.py -r examples/example.rules -f '"malware <ALL>" AND ("attack_target http-server" or "attack_target tls-server")' -o newrules.rules
Important
Because Aristotle requires key-value pairs (values) in the filter string to be enclosed in double quotes, a filter string specified on the command line must be enclosed in single quotes.
Statistics¶
The statistics command line option allows a user to to easily see what metadata key-value pairs the ruleset contains to assist in building a filter string.
If no key names are passed, summary info on all present keys is displayed:
$ python aristotle.py -r examples/example.rules -s
Aristotle
Ruleset Metadata Tool
All Rules: Total: 6799; Enabled: 4977; Disabled: 1822
attack_target (Total: 6028; Enabled: 4554; Disabled: 1474)
malware (Total: 3467; Enabled: 3330; Disabled: 137)
cve (Total: 1570; Enabled: 887; Disabled: 683)
hostile (Total: 5962; Enabled: 4403; Disabled: 1559)
created_at (Total: 6799; Enabled: 4977; Disabled: 1822)
capec_id (Total: 2669; Enabled: 1191; Disabled: 1478)
updated_at (Total: 6799; Enabled: 4977; Disabled: 1822)
cwe_id (Total: 5199; Enabled: 4332; Disabled: 867)
priority (Total: 6799; Enabled: 4977; Disabled: 1822)
cvss_v3_base (Total: 271; Enabled: 259; Disabled: 12)
infected (Total: 2679; Enabled: 2520; Disabled: 159)
sid (Total: 6799; Enabled: 4977; Disabled: 1822)
cvss_v2_base (Total: 1130; Enabled: 829; Disabled: 301)
rule_source (Total: 6799; Enabled: 4977; Disabled: 1822)
cvss_v3_temporal (Total: 271; Enabled: 259; Disabled: 12)
filename (Total: 6799; Enabled: 4977; Disabled: 1822)
cvss_v2_temporal (Total: 1130; Enabled: 829; Disabled: 301)
protocols (Total: 6799; Enabled: 4977; Disabled: 1822)
If one or more key names are passed, summary info is displayed for those keys:
$ python aristotle.py -r examples/example.rules -s malware protocols
Aristotle
Ruleset Metadata Tool
All Rules: Total: 6799; Enabled: 4977; Disabled: 1822
malware (Total: 3467; Enabled: 3330; Disabled: 137)
download-attempt (Total: 178; Enabled: 171; Disabled: 7)
malware (Total: 135; Enabled: 117; Disabled: 18)
post-infection (Total: 2647; Enabled: 2589; Disabled: 58)
pre-infection (Total: 507; Enabled: 453; Disabled: 54)
protocols (Total: 6799; Enabled: 4977; Disabled: 1822)
smtp (Total: 143; Enabled: 82; Disabled: 61)
pop (Total: 64; Enabled: 45; Disabled: 19)
rpc (Total: 16; Enabled: 4; Disabled: 12)
dnp3 (Total: 5; Enabled: 0; Disabled: 5)
vnc (Total: 1; Enabled: 0; Disabled: 1)
ftp (Total: 130; Enabled: 65; Disabled: 65)
sip (Total: 5; Enabled: 3; Disabled: 2)
iccp (Total: 4; Enabled: 0; Disabled: 4)
dns (Total: 20; Enabled: 6; Disabled: 14)
ldap (Total: 1; Enabled: 1; Disabled: 0)
irc (Total: 21; Enabled: 19; Disabled: 2)
nntp (Total: 4; Enabled: 0; Disabled: 4)
smb (Total: 60; Enabled: 42; Disabled: 18)
http (Total: 5447; Enabled: 4199; Disabled: 1248)
telnet (Total: 9; Enabled: 3; Disabled: 6)
dcerpc (Total: 1; Enabled: 1; Disabled: 0)
tcp (Total: 6788; Enabled: 4976; Disabled: 1812)
imap (Total: 55; Enabled: 25; Disabled: 30)
tls (Total: 145; Enabled: 128; Disabled: 17)
modbus (Total: 7; Enabled: 0; Disabled: 7)
tftp (Total: 1; Enabled: 0; Disabled: 1)
ssh (Total: 9; Enabled: 4; Disabled: 5)