diff --git a/README-Japanese.md b/README-Japanese.md index d3745188..e38e236c 100644 --- a/README-Japanese.md +++ b/README-Japanese.md @@ -56,6 +56,7 @@ Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/) - [英語](#英語) - [日本語](#日本語) - [貢献](#貢献) +- [バグの報告](#バグの報告) - [ライセンス](#ライセンス) ## 主な目的 @@ -363,7 +364,7 @@ CSVファイルとして保存する場合、以下の2つのフィールドが ## 標準出力へのカラー設定 `-c`または`--color`を指定することで、Hayabusaの結果は`level`毎に文字色を変えることができます。 -`.\config\level_color.txt`の値を変更することで文字色を変えることができます。 +`./config/level_color.txt`の値を変更することで文字色を変えることができます。 形式は`level名,(6桁のRGBのカラーhex)`です。 注意: True Colorに対応しているターミナルが必要です。 例: [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/install) またはmacOSの[iTerm2](https://iterm2.com/)。 @@ -372,7 +373,7 @@ CSVファイルとして保存する場合、以下の2つのフィールドが Hayabusa検知ルールはSigmaのようなYML形式で記述されています。`rules`ディレクトリに入っていますが、将来的には[https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules)のレポジトリで管理する予定なので、ルールのissueとpull requestはhayabusaのレポジトリではなく、ルールレポジトリへお願いします。 -ルールの作成方法については、[AboutRuleCreation-Japanese.md](./doc/AboutRuleCreation-Japanese.md) をお読みください。 +ルールの作成方法については、[hayabusa-rulesレポジトリのREADME](https://github.com/Yamato-Security/hayabusa-rules/blob/main/README-Japanese.md) をお読みください。 [hayabusa-rulesレポジトリ](https://github.com/Yamato-Security/hayabusa-rules)にあるすべてのルールは、`rules`フォルダに配置する必要があります。 @@ -413,9 +414,9 @@ Sigmaルールは、最初にHayabusaルール形式に変換する必要があ ファイアウォールやIDSと同様に、シグネチャベースのツールは、環境に合わせて調整が必要になるため、特定のルールを永続的または一時的に除外する必要がある場合があります。 -ルールID(例: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) を `rules\config\exclude_rules.txt`に追加すると、不要なルールや利用できないルールを無視することができます。 +ルールID(例: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) を `rules/config/exclude_rules.txt`に追加すると、不要なルールや利用できないルールを無視することができます。 -ルールIDを `rules\config\noisy_rules.txt`に追加して、デフォルトでルールを無視することもできますが、` -n`または `--enable-noisy-rules`オプションを指定してルールを使用することもできます。 +ルールIDを `rules/config/noisy_rules.txt`に追加して、デフォルトでルールを無視することもできますが、` -n`または `--enable-noisy-rules`オプションを指定してルールを使用することもできます。 ## イベントIDフィルタリング @@ -485,6 +486,10 @@ Sigmaルールは、最初にHayabusaルール形式に変換する必要があ 少なくとも、私たちのツールを気に入っていただけたなら、Githubで星を付けて、あなたのサポートを表明してください。 +# バグの報告 + +見つけたバグを[こちら](https://github.com/Yamato-Security/hayabusa/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5Bbug%5D)でご連絡ください。報告されたバグを喜んで修正します！ + # ライセンス Hayabusaは[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)で公開され、すべてのルールは[Detection Rule License (DRL) 1.1](https://github.com/SigmaHQ/sigma/blob/master/LICENSE.Detection.Rules.md)で公開されています。 diff --git a/README.md b/README.md index 5916a51e..0ffd96aa 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ Hayabusa is a **Windows event log fast forensics timeline generator** and **thre - [English](#english) - [Japanese](#japanese) - [Contribution](#contribution) +- [Bug Submission](#bug-submission) - [License](#license) ## Main goals @@ -359,7 +360,7 @@ It will display in real time the number and percent of evtx files that it has fi ## Color Output You can output the alerts in color based on the alert `level` by specifying `-c` or `--color`. -You can change the default colors in the config file at `.\config\level_color.txt` in the format of `level,(RGB 6-digit ColorHex)`. +You can change the default colors in the config file at `./config/level_color.txt` in the format of `level,(RGB 6-digit ColorHex)`. Note: Color can only be displayed in terminals that support [True Color](https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)). Example: [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/install) or [iTerm2](https://iterm2.com/) for macOS. @@ -367,7 +368,7 @@ Example: [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/in Hayabusa detection rules are written in a sigma-like YML format and are located in the `rules` folder. In the future, we plan to host the rules at [https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules) so please send any issues and pull requests for rules there instead of the main hayabusa repository. -Please read [AboutRuleCreation-English.md](./doc/AboutRuleCreation-English.md) to understand about the rule format how to create rules. +Please read [the hayabusa-rules repository README](https://github.com/Yamato-Security/hayabusa-rules/blob/main/README.md) to understand about the rule format and how to create rules. All of the rules from the hayabusa-rules repository should be placed in the `rules` folder. `informational` level rules are considered `events`, while anything with a `level` of `low` and higher are considered `alerts`. @@ -407,13 +408,13 @@ Sigma rules need to first be converted to hayabusa rule format explained [here]( Like firewalls and IDSes, any signature-based tool will require some tuning to fit your environment so you may need to permanently or temporarily exclude certain rules. -You can add a rule ID (Example: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) to `rules\config\exclude_rules.txt` in order to ignore any rule that you do not need or cannot be used. +You can add a rule ID (Example: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) to `rules/config/exclude_rules.txt` in order to ignore any rule that you do not need or cannot be used. -You can also add a rule ID to `rules\config\noisy_rules.txt` in order to ignore the rule by default but still be able to use the rule with the `-n` or `--enable-noisy-rules` option. +You can also add a rule ID to `rules/config/noisy_rules.txt` in order to ignore the rule by default but still be able to use the rule with the `-n` or `--enable-noisy-rules` option. ## Event ID filtering -You can filter on event IDs by placing event ID numbers in `config\target_eventids.txt`. +You can filter on event IDs by placing event ID numbers in `config/target_eventids.txt`. This will increase performance so it is recommended if you only need to search for certain IDs. We have provided a sample ID filter list at [`config/target_eventids_sample.txt`](https://github.com/Yamato-Security/hayabusa/blob/main/config/target_eventids_sample.txt) created from the `EventID` fields in all of the rules as well as IDs seen in actual results. @@ -479,6 +480,11 @@ We would love any form of contribution. Pull requests, rule creation and sample At the least, if you like our tool then please give us a star on Github and show your support! +# Bug Submission + +Please submit any bugs you find [here.](https://github.com/Yamato-Security/hayabusa/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5Bbug%5D) +This project is currently actively maintained and we are happy to fix any bugs reported. + # License Hayabusa is released under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) and all rules are released under the [Detection Rule License (DRL) 1.1](https://github.com/SigmaHQ/sigma/blob/master/LICENSE.Detection.Rules.md). \ No newline at end of file diff --git a/doc/AboutRuleCreation-English.md b/doc/AboutRuleCreation-English.md deleted file mode 100644 index 1bc64963..00000000 --- a/doc/AboutRuleCreation-English.md +++ /dev/null @@ -1,596 +0,0 @@ -## About rule files -Hayabusa detection rules are written in [YAML](https://en.wikipedia.org/wiki/YAML) format. -They are a subset of sigma rules with some additions. We are trying to make them as close to sigma rules as possible so that it is easy to convert Hayabusa rules back to sigma to give back to the community. -Hayabusa rules can express complex detection rules by combining not only simple string matching but also regular expressions, `AND`, `OR`, and other conditions. -In this section, we will explain how to write Hayabusa detection rules. - -# Rule file format -Example: - -```yaml -#Author section -author: Eric Conrad, Zach Mathis -date: 2020/11/08 -modified: 2021/11/26 - -#Alert section -title: User added to local Administrators group -title_jp: ユーザがローカル管理者グループに追加された -details: 'User: %SubjectUserName% : Group: %TargetUserName% : LogonID: %SubjectLogonId%' -details_jp: 'ユーザ: %SubjectUserName% : グループ名: %TargetUserName% : ログオンID: %SubjectLogonId%' -description: A user was added to the local Administrators group. -description_jp: ユーザがローカル管理者グループに追加された。 - -#Rule section -id: 611e2e76-a28f-4255-812c-eb8836b2f5bb -level: high -status: stable -detection: - selection: - Channel: Security - EventID: 4732 - TargetUserName: Administrators - condition: selection -falsepositives: - - system administrator -tags: - - attack.persistence - - attack.t1098 -references: - - https://www.ultimatewindowssecurity.com/securitylog/encyclopedia/event.aspx?eventid=4732 -sample-evtx: ./sample-evtx/EVTX-to-MITRE-Attack/TA0003-Persistence/T1098.xxx-Account manipulation/ID4732-User added to local admin groups.evtx -logsource: default -ruletype: Hayabusa -``` - -> ## Author section -* **author [required]**: Name of the author(s). -* **contributor** [optional]: Name of any contributor(s) (anyone who made any minor corrections). -* **date [required]**: Date the rule was made. -* **modified** [optional]: Date the rule was updated. - -> ## Alert section -* **title [required]**: Rule file title. This will also be the name of the alert that gets displayed so the briefer the better. (Should not be longer than 85 characters.) -* **title_jp** [optional]: The title in Japanese. -* details [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 `rules\config\eventkey_alias.txt`. (Explained below.) -* **details_jp** [optional]: The details message in Japanese. -* **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 -* **id [required]**: A randomly generated version 4 UUID used to uniquely identify the rule. You can generate one [here](https://www.uuidgenerator.net/version4). -* **level [required]**: Severity level based on [sigma's definition](https://github.com/SigmaHQ/sigma/wiki/Specification). Please write one of the following: `informational`,`low`,`medium`,`high`,`critical` -* **status[required]**: `stable` for tested rules and `testing` for rules that need to be tested. -* **detection [required]**: The detection logic goes here. (Explained below.) -* **falsepositives [required]**: The possibilities for false positives. For example: `system administrator`, `normal user usage`, `normal system usage`, `legacy application`, `security team`, `none`. If it is unknown, please write `unknown`. -* **tags** [optional]: If the technique is a [LOLBINS/LOLBAS](https://lolbas-project.github.io/) technique, please add the `lolbas` tag. If the alert can be mapped to a technique in the [MITRE ATT&CK](https://attack.mitre.org/) framework, please add the tactic ID (Example: `attack.t1098`) and any applicable tactics below: - * `attack.impact` -> Impact - * `attack.initial_access` -> Initial Access - * `attack.execution` -> Execution - * `attack.lateral_movement` -> Lateral Movement - * `attack.persistence` -> Persistence - * `attack.privilege_escalation` -> Privilege Escalation - * `attack.reconnaissance` -> Reconnaissance - * `attack.collection` -> Collection - * `attack.command_and_control` -> Command and Control - * `attack.credential_access` -> Credential Access - * `attack.defense_evasion` -> Defense Evasion - * `attack.discovery` -> Discovery - * `attack.exfiltration` -> Exfiltration - * `attack.resource_development` -> Resource Development -* **references** [optional]: Any links to references. -* **sample-evtx [required]**: File path or URL to an event log file that this rule will detect. -* **logsource [required]**: The source of where the log comes from. Please specify one of the following: - * `default`: For logs that are turned on in Windows by default. - * `non-default`: For logs that need to be turned on through group policy, security baselines, etc... - * `sysmon`: Logs that require sysmon to be installed. -* **non-default-setting** [optional]: Explanation of how to turn on the log setting for `non-default` log sources. -* **ruletype [required]**: `Hayabusa` for hayabusa rules. Rules automatically converted from sigma Windows rules will be `Sigma`. - -# Detection field -## Selection fundamentals -First, the fundamentals of how to create a selection rule will be explained. - -### How to write AND and OR logic -To write AND logic, we use nested dictionaries. -The detection rule below defines that **both conditions** have to be true in order for the rule to match. -* EventID has to exactly be `7040`. -* **AND** -* Channel has to exactly be `System`. - -```yaml -detection: - selection: - Event.System.EventID: 7040 - Event.System.Channel: System - condition: selection -``` - -To write OR logic, we use lists (Dictionaries that start with `- `). -In the detection rule below, **either one** of the conditions will result in the rule being triggered. -* EventID has to exactly be `7040`. -* **OR** -* Channel has to exactly be `System`. - -```yaml -detection: - selection: - - Event.System.EventID: 7040 - - Event.System.Channel: System - condition: selection -``` - -We can also combine `AND` and `OR` logic as shown below. -In this case, the rule matches when the following two conditions are both true. -* EventID is either exactly `7040` **OR** `7041`. -* **AND** -* Channel is exactly `System`. - -```yaml -detection: - selection: - Event.System.EventID: - - 7040 - - 7041 - Event.System.Channel: System - condition: selection -``` - -### Eventkeys -The following is an excerpt of a Windows event log, formatted in the original XML. The `Event.System.Channel` field in the rule file example above refers to the original XML tag: `System`. Nested XML tags are replaced by tag names seperated by dots (`.`). In hayabusa rules, these field strings connected together with dots are refered to as `eventkeys`. - -```xml - - - 7040 - System - - - Background Intelligent Transfer Service - auto start - - -``` - -#### Eventkey Aliases -Long eventkeys with many `.` seperations are common, so hayabusa will use aliases to make them easier to work with. Aliases are defined in the `rules\config\eventkey_alias.txt` file. This file is a CSV file made up of `alias` and `event_key` mappings. You can rewrite the rule above as shown below with aliases making the rule easier to read. - -```yaml -detection: - selection: - Channel: System - EventID: 7040 - condition: selection -``` - -#### Caution: Undefined Eventkey Aliases -Not all eventkey aliases are defined in `rules\config\eventkey_alias.txt`. If you are not getting the correct data in the `details`(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 `rules\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. - -```xml - - - - 4672 - 607469 - Security - - - -``` -To specify XML attributes in an eventkey, use the format `{eventkey}_attributes.{attribute_name}`. For example, to specify the `Name` attribute of the `Provider` element in a rule file, it would look like this: - -```yaml -detection: - selection: - Channel: Security - EventID: 4672 - Event.System.Provider_attributes.Name: 'Microsoft-Windows-Security-Auditing' - condition: selection -``` - -### grep search -Hayabusa can perform grep searches in Windows event log files by not specifying any eventkeys. - -To do a grep search, specify the detection as shown below. In this case, if the strings `mimikatz` or `metasploit` are included in the Windows Event log, it will match. It is also possible to specify wildcards. - -```yaml -detection: - selection: - - mimikatz - - metasploit -``` - -> Note: Hayabusa internally converts Windows event log data to JSON format before processing the data so it is not possible to match on XML tags. - -### EventData -Windows event logs are divided into two parts: the `System` part where the fundamental data (Event ID, Timestamp, Record ID, Log name (Channel)) is written, and the `EventData` part where arbitrary data is written depending on the Event ID. The problem is that the names of the tags nested in EventData are all called `Data` so the eventkeys described so far cannot distinguish between `SubjectUserSid` and `SubjectUserName`. - -```xml - - - 5379 - - 607469 - Security - - - - S-1-1-11-1111111111-111111111-1111111111-1111 - hayabusa - DESKTOP-HAYABUSA - 0x11111111 - - -``` - -To deal with this problem, you can specify the value assigned in `Data Name`. For example, if you want to use `SubjectUserName` and `SubjectDomainName` in the EventData as a condition of a rule, you can describe it as follows: - -```yaml -detection: - selection: - Channel: System - EventID: 7040 - Event.EventData.SubjectUserName: hayabusa - Event.EventData.SubjectDomainName: DESKTOP-HAYBUSA - condition: selection -``` - -### Abnormal patterns in EventData -Some of the tags nested in `EventData` do not have a `Name` attribute. - -```xml - - - 5379 - Security - - - - Available - None - NewEngineState=Available PreviousEngineState=None SequenceNumber=9 HostName=ConsoleHost HostVersion=2.0 HostId=5cbb33bf-acf7-47cc-9242-141cd0ba9f0c EngineVersion=2.0 RunspaceId=c6e94dca-0daf-418c-860a-f751a9f2cbe1 PipelineId= CommandName= CommandType= ScriptName= CommandPath= CommandLine= - - -``` - -To detect an event log like the one above, you can specify an eventkey named `EventData`. In this case, the condition will match as long as any one of the nested tags without a `Name` attribute matches. - -```yaml -detection: - selection: - Channel: Security - EventID: 5379 - EventData: None - condition: selection -``` - -## Pipes -A pipe can be used with eventkeys as shown below for matching strings. All of the conditions we have described so far use exact matches, but by using pipes, you can describe more flexible detection rules. In the following example, if the value of `EventData` matches the regular expression `[\s\S]*EngineVersion=2\.0[\s\S]*`, it will match the condition. - -```yaml -detection: - selection: - Channel: Microsoft-Windows-PowerShell/Operational - EventID: 400 - EventData|re: '[\s\S]*EngineVersion=2\.0[\s\S]*' - condition: selection -``` - -This is a list of what you can specify after the pipe. At the moment, hayabusa does not support chaining multiple pipes together. -String matches are normally case insensitive. However, they become case sensitive whenever the following are used: - -* startswith: Checks the string from the beginning -* endswith: Checks the end of the string -* contains: Checks if a word is contained in the data -* re: Use regular expressions. (We are using the regex crate so please out the documentation at https://docs.rs/regex/1.5.4/regex/ to know how to write correct regular expressions.) - > Caution: Some sigma rules that use regular expressions may fail to detect due to differences in Rust's implementation of regex. - -## Wildcards -Wildcards can be used in eventkeys. In the example below, if `ProcessCommandLine` starts with the string "malware", the rule will match. -The specification is fundamentally the same as sigma rule wildcards so will be case insensitive. - -```yaml -detection: - selection: - Channel: Security - EventID: 4688 - ProcessCommandLine: malware* - condition: selection -``` - -The following two wildcards can be used. -* `*`: Matches any string of zero or more characters. (Internally it is converted to the regular expression `.*`) -* `?`: Matches any single character. (Internally converted to the regular expression `.`) - -About escaping wildcards: -* Wildcards (`*` and `?`) can be escaped by using a backslash: `\*`, `\?`. -* If you want to use a backslash right before a wildcard then write `\\*` or `\\?`. -* Escaping is not required if you are using backslashes by themselves. - -## Nesting keywords inside eventkeys -Eventkeys can be nested with specific keywords. -In the example below, the rule will match if the following are true: -* `ServiceName` is called `malicious-service` or contains a regular expression in `./rules/config/regex/detectlist_suspicous_services.txt`. -* `ImagePath` has a minimum of 1000 characters. -* `ImagePath` does not have any matches in the `allowlist`. - -```yaml -detection: - selection: - Channel: System - EventID: 7045 - ServiceName: - - value: malicious-service - - regexes: ./rules/config/regex/detectlist_suspicous_services.txt - ImagePath: - min_length: 1000 - allowlist: ./rules/config/regex/allowlist_legitimate_services.txt - condition: selection -``` - -Currently, the following keywords can be specified: -* `value`: matches by string (wildcards and pipes can also be specified). -* `min_length`: matches when the number of characters is greater than or equal to the specified number. -* `regexes`: matches if one of the regular expressions in the file that you specify in this field matches. -* `allowlist`: rule will be skipped if there is any match found in the list of regular expressions in the file that you specify in this field. - -### regexes and allowlist keywords -Hayabusa has two built-in regular expression files used for the `.\rules\hayabusa\default\alerts\System\7045_CreateOrModiftySystemProcess-WindowsService_MaliciousServiceInstalled.yml` file: -* `./rules/config/regex/detectlist_suspicous_services.txt`: to detect suspicious service names -* `./rules/config/regex/allowlist_legitimate_services.txt`: to allow legitimate services - -Files defined in `regexes` and `allowlist` can be edited to change the behavior of all rules that reference them without having to change any rule file itself. - -You can also use different detectlist and allowlist textfiles that you create. -Please refer to the built-in `./rules/config/regex/detectlist_suspicous_services.txt` and `./rules/config/regex/allowlist_legitimate_services.txt` when creating your own. - -## condition -With the notation we explained above, you can express `AND` and `OR` logic but it will be confusing if you are trying to define complex logic. -When you want to make more complex rules, you should use the `condition` keyword as shown below. - -```yaml -detection: - SELECTION_1: - EventID: 3 - SELECTION_2: - Initiated: 'true' - SELECTION_3: - DestinationPort: - - '4444' - - '666' - SELECTION_4: - Image: '*\Program Files*' - SELECTION_5: - DestinationIp: - - 10.* - - 192.168.* - - 172.16.* - - 127.* - SELECTION_6: - DestinationIsIpv6: 'false' - condition: (SELECTION_1 and (SELECTION_2 and SELECTION_3) and not ((SELECTION_4 or (SELECTION_5 and SELECTION_6)))) -``` - -The following expressions can be used for `condition`. -* `{expression1} and {expression2}`: Require both {expression1} AND {expression2} -* `{expression1} or {expression2}`: Require either {expression1} OR {expression2} -* `not {expression}`: Reverse the logic of {expression} -* `( {expression} )`: Set precedance of {expression}. It follows the same precedance logic as in mathematics. - -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. - -## 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: - -```yaml -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. -In this password spray detection example below, a conditional expression is used to determine if there are 5 or more `TargetUserName` values from one source `IpAddress` within a timeframe of 5 minutes. - -```yaml -detection: - selection: - Channel: Security - EventID: 4648 - condition: selection | count(TargetUserName) by IpAddress > 5 - timeframe: 5m -``` - -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: -* `==`: If the value is equal to the specified value, it is treated as matching the condition. -* `>=`: If the value is greater than or equal to the specified value, the condition is considered to have been met. -* `>`: If the value is greater than the specified value, the condition is considered to have been met. -* `<=`: If the value is less than or equal to the specified value, the condition is considered to have been met. -* `<`: If the value is less than the specified value, it will be treated as if the condition is met. - -`{number}` must be a number. - -`timeframe` can be defined in the following: -* `15s`: 15 seconds -* `30m`: 30 minutes -* `12h`: 12 hours -* `7d`: 7 days -* `3M`: 3 months - - -### Four patterns for aggregation conditions: -1. No count argument or `by` keyword. Example: `selection | count() > 10` - > If `selection` matches more than 10 times within the timeframe, the condition will match. -2. No count argument but there is a `by` keyword. Example: `selection | count() by IpAddress > 10` - > `selection` will have to be true more than 10 times for the **same** `IpAddress`. -3. There is a count argument but no `by` keyword. Example: `selection | count(TargetUserName) > 10` - > If `selection` matches and `TargetUserName` is **different** more than 10 times within the timeframe, the condition will match. -4. There is both a count argument and `by` keyword. Example: `selection | count(Users) by IpAddress > 10` - > For the **same** `IpAddress`, there will need to be more than 10 **different** `TargetUserName` in order for the condition to match. - -### Pattern 1 example: -This is the most basic pattern: `count() {operator} {number}`. The rule below will match if `selection` happens 3 or more times. - -![](CountRulePattern-1-EN.png) - -### Pattern 2 example: -`count() by {eventkey} {operator} {number}`: Log events that match the `condition` before the pipe are grouped by the **same** `{eventkey}`. If the number of matched events for each grouping satisfies the condition specified by `{operator}` and `{number}`, then the condition will match. - -![](CountRulePattern-2-EN.png) - -### Pattern 3 example: -`count({eventkey}) {operator} {number}`: Counts how many **different** values of `{eventkey}` exist in the log event that match the condition before the condition pipe. If the number satisfies the conditional expression specified in `{operator}` and `{number}`, the condition is considered to have been met. - -![](CountRulePattern-3-EN.png) - -### Pattern 4 example: -`count({eventkey_1}) by {eventkey_2} {operator} {number}`: The logs that match the condition before the condition pipe are grouped by the **same** `{eventkey_2}`, and the number of **different** values of `{eventkey_1}` in each group is counted. If the values counted for each grouping satisfy the conditional expression specified by `{operator}` and `{number}`, the condition will match. - -![](CountRulePattern-4-EN.png) - -### Count rule output: -The details output for count rules is fixed and will print the original count condition in `[condition]` followed by the recorded eventkeys in `[result]`. - -In the example below, a list of `TargetUserName` usernames that were being bruteforced followed by the source `IpAddress`: -``` -[condition] count(TargetUserName) by IpAddress >= 5 in timeframe [result] count:41 TargetUserName:jorchilles/jlake/cspizor/lpesce/bgalbraith/jkulikowski/baker/eskoudis/dpendolino/sarmstrong/lschifano/drook/rbowes/ebooth/melliott/econrad/sanson/dmashburn/bking/mdouglas/cragoso/psmith/bhostetler/zmathis/thessman/kperryman/cmoody/cdavis/cfleener/gsalinas/wstrzelec/jwright/edygert/ssims/jleytevidal/celgee/Administrator/mtoussain/smisenar/tbennett/bgreenwood IpAddress:10.10.2.22 timeframe:5m -``` -The timestamp of the alert will be the time from the first event detected. - -# Rule creation advice -1. **When possible, always specify `Channel` and `EventID` name.** In the future, we may filter on channel names and event IDs so your rule may be ignored if this is not set. - -2. **Please do not use multiple `selection` or `filter` fields and excessive grouping when it is not needed.** For example: - -### Instead of: -```yaml -detection: - SELECTION_1: - Channnel: Security - SELECTION_2: - EventID: 4625 - SELECTION_3: - LogonType: 3 - FILTER_1: - SubStatus: "0xc0000064" #Non-existent user - FILTER_2: - SubStatus: "0xc000006a" #Wrong password - condition: SELECTION_1 and SELECTION_2 and SELECTION_3 and not (FILTER_1 or FILTER_2) -``` - -### Please do this: -```yaml -detection: - selection: - Channel: Security - EventID: 4625 - LogonType: 3 - filter: - - SubStatus: "0xc0000064" #Non-existent user - - SubStatus: "0xc000006a" #Wrong password - condition: selection and not filter -``` - -3. **When you need multiple sections, please name the first section with channel and event ID information in the `section_basic_info` section and other selections with meaningful names after `section_` and `filter_`, or use the notation `section_1`, `filter_1`, etc... Also, please write comments to explain anything difficult to understand.** - -### Instead of: -```yaml -detection: - Takoyaki: - Channel: Security - EventID: 4648 - Naruto: - TargetUserName|endswith: "$" - IpAddress: "-" - Sushi: - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - Godzilla: - SubjectUserName|endswith: "$" - Ninja: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" - IpAddress: "-" - Daisuki: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: Takoyaki and Daisuki and not (Naruto and not Godzilla) and not Ninja and not Sushi -``` - -### Please do this: -```yaml -detection: - selection_1: - Channel: Security - EventID: 4648 - selection_2: - TargetUserName|endswith: "$" - IpAddress: "-" - filter_1: #Filter system noise - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - filter_2: - SubjectUserName|endswith: "$" - filter_3: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" #Filter out default Desktop Windows Manager and User Mode Driver Framework accounts - IpAddress: "-" #Don't filter if the IP address is remote to catch attackers who created backdoor accounts that look like DWM-12, etc.. - selection_4: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: selection_1 and selection_4 and not (selection_2 and not filter_2) and not filter_3 and not filter_1 -``` - -### Or ideally something like this: -```yaml -detection: - selection_BasicInfo: - Channel: Security - EventID: 4648 - selection_TargetUserIsComputerAccount: - TargetUserName|endswith: "$" - IpAddress: "-" - filter_UsersAndTargetServerAreComputerAccounts: #Filter system noise - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - filter_SubjectUserIsComputerAccount: - SubjectUserName|endswith: "$" - filter_SystemAccounts: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" #Filter out default Desktop Windows Manager and User Mode Driver Framework accounts - IpAddress: "-" #Don't filter if the IP address is remote to catch attackers who created backdoor accounts that look like DWM-12, etc.. - selection_SuspiciousProcess: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: selection_basic and selection_SuspiciousProcess and not (selection_TargetUserIsComputerAccount - and not filter_SubjectUserIsComputerAccount) and not filter_SystemAccounts and not filter_UsersAndTargetServerAreComputerAccounts -``` - -# Converting sigma rules to hayabusa format -We have created a backend for sigmac to convert rules from sigma to hayabusa format [here](https://github.com/Yamato-Security/hayabusa/blob/main/tools/sigmac/). - -The documentation for how to use it is [here](https://github.com/Yamato-Security/hayabusa/blob/main/tools/sigmac/README-English.md). \ No newline at end of file diff --git a/doc/AboutRuleCreation-Japanese.md b/doc/AboutRuleCreation-Japanese.md deleted file mode 100644 index 6bdc4019..00000000 --- a/doc/AboutRuleCreation-Japanese.md +++ /dev/null @@ -1,595 +0,0 @@ -# ルールファイルについて -Hayabusaの検知ルールは[YAML](https://en.wikipedia.org/wiki/YAML) 形式で記述されています。 -単純な文字列のマッチングだけでなく、正規表現や`AND`、`OR`などの条件を組み合わせて複雑な検知ルールを表現することができます。 -本節ではHayabusaの検知ルールの書き方について説明します。 - -## ルールファイル形式 -記述例: - -```yaml -#Author section -author: Eric Conrad, Zach Mathis -date: 2020/11/08 -modified: 2021/11/26 - -#Alert section -title: User added to local Administrators group -title_jp: ユーザがローカル管理者グループに追加された -details: 'User: %SubjectUserName% : Group: %TargetUserName% : LogonID: %SubjectLogonId%' -details_jp: 'ユーザ: %SubjectUserName% : グループ名: %TargetUserName% : ログオンID: %SubjectLogonId%' -description: A user was added to the local Administrators group. -description_jp: ユーザがローカル管理者グループに追加された。 - -#Rule section -id: 611e2e76-a28f-4255-812c-eb8836b2f5bb -level: high -status: stable -detection: - selection: - Channel: Security - EventID: 4732 - TargetUserName: Administrators - condition: selection -falsepositives: - - system administrator -tags: - - attack.persistence - - attack.t1098 -references: - - https://www.ultimatewindowssecurity.com/securitylog/encyclopedia/event.aspx?eventid=4732 -sample-evtx: ./sample-evtx/EVTX-to-MITRE-Attack/TA0003-Persistence/T1098.xxx-Account manipulation/ID4732-User added to local admin groups.evtx -logsource: default -ruletype: Hayabusa -``` - -> ## 著者名欄 -* **author [必須]**: 著者名（複数可）。 -* **contributor** [オプション]: 寄稿者の名前（細かい修正をした人）。 -* **date [必須]**: ルールが作成された日付。 -* **modified** [オプション]: ルールが更新された日付。 - -> ## アラートセクション -* **title [必須]**: ルールファイルのタイトル。これは表示されるアラートの名前にもなるので、簡潔であるほどよいです。(85文字以下でなければなりません。) -* **title_jp** [オプション]: 日本語のタイトルです。 -* **details** [オプション]: 表示されるアラートの詳細です。Windowsイベントログの中で解析に有効なフィールドがあれば出力してください。フィールドは `" : "` で区切られます（両側ともスペース2つ）。フィールドのプレースホルダは `%` で囲まれ (例: `%MemberName%`) 、`rules\config\eventkey_alias.txt` で定義する必要があります。(以下で説明します) -* **details_jp** [オプション]: 日本語の出力メッセージ。 -* **description** [オプション]: ルールの説明。これは表示されないので、長く詳細に記述することができます。 -* **description_jp** [オプション]: 日本語の説明文です。 - -> ## ルールセクション -* **id [必須]**: ルールを一意に識別するために使用される、ランダムに生成されたバージョン4のUUIDです。 [ここ](https://www.uuidgenerator.net/version4) で生成することができます。 -* **level [必須]**: [sigmaルールの定義](https://github.com/SigmaHQ/sigma/wiki/Specification)に基づく重要度レベル。 以下のいずれかを記述してください。 `informational`,`low`,`medium`,`high`,`critical` -* **status[必須]**: テスト済みのルールには `stable` を、テストが必要なルールには `testing` を指定します。 -* **detection [必須]**: 検知ロジックはここに入ります。(以下で説明します。) -* **falsepositives [必須]**: 誤検知の可能性について記載を行います。例: `system administrator`, `normal user usage`, `normal system usage`, `legacy application`, `security team`, `none`。 不明な場合は `unknown` と記述してください。 -* **tags** [オプション]: [LOLBINS/LOLBAS](https://lolbas-project.github.io/)という手法を利用している場合、`lolbas` タグを追加してください。アラートを[MITRE ATT&CK](https://attack.mitre.org/) フレームワークにマッピングできる場合は、以下のリストから該当するものを追加してください。戦術ID（例：`attack.t1098`）を指定することも可能です。 - * `attack.impact` -> Impact - * `attack.initial_access` -> Initial Access - * `attack.execution` -> Execution - * `attack.lateral_movement` -> Lateral Movement - * `attack.persistence` -> Persistence - * `attack.privilege_escalation` -> Privilege Escalation - * `attack.reconnaissance` -> Reconnaissance - * `attack.collection` -> Collection - * `attack.command_and_control` -> Command and Control - * `attack.credential_access` -> Credential Access - * `attack.defense_evasion` -> Defense Evasion - * `attack.discovery` -> Discovery - * `attack.exfiltration` -> Exfiltration - * `attack.resource_development` -> Resource Development -* **references** [オプション]: 参考文献への任意のリンク。 -* **sample-evtx [必須]**: このルールが検知するイベントログファイルへのファイルパスまたはURL。 -* **logsource [必須]**: ログの出所。以下のいずれかを指定してください。 - * `default`: Windowsでデフォルトで有効になっているログの場合等 - * `non-default`: グループポリシーやセキュリティベースラインなどで有効にする必要があるログ用。 - * `sysmon`: sysmonのインストールが必要なログ。 -* **non-default-setting** [オプション]: `non-default` のログソースのログ設定をオンにする方法の説明です。 -* **ruletype [必須]**: Hayabusaルールには `Hayabusa` を指定します。SigmaのWindowsルールから自動変換されたルールは `Sigma` になります。 - -# detectionフィールド -## selectionの基礎知識 -まず、selectionの作り方の基本を説明します。 - - -### 論理積(AND)と論理和(OR)の書き方 -ANDを表現するには辞書（YAMLでは辞書を`:`で表します）を使用します。 -このルールでログが検知されるには、**両方の条件**が真である必要があります。 - -* イベントIDが `7040` であること。 -* チャンネルが `System` であること。 - -```yaml -detection: - selection: - Event.System.EventID: 7040 - Event.System.Channel: System - condition: selection -``` - -ORを表現するには、配列（YAMLでは配列を`- `で表します）を使用します。 -このルールでログが検知されるには、**片方の条件**が真である必要があります。 - -* イベントIDが `7040` であること。 -* チャンネルが `System` であること。 - -```yaml -detection: - selection: - - Event.System.EventID: 7040 - - Event.System.Channel: System - condition: selection -``` - -また、以下のように「AND」と「OR」を組み合わせることも可能です。 -この場合、以下の2つの条件が両方成立したときに、このルールでログが検知されます。 - -* イベントIDが `7040` **または** `7041` のどちらかであること。 -* チャンネルが `System` であること。 - -```yaml -detection: - selection: - Event.System.EventID: - - 7040 - - 7041 - Event.System.Channel: System - condition: selection -``` - -### イベントキー -WindowsイベントログをXML形式で出力すると下記のようになります。 - -```xml - - - 7040 - System - - - Background Intelligent Transfer Service - auto start - - -``` - -論理和の例で示したルールの `Event.System.Channel` フィールドは、下記のXMLタグで囲まれた値を参照しています。 ネストされたXMLタグはドット(`.`)で区切られたタグ名で置き換えられます。Hayabusaのルールでは、このドットでつながれた文字列のことをイベントキーと呼んでいます。 - -`System` - -#### イベントキーエイリアス -`.`の区切りが多くて長いイベントキーが一般的であるため、Hayabusaはエイリアスを使って簡単に扱えるようにします。エイリアスは `rules\config\eventkey_alias.txt`ファイルで定義されています。このファイルは `alias` と `event_key` のマッピングで構成されるCSVファイルです。以下に示すように、エイリアスを使用して上記のルールを書き直し、ルールを読みやすくすることができます。 - -```yaml -detection: - selection: - Channel: System - EventID: 7040 - condition: selection -``` - -#### 注意: 未定義のイベントキーエイリアスについて -すべてのイベントキーエイリアスが `rules\config\eventkey_alias.txt`に定義されているわけではありません。検知するはずのルールが検知しない場合や、`details`（アラートの詳細）メッセージに`%EventID%`のようなプレースホルダーが表示されている場合、`rules\config\eventkey_alias.txt`の設定を確認してください。 - -### XML属性を条件に使用する方法 -XMLのタグにはタグ名とは別に属性を設定できます。例えば、以下の `Provider Name` の `Name` は `Provider` タグの属性です。 - -```xml - - - - 4672 - 607469 - Security - - - -``` - -イベントキーでXMLの属性を指定するには、`{eventkey}_attributes.{attribute_name}`という形式で記述します。例えば、ルールファイルの `Provider` 要素の `Name` 属性を指定する場合は、以下のようになります。 - -```yaml -detection: - selection: - Channel: Security - EventID: 4672 - Event.System.Provider_attributes.Name: 'Microsoft-Windows-Security-Auditing' - condition: selection -``` - -### grep検索 -Hayabusaではeventkeyを指定せず、WindowsEventログに含まれる文字列にマッチするかどうかを判定する機能も用意されています。この機能をHayabusaではgrep検索と呼んでいます。 - -grep検索をするには下記のようにdetectionを指定します。この場合、`mimikatz`または`metasploit`という文字列がWindowsEventログに含まれる場合に、ルールが検知されます。また、grep検索にはワイルドカードを指定することも可能です。 - -```yaml -detection: - selection: - - `mimikatz` - - `metasploit` -``` - -> ※ Hayabusaでは内部的にWindowsEventログをJSON形式に変換しています。そのため、grep検索ではXMLのタグをマッチさせることはできません。 - -### EventData -Windowsのイベントログは、基本データ（イベントID、タイムスタンプ、レコードID、ログ名（チャンネル））が書き込まれる`System`タグと、イベントIDに応じて任意のデータが書き込まれる`EventData`タグの2つに分けられます。その内、`EventData`タグ はネストされたタグの名前がすべて `Data` であり、これまで説明したイベントキーでは `SubjectUserSid` と `SubjectUserName` を区別できません。 - -```xml - - - 5379 - - 607469 - Security - - - - S-1-1-11-1111111111-111111111-1111111111-1111 - Hayabusa - DESKTOP-Hayabusa - 0x11111111 - - -``` - -この問題に対処するため、`Data`タグの`Name`属性に指定された値をイベントキーとして利用できます。例えば、EventData の `SubjectUserName` と `SubjectDomainName` を条件として利用する場合、以下のように記述することが可能です。 - -```yaml -detection: - selection: - Channel: System - EventID: 7040 - Event.EventData.SubjectUserName: Hayabusa - Event.EventData.SubjectDomainName: DESKTOP-HAYBUSA - condition: selection -``` - -### EventDataの例外的なパターン -`EventData` タグにネストされたいくつかのタグは `Name` 属性を持ちません。 - -```xml - - - 5379 - Security - - - - Available - None - NewEngineState=Available PreviousEngineState=None SequenceNumber=9 HostName=ConsoleHost HostVersion=2.0 HostId=5cbb33bf-acf7-47cc-9242-141cd0ba9f0c EngineVersion=2.0 RunspaceId=c6e94dca-0daf-418c-860a-f751a9f2cbe1 PipelineId= CommandName= CommandType= ScriptName= CommandPath= CommandLine= - - -``` - -上記のようなイベントログを検知するには、`EventData`というイベントキーを指定します。この場合、`EventData`にネストされたタグの内、値がNoneになるタグが1つ以上存在すれば、条件にマッチすることになります。 - -```yaml -detection: - selection: - Channel: Security - EventID: 5379 - EventData: None - condition: selection -``` - -## パイプ -イベントキーにはパイプを指定することができます。ここまで説明した書き方では完全一致しか表現できませんでしたが、パイプを使うことでより柔軟な検知ルールを記載できるようになります。以下の例では、`EventData`の値が正規表現 `[\s\S]*EngineVersion=2.0[\s\S]*` に当てはまる場合、条件にマッチすることになります。 - -```yaml -detection: - selection: - Channel: Microsoft-Windows-PowerShell/Operational - EventID: 400 - EventData|re: '[\s\S]*EngineVersion=2\.0[\s\S]*' - condition: selection -``` - -パイプには以下のキーワードを指定できます。v1の時点で複数のパイプを連結することはできません。 -通常は大文字小文字を区別しません。以下のキーワードを指定した場合は大文字小文字を区別します。 - -* startswith: 指定された文字列で始まることをチェックします。 -* endswith: 指定された文字列で終わることをチェックします。 -* contains: 指定された文字列が含まれることをチェックします。 -* re: 正規表現を使用します。(正規表現の書き方については https://docs.rs/regex/1.5.4/regex/ を参照してください)。 - > 注意: SigmaルールとHayabusaルールは正規表現の記法に一部差異があります。そのため、HayabusaではSigmaルールを正しく検知できない場合があります。 - -## ワイルドカード - -Hayabusaルールではワイルドカードを使用することができます。以下の例では、`ProcessCommandLine` が "malware" という文字列で始まる場合、このルールでログが検知されます。この仕様はSigmaルールのワイルドカードと同じく、大文字小文字を区別しません。 - -```yaml -detection: - selection: - Channel: Security - EventID: 4688 - ProcessCommandLine: malware* - condition: selection -``` - -以下の2つのワイルドカードを使用することができます。 -* `*`: 0文字以上の任意の文字列にマッチします。(内部的には`.*`という正規表現に変換されます)。 -* `?`: 任意の1文字にマッチします。(内部的には`.`という正規表現に変換されます)。 - -ワイルドカードのエスケープについて -* ワイルドカード(`*`と`?`)はバックスラッシュでエスケープできます: `\*` と `\?`. -* ワイルドカードの直前にバックスラッシュを使用する場合、 `\\*` または `\\?` と記述してください。 -* バックスラッシュを単独で使用する場合、エスケープは不要です。 - -## イベントキー内のキーワードのネスト -イベントキーには特定のキーワードをネストすることができます。 - -```yaml -detection: - selection: - Channel: System - EventID: 7045 - ServiceName: - - value: malicious-service - - regexes: ./rules/config/regex/detectlist_suspicous_services.txt - ImagePath: - min_length: 1000 - allowlist: ./rules/config/regex/allowlist_legitimate_services.txt - condition: selection -``` - -現在、指定できるキーワードは以下の通りです。 -* `value`: 文字列によるマッチング (ワイルドカードやパイプも指定可能)。 -* `min_length`: 指定された文字数以上の場合にマッチします。 -* `regexes`: 指定されたファイルに定義された正規表現に1つ以上に一致する場合、**条件にマッチした**ものとして扱われます。 -* `allowlist`: 指定されたファイルに定義された正規表現に1つ以上に一致する場合、**条件にマッチしてない**ものとして扱われます。 - -### regexesとallowlistキーワード -Hayabusaに`.\rules\hayabusa\default\alerts\System\7045_CreateOrModiftySystemProcess-WindowsService_MaliciousServiceInstalled.yml`のルールのために使う2つの正規表現ファイルが用意されています。 -* `./rules/config/regex/detectlist_suspicous_services.txt`: 怪しいサービス名を検知するためのものです。 -* `./rules/config/regex/allowlist_legitimate_services.txt`: 正規のサービスを許可するためのものです。 - -`regexes` と `allowlist` で定義されたファイルの正規表現を変更すると、それらを参照するすべてのルールの動作を一度に変更できます。 - -また、`regexes` と `allowlist` にはユーザーが独自で作成したファイルを指定することも可能です。 -デフォルトの `./rules/config/detectlist_suspicous_services.txt` と `./rules/config/allowlist_legitimate_services.txt` を参考にして、独自のファイルを作成してください。 - -## condition (条件) -これまで説明した記法では簡単な`AND`や`OR`であれば表現可能ですが、複雑な条件は定義できません。そのような場合、`condition` キーワードを使用します。 - -```yaml -detection: - SELECTION_1: - EventID: 3 - SELECTION_2: - Initiated: 'true' - SELECTION_3: - DestinationPort: - - '4444' - - '666' - SELECTION_4: - Image: '*\Program Files*' - SELECTION_5: - DestinationIp: - - 10.* - - 192.168.* - - 172.16.* - - 127.* - SELECTION_6: - DestinationIsIpv6: 'false' - condition: (SELECTION_1 and (SELECTION_2 and SELECTION_3) and not ((SELECTION_4 or (SELECTION_5 and SELECTION_6)))) -``` - - `condition`には、以下の式を用いることができます。 -* `{expression1} and {expression2}`: {expression1} と {expression2} の両方が真である場合にマッチします。 -* `{expression1} or {expression2}`: {expression1} または {expression2} のどちらかが真である場合にマッチします。 -* `not {expression}`: {expression} の真偽を反転させます。 -* `( {expression} )`: `()`で囲まれた {expression} を先に評価します。数学と同じ優先順位に従います。 - -上記の例では、 `SELECTION_1`、` SELECTION_2`などの名前が使用されていますが、名前には `a-z A-Z 0-9 _`の文字を使用可能です。ただし、`selection_1`、` selection_2`、 `filter_1`、` filter_2`などの標準的な規則の利用を推奨します。 - -## notロジック -ルールを作成する場合、誤検知を減らすためにフィルターを作成することはよくあります。以下に利用例を示します。 - -```yaml -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 condition -### 基本事項 -上記の `condition` キーワードは `AND` や `OR` だけでなく、マッチしたイベントの集計も可能です。この機能を利用するには`aggregation condition`を利用します。指定するには条件をパイプでつなぎます。 -以下のパスワードスプレー攻撃の例では、5分以内に同じ送信元の`IpAddress`で5個以上の `TargetUserName`があるかどうかを判断します。 - -```yaml -detection: - selection: - Channel: Security - EventID: 4648 - condition: selection | count(TargetUserName) by IpAddress > 5 - timeframe: 5m -``` - -`aggregation condition`は以下の形式で定義します。 -* `count() {operator} {number}`: パイプの前の最初の条件にマッチするログイベントに対して、マッチしたログの数が `{operator}` と `{number}` で指定した条件式を満たす場合に条件がマッチします。 - -`{operator}` は以下のいずれかになります。 -* `==`: 指定された値と等しい場合、条件にマッチしたものとして扱われる。 -* `>=`: 指定された値以上であれば、条件にマッチしたものとして扱われる。 -* `>`: 指定された値以上であれば、条件にマッチしたものとして扱われる。 -* `<=`: 指定された値以下の場合、条件にマッチしたものとして扱われる。 -* `<`: 指定された値より小さい場合、条件にマッチしたものとして扱われる。 - -`{number}` は数値である必要があります。 - -`timeframe` は以下のように定義することができます。 -* `15s`: 15秒 -* `30m`: 30分 -* `12h`: 12時間 -* `7d`: 7日間 -* `3M`: 3ヶ月 - - -### countの4パターン -1. countの引数と`by` キーワード共に指定しないパターン。例: `selection | count() > 10` - > `selection`にマッチしたログが10件以上ある場合、このルールは検知します。 -2. countの引数はないが、`by` キーワードはある。例: `selection | count() by date > 10` - > `selection`にマッチするログが10件以上あるかどうか、日付毎にチェックします。 -3. countの引数があるが、`by` キーワードがない場合。例: `selection | count(TargetUserName) > 10` - > `selection`に一致する`TargetUserName`が10人以上存在する場合、このルールは検知します。 -4. count 引数と `by` キーワードの両方が存在する。例: `selection | count(TargetUserName) by date > 10` - > `selection`に一致する`TargetUserName`が10人以上存在するかどうか、日付毎にチェックします。 - - -### パターン1の例： -これは最も基本的なパターンです：`count() {operator} {number}`. 以下のルールは、`selection`にマッチしたログが3つ以上である場合、このルールが検知されます。 - -![](CountRulePattern-1-JP.png) - -### パターン2の例： -`count() by {eventkey} {operator} {number}`： `selection`にマッチしたログは、`{eventkey}`の値が**同じログ毎にグルーピング**されます。各グループにおいて、マッチしたイベントの数が`{operator}`と`{number}`で指定した条件を満たした場合、このルールが検知されます。 - -![](CountRulePattern-2-JP.png) - -### パターン3の例： -`count({eventkey}) {operator} {number}`：`selection`にマッチしたログの内、 `{eventkey}` が**異なる**値の数をカウントします。そのカウントされた値が`{operator}`と`{number}`で指定された条件式を満たす場合、このルールが検知されます。 - -![](CountRulePattern-3-JP.png) - -### パターン4の例： -`count({eventkey_1}) by {eventkey_2} {operator} {number}`： `selection`にマッチしたログは、`{eventkey}`の値が**同じログ毎にグルーピングし**、各グループに含まれる`{eventkey_1}`が**異なる**値の数をカウントします。各グループでカウントされた値が`{operator}`と`{number}`で指定された条件式を満たした場合、このルールが検知されます。 - -![](CountRulePattern-4-JP.png) - -### Countルールの出力: -CountルールのDetails出力は固定で、`[condition]`にcount条件と`[result]`に記録されたイベントキーが出力されます。 - -以下の例では、ブルートフォースされた`TargetUserName`のユーザ名のリストと送信元の`IpAddress`が出力されます： -``` -[condition] count(TargetUserName) by IpAddress >= 5 in timeframe [result] count:41 TargetUserName:jorchilles/jlake/cspizor/lpesce/bgalbraith/jkulikowski/baker/eskoudis/dpendolino/sarmstrong/lschifano/drook/rbowes/ebooth/melliott/econrad/sanson/dmashburn/bking/mdouglas/cragoso/psmith/bhostetler/zmathis/thessman/kperryman/cmoody/cdavis/cfleener/gsalinas/wstrzelec/jwright/edygert/ssims/jleytevidal/celgee/Administrator/mtoussain/smisenar/tbennett/bgreenwood IpAddress:10.10.2.22 timeframe:5m -``` -アラートのタイムスタンプには、timeframe内で最初に検知されたイベントの時間が表示されます。 - -# ルール作成のアドバイス -1. **可能な場合は、常に `Channel`と`EventID`を指定してください。** 将来的には、チャネル名とイベンドIDでフィルタリングする可能性があるため、適切な` Channel`と`EventID`が設定されていない場合はルールが無視される可能性があります。 - -2. **不要な場合は複数の `selection`と`filter`セクションを使用しないでください。** - -### 悪い例： -```yaml -detection: -detection: - SELECTION_1: - Channnel: Security - SELECTION_2: - EventID: 4625 - SELECTION_3: - LogonType: 3 - FILTER_1: - SubStatus: "0xc0000064" - FILTER_2: - SubStatus: "0xc000006a" - condition: SELECTION_1 and SELECTION_2 and SELECTION_3 and not (FILTER_1 or FILTER_2) -``` - -### 良い例： -```yaml -detection: - selection: - Channel: Security - EventID: 4625 - LogonType: 3 - filter: - - SubStatus: "0xc0000064" #Non-existent user - - SubStatus: "0xc000006a" #Wrong password - condition: selection and not filter -``` - -3. **複数のセクションが必要な場合は、チャンネル名とイベントIDの情報を記入する最初のセクションを `section_basic_info` セクションに、その他のセクションを `section_` と `filter_` の後に意味のある名前を付けるか、または `section_1`, `filter_1` などの記法を用いてください。また、分かりにくいところはコメントを書いて説明してください。** - -### 悪い例： -```yaml -detection: - Takoyaki: - Channel: Security - EventID: 4648 - Naruto: - TargetUserName|endswith: "$" - IpAddress: "-" - Sushi: - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - Godzilla: - SubjectUserName|endswith: "$" - Ninja: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" - IpAddress: "-" - Daisuki: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: Takoyaki and Daisuki and not (Naruto and not Godzilla) and not Ninja and not Sushi -``` - -### OKな例： -```yaml -detection: - selection_1: - Channel: Security - EventID: 4648 - selection_2: - TargetUserName|endswith: "$" - IpAddress: "-" - filter_1: #Filter system noise - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - filter_2: - SubjectUserName|endswith: "$" - filter_3: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" #Filter out default Desktop Windows Manager and User Mode Driver Framework accounts - IpAddress: "-" #Don't filter if the IP address is remote to catch attackers who created backdoor accounts that look like DWM-12, etc.. - selection_4: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: selection_1 and selection_4 and not (selection_2 and not filter_2) and not filter_3 and not filter_1 -``` - -### 良い例： -```yaml -detection: - selection_BasicInfo: - Channel: Security - EventID: 4648 - selection_TargetUserIsComputerAccount: - TargetUserName|endswith: "$" - IpAddress: "-" - filter_UsersAndTargetServerAreComputerAccounts: #Filter system noise - SubjectUserName|endswith: "$" - TargetUserName|endswith: "$" - TargetInfo|endswith: "$" - filter_SubjectUserIsComputerAccount: - SubjectUserName|endswith: "$" - filter_SystemAccounts: - TargetUserName|re: "(DWM|UMFD)-([0-9]|1[0-2])$" #Filter out default Desktop Windows Manager and User Mode Driver Framework accounts - IpAddress: "-" #Don't filter if the IP address is remote to catch attackers who created backdoor accounts that look like DWM-12, etc.. - selection_SuspiciousProcess: - - ProcessName|endswith: "powershell.exe" - - ProcessName|endswith: "WMIC.exe" - condition: selection_basic and selection_SuspiciousProcess and not (selection_TargetUserIsComputerAccount - and not filter_SubjectUserIsComputerAccount) and not filter_SystemAccounts and not filter_UsersAndTargetServerAreComputerAccounts -``` - -# SigmaルールからHayabusaルール形式への自動変換 -SigmaルールからHayabusaルール形式に自動で変換する[ツール](https://github.com/Yamato-Security/hayabusa/tree/main/tools/sigmac)を作成しました。 - -使用方法は[Readme](https://github.com/Yamato-Security/hayabusa/blob/main/tools/sigmac/README-Japanese.md)を参照してください。 \ No newline at end of file diff --git a/doc/CountRulePattern-1-EN.png b/doc/CountRulePattern-1-EN.png deleted file mode 100644 index 4e8de081..00000000 Binary files a/doc/CountRulePattern-1-EN.png and /dev/null differ diff --git a/doc/CountRulePattern-1-JP.png b/doc/CountRulePattern-1-JP.png deleted file mode 100644 index 495739f2..00000000 Binary files a/doc/CountRulePattern-1-JP.png and /dev/null differ diff --git a/doc/CountRulePattern-2-EN.png b/doc/CountRulePattern-2-EN.png deleted file mode 100644 index 2ebdea1a..00000000 Binary files a/doc/CountRulePattern-2-EN.png and /dev/null differ diff --git a/doc/CountRulePattern-2-JP.png b/doc/CountRulePattern-2-JP.png deleted file mode 100644 index cc6b92d1..00000000 Binary files a/doc/CountRulePattern-2-JP.png and /dev/null differ diff --git a/doc/CountRulePattern-3-EN.png b/doc/CountRulePattern-3-EN.png deleted file mode 100644 index 264ecc47..00000000 Binary files a/doc/CountRulePattern-3-EN.png and /dev/null differ diff --git a/doc/CountRulePattern-3-JP.png b/doc/CountRulePattern-3-JP.png deleted file mode 100644 index e8eb53a2..00000000 Binary files a/doc/CountRulePattern-3-JP.png and /dev/null differ diff --git a/doc/CountRulePattern-4-EN.png b/doc/CountRulePattern-4-EN.png deleted file mode 100644 index 52009cb8..00000000 Binary files a/doc/CountRulePattern-4-EN.png and /dev/null differ diff --git a/doc/CountRulePattern-4-JP.png b/doc/CountRulePattern-4-JP.png deleted file mode 100644 index 4751f8db..00000000 Binary files a/doc/CountRulePattern-4-JP.png and /dev/null differ