From 197bef17a745962232965de85cb74547ccddd037 Mon Sep 17 00:00:00 2001 From: Tanaka Zakku <71482215+YamatoSecurity@users.noreply.github.com> Date: Sun, 19 Dec 2021 22:08:36 +0900 Subject: [PATCH] readme update --- README-English.md | 81 ++++++++----- README-Japanese.md | 295 ++++++++++++++++++++++++++++++++------------- contributors.txt | 1 + 3 files changed, 262 insertions(+), 115 deletions(-) diff --git a/README-English.md b/README-English.md index 1f73090c..2794d8b5 100644 --- a/README-English.md +++ b/README-English.md @@ -7,7 +7,7 @@ # About Hayabusa -Hayabusa is a **Windows event log fast forensics timeline generator** and **threat hunting tool** created by the [Yamato Security](https://yamatosecurity.connpass.com/) group in Japan. Hayabusa means "[peregrine falcon](https://en.wikipedia.org/wiki/Peregrine_falcon" in Japanese and was chosen as peregrine falcons are the fastest animal in the world, great at hunting and highly trainable. It is written in [Rust](https://www.rust-lang.org/) and supports multi-threading in order to be as fast as possible. We have provided a tool to convert [sigma](https://github.com/SigmaHQ/sigma) rules into hayabusa rule format. The hayabusa detection rules, like sigma, are also written in YAML in order to be as easily customizable and extensible as possible. It can be run either on running systems for live analysis or by gathering logs from multiple systems for offline analysis. (At the moment, it does not support real-time alerting or periodic scans.) The output will be consolidated into a single CSV timeline for easy analysis in Excel or [timeline explorer](https://ericzimmerman.github.io/#!index.md). +Hayabusa is a **Windows event log fast forensics timeline generator** and **threat hunting tool** created by the [Yamato Security](https://yamatosecurity.connpass.com/) group in Japan. Hayabusa means ["peregrine falcon"](https://en.wikipedia.org/wiki/Peregrine_falcon") in Japanese and was chosen as peregrine falcons are the fastest animal in the world, great at hunting and highly trainable. It is written in [Rust](https://www.rust-lang.org/) and supports multi-threading in order to be as fast as possible. We have provided a [tool](https://github.com/Yamato-Security/hayabusa/tree/main/tools/sigmac) to convert [sigma](https://github.com/SigmaHQ/sigma) rules into hayabusa rule format. The hayabusa detection rules, like sigma, are also written in YAML in order to be as easily customizable and extensible as possible. It can be run either on running systems for live analysis or by gathering logs from multiple systems for offline analysis. (At the moment, it does not support real-time alerting or periodic scans.) The output will be consolidated into a single CSV timeline for easy analysis in Excel or [Timeline Explorer](https://ericzimmerman.github.io/#!index.md). ## Main goals @@ -22,17 +22,17 @@ Hayabusa is not intended to be a replacement for tools like [Evtx Explorer](http First inspired by the [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI) Windows event log analyzer, we started in 2020 porting it over to Rust for the [RustyBlue](https://github.com/Yamato-Security/RustyBlue) project, then created sigma-like flexible detection signatures written in YAML, and then added a backend to sigma to support converting sigma rules into our hayabusa rule format. # Screenshots -Startup: +## Startup: ![Hayabusa Startup](/screenshots/hayabusa-start.png) -Terminal output: +## Terminal output: ![Hayabusa terminal output](/screenshots/hayabusa-results.png) -Results summary: +## Results summary: ![Hayabusa results summary](/screenshots/hayabusa-results-summary.png) @@ -55,13 +55,13 @@ Results summary: * MITRE ATT&CK heatmap generation * User logon and failed logon summary * Input from JSON logs -* Output to JSON -> import to Elastic Stack/Splunk +* JSON support for sending alerts to Elastic Stack/Splunk, etc... # Downloads You can download pre-compiled binaries for the Windows, Linux and macOS at [Releases.](https://github.com/Yamato-Security/hayabusa/releases) # Compiling from source -If you have rust installed, you can compile from source with the following command. +If you have rust installed, you can compile from source with the following command: ```` cargo build --release @@ -71,20 +71,22 @@ cargo build --release ## Command line options ```` USAGE: + -d --directory=[DIRECTORY] 'Directory of multiple .evtx files' -f --filepath=[FILEPATH] 'File path to one .evtx file' - --csv-timeline=[CSV_TIMELINE] 'Save the timeline in CSV format' + -r --rules=[RULEDIRECTORY] 'Rule file directory (default: ./rules)' + -o --output=[CSV_TIMELINE] 'Save the timeline in CSV format. Example: results.csv' + -v --verbose 'Output verbose information' + -D --enable-deprecated-rules 'Enable sigma rules marked as deprecated' + -n --enable-noisy-rules 'Enable rules marked as noisy' + -m --min-level=[LEVEL] 'Minimum level for rules (default: informational)' + --start-timeline=[STARTTIMELINE] 'Start time of the event to load from event file. Example: '2018/11/28 12:00:00 +09:00'' + --end-timeline=[ENDTIMELINE] 'End time of the event to load from event file. Example: '2018/11/28 12:00:00 +09:00'' --rfc-2822 'Output date and time in RFC 2822 format. Example: Mon, 07 Aug 2006 12:34:56 -0600' --rfc-3339 'Output date and time in RFC 3339 format. Example: 2006-08-07T12:34:56.485214 -06:00' - --verbose 'Output verbose information to target event file path and rule file' - -q 'Quiet mode. Do not display the launch banner' - -r --rules=[RULEDIRECTORY] 'Rule file directory (default: ./rules)' - -m --min-level=[LEVEL] 'Minimum level for rules (default: informational)' -u --utc 'Output time in UTC format (default: local time)' - -d --directory=[DIRECTORY] 'Directory of multiple .evtx files' + -t --thread-number=[NUMBER] 'Thread number (default: optimal number for performance)' -s --statistics 'Prints statistics of event IDs' - -n --show-noisyalerts 'do not exclude noisy rules' - -t --threadnum=[NUM] 'Thread number (default: optimal number for performance)' - --show-deprecated 'do not exclude rules with YAML's status deprecated' + -q --quiet 'Quiet mode. Do not display the launch banner' --contributors 'Prints the list of contributors' ```` @@ -101,22 +103,37 @@ hayabusa.exe -d .\sample-evtx * Export to a single CSV file for further analysis with excel or timeline explorer: ```` -hayabusa.exe -d .\sample-evtx --csv-timeline results.csv +hayabusa.exe -d .\sample-evtx -o results.csv ```` -* Only run hayabusa rules: +* Only run hayabusa rules (the default is to run all the rules in `-r .\rules`): ```` -hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r .\rules/hayabusa +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa -o results.csv ```` -* Only run sigma rules and enable deprecated and noisy rules (both disabled by default): +* Only run hayabusa rules for logs that are enabled by default on Windows: ```` -hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r .\rules\sigma --show-noisyalerts --show-deprecated +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa\default -o results.csv +```` + +* Only run hayabusa rules for sysmon logs: +```` +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa\sysmon -o results.csv +```` + +* Only run sigma rules: +```` +hayabusa.exe -d .\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`): +```` +hayabusa.exe -d .\sample-evtx --enable-noisy-rules --enable-deprecated-rules -o results.csv ```` * Only run rules to analyze logons and output in the UTC timezone: ```` -hayabusa.exe -d .\sample-evtx --csv-timeline results.csv -r .\rules\hayabusa\default\events\Security\Logons -u +hayabusa.exe -d .\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): @@ -126,7 +143,7 @@ hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low * Get event ID statistics: ```` -hayabusa.exe -d C:\Windows\System32\winevt\Logs -s +hayabusa.exe -f Security.evtx -s ```` ## Testing hayabusa out on sample evtx files @@ -137,12 +154,12 @@ Hayabusa detection rules are written in a sigma-like YAML format and are located Please read [AboutRuleCreation-English.md](./doc/AboutRuleCreation-English.md) to understand about the rule format how to create rules. -All of the rules are in the `rules` folder. -`informational` level rules are considered `events`, while anything rated `low` and higher are considered `alerts`. +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`. The hayabusa rule directory structure is separated into 3 directories: - * `default`: logs that are turned on by default - * `non-default`: logs that need to be turned on through group policy + * `default`: logs that are turned on in Windows by default. + * `non-default`: logs that need to be turned on through group policy, security baselines, etc... * `sysmon`: logs that are generated by [sysmon](https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon). * `testing`: a temporary directory to put rules that you are currently testing @@ -169,9 +186,9 @@ Sigma rules need to first be converted to hayabusa rule format explained [here]( ## Detection rule tuning 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 `config/exclude-rules.txt` in order to ignore any rule you do not need. +You can add a rule ID (Example: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) to `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 `config/noisy-rules.txt` in order to ignore the rule by default but still be able to use the rule with the `-n` or `--show-noisyalerts` option. +You can also add a rule ID to `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. # Other Windows event log analyzers and related projects There is no "one tool to rule them all" and we have found that each has its own merits so we recommend checking out these other great tools and projects and seeing which ones you like. @@ -195,16 +212,16 @@ There is no "one tool to rule them all" and we have found that each has its own Please understand that it is not possible to do a perfect comparison as results will differ based on the target sample data, command-line options, rule tuning, etc... In our tests, we have found hayabusa to support the largest number of sigma rules out of all the tools while still maintaining very fast speeds and does not require a great amount of memory. -The following benchmarks were taken on a Lenovo P51 based on approximately 500 evtx files (130MB) from our [sample-evtx repository](https://github.com/Yamato-Security/hayabusa-sample-evtx) at 2021/12/09. +The following benchmarks were taken on a Lenovo P51 based on approximately 500 evtx files (130MB) from our [sample-evtx repository](https://github.com/Yamato-Security/hayabusa-sample-evtx) at 2021/12/19. | | Elapsed Time | Memory Usage | Unique Sigma Rules With Detections | | :---: | :---: | :---: | :---: | | Chainsaw | 7.5 seconds | 75 MB | 170 | -| Hayabusa | 8 seconds | 340 MB | 267 | -| Zircolite | 55 seconds | 400 MB | 237 | +| Hayabusa | 7.5 seconds | 400 MB | 267 | +| Zircolite | 34 seconds | 380 MB | 237 | With hayabusa rules enabled, it will detect over 300 unique alerts and events. -Hayabusa will usually require a minimum of about 300MB of memory but will normally not go over the file size of large evtx files compared to Zircolite's memory usage which usually requires 2~3 times the size of the logs. +Just by looking at these benchmarks it looks like Hayabusa will use more memory than Zircolite as it usually uses a minimum of around 00MB. However, Hayabusa will normally not go over the file size of large evtx files compared to Zircolite's memory usage which usually requires 2~3 times the size of the logs. # License diff --git a/README-Japanese.md b/README-Japanese.md index d4fe4aa2..75cfed40 100644 --- a/README-Japanese.md +++ b/README-Japanese.md @@ -2,108 +2,237 @@

