CSEC_PUBLIC/hayabusa
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Hotfix/moved rule configs to hayabusa rules repo#409 (#414)

Browse Source 
* fixed target config path #409

* fixed target config file path in test #409

* fixed rules target #409

* Documentation fix, deleted unneeded config files

* added workflow

* changed submodule option

* fixed worksflow to ref submodule

* fixed gitmodules

* fixed workflow

* check code insert

* added update submodules command

* test rules update

* removed test runs

* fixed error

Co-authored-by: Tanaka Zakku <71482215+YamatoSecurity@users.noreply.github.com>
This commit is contained in:
DustInDark
2022-02-26 18:19:19 +09:00
committed by GitHub
parent 02b1d7f07c
commit 92c472d451
19 changed files with 39 additions and 515 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/AboutRuleCreation-English.md
View File

@@ -52,7 +52,7 @@ ruletype: Hayabusa
> ## 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 `config\eventkey_alias.txt`. (Explained below.)
* 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.
@@ -153,7 +153,7 @@ The following is an excerpt of a Windows event log, formatted in the original XM
```
#### 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 `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.
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:
@@ -164,7 +164,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 `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 `config\eventkey_alias.txt` with a new alias.
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.
@@ -313,7 +313,7 @@ About escaping wildcards:
## 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 `./config/regex/detectlist_suspicous_services.txt`.
* `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`.
@@ -324,10 +324,10 @@ detection:
EventID: 7045
ServiceName:
- value: malicious-service
- regexes: ./config/regex/detectlist_suspicous_services.txt
- regexes: ./rules/config/regex/detectlist_suspicous_services.txt
ImagePath:
min_length: 1000
allowlist: ./config/regex/allowlist_legitimate_services.txt
allowlist: ./rules/config/regex/allowlist_legitimate_services.txt
condition: selection
```
@@ -339,13 +339,13 @@ Currently, the following keywords can be specified:
### 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:
* `./config/regex/detectlist_suspicous_services.txt`: to detect suspicious service names
* `./config/regex/allowlist_legitimate_services.txt`: to allow legitimate services
* `./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 `./config/regex/detectlist_suspicous_services.txt` and `./config/regex/allowlist_legitimate_services.txt` when creating your own.
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.

16
doc/AboutRuleCreation-Japanese.md
View File

@@ -51,7 +51,7 @@ ruletype: Hayabusa
> ## アラートセクション
* **title [必須]**: ルールファイルのタイトル。これは表示されるアラートの名前にもなるので、簡潔であるほどよいです。(85文字以下でなければなりません。)
* **title_jp** [オプション]: 日本語のタイトルです。
* **details** [オプション]: 表示されるアラートの詳細です。Windowsイベントログの中で解析に有効なフィールドがあれば出力してください。フィールドは `" : "` で区切られます（両側ともスペース2つ）。フィールドのプレースホルダは `%` で囲まれ (例: `%MemberName%`) 、`config_eventkey_alias.txt` で定義する必要があります。(以下で説明します)
* **details** [オプション]: 表示されるアラートの詳細です。Windowsイベントログの中で解析に有効なフィールドがあれば出力してください。フィールドは `" : "` で区切られます（両側ともスペース2つ）。フィールドのプレースホルダは `%` で囲まれ (例: `%MemberName%`) 、`rules\config\eventkey_alias.txt` で定義する必要があります。(以下で説明します)
* **details_jp** [オプション]: 日本語の出力メッセージ。
* **description** [オプション]: ルールの説明。これは表示されないので、長く詳細に記述することができます。
* **description_jp** [オプション]: 日本語の説明文です。
@@ -157,7 +157,7 @@ WindowsイベントログをXML形式で出力すると下記のようになり
`<Event><System><Channel>System<Channel><System></Event>`
#### イベントキーエイリアス
`.`の区切りが多くて長いイベントキーが一般的であるため、Hayabusaはエイリアスを使って簡単に扱えるようにします。エイリアスは `config\eventkey_alias.txt`ファイルで定義されています。このファイルは `alias` と `event_key` のマッピングで構成されるCSVファイルです。以下に示すように、エイリアスを使用して上記のルールを書き直し、ルールを読みやすくすることができます。
`.`の区切りが多くて長いイベントキーが一般的であるため、Hayabusaはエイリアスを使って簡単に扱えるようにします。エイリアスは `rules\config\eventkey_alias.txt`ファイルで定義されています。このファイルは `alias` と `event_key` のマッピングで構成されるCSVファイルです。以下に示すように、エイリアスを使用して上記のルールを書き直し、ルールを読みやすくすることができます。
```yaml
detection:
@@ -168,7 +168,7 @@ detection:
```
#### 注意: 未定義のイベントキーエイリアスについて
すべてのイベントキーエイリアスが `config\eventkey_alias.txt`に定義されているわけではありません。検知するはずのルールが検知しない場合や、`details`（アラートの詳細）メッセージに`%EventID%`のようなプレースホルダーが表示されている場合、`config\eventkey_alias.txt`の設定を確認してください。
すべてのイベントキーエイリアスが `rules\config\eventkey_alias.txt`に定義されているわけではありません。検知するはずのルールが検知しない場合や、`details`（アラートの詳細）メッセージに`%EventID%`のようなプレースホルダーが表示されている場合、`rules\config\eventkey_alias.txt`の設定を確認してください。
### XML属性を条件に使用する方法
XMLのタグにはタグ名とは別に属性を設定できます。例えば、以下の `Provider Name` の `Name` は `Provider` タグの属性です。
@@ -325,10 +325,10 @@ detection:
EventID: 7045
ServiceName:
- value: malicious-service
- regexes: ./config/regex/detectlist_suspicous_services.txt
- regexes: ./rules/config/regex/detectlist_suspicous_services.txt
ImagePath:
min_length: 1000
allowlist: ./config/regex/allowlist_legitimate_services.txt
allowlist: ./rules/config/regex/allowlist_legitimate_services.txt
condition: selection
```
@@ -340,13 +340,13 @@ detection:
### regexesとallowlistキーワード
Hayabusaに`.\rules\hayabusa\default\alerts\System\7045_CreateOrModiftySystemProcess-WindowsService_MaliciousServiceInstalled.yml`のルールのために使う2つの正規表現ファイルが用意されています。
* `./config/regex/detectlist_suspicous_services.txt`: 怪しいサービス名を検知するためのものです。
* `./config/regex/allowlist_legitimate_services.txt`: 正規のサービスを許可するためのものです。
* `./rules/config/regex/detectlist_suspicous_services.txt`: 怪しいサービス名を検知するためのものです。
* `./rules/config/regex/allowlist_legitimate_services.txt`: 正規のサービスを許可するためのものです。
`regexes` と `allowlist` で定義されたファイルの正規表現を変更すると、それらを参照するすべてのルールの動作を一度に変更できます。
また、`regexes` と `allowlist` にはユーザーが独自で作成したファイルを指定することも可能です。
デフォルトの `./config/detectlist_suspicous_services.txt` と `./config/allowlist_legitimate_services.txt` を参考にして、独自のファイルを作成してください。
デフォルトの `./rules/config/detectlist_suspicous_services.txt` と `./rules/config/allowlist_legitimate_services.txt` を参考にして、独自のファイルを作成してください。
## condition (条件)
これまで説明した記法では簡単な`AND`や`OR`であれば表現可能ですが、複雑な条件は定義できません。そのような場合、`condition` キーワードを使用します。