From 0a66cbd3492454ef2d3ea04baee394907a0cab9f Mon Sep 17 00:00:00 2001 From: Tanaka Zakku <71482215+YamatoSecurity@users.noreply.github.com> Date: Thu, 16 Dec 2021 14:49:41 +0900 Subject: [PATCH] Readme-EN-update --- README-English.md | 15 ++++++++------ doc/AboutRuleCreation-English.md | 34 +++++++++++++++++++++++++++----- 2 files changed, 38 insertions(+), 11 deletions(-) diff --git a/README-English.md b/README-English.md index 28fc7940..c1d2d23a 100644 --- a/README-English.md +++ b/README-English.md @@ -38,7 +38,7 @@ Results summary: # Features * Cross-platform support: Windows, Linux, macOS * Developed in Rust to be memory safe and faster than a hayabusa falcon! -* Multi-thread support +* Multi-thread support delivering up to a 5x speed improvement! * Creates a single easy-to-analyze CSV timeline for forensic investigations and incident response * Threat hunting based on IoC signatures written in easy to read/create/edit YAML based hayabusa rules * Sigma rule support to convert sigma rules to hayabusa rules @@ -76,12 +76,13 @@ USAGE: --verbose 'Output verbose information to target event file path and rule file' -q 'Quiet mode. Do not display the launch banner' -r --rules=[RULEDIRECTORY] 'Rule file directory (default: ./rules)' - -m --min-level=[LEVEL] 'Minimum level for rules (default: informational)' (Possiblities are: informational, low, medium, high, critical) + -m --min-level=[LEVEL] 'Minimum level for rules (default: informational)' -u --utc 'Output time in UTC format (default: local time)' -d --directory=[DIRECTORY] 'Directory of multiple .evtx files' -s --statistics 'Prints statistics of event IDs' -n --show-noisyalerts 'do not exclude noisy rules' - -t --threadnum=[NUM] 'Thread number (default: optimal number for performance)' (Usually there is no performance benefit in increasing the number of threads but you may want to lower to a smaller number to reduce CPU load.) + -t --threadnum=[NUM] 'Thread number (default: optimal number for performance)' + --show-deprecated 'do not exclude rules with YAML's status deprecated' --contributors 'Prints the list of contributors' ```` @@ -106,9 +107,9 @@ hayabusa.exe -d .\sample-evtx --csv-timeline results.csv hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r ./rules/hayabusa ```` -* Only run sigma rules and show noisy alerts (disabled by default): +* Only run sigma rules and enable deprecated and noisy rules (both disabled by default): ```` -hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r ./rules/sigma --show-noisyalerts +hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r ./rules/sigma --show-noisyalerts --show-deprecated ```` * Only run rules to analyze logons and output in the UTC timezone: @@ -198,9 +199,11 @@ The following were taken based on approximately 500 logs (130MB) from our sample | | Elapsed Time | Memory Usage | Total Sigma Events Detected | Unique Sigma Events Detected | | :---: | :---: | :---: | :---: | :---: | | Chainsaw | 10 seconds | 75 MB | 552 | 170 | -| Hayabusa | xx | xx | 9783 | 265 | +| Hayabusa | 12 seconds | 340 MB | 10630 | 267 | | Zircolite | 55 seconds | 400 MB | 1954 | 237 | +With hayabusa rules enabled, it will detect over 300 unique alerts and events. + # License Hayabusa is released under GPLv3 and all rules are released under the Detection Rule License (DRL) 1.1 diff --git a/doc/AboutRuleCreation-English.md b/doc/AboutRuleCreation-English.md index a4964187..22d6a28f 100644 --- a/doc/AboutRuleCreation-English.md +++ b/doc/AboutRuleCreation-English.md @@ -52,7 +52,7 @@ ruletype: Hayabusa * **title_jp** [optional]: The title in Japanese. * output [optional]: The details of the alert that gets displayed. Please output any fields in the Windows event log that are useful for analysis. Fields are seperated by `" : "` (two spaces on both sides). Field placeholders are enclosed with a `%` (Example: `%MemberName%`) and need to be defined in `config\eventkey_alias.txt`. (Explained below.) * **output_jp** [optional]: The output message in Japanese. -* **description** [optional]: A description of the rule. This does not get displayed so you can make this long. +* **description** [optional]: A description of the rule. This does not get displayed so you can make this long and detailed. * **description_jp** [optional]: The description in Japanese. > #Rule section @@ -162,7 +162,7 @@ detection: `````` #### Caution: Undefined Eventkey Aliases -Not all eventkey aliases are defined in `config\eventkey_alias.txt`. If you are not getting the correct data in the `output`(Alert details) message, and instead are getting results like `%EventID%`, then you need to update `config\eventkey_alias.txt` with a new alias. +Not all eventkey aliases are defined in `config\eventkey_alias.txt`. If you are not getting the correct data in the `output`(Alert details) message, and instead are getting results like `%EventID%` or if the selection in your detection logic is not working properly, then you need to update `config\eventkey_alias.txt` with a new alias. ### How to use XML attributes in conditions XML elements may have attributes set by adding a space to the element. For example, `Name` in `Provider Name` below is an XML attribute of the `Provider` element. @@ -365,7 +365,31 @@ The following expressions can be used for `condition`. In the above example, selection names such as `SELECTION_1`, `SELECTION_2`, etc... are used but they can be named anything as long as they only contain the following characters: `a-z A-Z 0-9 _` > However, please use the standard convention of `selection_1`, `selection_2`, `filter_1`, `filter_2`, etc... to make things easy to read whenever possible. -## aggregation condition +## not logic +Many rules will result in false positives so it is very common to have a selection for signatures to search for but also a filter selection to not alert on false positives. +For example: + +`````` +detection: + selection: + Channel: Security + EventID: 4673 + filter: + - ProcessName: C:\Windows\System32\net.exe + - ProcessName: C:\Windows\System32\lsass.exe + - ProcessName: C:\Windows\System32\audiodg.exe + - ProcessName: C:\Windows\System32\svchost.exe + - ProcessName: C:\Windows\System32\mmc.exe + - ProcessName: C:\Windows\System32\net.exe + - ProcessName: C:\Windows\explorer.exe + - ProcessName: C:\Windows\System32\SettingSyncHost.exe + - ProcessName: C:\Windows\System32\sdiagnhost.exe + - ProcessName|startswith: C:\Program Files + - SubjectUserName: LOCAL SERVICE + condition: selection and not filter +`````` + +## Aggregation conditions (Count rules) ### Basics The `condition` keyword described above implements not only `AND` and `OR` logic, but is also able to count or "aggregate" events. This function is called the "aggregation condition" and is specified by connecting a condition with a pipe. @@ -380,7 +404,7 @@ detection: timeframe: 24h `````` -The aggregation condition can be defined in the following format: +Aggregation conditions can be defined in the following format: * `count() {operator} {number}`: For log events that match the first condition before the pipe, the condition will match if the number of matched logs satisfies the condition expression specified by `{operator}` and `{number}`. `{operator}` can be one of the following: @@ -398,7 +422,7 @@ The aggregation condition can be defined in the following format: * `12h`: 12 hours * `7d`: 7 days * `3M`: 3 months -> `timeframe` is not required by highly encouraged to define when possible for performance and memory efficiency. +> `timeframe` is not required but highly encouraged to define when possible for performance and memory efficiency. ### Four patterns for aggregation conditions: