From 474ed513b1f71cffde8305d9ec34f52aee47a876 Mon Sep 17 00:00:00 2001 From: James Takai / hach1yon <32596618+hach1yon@users.noreply.github.com> Date: Fri, 24 Dec 2021 17:59:46 +0900 Subject: [PATCH] =?UTF-8?q?readme=E3=82=92=E8=89=B2=E3=80=85=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=20(#346)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 色々修正 * ちょっと修正 * fix camelcase * fix * little fix * fix * Added section on running from bin directory * fix jp Co-authored-by: Tanaka Zakku <71482215+YamatoSecurity@users.noreply.github.com> --- README-English.md | 34 +++--- README-Japanese.md | 46 ++++---- doc/AboutRuleCreation-English.md | 5 +- doc/AboutRuleCreation-Japanese.md | 178 ++++++++++++++---------------- 4 files changed, 133 insertions(+), 130 deletions(-) diff --git a/README-English.md b/README-English.md index 13112a1b..215ff84e 100644 --- a/README-English.md +++ b/README-English.md @@ -107,9 +107,17 @@ You can download the sample evtx files to a new `hayabusa-sample-evtx` sub-direc git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git ``` -> Note: Please run this command from the hayabusa root folder if you want to follow along in the examples below. +> Note: You need to run the binary from the Hayabusa root directory. # Usage +You need to run the binary from the Hayabusa root directory. +There are different binary versions in `.\bin` compiled for different operating systems and architectures. +Also, there are two different versions of the evtx library being used when compiled: `0.6.7` and `0.7.2`. +The `0.7.2` version should work but we have only tested it with `0.6.7` so please use that if you experience any problems with `0.7.2`. +Please replace `hayabusa.exe` in the examples below with the appropriate Hayabusa binary filename. + +> Note: You need to run the Hayabusa binary from the Hayabusa root directory. + ## Command line options ```bash USAGE: @@ -136,62 +144,62 @@ USAGE: ## Usage examples * Run hayabusa against one Windows event log file: ```bash -hayabusa.exe -f eventlog.evtx +.\bin\hayabusa.exe -f eventlog.evtx ``` * Run hayabusa against the sample-evtx directory with multiple Windows event log files: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx ``` * Export to a single CSV file for further analysis with excel or timeline explorer: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv ``` * Only run hayabusa rules (the default is to run all the rules in `-r .\rules`): ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv ``` * Only run hayabusa rules for logs that are enabled by default on Windows: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default -o results.csv ``` * Only run hayabusa rules for sysmon logs: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv ``` * Only run sigma rules: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv ``` * Enable deprecated rules (those with `status` marked as `deprecated`) and noisy rules (those whose rule ID is listed in `.\config\noisy-rules.txt`): ```bash -hayabusa.exe -d .\hayabusa-sample-evtx --enable-noisy-rules --enable-deprecated-rules -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx --enable-noisy-rules --enable-deprecated-rules -o results.csv ``` * Only run rules to analyze logons and output in the UTC timezone: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default\events\Security\Logons -u -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default\events\Security\Logons -u -o results.csv ``` * Run on a live Windows machine (requires Administrator privileges) and only detect alerts (potentially malicious behavior): ```bash -hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low +.\bin\hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low ``` * Get event ID statistics: ```bash -hayabusa.exe -f Security.evtx -s +.\bin\hayabusa.exe -f Security.evtx -s ``` * Print verbose information (useful for determining which files take long to process, parsing errors, etc...): ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -v +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -v ``` * Verbose output example: diff --git a/README-Japanese.md b/README-Japanese.md index 52ec8848..cd0bfc0e 100644 --- a/README-Japanese.md +++ b/README-Japanese.md @@ -7,22 +7,22 @@ # Hayabusa について -Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/)グループによって作られた**Windowsイベントログのファストフォレンジックタイムライン生成**および**スレットハンティングツール**であります。 Hayabusaは日本語で[「ハヤブサ」](https://en.wikipedia.org/wiki/Peregrine_falcon)を意味し、ハヤブサが世界で最も速く、狩猟(hunting)に優れ、とても訓練しやすい動物であることから選ばれました。[Rust](https://www.rust-lang.org/) で開発され、マルチスレッドに対応し、可能な限り高速に動作するよう配慮されています。[Sigma](https://github.com/SigmaHQ/Sigma)ルールをHayabusaルール形式に変換する[ツール](https://github.com/Yamato-Security/hayabusa/tree/main/tools/Sigmac)も提供しています。Hayabusaの検知ルールもSigmaと同様に、できるだけ簡単にカスタマイズや拡張ができるようにYMLで書かれています。稼働中のシステムで実行してライブ調査することも、複数のシステムからログを収集してオフライン調査することも可能です。(※現時点では、リアルタイムアラートや定期的なスキャンには対応していません。) 出力は一つの CSV タイムラインにまとめられ、Excelや[Timeline Explorer](https://ericzimmerman.github.io/#!index.md)で簡単に分析できるようになります。 +Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/)グループによって作られた**Windowsイベントログのファストフォレンジックタイムライン生成**および**スレットハンティングツール**です。 Hayabusaは日本語で[「ハヤブサ」](https://en.wikipedia.org/wiki/Peregrine_falcon)を意味し、ハヤブサが世界で最も速く、狩猟(hunting)に優れ、とても訓練しやすい動物であることから選ばれました。[Rust](https://www.rust-lang.org/) で開発され、マルチスレッドに対応し、可能な限り高速に動作するよう配慮されています。[Sigma](https://github.com/SigmaHQ/Sigma)ルールをHayabusaルール形式に変換する[ツール](https://github.com/Yamato-Security/hayabusa/tree/main/tools/Sigmac)も提供しています。Hayabusaの検知ルールもSigmaと同様にYML形式であり、カスタマイズ性や拡張性に優れます。稼働中のシステムで実行してライブ調査することも、複数のシステムからログを収集してオフライン調査することも可能です。(※現時点では、リアルタイムアラートや定期的なスキャンには対応していません。) 出力は一つのCSVタイムラインにまとめられ、Excelや[Timeline Explorer](https://ericzimmerman.github.io/#!index.md)で簡単に分析できるようになります。 ## 主な目的 ### スレット(脅威)ハンティング -Hayabusa には現在、1000以上のSigmaルールと約50のHayabusa検知ルールがあり、定期的にルールが追加されています。 最終的な目標はインシデントの後で、または定期的なスレットハンティングのために、HayabusaエージェントをすべてのWindows端末にプッシュして、中央サーバーにアラートを返すことができるようにすることです。 +Hayabusa には現在、1000以上のSigmaルールと約50のHayabusa検知ルールがあり、定期的にルールが追加されています。 最終的な目標はインシデントレスポンスや定期的なスレットハンティングのために、HayabusaエージェントをすべてのWindows端末にインストールして、中央サーバーにアラートを返す仕組みを作ることです。 ### フォレンジックタイムラインの高速生成 Windowsのイベントログは、 1）解析が困難なデータ形式であること 2）データの大半がノイズであり調査に有用でないこと から、従来は非常に長い時間と手間がかかる解析作業となっていました。 Hayabusa は、有用なデータのみを抽出し、専門的なトレーニングを受けた分析者だけでなく、Windowsのシステム管理者であれば誰でも利用できる読みやすい形式で提示することを主な目的としています。 -[Evtx Explorer](https://ericzimmerman.github.io/#!index.md)や[Event Log Explorer](https://eventlogxp.com/)のような、より深く掘り下げた分析を行うツールの代替となることは意図していませんが、分析者が20%の時間で80%の作業を行えるようにすることを目的としています。 +[Evtx Explorer](https://ericzimmerman.github.io/#!index.md)や[Event Log Explorer](https://eventlogxp.com/)のような深掘り分析を行うツールの代替ではなく、分析者が20%の時間で80%の作業を行えるようにすることを目的としています。 # 開発について -[DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI)というWindowsイベントログ解析ツールに触発されて、2020年に[RustyBlue](https://github.com/Yamato-Security/RustyBlue)プロジェクト用にRustに移植することから始めました。その後、YMLで書かれたSigmaのような柔軟な検知シグネチャを作り、Sigmaルールを我々のHayabusaルール形式へ変換するサポートをSigmaへのバックエンドとして追加しています。 +[DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI)というWindowsイベントログ解析ツールに触発されて、2020年に[RustyBlue](https://github.com/Yamato-Security/RustyBlue)プロジェクト用にRustに移植することから始めました。その後、YMLで書かれたSigmaのような柔軟な検知シグネチャを作り、Sigmaルールを我々のHayabusaルール形式へ変換するツールも作成しました。 # スクリーンショット ## 起動画面: @@ -111,6 +111,14 @@ git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git > ※ 以下の例でHayabusaを試したい方は、上記コマンドをhayabusaのルートフォルダから実行してください。 # 使用方法 +Hayabusaはルートディレクトリでバイナリを実行する必要があります。 +.\bin` には、OSやアーキテクチャごとにコンパイルされたバイナリが用意されています。 +また、evtxライブラリのバージョン(`0.6.7`と`0.7.2`)毎に、コンパイルされたバイナリが用意されています。 +`0.7.2`バージョンでも動作するはずですが、`0.6.7`でしかテストしていませんので、`0.7.2`で問題が発生した場合はそちらをご利用ください。 +以下の例の `hayabusa.exe` は、適切なHayabusaのバイナリファイル名に置き換えてください。 + +> 注意: Hayabusaのルートディレクトリから、バイナリを実行する必要があります。 + ## コマンドラインオプション ```bash USAGE: @@ -137,62 +145,62 @@ USAGE: ## 使用例 * 1 つのWindowsイベントログファイルに対してHayabusaを実行します: ```bash -hayabusa.exe -f eventlog.evtx +.\bin\hayabusa.exe -f eventlog.evtx ``` * 複数のWindowsイベントログファイルのあるsample-evtxディレクトリに対して、Hayabusaを実行します: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx ``` * 1 つのCSVファイルにエクスポートして、EXCELやTimeline Explorerでさらに分析することができます: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv ``` * Hayabusaルールのみを実行します（デフォルトでは `-r .\rules` にあるすべてのルールが利用されます）: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv ``` * Windowsでデフォルトで有効になっているログに対してのみ、Hayabusaルールを実行します: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default -o results.csv ``` * Sysmonログに対してのみHayabusaルールを実行します: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv ``` * Sigmaルールのみを実行します: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv ``` * 廃棄(deprecated)されたルール(`status`が`deprecated`になっているルール)とノイジールール(`.\config\noisy-rules.txt`にルールIDが書かれているルール)を有効にします: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx --enable-deprecated-rules --enable-noisy-rules -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx --enable-deprecated-rules --enable-noisy-rules -o results.csv ``` * ログオン情報を分析するルールのみを実行し、UTCタイムゾーンで出力します: ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -r ./rules/Hayabusa/default/events/Security/Logons -u -o results.csv +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -r ./rules/Hayabusa/default/events/Security/Logons -u -o results.csv ``` * 起動中のWindows端末上で実行し（Administrator権限が必要）、アラート（悪意のある可能性のある動作）のみを検知します: ```bash -hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low +.\bin\hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low ``` * イベントIDの統計情報を取得します: ```bash -hayabusa.exe -f Security.evtx -s +.\bin\hayabusa.exe -f Security.evtx -s ``` * 詳細なメッセージを出力します(処理に時間がかかるファイル、パースエラー等を特定するのに便利): ```bash -hayabusa.exe -d .\hayabusa-sample-evtx -v +.\bin\hayabusa.exe -d .\hayabusa-sample-evtx -v ``` * Verbose出力の例: @@ -214,7 +222,7 @@ Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1218.004_ エラーメッセージを保存したくない場合は、`-Q`を追加してください。 # Hayabusaの出力 -Hayabusaの出力を画面に表示しているとき（デフォルト）は、以下の情報を表示します: +Hayabusaの結果を標準出力に表示しているとき（デフォルト）は、以下の情報を表示します: * `Timestamp`: デフォルトでは`YYYY-MM-DD HH:mm:ss.sss +hh:mm`形式になっています。イベントログの``フィールドから来ています。デフォルトのタイムゾーンはローカルのタイムゾーンになりますが、`--utc` オプションで UTC に変更することができます。 * `Computer`: イベントログの``フィールドから来ています。 @@ -232,13 +240,13 @@ CSVファイルとして保存する場合、以下の2つのフィールドが 解析したevtxファイルの数と割合をリアルタイムで表示します。 # Hayabusa ルール -Hayabusa検知ルールはSigmaのようなYML形式で記述されています。`rules`ディレクトリに入っていますが、将来的人[https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules)のレポジトリで管理する予定なので、ルールのissueとpull requestはhayabusaのレポジトリではなく、ルールレポジトリへお願いします。 +Hayabusa検知ルールはSigmaのようなYML形式で記述されています。`rules`ディレクトリに入っていますが、将来的には[https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules)のレポジトリで管理する予定なので、ルールのissueとpull requestはhayabusaのレポジトリではなく、ルールレポジトリへお願いします。 ルールの作成方法については、[AboutRuleCreation-Japanase.md](./doc/AboutRuleCreation-Japanase.md) をお読みください。 [hayabusa-rulesレポジトリ](https://github.com/Yamato-Security/hayabusa-rules)にあるすべてのルールは、`rules`フォルダに配置する必要があります。 -情報レベルのルールは `events` とみなされ、`level`が`low` 以上のものは `alerts` とみなされます。 +`level`がinformationのルールは `events` とみなされ、`low` 以上は `alerts` とみなされます。 Hayabusaルールのディレクトリ構造は、3つのディレクトリに分かれています。 * `default`: Windows OSでデフォルトで記録されるログ diff --git a/doc/AboutRuleCreation-English.md b/doc/AboutRuleCreation-English.md index 7b1c97d3..45a18a99 100644 --- a/doc/AboutRuleCreation-English.md +++ b/doc/AboutRuleCreation-English.md @@ -87,8 +87,8 @@ ruletype: Hayabusa * **ruletype [required]**: `Hayabusa` for hayabusa rules. Rules automatically converted from sigma Windows rules will be `Sigma`. # Detection field -## Detection fundamentals -First, the fundamentals of how to create a detection rule will be explained. +## 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. @@ -437,7 +437,6 @@ Aggregation conditions can be defined in the following format: * `12h`: 12 hours * `7d`: 7 days * `3M`: 3 months -> `timeframe` is not required but highly encouraged to define when possible for performance and memory efficiency. ### Four patterns for aggregation conditions: diff --git a/doc/AboutRuleCreation-Japanese.md b/doc/AboutRuleCreation-Japanese.md index c04743b9..ca1eb8d1 100644 --- a/doc/AboutRuleCreation-Japanese.md +++ b/doc/AboutRuleCreation-Japanese.md @@ -1,7 +1,7 @@ # ルールファイルについて -Hayabusaの検知ルールは、[YAML](https://en.wikipedia.org/wiki/YAML) 形式で記述されています。 +Hayabusaの検知ルールは[YAML](https://en.wikipedia.org/wiki/YAML) 形式で記述されています。 単純な文字列のマッチングだけでなく、正規表現や`AND`、`OR`などの条件を組み合わせて複雑な検知ルールを表現することができます。 -本節では、Hayabusaの検知ルールの書き方について説明します。 +本節ではHayabusaの検知ルールの書き方について説明します。 ## ルールファイル形式 記述例: @@ -51,7 +51,7 @@ ruletype: Hayabusa > ## アラートセクション * **title [必須]**: ルールファイルのタイトル。これは表示されるアラートの名前にもなるので、簡潔であるほどよいです。(85文字以下でなければなりません。) * **title_jp** [オプション]: 日本語のタイトルです。 -* details [オプション]: 表示されるアラートの詳細です。Windowsイベントログの中で解析に有効なフィールドがあれば出力してください。フィールドは `" : "` で区切られます（両側ともスペース2つ）。フィールドのプレースホルダは `%` で囲まれ (例: `%MemberName%`) 、`config_eventkey_alias.txt` で定義する必要があります。(以下で説明します) +* **details** [オプション]: 表示されるアラートの詳細です。Windowsイベントログの中で解析に有効なフィールドがあれば出力してください。フィールドは `" : "` で区切られます（両側ともスペース2つ）。フィールドのプレースホルダは `%` で囲まれ (例: `%MemberName%`) 、`config_eventkey_alias.txt` で定義する必要があります。(以下で説明します) * **details_jp** [オプション]: 日本語の出力メッセージ。 * **description** [オプション]: ルールの説明。これは表示されないので、長く詳細に記述することができます。 * **description_jp** [オプション]: 日本語の説明文です。 @@ -62,7 +62,7 @@ ruletype: Hayabusa * **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`）や以下に該当する戦術を追加してください。 +* **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 @@ -86,17 +86,17 @@ ruletype: Hayabusa * **non-default-setting** [オプション]: `non-default` のログソースのログ設定をオンにする方法の説明です。 * **ruletype [必須]**: Hayabusaルールには `Hayabusa` を指定します。SigmaのWindowsルールから自動変換されたルールは `Sigma` になります。 -# 検知フィールド -## 検知の基礎知識 -まず、検知の作り方の基本を説明します。 +# detectionフィールド +## selectionの基礎知識 +まず、selectionの作り方の基本を説明します。 -### AND論理とOR論理の書き方 -ANDロジックを書くには、ネストされた辞書を使用します。 -以下の検知ルールでは、ルールがマッチするためには、**両方の条件**が真でなければならないと定義しています。 +### 論理積(AND)と論理和(OR)の書き方 +ANDを表現するには辞書（YAMLでは辞書を`:`で表します）を使用します。 +このルールでログが検知されるには、**両方の条件**が真である必要があります。 -* イベントIDは `7040` であること。 -* チャンネルは `System` であること。 +* イベントIDが `7040` であること。 +* チャンネルが `System` であること。 ```yaml detection: @@ -106,13 +106,11 @@ detection: condition: selection ``` -OR論理を記述するには、リスト（`- `で始まる辞書）を使用します。 -以下の検知ルールでは、**片方**の条件がトリガーされることになります。 +ORを表現するには、配列（YAMLでは配列を`- `で表します）を使用します。 +このルールでログが検知されるには、**片方の条件**が真である必要があります。 -* イベントIDは `7040` であること。 - -**または** -* チャンネルは `System` であること。 +* イベントIDが `7040` であること。 +* チャンネルが `System` であること。 ```yaml detection: @@ -122,10 +120,10 @@ detection: condition: selection ``` -また、以下のように「AND」と「OR」の論理を組み合わせることも可能です。 -この場合、以下の2つの条件が両方成立したときにルールがマッチします。 +また、以下のように「AND」と「OR」を組み合わせることも可能です。 +この場合、以下の2つの条件が両方成立したときに、このルールでログが検知されます。 -* イベントID が `7040` **または** `7041` のどちらかであること。 +* イベントIDが `7040` **または** `7041` のどちらかであること。 * チャンネルが `System` であること。 ```yaml @@ -139,11 +137,7 @@ detection: ``` ### イベントキー -以下は、Windowsイベントログの抜粋で、オリジナルのXMLでフォーマットしたものです。上記のルールファイルの例の `Event.System.Channel` フィールドは、オリジナルのXMLタグを参照しています。 - -`System` - -ネストされたXMLタグはドット(`.`)で区切られたタグ名で置き換えられます。Hayabusaのルールでは、ドットでつながれたこれらのフィールド文字列は `eventkeys` と呼ばれます。 +WindowsイベントログをXML形式で出力すると下記のようになります。 ```xml @@ -158,8 +152,12 @@ detection: ``` +論理和の例で示したルールの `Event.System.Channel` フィールドは、下記のXMLタグで囲まれた値を参照しています。 ネストされたXMLタグはドット(`.`)で区切られたタグ名で置き換えられます。Hayabusaのルールでは、このドットでつながれた文字列のことをイベントキーと呼んでいます。 + +`System` + #### イベントキーエイリアス -`.`の区切りが多くて長いイベントキーが一般的であるため、Hayabusaはエイリアスを使って簡単に扱えるようにします。エイリアスは `config\eventkey_alias.txt`ファイルで定義されています。このファイルは `alias` と `event_key` のマッピングで構成される CSV ファイルです。以下に示すように、エイリアスを使用して上記のルールを書き直し、ルールを読みやすくすることができます。 +`.`の区切りが多くて長いイベントキーが一般的であるため、Hayabusaはエイリアスを使って簡単に扱えるようにします。エイリアスは `config\eventkey_alias.txt`ファイルで定義されています。このファイルは `alias` と `event_key` のマッピングで構成されるCSVファイルです。以下に示すように、エイリアスを使用して上記のルールを書き直し、ルールを読みやすくすることができます。 ```yaml detection: @@ -170,10 +168,10 @@ detection: ``` #### 注意: 未定義のイベントキーエイリアスについて -すべてのイベントキーエイリアスが `config\eventkey_alias.txt`で定義されているわけではありません。`details`（アラートの詳細）メッセージで正しいデータを取得しておらず、代わりに`%EventID%`のような結果を取得している場合、または検知ロジックの選択が正しく機能していない場合は、新しいエイリアスを使用して `config\eventkey_alias.txt`を更新する必要があります。 +すべてのイベントキーエイリアスが `config\eventkey_alias.txt`に定義されているわけではありません。検知するはずのルールが検知しない場合や、`details`（アラートの詳細）メッセージに`%EventID%`のようなプレースホルダーが表示されている場合、`config\eventkey_alias.txt`の設定を確認してください。 -### 条件におけるXML属性の使用方法 -XML要素には、スペースを入れることで属性を設定することができます。例えば、以下の `Provider Name` の `Name` は `Provider` 要素のXML属性です。 +### XML属性を条件に使用する方法 +XMLのタグにはタグ名とは別に属性を設定できます。例えば、以下の `Provider Name` の `Name` は `Provider` タグの属性です。 ```xml @@ -186,7 +184,8 @@ XML要素には、スペースを入れることで属性を設定すること ``` -イベントキーのXML属性を指定するには、`{eventkey}_attributes.{attribute_name}`という形式を使います。例えば、ルールファイルの `Provider` 要素の `Name` 属性を指定する場合は、以下のようになります。 + +イベントキーでXMLの属性を指定するには、`{eventkey}_attributes.{attribute_name}`という形式で記述します。例えば、ルールファイルの `Provider` 要素の `Name` 属性を指定する場合は、以下のようになります。 ```yaml detection: @@ -200,7 +199,7 @@ detection: ### grep検索 Hayabusaではeventkeyを指定せず、WindowsEventログに含まれる文字列にマッチするかどうかを判定する機能も用意されています。この機能をHayabusaではgrep検索と呼んでいます。 -grep検索をするには下記のようにdetectionを指定します。この場合、`mimikatz`または`metasploit`という文字列がWindowsEventログに含まれる場合に、条件に一致したものとして条件に一致したものとして処理されます。また、grep検索にはワイルドカードを指定することも可能です。 +grep検索をするには下記のようにdetectionを指定します。この場合、`mimikatz`または`metasploit`という文字列がWindowsEventログに含まれる場合に、ルールが検知されます。また、grep検索にはワイルドカードを指定することも可能です。 ```yaml detection: @@ -209,10 +208,10 @@ detection: - `metasploit` ``` -> ※ Hayabusaでは内部的にWindowsEventログをJSON形式に変換して上で処理を行っています。そのため、XMLのタグをgrep検索でマッチさせることはできません。 +> ※ Hayabusaでは内部的にWindowsEventログをJSON形式に変換しています。そのため、grep検索ではXMLのタグをマッチさせることはできません。 -### イベントデータ -Windowsのイベントログは、基本データ（イベントID、タイムスタンプ、レコードID、ログ名（チャンネル））が書き込まれる`System`部分と、イベントIDに応じて任意のデータが書き込まれる`EventData`部分の2つに分けられます。問題は、`EventData` にネストされたタグの名前がすべて `Data` であるため、これまで説明したイベントキーでは `SubjectUserSid` と `SubjectUserName` を区別できないことです。 +### EventData +Windowsのイベントログは、基本データ（イベントID、タイムスタンプ、レコードID、ログ名（チャンネル））が書き込まれる`System`タグと、イベントIDに応じて任意のデータが書き込まれる`EventData`タグの2つに分けられます。その内、`EventData`タグ はネストされたタグの名前がすべて `Data` であり、これまで説明したイベントキーでは `SubjectUserSid` と `SubjectUserName` を区別できません。 ```xml @@ -232,7 +231,7 @@ Windowsのイベントログは、基本データ（イベントID、タイム ``` -この問題に対処するために、`Data Name`で割り当てられた値を指定することができます。例えば、EventData に含まれる `SubjectUserName` と `SubjectDomainName` をルールの条件として利用したい場合、以下のように記述することが可能です。 +この問題に対処するため、`Data`タグの`Name`属性に指定された値をイベントキーとして利用できます。例えば、EventData の `SubjectUserName` と `SubjectDomainName` を条件として利用する場合、以下のように記述することが可能です。 ```yaml detection: @@ -244,8 +243,8 @@ detection: condition: selection ``` -### EventDataの異常なパターン -`EventData` にネストされたいくつかのタグは `Name` 属性を持ちません。 +### EventDataの例外的なパターン +`EventData` タグにネストされたいくつかのタグは `Name` 属性を持ちません。 ```xml @@ -262,7 +261,7 @@ detection: ``` -上記のようなイベントログを検知するには、`EventData`という名前のイベントキーを指定します。この場合、`Name`属性を持たないネストされたタグのいずれかがマッチする限り、条件はマッチします。 +上記のようなイベントログを検知するには、`EventData`というイベントキーを指定します。この場合、`EventData`にネストされたタグの内、値がNoneになるタグが1つ以上存在すれば、条件にマッチすることになります。 ```yaml detection: @@ -274,7 +273,7 @@ detection: ``` ## パイプ -パイプは、以下のようにイベントキーと組み合わせて、文字列のマッチングに使用することができます。これまで説明した条件はすべて完全一致ですが、パイプを使うことで、より柔軟な検知ルールを記述することができます。以下の例では、`EventData`の値が正規表現 `[\s\S]*EngineVersion=2.0[\s\S]*` にマッチする場合、条件にマッチすることになります。 +イベントキーにはパイプを指定することができます。ここまで説明した書き方では完全一致しか表現できませんでしたが、パイプを使うことでより柔軟な検知ルールを記載できるようになります。以下の例では、`EventData`の値が正規表現 `[\s\S]*EngineVersion=2.0[\s\S]*` に当てはまる場合、条件にマッチすることになります。 ```yaml detection: @@ -285,16 +284,15 @@ detection: condition: selection ``` -パイプの後に指定できるものの一覧です。現時点では、Hayabusa は複数のパイプを連結することはサポートしていません。 -* startswith: 文字列を先頭からチェックします。 -* endswith: 文字列の末尾をチェックします。 -* contains: ある単語がデータ内に含まれているかどうかをチェックします。 -* re: 正規表現を使用します。(私たちは regex crate を使っているので、正しい正規表現の書き方については https://docs.rs/regex/1.5.4/regex/ のドキュメントを参照してください)。 - > 注意: 正規表現を使用するSigmaルールの中には、Rustが正規表現を使用する方法の違いにより、 検知に失敗するものがあります。 +パイプには以下のキーワードを指定できます。v1の時点で複数のパイプを連結することはできません。 +* startswith: 指定された文字列で始まることをチェックします。 +* endswith: 指定された文字列で終わることをチェックします。 +* contains: 指定された文字列が含まれることをチェックします。 +* re: 正規表現を使用します。(正規表現の書き方については https://docs.rs/regex/1.5.4/regex/ を参照してください)。 + > 注意: SigmaルールとHayabusaルールは正規表現の記法に一部差異があります。そのため、HayabusaではSigmaルールを正しく検知できない場合があります。 ## ワイルドカード -イベントキーにワイルドカードを使用することができます。以下の例では、`ProcessCommandLine` が "malware" という文字列で始まる場合、このルールはマッチします。 -この仕様は、Sigmaルールのワイルドカードと基本的に同じです。 +Hayabusaルールではワイルドカードを使用することができます。以下の例では、`ProcessCommandLine` が "malware" という文字列で始まる場合、このルールでログが検知されます。この仕様はSigmaルールのワイルドカードと同じです。 ```yaml detection: @@ -306,20 +304,16 @@ detection: ``` 以下の2つのワイルドカードを使用することができます。 -* `*`: 0文字以上の任意の文字列にマッチします。(内部的には正規表現 `.*` に変換されます)。 -* `?`: 任意の1文字にマッチします。(内部的には正規表現 `. ` に変換されます)。 +* `*`: 0文字以上の任意の文字列にマッチします。(内部的には`.*`という正規表現に変換されます)。 +* `?`: 任意の1文字にマッチします。(内部的には`.`という正規表現に変換されます)。 ワイルドカードのエスケープについて -* ワイルドカード(`*` and `?`)は、バックスラッシュでエスケープできます: `\*` と `\?`. -* もし、ワイルドカードの直前にバックスラッシュを使用したい場合は、 `\\*` または `\\?` と記述してください。 -* バックスラッシュを単独で使用する場合は、エスケープは必要ありません。 +* ワイルドカード(`*`と`?`)はバックスラッシュでエスケープできます: `\*` と `\?`. +* ワイルドカードの直前にバックスラッシュを使用する場合、 `\\*` または `\\?` と記述してください。 +* バックスラッシュを単独で使用する場合、エスケープは不要です。 ## イベントキー内のキーワードのネスト -イベントキーは、特定のキーワードでネストすることができます。 -以下の例では、以下の場合にルールがマッチします。 -* `ServiceName` が `malicious-service` であるか、または `./config/regex/regexes_suspicous_service.txt` にある正規表現を含んでいる場合。 -* `ImagePath` は1000文字以上であること。 -* `ImagePath` は `allowlist` にマッチするものが一つもありません。 +イベントキーには特定のキーワードをネストすることができます。 ```yaml detection: @@ -338,22 +332,21 @@ detection: 現在、指定できるキーワードは以下の通りです。 * `value`: 文字列によるマッチング (ワイルドカードやパイプも指定可能)。 * `min_length`: 指定された文字数以上の場合にマッチします。 -* `regexes`: このフィールドで指定したファイル内の正規表現のいずれかにマッチする場合にマッチします。 -* `allowlist`: このフィールドで指定したファイル内の正規表現のリストにマッチするものがある場合、ルールはスキップされます。 +* `regexes`: 指定されたファイルに定義された正規表現に1つ以上に一致する場合、**条件にマッチした**ものとして扱われます。 +* `allowlist`: 指定されたファイルに定義された正規表現に1つ以上に一致する場合、**条件にマッチしてない**ものとして扱われます。 ### 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`: 正規のサービスを許可するためのものです。 -`regexes` と `allowlist` で定義されたファイルは、ルールファイル自体を変更することなく、それらを参照するすべてのルールの動作を変更するために編集することが可能です。 +`regexes` と `allowlist` で定義されたファイルの正規表現を変更すると、それらを参照するすべてのルールの動作を一度に変更できます。 -また、自分で作成した異なる regexes と allowlist テキストファイルを使用することもできます。 +また、`regexes` と `allowlist` にはユーザーが独自で作成したファイルを指定することも可能です。 デフォルトの `./config/detectlist_suspicous_services.txt` と `./config/allowlist_legitimate_services.txt` を参考にして、独自のファイルを作成してください。 ## condition (条件) -上記で説明した表記法では、`AND`や`OR`の論理を表現することができますが、複雑な論理を定義しようとすると混乱してしまうでしょう。 -より複雑なルールを作りたい場合は、以下のように `condition` キーワードを使用します。 +これまで説明した記法では簡単な`AND`や`OR`であれば表現可能ですが、複雑な条件は定義できません。そのような場合、`condition` キーワードを使用します。 ```yaml detection: @@ -379,18 +372,15 @@ detection: ``` `condition`には、以下の式を用いることができます。 -* `{expression1} and {expression2}`: {expression1} と {expression2} の両方を必要とする。 -* `{expression1} or {expression2}`: {expression1} または {expression2} のどちらかを必要とする -* `not {expression}`: {expression} の論理を反転させる -* `( {expression} )`: {expression} の優先順位を設定する。数学と同じ優先順位の論理に従う。 +* `{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`などの標準的な規則を使用してください。 +上記の例では、 `SELECTION_1`、` SELECTION_2`などの名前が使用されていますが、名前には `a-z A-Z 0-9 _`の文字を使用可能です。ただし、`selection_1`、` selection_2`、 `filter_1`、` filter_2`などの標準的な規則の利用を推奨します。 ## notロジック -多くのルールは誤検知を引き起こすので、検索するシグネチャーの選択と同時に、誤検知が無いようにフィルターの選択をすることはよくあります。 - -例えば +ルールを作成する場合、誤検知を減らすためにフィルターを作成することはよくあります。以下に利用例を示します。 ```yaml detection: @@ -412,11 +402,10 @@ detection: condition: selection and not filter ``` -## aggregation condition (集計条件) (別名: カウントルール) +## aggregation condition ### 基本事項 -上記の `condition` キーワードは `AND` や `OR` ロジックを実装しているだけでなく、イベントをカウントしたり、「aggregate(集約)」したりすることも可能です。 -この機能は「集計条件」と呼ばれ、条件をパイプでつないで指定をします。 -以下のパスワードスプレー攻撃の例では、5分以内に同じ送信元の`IpAddress`で5個以上の `TargetUserName`があるかどうかを判断するために条件式が使用されています。 +上記の `condition` キーワードは `AND` や `OR` だけでなく、マッチしたイベントの集計も可能です。この機能を利用するには`aggregation condition`を利用します。指定するには条件をパイプでつなぎます。 +以下のパスワードスプレー攻撃の例では、5分以内に同じ送信元の`IpAddress`で5個以上の `TargetUserName`があるかどうかを判断します。 ```yaml detection: @@ -427,7 +416,7 @@ detection: timeframe: 5m ``` -集計条件は以下の形式で定義することができます。 +`aggregation condition`は以下の形式で定義します。 * `count() {operator} {number}`: パイプの前の最初の条件にマッチするログイベントに対して、マッチしたログの数が `{operator}` と `{number}` で指定した条件式を満たす場合に条件がマッチします。 `{operator}` は以下のいずれかになります。 @@ -445,37 +434,36 @@ detection: * `12h`: 12時間 * `7d`: 7日間 * `3M`: 3ヶ月 -> `timeframe` は必須ではありませんが、パフォーマンスとメモリ効率のために、可能な限り定義することが強く推奨されます。 -### 集計条件として4パターン: -1. count 引数または `by` キーワードを指定しない。例: `selection | count() > 10` - > もし `selection` が時間枠内に10回以上マッチすれば、条件にマッチします。 -2. count 引数はないが、`by` キーワードはある。例: `selection | count() by IpAddress > 10` - > `selection` は**同じ**`IpAddress` に対して10回以上 true になる必要があります。 -3. count 引数があるが、`by` キーワードがない場合。例: `selection | count(TargetUserName) > 10` - > `selection` がマッチし、かつ `TargetUserName` が時間枠内で10回以上**異なる**場合であれば、条件にマッチします。 -4. count 引数と `by` キーワードの両方が存在する。例: `selection | count(TargetUserName) by IpAddress > 10` - > **同じ**「日付」に対して、条件が一致するためには、10人以上の**異なる**「ユーザ」が存在する必要があります。 +### 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回以上発生した場合にマッチします。 +これは最も基本的なパターンです：`count() {operator} {number}`. 以下のルールは、`selection`にマッチしたログが3つ以上である場合、このルールが検知されます。 ![](CountRulePattern-1-JP.png) ### パターン2の例： -`count() by {eventkey} {operator} {number}`： パイプの前の `condition` にマッチするログイベントは、**同じ**`{eventkey}`でグループ化されます。各グループ化において、マッチしたイベントの数が`{operator}`と`{number}`で指定した条件を満たした場合、条件にマッチすることになります。 +`count() by {eventkey} {operator} {number}`： `selection`にマッチしたログは、`{eventkey}`の値が**同じログ毎にグルーピング**されます。各グループにおいて、マッチしたイベントの数が`{operator}`と`{number}`で指定した条件を満たした場合、このルールが検知されます。 ![](CountRulePattern-2-JP.png) ### パターン3の例： -`count({eventkey}) {operator} {number}`： 条件パイプの前に、条件にマッチする `{eventkey}` の**異なる**値がいくつログイベント内に存在するかを数えます。その数が`{operator}`と`{number}`で指定された条件式を満たす場合、条件を満たしたものとみなします。 +`count({eventkey}) {operator} {number}`：`selection`にマッチしたログの内、 `{eventkey}` が**異なる**値の数をカウントします。そのカウントされた値が`{operator}`と`{number}`で指定された条件式を満たす場合、このルールが検知されます。 ![](CountRulePattern-3-JP.png) ### パターン4の例： -`count({eventkey_1}) by {eventkey_2} {operator} {number}`： 条件パイプの前にある条件にマッチしたログを**同じ**`{eventkey_2}`でグループ化し、各グループに含まれる`{eventkey_1}`の**異なる**値の数をカウントしています。各グループでカウントされた値が`{operator}`と`{number}`で指定された条件式を満たした場合、条件にマッチすることになります。 +`count({eventkey_1}) by {eventkey_2} {operator} {number}`： `selection`にマッチしたログは、`{eventkey}`の値が**同じログ毎にグルーピングし**、各グループに含まれる`{eventkey_1}`が**異なる**値の数をカウントします。各グループでカウントされた値が`{operator}`と`{number}`で指定された条件式を満たした場合、このルールが検知されます。 ![](CountRulePattern-4-JP.png) @@ -486,7 +474,7 @@ CountルールのDetails出力は固定で、`[condition]`にcount条件と`[res ``` [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`が設定されていない場合はルールが無視される可能性があります。 @@ -599,6 +587,6 @@ detection: ``` # SigmaルールからHayabusaルール形式への自動変換 -SigmaルールからHayabusaルール形式への自動変換を行うsigmacのバックエンドを[こちら](https://github.com/Yamato-Security/hayabusa/tree/main/tools/sigmac)で作成しました。 +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 +使用方法は[Readme](https://github.com/Yamato-Security/hayabusa/blob/main/tools/sigmac/README-Japanese.md)を参照してください。 \ No newline at end of file