![Hayabusa Logo](hayabusa-logo.png) +

-# Hayabusa -Hayabusaは非常に高速なWindowsイベントアナライザで、フォレンジックタイムラインの作成や、HayabusaまたはSIGMAルールで記述されたIoCに基づいた脅威のハンティングを行うために使用されます。ライブでもオフラインでも実行でき、インシデント後に企業内のエンドポイントで実行されるエージェントとしてプッシュアウトすることもできます。 +# 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と同様に、できるだけ簡単にカスタマイズや拡張ができるようにYAMLで書かれています。稼働中のシステムで実行してライブ調査することも、複数のシステムからログを収集してオフライン調査することも可能です。(※現時点では、リアルタイムアラートや定期的なスキャンには対応していません。) 出力は一つの CSV タイムラインにまとめられ、Excelや[Timeline Explorer](https://ericzimmerman.github.io/#!index.md)で簡単に分析できるようになります。 -# Hayabusaについて -Hayabusaは日本のYamato Securityグループによって書かれました。最初にDeepblueCLI Windowsイベントログアナライザに触発され、2020年にRustyBlueプロジェクトのためにRustに移植することから始まり、SIGMAのようなYAMLベースの柔軟なシグネチャを作成し、SIGMAのルールをhayabusaのルールに変換することをサポートするためにSIGMAにバックエンドを追加しました。マルチスレッドをサポートし、（我々の知る限り）現在最速のフォレンジックタイムラインジェネレータと脅威探索ツールであり、SIGMAの最も多くの機能をサポートしています。複数のWindowsイベントログを分析し、分析しやすいように結果を一つのタイムラインに集約することができます。また、CSV形式で出力されるので、Timeline ExplorerやExcelなどのツールに取り込んで分析することができます。 +## 主な目的 + +### 脅威ハンティング +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%の作業を行えるようにすることを目的としています。 + +# 開発について +[DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI)というWindowsイベントログ解析ツールに触発されて、2020年に[RustyBlue](https://github.com/Yamato-Security/RustyBlue)プロジェクト用にRustに移植することから始めました。その後、YAMLで書かれたSigmaのような柔軟な検出シグネチャを作り、Sigmaルールを我々のHayabusaルール形式へ変換するサポートをSigmaへのバックエンドとして追加しています。 # スクリーンショット -screenshotを入れる +## 起動画面: -# 機能 -* 複数のOSに対応: Windows, Linux, macOS (Intel + ARM) -* ハヤブサよりも速い！ -* 英語と日本語に対応 -* マルチスレッド -* フォレンジック調査用のイベントタイムライン作成 -* 作成・編集しやすいYAML形式のhayabusaルールでIoCシグネチャーを作成し、攻撃検知(スレットハンティング)を行う -* SIGMAルールをhayabusaルールに自動変換 -* イベントログの集計(どのようなイベントがあるかを把握するためやログ設定のチューニングに便利) +![Hayabusa 起動画面](/screenshots/Hayabusa-start.png) + + +## ターミナル出力画面: + +![Hayabusa ターミナル出力画面](/screenshots/Hayabusa-results.png) + + +## 結果サマリ画面: + +![Hayabusa 結果サマリ画面](/screenshots/Hayabusa-results-summary.png) + + +# 特徴 +* クロスプラットフォーム対応: Windows, Linux, macOS +* Rustで開発され、メモリセーフでハヤブサよりも高速です！ +* マルチスレッド対応により、最大5倍のスピードアップを実現! +* フォレンジック調査やインシデントレスポンスのために、分析しやすいCSVタイムラインを作成します。 +* 読みやすい/作成/編集可能なYAMLベースのHayabusaルールで記述されたIoCシグネチャに基づく脅威ハンティング +* SigmaルールをHayabusaルールに変換するためのSigmaルールのサポートがされています。 +* 現在、他の類似ツールに比べ最も多くのSigmaルールをサポートしており、カウントルールにも対応しています。 +* イベントログの統計（どのような種類のイベントがあるのかを把握し、ログ設定のチューニングに有効です。） +* 不良ルールやノイズの多いルールを除外するルールチューニング設定が可能です。 + +# 予定されている機能 +* すべてのエンドポイントでの企業全体の脅威ハンティング +* 日本語対応 +* MITRE ATT&CK とのマッピング +* MITRE ATT&CK ヒートマップ生成機能 +* ユーザーログオンと失敗したログオンのサマリー +* JSONログからの入力 +* JSONへの出力→Elastic Stack/Splunkへのインポート # ダウンロード -[Releases](https://github.com/Yamato-Security/hayabusa/releases)からコンパイル済みの実行ファイルをダウンロードできます。 - -# 使い方 -## コマンドラインオプション -```` -USAGE: - hayabusa.exe [FLAGS] [OPTIONS] - -FLAGS: - --credits コントリビューターの一覧表示 - -h, --help ヘルプ画面の表示 - --rfc-2822 日付と時間をRFC 2822形式で表示する。例： Mon, 07 Aug 2006 12:34:56 -0600 - -s, --statistics イベントログの集計 - -u, --utc 時間をUTCで出力する（デフォルトはローカル時間） - -V, --version バージョン情報を出力する - -OPTIONS: - --csv-timeline タイムラインをCSVに保存する - -d, --directory イベントログファイルが入っているディレクトリ - -f, --filepath イベントファイルのパス - --human-readable-timeline 読みやすいタイミングを出力 - -l, --lang 出力する言語 - -t, --threadnum スレッド数（デフォルトではCPUコア数） -```` - -## 使い方の例 -* Windowsイベントログを一つ指定する: -```` -hayabusa.exe --filepath=eventlog.evtx -```` - -* Windowsイベントログが格納されているフォルダを指定する: -```` -hayabusa.exe --directory=.\evtx -```` - -* 結果をCSVファイルに出力する: -```` -hayabusa.exe --directory=.\evtx --csv-timeline kekka.csv -```` - -# ルールファイル -HayabusaではWindowsEventログを検知するルールをYAML形式で定義します。 - -ルールの記載方法については[AboutRuleCreation-Japanese.md](./doc/AboutRuleCreation-Japanese.md)を参照してください。 - -ルールファイルはrulesフォルダ内に設置します。 -rulesフォルダには組み込みルールファイルも設置されていますので、参考にしてください。 +Windows、Linux、macOS用のコンパイル済みバイナリは、[Releases](https://github.com/Yamato-Security/Hayabusa/releases)からダウンロードできます。 # ソースコードからのコンパイル -下記のコマンドでビルドできます。 +rustがインストールされている場合、以下のコマンドでソースコードからコンパイルすることができます: ```` cargo build --release ```` -# 関連するWindowsイベントログのスレットハンティングプロジェクト -まだ完璧なWindowsイベントログ解析ツールは存在していなくて、それぞれ長所短所があるので、以下のツールとプロジェクトもチェックして、好きなツールを使ってくださいね！ +# 使用方法 +## コマンドラインオプション +```` +USAGE: + -d --directory=[DIRECTORY] 'Directory of multiple .evtx files' + -f --filepath=[FILEPATH] 'File path to one .evtx file' + -r --rules=[RULEDIRECTORY] 'Rule file directory (default: ./rules)' + -o --output=[CSV_TIMELINE] 'Save the timeline in CSV format. Example: results.csv' + -v --verbose 'Output verbose information' + -D --enable-deprecated-rules 'Enable sigma rules marked as deprecated' + -n --enable-noisy-rules 'Enable rules marked as noisy' + -m --min-level=[LEVEL] 'Minimum level for rules (default: informational)' + --start-timeline=[STARTTIMELINE] 'Start time of the event to load from event file. Example: '2018/11/28 12:00:00 +09:00'' + --end-timeline=[ENDTIMELINE] 'End time of the event to load from event file. Example: '2018/11/28 12:00:00 +09:00'' + --rfc-2822 'Output date and time in RFC 2822 format. Example: Mon, 07 Aug 2006 12:34:56 -0600' + --rfc-3339 'Output date and time in RFC 3339 format. Example: 2006-08-07T12:34:56.485214 -06:00' + -u --utc 'Output time in UTC format (default: local time)' + -t --thread-number=[NUMBER] 'Thread number (default: optimal number for performance)' + -s --statistics 'Prints statistics of event IDs' + -q --quiet 'Quiet mode. Do not display the launch banner' + --contributors 'Prints the list of contributors' +```` -- [APT-Hunter](https://github.com/ahmedkhlief/APT-Hunter) - Pythonで書かれた攻撃検知ツール。 -- [Chainsaw](https://github.com/countercept/chainsaw)　- 他のRustで書かれたSIGMAベースの攻撃検知ツール。 -- [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI) Powershellで書かれた攻撃検知ツール。 -- [EvtxToElk](https://www.dragos.com/blog/industry-news/evtxtoelk-a-python-module-to-load-windows-event-logs-into-elasticsearch/) - EvtxデータをElastic Stackにインポートするツール。 -- [EVTX ATTACK Samples](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES) - 攻撃の痕跡が入っているEVTXサンプルファイルのリポジトリ。作者：[SBousseaden](https://twitter.com/SBousseaden)。 -- [EVTX-to-MITRE-Attack](https://github.com/mdecrevoisier/EVTX-to-MITRE-Attack) - もう一つの素晴らしい攻撃の痕跡が入っているEVTXサンプルファイルのリポジトリ。攻撃はMITE ATT&CKにマッピングされている。 -- [EVTXパーサ](https://github.com/omerbenamram/evtx) - Hayabusaが使っているRustライブラリ。作者：[@OBenamram](https://twitter.com/obenamram)。 -- [LogonTracer](https://github.com/JPCERTCC/LogonTracer) - 横展開を検知するためのEVTX可視化ツール。作者：[JPCERTCC](https://twitter.com/jpcert)。 -- [RustyBlue](https://github.com/Yamato-Security/RustyBlue) - DeepBlueCLIをRustに書き換えたツール。 -- [SIGMA](SIGMA: https://github.com/SigmaHQ/sigma) - SIEM等のジェネリックな攻撃検知ルール。 -- [so-import-evtx](https://docs.securityonion.net/en/2.3/so-import-evtx.html) - evtxファイルをSecurity Onionにインポートするコマンド。 -- [Timeline Explorer](https://ericzimmerman.github.io/#!index.md) - CSV形式のタイムラインの最高な解析ツール。作者：[Eric Zimmerman](https://twitter.com/ericrzimmerman)。 -- [Zircolite](https://github.com/wagga40/Zircolite) - Pythonで書かれたSIGMAベースの攻撃検知ツール。 +## 使用例 +* 1 つのWindowsイベントログファイルに対してHayabusaを実行します: +```` +hayabusa.exe -f eventlog.evtx +```` -## ライセンス +* 複数のWindowsイベントログファイルのあるsample-evtxディレクトリに対して、Hayabusaを実行します: +```` +hayabusa.exe -d .\sample-evtx +```` -HayabusaのライセンスはGPLv3で、ルールはすべてDetection Rule License (DRL) 1.1でリリースしています。 +* 1 つのCSVファイルにエクスポートして、EXCELやTimeline Explorerでさらに分析することができます: +```` +hayabusa.exe -d .\sample-evtx -o results.csv +```` -## 貢献 +* Hayabusaルールのみを実行します（デフォルトでは `-r .\rules` にあるすべてのルールが利用されます）: +```` +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa -o results.csv +```` -コントリビューターは大募集中です！プルリクエストやルール作成が一番ですが、機能リクエストやバグのお知らせなども大歓迎です。 +* Windowsでデフォルトで有効になっているログに対してのみ、Hayabusaルールを実行します: +```` +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa\default -o results.csv +```` -hayabusaを気に入って頂けたら、Githubで星をつけて応援してくださいね！ \ No newline at end of file +* Sysmonログに対してのみHayabusaルールを実行します: +```` +hayabusa.exe -d .\sample-evtx -r .\rules\hayabusa\sysmon -o results.csv +```` + +* Sigmaルールのみを実行します: +```` +hayabusa.exe -d .\sample-evtx -r .\rules\sigma -o results.csv +```` + +* 廃棄(deprecated)されたルール(`status`が`deprecated`になっているルール)とノイジールール(`.\config\noisy-rules.txt`にルールIDが書かれているルール)を有効にします: +```` +hayabusa.exe -d .\sample-evtx --enable-deprecated-rules --enable-noisy-rules -o results.csv +```` + +* ログオン情報を分析するルールのみを実行し、UTCタイムゾーンで出力します: +```` +hayabusa.exe -d .\sample-evtx -r ./rules/Hayabusa/default/events/Security/Logons -u -o results.csv +```` + +* 起動中のWindows端末上で実行し（Administrator権限が必要）、アラート（悪意のある可能性のある動作）のみを検出します: +```` +hayabusa.exe -d C:\Windows\System32\winevt\Logs -m low +```` + +* イベントIDの統計情報を取得します: +```` +hayabusa.exe -f Security.evtx -s +```` + +## サンプルevtxファイルでHayabusaをテストする +Hayabusaをテストしたり、新しいルールを作成したりするためのサンプルevtxファイルをいくつか提供しています: [https://github.com/Yamato-Security/Hayabusa-sample-evtx](https://github.com/Yamato-Security/Hayabusa-sample-evtx) + +# Hayabusa ルール +Hayabusa検出ルールはSigmaのようなYAML形式で記述されております: [https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules). + +ルールの作成方法については、[AboutRuleCreation-Japanase.md](./doc/AboutRuleCreation-Japanase.md) をお読みください。 + +[hayabusa-rulesレポジトリ](https://github.com/Yamato-Security/hayabusa-rules)にあるすべてのルールは、`rules`フォルダに配置する必要があります。 + +情報レベルのルールは `events` とみなされ、`level`が`low` 以上のものは `alerts` とみなされます。 + +Hayabusaルールのディレクトリ構造は、3つのディレクトリに分かれています。 + * `default`: Windows OSでデフォルトで記録されるログ + * `non-default`: グループポリシーやセキュリティベースラインの適用でオンにする必要があるログ + * `sysmon`: [sysmon](https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon)によって生成されるログ。 + * `testing`: 現在テストしているルールを配置するための一時ディレクトリ + +ルールはさらにログタイプ（例：Security、Systemなど）によってディレクトリに分けられ、次の形式で名前が付けられます。 + * アラート形式: `<イベントID>__<詳細>.yml` + * アラート例: `1102_IndicatorRemovalOnHost-ClearWindowsEventLogs_SecurityLogCleared.yml` + * イベント形式: `<イベントID>_<詳細>.yml` + * イベント例: `4776_NTLM-LogonToLocalAccount.yml` + +現在のルールをご確認いただき、新規作成時のテンプレートとして、また検出ロジックの確認用としてご利用ください。 + +## Hayabusa v.s. 変換されたSigmaルール +Sigmaルールは、最初にHayabusaルール形式に変換する必要があります。変換のやり方は[ここ](https://github.com/Yamato-Security/Hayabusa/blob/main/tools/Sigmac/README-Japanese.md)で説明されています。Hayabusaルールは、Windowsのイベントログ解析専用に設計されており、以下のような利点があります: +1. ログの有用なフィールドのみから抽出された追加情報を表示するための `output` フィールドを追加しています。 +2. Hayabusaルールはすべてサンプルログに対してテストされ、検知することが確認されています。 + > 変換処理のバグ、サポートされていない機能、実装の違い(正規表現など)により、一部のSigmaルールは意図したとおりに動作しない可能性があります。 + +**制限事項**: 私たちの知る限り、Hayabusa はオープンソースの Windows イベントログ解析ツールの中でSigmaルールを最も多くサポートしていますが、まだサポートされていないルールもあります。 +1. [Rust正規表現クレート](https://docs.rs/regex/1.5.4/regex/)では機能しない正規表現を使用するルール。 +2. [Sigmaルール仕様](https://github.com/SigmaHQ/Sigma/wiki/Specification)の`count`以外の集計式。 + +> 注意：この制限はSigmaルールの変換ツールにあり、Hayabusa自身にあるわけではありません。 + +## 検知ルールのチューニング +ファイアウォールやIDSと同様に、シグネチャベースのツールは、環境に合わせて調整が必要になるため、特定のルールを永続的または一時的に除外する必要がある場合があります。 + +ルールID(例: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) を `config/exclude-rules.txt`に追加すると、不要なルールや利用できないルールを無視することができます。 + +ルールIDを `config/noisy-rules.txt`に追加して、デフォルトでルールを無視することもできますが、` -n`または `--enable-noisy-rules`オプションを指定してルールを使用することもできます。 + +# その他のWindowsイベントログ解析ツールおよび関連プロジェクト +「すべてを統治する1つのツール」というものはなく、それぞれにメリットがあるため、これらの他の優れたツールやプロジェクトをチェックして、どれが気に入ったかを確認することをお勧めします。 + +- [APT-Hunter](https://github.com/ahmedkhlief/APT-Hunter) - Pythonで記述された攻撃検出ツール。 +- [Chainsaw](https://github.com/countercept/chainsaw) - Rustで記述された同様のSigmaベースの攻撃検出ツール。 +- [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI) - [Eric Conrad](https://twitter.com/eric_conrad) によってPowershellで記述された攻撃検出ツール。 +- [EvtxToElk](https://www.dragos.com/blog/industry-news/evtxtoelk-a-python-module-to-load-windows-event-logs-into-elasticsearch/) - Elastic StackにEvtxデータを送信するPythonツール。 +- [EVTX ATTACK Samples](https://github.com/sbousseaden/EVTX-ATTACK-SAMPLES) - [SBousseaden](https://twitter.com/SBousseaden) によるEVTX攻撃サンプルイベントログファイル。 +- [EVTX-to-MITRE-Attack](https://github.com/mdecrevoisier/EVTX-to-MITRE-Attack) - ATT&CKにマッピングされたEVTX攻撃サンプルログのもう一つの素晴らしいレポジトリ。 +- [EVTX parser](https://github.com/omerbenamram/evtx) - [@OBenamram](https://twitter.com/obenamram) によって書かれた、私たちが使用したRustライブラリ。. +- [LogonTracer](https://github.com/JPCERTCC/LogonTracer) - [JPCERTCC](https://twitter.com/jpcert_en) による、横方向の動きを検出するためにログオンを視覚化するグラフィカルなインターフェースです。 +- [RustyBlue](https://github.com/Yamato-Security/RustyBlue) - 大和セキュリティによるDeepBlueCLIのRust版。 +- [Sigma](https://github.com/SigmaHQ/Sigma) - コミュニティベースの汎用SIEMルール。 +- [so-import-evtx](https://docs.securityonion.net/en/2.3/so-import-evtx.html) - evtxファイルをSecurityOnionにインポートします。 +- [Timeline Explorer](https://ericzimmerman.github.io/#!index.md) - [Eric Zimmerman](https://twitter.com/ericrzimmerman) による最高のCSVタイムラインアナライザーです。 +- [Windows Event Log Analysis - Analyst Reference](https://www.forwarddefense.com/media/attachments/2021/05/15/windows-event-log-analyst-reference.pdf) - Forward DefenseのSteve Ansonによるものです。 +- [Zircolite](https://github.com/wagga40/Zircolite) - Pythonで書かれたSigmaベースの攻撃検知ツール。 + +## Sigmaをサポートする他の類似ツールとの比較 +対象となるサンプルデータ、コマンドラインオプション、ルールのチューニング等によって結果が異なるため、完全な比較はできませんが、ご了承ください。 +我々のテストでは、Hayabusaはすべてのツールの中で最も多くのSigmaルールをサポートしながらも、非常に高速な速度を維持し、大量のメモリを必要としないことが分かっています。 + +以下のベンチマークは、2021/12/19に [sample-evtx repository](https://github.com/Yamato-Security/Hayabusa-sample-evtx) から約500個のevtxファイル（130MB）を基に、Lenovo P51で計測したものです。 + +| | 経過時間 | メモリ使用量 | 検出機能を備えた独自のSigmaルール数 | +| :---: | :---: | :---: | :---: | +| Chainsaw | 7.5 seconds | 70 MB | 170 | +| Hayabusa | 7.5 seconds | 400 MB | 267 | +| Zircolite | 34 seconds | 380 MB | 237 | + +Hayabusaルールも有効にすると、300以上のユニークなアラートとイベントを検出します。 +このベンチマークを見ただけでは、Hayabusaは通常最低でも約400MBのメモリを使うので、Zircoliteよりもメモリを多く使うように見えますが、大きなevtxデータを解析する時にHayabusaの方が有利になります。Zircoliteのメモリ使用量が通常ログサイズの2〜3倍が必要になりますが、Hayabusaのメモリ使用はログサイズをそんなに超えません。 + +# ライセンス + +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)で公開されています。 + +# 貢献 + +どのような形でも構いませんので、ご協力をお願いします。プルリクエスト、ルール作成、evtxログのサンプルなどがベストですが、機能リクエスト、バグの通知なども大歓迎です。 + +少なくとも、私たちのツールを気に入っていただけたなら、Githubで星を付けて、あなたのサポートを表明してください。 diff --git a/contributors.txt b/contributors.txt index 927b19a0..a1ca3a11 100644 --- a/contributors.txt +++ b/contributors.txt @@ -6,6 +6,7 @@ Garigariganzy (@garigariganzy31): Developer, event ID statistics implementation, ItiB (@itiB_S144) : Core developer, sigmac hayabusa backend, rule creation, etc... James Takai / hachiyone(@hach1yon): Current lead developer, tokio multi-threading, sigma aggregation logic, sigmac backend, rule creation, etc… Kazuminn (@k2warugaki): Developer +Tsubokku (@ytsuboi0322): Translations Yusuke Matsui (@apt773): AD hacking working group leader, rule testing, documentation, research, support, etc... Zach Mathis (@yamatosecurity, Yamato Security Founder): Project leader, tool and concept design, rule creation and tuning, etc…