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

RuleCreationの英訳

Browse Source
This commit is contained in:
Tanaka Zakku
2021-11-11 07:23:11 +11:00
parent 5bfa6832c0
commit 9fad9332b3
1 changed files with 104 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/AboutRuleCreation-English.md
+104 -92
View File
@@ -1,10 +1,10 @@
# ルールファイル # Rule files
HayabusaはWindowsEventログの検知ルールをYAML形式のファイルに記載します。 Hayabusa uses detection rules for Windows Event logs in a YAML format file.
単なる文字列一致だけでなく、正規表現やANDやOR等の条件を組み合わせることができ、複雑な検知ルールも表現できるようになっています。 It 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 the detection rules.
# ルールファイルのフォーマット # Rule file format
ルールファイルのフォーマットは下記の通りです。 The rule file format is described below.
`````` ``````
title: PowerShell Execution Pipeline title: PowerShell Execution Pipeline
@@ -22,25 +22,25 @@ creation_date: 2020/11/8
updated_date: 2020/11/8 updated_date: 2020/11/8
`````` ``````
* title [required]: ルールファイルのタイトルを入力します。 * title [required]: Rule file title. This will also be the name of the alert that gets displayed so the briefer the better.
* description [optional]: ルールファイルの説明を入力します。 * description [optional]: A description of the rule. This does not get displayed so you can make this long.
* author [optional]: ルールファイルの作者を入力します。 * author [optional]: The name of the person or persons who created the logic for the rule.
* detection [required]: 検知ルールを入力します。 * detection [required]: The detection logic goes here.
* falsepositives [optional]: 誤検知に関する情報を入力します。例：System Administrator、Normal User Usage、Security Team等々。 * falsepositives [optional]: The possibilities for false positives. For example: unknown、system administrator、normal user usage、normal system usage、legacy application、security team. If it is unknown, write "unknown".
* level [optional]: リスクレベルを入力します。指定する値は`info`,`low`,`medium`,`high`,`critical`のいづれかです。 * level [optional]: Risk level. Please write one of the following: `info`,`low`,`medium`,`high`,`critical`
* output [required]: イベントログが検知した場合に表示されるメッセージを入力します。 * output [required]: The details of the alert. (Please output any and only useful fields in the Windows event log for easy analysis.)
* creation_date [optional]: ルールファイルの作成日を入力します。 * creation_date [optional]: The creation date.
* updated_date [optional]: ルールファイルの更新日を入力します。 * updated_date [optional]: The date of the last revision.
# detectionの記法について # About detection notation
## detectionの基本 ## Detection fundamentals
まず、detectionの基本的な書き方について説明します。 First, the fundamentals of how to create a detection rule will be explained.
### AND条件とOR条件の書き方 ### How to write AND and OR logic
AND条件を記載する場合はYAMLのハッシュを用いて記載します。 To write AND logic, we use the YAML hash.
下記のようにdetectionを記載すると、以下`両方の条件を満たす`イベントログを検知します。 The detection rule below defines that *both conditions* have to be true in order for the rule to match.
* EventIDが`7040`に完全一致する * EventID has to exactly be `7040`.
* Channelが`System`に完全一致する * Channel has to exactly be `System`.
`````` ``````
detection: detection:
@@ -49,10 +49,10 @@ detection:
Event.System.Channel: System Event.System.Channel: System
`````` ``````
OR条件を記載する場合は配列を利用します。 To write OR logic, we use arrays.
下記のようにdetectionを記載すると、以下`いずれの条件を満たす`イベントログを検知します。 In the detection rule below, *either one* of the conditions will result in the rule being triggered.
* EventIDが`7040`に完全一致する * EventID has to exactly be `7040`.
* Channelが`System`に完全一致する * Channel has to exactly be `System`.
`````` ``````
detection: detection:
@@ -61,10 +61,10 @@ detection:
- Event.System.Channel: System - Event.System.Channel: System
`````` ``````
また、下記のように記載することもできます。 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が`7040`又は`7041`に完全一致する * EventID is either exactly `7040` or `7041`.
* Channelが`System`に完全一致する * Channel is exactly `System`.
`````` ``````
detection: detection:
@@ -75,8 +75,8 @@ detection:
Event.System.Channel: System Event.System.Channel: System
`````` ``````
### eventkey ### Eventkey
WindowsイベントログをXML形式で一部抜粋で出力すると、下記のようになります。ルールファイルの例に含まれる`Event.System.Channel`は、XMLの`<Event><System><Channel>System<Channel><System></Event>`を指しています。今回の例のように、XML形式のWindowsイベントログについて、入れ子になったXMLのタグに含まれる値をルールの条件に指定する場合、`.`でつなげて指定します。ルールファイルでは、この`.`でつなげた文字列をeventkeyと呼んでいます。 The following is an excerpt of a Windows event log, formatted in the original XML. The `Event.System.Channel` in the rule file example refers to the XML `<Event><System><Channel>System<Channel><System></Event>`. For Windows event logs in XML format, as in this example, if you want to specify the values contained in the nested XML tags as the condition of the rule, you can specify them by connecting them with a dot (`. `). In the rule file, these strings connected together with dots are called `eventkeys`.
`````` ``````
<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'> <Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>
@@ -86,13 +86,13 @@ WindowsイベントログをXML形式で一部抜粋で出力すると、下記
</System> </System>
<EventData> <EventData>
<Data Name='param1'>Background Intelligent Transfer Service</Data> <Data Name='param1'>Background Intelligent Transfer Service</Data>
<Data Name='param2'>自動的な開始</Data> <Data Name='param2'>auto start</Data>
</EventData> </EventData>
</Event> </Event>
`````` ``````
### eventkeyのalias ### Eventkey Aliases
`.`でつなげたeventkeyは長い文字列になってしまうことがあるため、hayabusaではeventkeyに対するエイリアスを使用できます。エイリアスは`config\eventkey_alias.txt`というファイルに定義されています。ファイルはCSV形式であり、aliasとevent_keyという列から構成されています。aliasにはエイリアスを定義し、event_keyには`.`でつなげたeventkeyを指定します。このエイリアスを用いると、最初に例に挙げたdetectionは以下のように書き換えることができます。 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.
`````` ``````
detection: detection:
@@ -100,8 +100,9 @@ detection:
EventID: 7040 EventID: 7040
Channel: System Channel: System
`````` ``````
### XMLの属性(attribute)をルールの条件にする方法
WindowsEventログをXML形式で出力すると、XMLの属性に値が設定されている場合もあります。下記の例だと、ProviderタグのNameがXMLの属性です。 ### How to use XML attributes in conditions
When Windows event logs are output in XML format, the XML attributes may have values set in them. In the example below, `Name` in `Provider Name` is an XML attribute.
```````````` ````````````
<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'> <Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>
@@ -114,8 +115,7 @@ WindowsEventログをXML形式で出力すると、XMLの属性に値が設定
</System> </System>
</Event> </Event>
```````````` ````````````
To specify XML attributes in an eventkey, use the format `{eventkey}_attributes.{attribute_name}`. For example, to specify the `Name` attribute of the `Provider` tag in the rule file, it would look like this:
XMLの属性をeventkeyで指定するには、{eventkey}_attributes.{attribute_name}という形式で指定します。例えば、ProviderタグのName属性をルールファイルに指定する場合、下記のようになります。
`````` ``````
detection: detection:
@@ -126,7 +126,8 @@ detection:
`````` ``````
### EventData ### EventData
WindowsEventログをXML形式で出力すると、EventDataというタグが使用されている場合があります。(EventDataタグは様々なEventIDのログで頻繁に利用されます。)このEventDataにネストされたタグの名前は全て`Data`となっており、ここまで説明してきたeventkeyではSubjectUserSidやSubjectUserNameを区別することができません。 Windows event logs are divided into two parts: the `System` part where the fundamental data (Event ID, Timestamp, Record ID, Log name (aka 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 `Data` so the eventkeys described so far cannot distinguish between `SubjectUserSid` and `SubjectUserName`.
```````````` ````````````
<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'> <Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>
<System> <System>
@@ -145,7 +146,7 @@ WindowsEventログをXML形式で出力すると、EventDataというタグが
</Event> </Event>
```````````` ````````````
この問題に対応するため、eventkeyで`Data`の代わりに`Name`に指定されている値をeventkeyに指定できるようになっています。例えば、EventData内のSubjectUserNameとSubjectDomainNameをルールの条件とする場合、下記のように記載します。 To deal with this problem, you can specify the value specified for `Name` in the eventkey instead of `Data`. For example, if you want to use `SubjectUserName` and `SubjectDomainName` in the EventData as a condition of the rule, you can describe it as follows:
`````` ``````
detection: detection:
@@ -156,8 +157,9 @@ detection:
Event.EventData.SubjectDomainName: DESKTOP-HAYBUSA Event.EventData.SubjectDomainName: DESKTOP-HAYBUSA
`````` ``````
### EventDataの特殊なパターン ### Special patterns in EventData
EventDataというタグにネストされたタグの中には、Name属性が存在しないタグもあります。 Some of the tags nested in EventData do not have a Name attribute.
`````` ``````
<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'> <Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'>
<System> <System>
@@ -173,7 +175,8 @@ EventDataというタグにネストされたタグの中には、Name属性が
</Event> </Event>
`````` ``````
上記のようなイベントログを検知する場合、`EventData`というeventkeyを指定します。この場合、EventDataタグにネストされているName属性の指定されてないタグのうち、いずれか一つでも一致するタグがあれば、条件に一致したものとして処理されます。 To detect an event log like the one above, you can specify an eventkey named `EventData`. In this case, the condition will matach as long as any one of the nested tags without a Name attribute matches.
`````` ``````
detection: detection:
selection: selection:
@@ -182,8 +185,8 @@ detection:
EventData: None EventData: None
`````` ``````
## パイプ ## Pipes
eventkeyにはパイプを指定することができます。ここまで説明した書き方では完全一致しか表現できませんでしたが、パイプを使うことでより柔軟な検知ルールを記載できるようになります。下記の例ではCommandLineの値が`yamato.*hayabusa`という正規表現にマッチする場合、条件に一致したものとして処理されます。 A pipe can be used with eventkeys as shown below. 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 `CommandLine` matches the regular expression `yamato.*hayabusa`, it will match the condition.
`````` ``````
detection: detection:
@@ -193,14 +196,15 @@ detection:
CommandLine|re: yamato.*hayabusa CommandLine|re: yamato.*hayabusa
`````` ``````
使用できるパイプの一覧です。なお、v1.0.0時点では、複数のパイプをつなげて使用することはできません。 This is a list of what you can specify after the pipe. At the moment, hayabusa does not support chaining multiple pipes together.
* startswith: 先頭一致 * startswith: Checks the string from the beginning
* endswith: 後方一致 * endswith: Checks the end of the string
* contains: 部分一致 * contains: Checks if a word is contained in the data
* re: 正規表現(正規表現の処理にはregexクレートを使用しています。正規表現の詳細記法についてはhttps://docs.rs/regex/1.5.4/regex/を参照してください。) * re: Use regular expressions. (We are using the regex crate so please out the documentation at https://docs.rs/regex/1.5.4/regex/ on how to write regular expressions.)
## ワイルドカード ## Wildcards
eventkeyに対応する値にはワイルドカードを指定することができます。下記の例ではCommandLineがhayabusaという文字列で始まっていれば、条件に一致したものとして処理されます。基本的にはsigmaルールのwildcardと同じ仕様になっています。 Wildcards can be specified for the value corresponding to eventkey. In the example below, if the CommandLine starts with the string "hayabusa", it will be processed as if it matches the condition.
The specification is fundamentally the same as SIGMA rule wildcards.
`````` ``````
detection: detection:
@@ -210,17 +214,18 @@ detection:
CommandLine: hayabusa* CommandLine: hayabusa*
`````` ``````
使用できるワイルドカードの一覧です。 The following wildcards can be used.
* `*`: 任意の0文字以上の文字列にマッチします。(内部的には`.*`という正規表現に変換されます。) * `*`: Matches any string of zero or more characters. (Internally it is converted to the regular expression `. *`.)
* `?`: 任意の1文字にマッチします。(内部的には`.`という正規表現に変換されます。) * `? `: Matches any single character. (Internally converted to the regular expression `. `.)
ワイルドカードを使用する場合、下記のルールに則って解釈されます。 When wildcards are used, they will be interpreted according to the following rules.
* ワイルドカード(`*`と`?`)をエスケープするにはバックスラッシュ(`/`)を使用します。 * Wildcards (`*` and `? `) can be escaped by using a backslash (`/`).
* ワイルドカードの直前に文字としてのバックスラッシュ(`/`)を使用する場合、`\\*`又は`\\?`と記載してください。 * If you want to use a backslash right before a wildcard then write `\\*` or `\\?`.
* バックスラッシュを単体で使う分にはエスケープ不要です。 * No escaping is required if you are using backslashes by themselves.
## eventkeyにネストできるキーワード ## Nesting keywords in the eventkey
eventkeyには特定のキーワードをネストさせることができます。下記の例ではCommandLineの値が`aa*bb`というワイルドカードにマッチした上で文字列長が10以上である場合、条件に一致したものと処理されます。 The eventkey can be nested with specific keywords.
In the example below, if the value of CommandLine matches the wildcard `aa*bb` and the length of the string is 10 or more, the condition will match.
`````` ``````
detection: detection:
@@ -232,19 +237,22 @@ detection:
min_length: 10 min_length: 10
`````` ``````
現状では下記のキーワードを指定できます。 Currently, the following keywords can be specified.
* value: 文字列による一致(ワイルドカードやパイプを指定することもできます) * value: matches by string (wildcards and pipes can also be specified).
* min_length: 指定した文字数以上である場合、条件に一致したものとして処理されます。 * min_length: matches when the number of characters is greater than or equal to the specified number.
* regexes: 指定したファイルに記載された正規表現のリストにひとつでも一致すれば、`条件に一致した`ものとして処理されます。 * regexes: matches if one of the regular expressions in the file that you specify in this field matches.
* allowlist: 指定したファイルに記載された正規表現のリストにひとつでも一致すれば、`条件に一致していない`ものとして処理されます。 * 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.txtとallowlist.txt ### regexes.txt and allowlist.txt
hayabusaではregexesやallowlistを使用した組み込みのルールを用意しており、それらのルールはregexes.txtとallowlist.txtを参照しています。regexes.txtとallowlist.txtを書き換えることで、参照する全てのルールの挙動を一度に変更することが可能です。 Hayabusa provides built-in rules using regular expressions (defined in `regexes.txt`) and allowlisting (defined in `allowlist.txt`).
regexes.txt and allowlist.txt can be edited to change the behavior of all referenced rules at once.
また、regexesやallowlistに指定するファイルは、ユーザーが独自に作成することも可能です。作成する場合、regexes.txtとallowlist.txtを参考にしてください。 You can also specify to use different regexes and allowlist textfiles.
Please refer to the default regexes.txt and allowlist.txt when creating your own.
## condition ## condition
これまでの記法を用いると、AND条件やOR条件を表現することができますが、ANDやOR等が複雑に入り組んだ条件を定義することは難しい場合があります。その場合、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 `condition` as shown below.
`````` ``````
detection: detection:
@@ -264,16 +272,18 @@ detection:
condition: ( selection_1 or selection_2 ) and selection_3 and ( selection_4 or selection_5 ) and ( not selection_6 ) condition: ( selection_1 or selection_2 ) and selection_3 and ( selection_4 or selection_5 ) and ( not selection_6 )
`````` ``````
conditionには以下のキーワードを使用することができます。 The following keywords can be used for `condition`.
* {expression1} and {expression2}: {expression1}と{expression2}のAND条件を表します。 * {expression1} and {expression2}: Require both {expression1} AND {expression2}
* {expression1} or {expression2}: {expression1}と{expression2}のOR条件を表します。 * {expression1} or {expression2}: Require either {expression1} OR {expression2}
* not {expression}: {expression}の条件式の真偽を逆転させます。 * not {expression}: Reverse the logic of {expression}
* ( {expression} ) : {expression}の条件式を優先して評価します。数学等で現れる括弧と同じです。 * ( {expression} ) : Set precedance of {expression}. It follows the same precedance logic as in mathematics.
なお、上記の例では、条件式をグルーピングするためにselection_1やselection_2といった名前を使用していますが、selectionというprefixを付ける必要はなく、ユーザーが任意の名前を定義できます。ただし、使用可能な文字は`\w`という正規表現にマッチする文字のみです。 In the above example, names such as selection_1 and selection_2 are used for grouping conditional expressions, but there is no need to add the prefix "selection", and the user can define any name. However, the only characters that can be used are those that match the regular expression `\w`.
## aggregation condition ## aggregation condition
上記で説明したconditionには、andやor条件だけでなく、検知したイベントログを集計するような機能も実装されています。この機能をaggregation conditionと呼んでおり、conditionの後にパイプでつなげて指定します。下記の例では、DestinationIpの値が3種類以上あるかどうかをSubjectUserName毎に判定する条件式になります。 The condition field described above implements not only the AND and OR conditions, but also a function to aggregate the detected event logs.
This function is called the aggregation condition, and is specified by connecting it with a pipe after the condition.
In the example below, a conditional expression is used to determine if there are three or more `DestinationIp` values for each `SubjectUserName`.
`````` ``````
detection: detection:
@@ -283,32 +293,34 @@ detection:
condition: selection | count(DestinationIp) by SubjectUserName >= 3 condition: selection | count(DestinationIp) by SubjectUserName >= 3
`````` ``````
aggregation conditionは下記の形式で定義できます。なお、{number}には数値を指定します。 The aggregation condition can be defined in the following format. Note that {number} must be a number.
* `count() {operator} {number}`: conditionのパイプ以前の条件に一致したログについて、一致したログ数が{operator}と{number}で指定した条件式を満たす場合に、条件に一致したものとして処理されます。 * `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}.
![](count1.png) ![](count1.png)
* `count() by {eventkey_2} {operator} {number}`: conditionのパイプ以前の条件に一致したログを{eventkey_2}毎にグルーピングし、グルーピング毎に一致したログ数が{operator}と{number}で指定した条件式を満たす場合に、条件に一致したものとして処理されます。 * `count() by {eventkey_2} {operator} {number}`: Log events that match the first condition before pipe are grouped by {eventkey_2}, and if the number of matched events for each grouping satisfies the condition expression specified by {operator} and {number}, the condition will match.
![](count2.png) ![](count2.png)
* `count({eventkey}) {operator} {number}`: conditionのパイプ以前の条件に一致したログについて、{eventkey}の値が何種類存在するか数えます。その数が{operator}と{number}で指定した条件式を満たす場合に、条件に一致したものとして処理されます。 * `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.
![](count3.png) ![](count3.png)
* `count({eventkey_1}) by {eventkey_2} {operator} {number}`: conditionのパイプ以前の条件に一致したログを{eventkey_2}毎にグルーピングし、そのグループ毎に{eventkey_1}の値が何種類存在するか数えます。そのグルーピング毎に数えた値が{operator}と{number}で指定した条件式を満たす場合に、条件に一致したものとして処理されます。 * `count({eventkey_1}) by {eventkey_2} {operator} {number}`: The logs that match the condition before the condition pipe are grouped by {eventkey_2}, and the number of 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 is considered to have been met.
![](count4.png) ![](count4.png)
また、上記のoperatorには下記を指定できます。 In addition, the following can be specified for the above operator:
* `==`: 指定された値と等しい場合、条件に一致したものと処理されます。 * `==`: 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.
# outputの記法 # output notation
detectionの条件に一致した場合に、出力されるメッセージを指定できます。固定の文字列が出力できる他、eventkeyを%で囲むことにより、検知したログの値を表示することも可能です。下記の例では検知した際のメッセージにScriptBlockTextというeventkeyの値を使用しています。 You can specify the message that will be outputted when the detection condition is met.
In addition to outputting a fixed string, it is also possible to display the value in the event log by enclosing the eventkey in a `%`.
In the example below, the eventkey value ScriptBlockText is used in the message when a detection is made.
`````` ``````
output: 'command=%ScriptBlockText%' output: 'command=%ScriptBlockText%'