diff --git a/README-Japanese.md b/README-Japanese.md index 253b9f39..135e367c 100644 --- a/README-Japanese.md +++ b/README-Japanese.md @@ -27,7 +27,6 @@ Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/) - [主な目的](#主な目的) - [スレット(脅威)ハンティング](#スレット脅威ハンティング) - [フォレンジックタイムラインの高速生成](#フォレンジックタイムラインの高速生成) -- [開発について](#開発について) - [スクリーンショット](#スクリーンショット) - [起動画面:](#起動画面) - [ターミナル出力画面:](#ターミナル出力画面) @@ -44,15 +43,20 @@ Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/) - [macOSでのコンパイルの注意点](#macosでのコンパイルの注意点) - [Linuxでのコンパイルの注意点](#linuxでのコンパイルの注意点) - [アドバンス: Rustパッケージの更新](#アドバンス-rustパッケージの更新) - - [サンプルevtxファイルでHayabusaをテストする](#サンプルevtxファイルでhayabusaをテストする) +- [Hayabusaの実行](#hayabusaの実行) + - [注意: アンチウィルス/EDRの誤検知](#注意-アンチウィルスedrの誤検知) + - [Windows](#windows) + - [Windows Terminalで利用する際の注意事項](#windows-terminalで利用する際の注意事項) + - [Linux](#linux) + - [macOS](#macos) - [使用方法](#使用方法) - - [Windows Terminalで利用する際の注意事項](#windows-terminalで利用する際の注意事項) - [コマンドラインオプション](#コマンドラインオプション) - [使用例](#使用例) +- [サンプルevtxファイルでHayabusaをテストする](#サンプルevtxファイルでhayabusaをテストする) - [Hayabusaの出力](#hayabusaの出力) - [プログレスバー](#プログレスバー) - [標準出力へのカラー設定](#標準出力へのカラー設定) -- [Hayabusa ルール](#hayabusa-ルール) +- [Hayabusaルール](#hayabusaルール) - [Hayabusa v.s. 変換されたSigmaルール](#hayabusa-vs-変換されたsigmaルール) - [検知ルールのチューニング](#検知ルールのチューニング) - [イベントIDフィルタリング](#イベントidフィルタリング) @@ -69,7 +73,7 @@ Hayabusaは、日本の[Yamato Security](https://yamatosecurity.connpass.com/) ### スレット(脅威)ハンティング -Hayabusa には現在、1000以上のSigmaルールと約50のHayabusa検知ルールがあり、定期的にルールが追加されています。 最終的な目標はインシデントレスポンスや定期的なスレットハンティングのために、HayabusaエージェントをすべてのWindows端末にインストールして、中央サーバーにアラートを返す仕組みを作ることです。 +Hayabusa には現在、1300以上のSigmaルールと約70のHayabusa検知ルールがあり、定期的にルールが追加されています。 最終的な目標はインシデントレスポンスや定期的なスレットハンティングのために、HayabusaエージェントをすべてのWindows端末にインストールして、中央サーバーにアラートを返す仕組みを作ることです。 ### フォレンジックタイムラインの高速生成 @@ -79,10 +83,6 @@ Windowsのイベントログは、 から、従来は非常に長い時間と手間がかかる解析作業となっていました。 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に移植することから始めました。その後、YMLで書かれたSigmaのような柔軟な検知シグネチャを作り、SigmaルールをHayabusaルール形式へ変換するツールも作成しました。 - # スクリーンショット ## 起動画面: @@ -117,31 +117,31 @@ CSVのタイムラインをExcelやTimeline Explorerで分析する方法は[こ # 特徴 -* クロスプラットフォーム対応: Windows, Linux, macOS +* クロスプラットフォーム対応: Windows, Linux, macOS。 * Rustで開発され、メモリセーフでハヤブサよりも高速です！ -* マルチスレッド対応により、最大5倍のスピードアップを実現! +* マルチスレッド対応により、最大5倍のスピードアップを実現。 * フォレンジック調査やインシデントレスポンスのために、分析しやすいCSVタイムラインを作成します。 -* 読みやすい/作成/編集可能なYMLベースのHayabusaルールで作成されたIoCシグネチャに基づくスレット +* 読みやすい/作成/編集可能なYMLベースのHayabusaルールで作成されたIoCシグネチャに基づくスレット。 * SigmaルールをHayabusaルールに変換するためのSigmaルールのサポートがされています。 * 現在、他の類似ツールに比べ最も多くのSigmaルールをサポートしており、カウントルールにも対応しています。 -* イベントログの統計（どのような種類のイベントがあるのかを把握し、ログ設定のチューニングに有効です。） +* イベントログの統計。(どのような種類のイベントがあるのかを把握し、ログ設定のチューニングに有効です。) * 不良ルールやノイズの多いルールを除外するルールチューニング設定が可能です。 -* MITRE ATT&CKとのマッピング +* MITRE ATT&CKとのマッピング (CSVの出力ファイルのみ)。 # 予定されている機能 -* すべてのエンドポイントでの企業全体のスレットハンティング -* 日本語対応 -* MITRE ATT&CKのヒートマップ生成機能 -* ユーザーログオンと失敗したログオンのサマリー -* JSONログからの入力 -* JSONへの出力→Elastic Stack/Splunkへのインポート +* すべてのエンドポイントでの企業全体のスレットハンティング。 +* 日本語対応。 +* MITRE ATT&CKのヒートマップ生成機能。 +* ユーザーログオンと失敗したログオンのサマリー。 +* JSONログからの入力。 +* JSONへの出力→Elastic Stack/Splunkへのインポート。 # ダウンロード -Hayabusaの[Releases](https://github.com/Yamato-Security/hayabusa/releases)から最新版をダウンロードできます。 +Hayabusaの[Releases](https://github.com/Yamato-Security/hayabusa/releases)からコンパイルされたバイナリが含まれている最新版をダウンロードできます。 -または、以下の`git clone`コマンドでレポジトリをダウンロードし、ソースコードからコンパイルして使用することも可能です。 +または、以下の`git clone`コマンドでレポジトリをダウンロードし、ソースコードからコンパイルして使用することも可能です： ```bash git clone https://github.com/Yamato-Security/hayabusa.git --recursive @@ -152,7 +152,7 @@ git clone https://github.com/Yamato-Security/hayabusa.git --recursive `git pull --recurse-submodules`コマンド、もしくは以下のコマンドで`rules`フォルダを同期し、Hayabusaの最新のルールを更新することができます: ```bash -.\hayabusa.exe -u +hayabusa.exe -u ``` アップデートが失敗した場合は、`rules`フォルダの名前を変更してから、もう一回アップデートしてみて下さい。 @@ -168,7 +168,7 @@ cargo build --release 以下のコマンドで定期的にRustをアップデートしてください： ```bash -rustup update +rustup update stable ``` コンパイルされたバイナリは`target/release`フォルダ配下で作成されます。 @@ -218,27 +218,74 @@ cargo update ※ アップデート後、何か不具合がありましたらお知らせください。 -## サンプルevtxファイルでHayabusaをテストする +# Hayabusaの実行 -Hayabusaをテストしたり、新しいルールを作成したりするためのサンプルevtxファイルをいくつか提供しています: [https://github.com/Yamato-Security/Hayabusa-sample-evtx](https://github.com/Yamato-Security/Hayabusa-sample-evtx) +## 注意: アンチウィルス/EDRの誤検知 -以下のコマンドで、サンプルのevtxファイルを新しいサブディレクトリ `hayabusa-sample-evtx` にダウンロードすることができます: +Hayabusaを実行する際にアンチウィルスやEDRにブロックされる可能性があります。 +誤検知のため、セキュリティ対策の製品がHayabusaを許可するように設定する必要があります。 +マルウェア感染が心配のであれば、ソースコードを確認した上で、自分でバイナリをコンパイルして下さい。 + +## Windows + +コマンドプロンプトやWindows Terminalから32ビットもしくは64ビットのWindowsバイナリをHayabusaのルートディレクトリから実行します。 +例: `hayabusa-1.2.0-windows-x64.exe` + +### Windows Terminalで利用する際の注意事項 + +2021/02/01の時点で、Windows Terminalから標準出力でhayabusaを使ったときに、コントロールコード(0x9D等)が検知結果に入っていると出力が止まることが確認されています。 +Windows Terminalからhayabusaを標準出力で解析させたい場合は、 `-c` (カラー出力)のオプションをつければ出力が止まることを回避できます。 + +## Linux + +まず、バイナリに実行権限を与える必要があります。 ```bash -git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git +chmod +x ./hayabusa-1.2.0-linux-x64 ``` -> ※ 以下の例でHayabusaを試したい方は、上記コマンドをhayabusaのルートフォルダから実行してください。 +次に、Hayabusaのルートディレクトリから実行します： + +```bash +./hayabusa-1.2.0-linux-x64 +``` + +## macOS + +まず、ターミナルやiTerm2からバイナリに実行権限を与える必要があります。 + +```bash +chmod +x ./hayabusa-1.2.0-mac-intel +``` + +次に、Hayabusaのルートディレクトリから実行してみてください： + +```bash +./hayabusa-1.2.0-mac-intel +``` + +macOSの最新版では、以下のセキュリティ警告が出る可能性があります： + +![Mac Error 1 JP](/screenshots/MacOS-RunError-1-JP.png) + +macOSの環境設定から「セキュリティとプライバシー」を開き、「一般」タブから「このまま許可」ボタンをクリックしてください。 + +![Mac Error 2 JP](/screenshots/MacOS-RunError-2-JP.png) + +その後、ターミナルからもう一回実行してみてください： + +```bash +./hayabusa-1.2.0-mac-intel +``` + +以下の警告が出るので、「開く」をクリックしてください。 + +![Mac Error 3 JP](/screenshots/MacOS-RunError-3-JP.png) + +これで実行できるようになります。 # 使用方法 -> 注意: Hayabusaのルートディレクトリから、バイナリを実行する必要があります。例：`.\hayabusa.exe` - -## Windows Terminalで利用する際の注意事項 - -2021/02/01現在、Windows Terminalから標準出力でhayabusaを使ったときに、コントロールコード(0x9D等)が検知結果に入っていると出力が止まることが確認されています。 -Windows Terminalからhayabusaを標準出力で解析させたい場合は、 `-c` (カラー出力)のオプションをつければ出力が止まることを回避できます。 - ## コマンドラインオプション ```bash @@ -271,73 +318,73 @@ USAGE: * １つのWindowsイベントログファイルに対してHayabusaを実行します: ```bash -.\hayabusa.exe -f eventlog.evtx +hayabusa.exe -f eventlog.evtx ``` * 複数のWindowsイベントログファイルのあるsample-evtxディレクトリに対して、Hayabusaを実行します: ```bash -.\hayabusa.exe -d .\hayabusa-sample-evtx +hayabusa.exe -d .\hayabusa-sample-evtx ``` -* １つのCSVファイルにエクスポートして、EXCELやTimeline Explorerでさらに分析することができます: +* １つのCSVファイルにエクスポートして、ExcelやTimeline Explorerでさらに分析することができます: ```bash -.\hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv +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 +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 +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 +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 +hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv ``` * 廃棄(deprecated)されたルール(`status`が`deprecated`になっているルール)とノイジールール(`.\rules\config\noisy_rules.txt`にルールIDが書かれているルール)を有効にします: ```bash -.\hayabusa.exe -d .\hayabusa-sample-evtx --enable-deprecated-rules --enable-noisy-rules -o results.csv +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 +hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default\events\Security\Logons -U -o results.csv ``` * 起動中のWindows端末上で実行し（Administrator権限が必要）、アラート（悪意のある可能性のある動作）のみを検知します: ```bash -.\hayabusa.exe -l -m low +hayabusa.exe -l -m low ``` * イベントIDの統計情報を取得します: ```bash -.\hayabusa.exe -f Security.evtx -s +hayabusa.exe -f Security.evtx -s ``` * 詳細なメッセージを出力します(処理に時間がかかるファイル、パースエラー等を特定するのに便利): ```bash -.\hayabusa.exe -d .\hayabusa-sample-evtx -v +hayabusa.exe -d .\hayabusa-sample-evtx -v ``` * Verbose出力の例: @@ -359,6 +406,18 @@ Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1218.004_ デフォルトでは、Hayabusaはエラーメッセージをエラーログに保存します。 エラーメッセージを保存したくない場合は、`-Q`を追加してください。 +# サンプルevtxファイルでHayabusaをテストする + +Hayabusaをテストしたり、新しいルールを作成したりするためのサンプルevtxファイルをいくつか提供しています: [https://github.com/Yamato-Security/Hayabusa-sample-evtx](https://github.com/Yamato-Security/Hayabusa-sample-evtx) + +以下のコマンドで、サンプルのevtxファイルを新しいサブディレクトリ `hayabusa-sample-evtx` にダウンロードすることができます: + +```bash +git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git +``` + +> ※ 以下の例でHayabusaを試したい方は、上記コマンドをhayabusaのルートフォルダから実行してください。 + # Hayabusaの出力 Hayabusaの結果を標準出力に表示しているとき（デフォルト）は、以下の情報を表示します: @@ -388,7 +447,7 @@ CSVファイルとして保存する場合、以下の2つのフィールドが 注意: True Colorに対応しているターミナルが必要です。 例: [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/install) またはmacOSの[iTerm2](https://iterm2.com/)。 -# Hayabusa ルール +# Hayabusaルール Hayabusa検知ルールはSigmaのようなYML形式で記述されています。`rules`ディレクトリに入っていますが、将来的には[https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules)のレポジトリで管理する予定なので、ルールのissueとpull requestはhayabusaのレポジトリではなく、ルールレポジトリへお願いします。 @@ -435,7 +494,7 @@ Sigmaルールは、最初にHayabusaルール形式に変換する必要があ ルール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フィルタリング @@ -454,6 +513,7 @@ Sigmaルールは、最初にHayabusaルール形式に変換する必要があ * [Awesome Event IDs](https://github.com/stuhli/awesome-event-ids) - フォレンジック調査とインシデント対応に役立つイベントIDのリソース。 * [Chainsaw](https://github.com/countercept/chainsaw) - Rustで開発された同様のSigmaベースの攻撃検知ツール。 * [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI) - [Eric Conrad](https://twitter.com/eric_conrad) によってPowershellで開発された攻撃検知ツール。 +* [Epagneul](https://github.com/jurelou/epagneul) - Windowsイベントログの可視化ツール。 * [EventList](https://github.com/miriamxyra/EventList/) - [Miriam Wiesner](https://github.com/miriamxyra)によるセキュリティベースラインの有効なイベントIDをMITRE ATT&CKにマッピングするPowerShellツール。 * [EvtxECmd](https://github.com/EricZimmerman/evtx) - [Eric Zimmerman](https://twitter.com/ericrzimmerman)によるEvtxパーサー。 * [EVTXtract](https://github.com/williballenthin/EVTXtract) - 未使用領域やメモリダンプからEVTXファイルを復元するツール。 @@ -465,6 +525,7 @@ Sigmaルールは、最初にHayabusaルール形式に変換する必要があ * [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にインポートするツール。 +* [SysmonTools](https://github.com/nshalabi/SysmonTools) - Sysmonの設定とオフライン可視化ツール。 * [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によるWindowsイベントログ解析の参考資料。 * [WELA (Windows Event Log Analyzer)](https://github.com/Yamato-Security/WELA/) - [Yamato Security](https://github.com/Yamato-Security/)によるWindowsイベントログ解析のマルチツール。 diff --git a/README.md b/README.md index 43cabf88..efa980eb 100644 --- a/README.md +++ b/README.md @@ -24,40 +24,44 @@ Hayabusa is a **Windows event log fast forensics timeline generator** and **thre - [About Hayabusa](#about-hayabusa) - [Table of Contents](#table-of-contents) - - [Main goals](#main-goals) - - [Threat hunting](#threat-hunting) - - [Fast forensics timeline generation](#fast-forensics-timeline-generation) -- [About the development](#about-the-development) + - [Main Goals](#main-goals) + - [Threat Hunting](#threat-hunting) + - [Fast Forensics Timeline Generation](#fast-forensics-timeline-generation) - [Screenshots](#screenshots) - [Startup](#startup) - - [Terminal output](#terminal-output) - - [Results summary](#results-summary) + - [Terminal Output](#terminal-output) + - [Results Summary](#results-summary) - [Analysis in Excel](#analysis-in-excel) - [Analysis in Timeline Explorer](#analysis-in-timeline-explorer) - - [Critical alert filtering and computer grouping in Timeline Explorer](#critical-alert-filtering-and-computer-grouping-in-timeline-explorer) -- [Sample timeline results](#sample-timeline-results) + - [Critical Alert Filtering and Computer Grouping in Timeline Explorer](#critical-alert-filtering-and-computer-grouping-in-timeline-explorer) +- [Sample Timeline Results](#sample-timeline-results) - [Features](#features) - [Planned Features](#planned-features) - [Downloads](#downloads) -- [Compiling from source (Optional)](#compiling-from-source-optional) - - [Cross-compiling 32-bit Windows binaries](#cross-compiling-32-bit-windows-binaries) - - [Notes on compiling on macOS](#notes-on-compiling-on-macos) - - [Notes on compiling on Linux](#notes-on-compiling-on-linux) - - [Advanced: Updating Rust packages](#advanced-updating-rust-packages) - - [Testing hayabusa out on sample evtx files](#testing-hayabusa-out-on-sample-evtx-files) +- [Compiling From Source (Optional)](#compiling-from-source-optional) + - [Cross-compiling 32-bit Windows Binaries](#cross-compiling-32-bit-windows-binaries) + - [macOS Compiling Notes](#macos-compiling-notes) + - [Linux Compiling Notes](#linux-compiling-notes) + - [Advanced: Updating Rust Packages](#advanced-updating-rust-packages) +- [Running Hayabusa](#running-hayabusa) + - [Caution: Anti-Virus/EDR Warnings](#caution-anti-virusedr-warnings) + - [Windows](#windows) + - [Caution: Windows Terminal Bug](#caution-windows-terminal-bug) + - [Linux](#linux) + - [macOS](#macos) - [Usage](#usage) - - [Caution: Output printed to screen may stop in Windows Terminal](#caution-output-printed-to-screen-may-stop-in-windows-terminal) - - [Command line options](#command-line-options) - - [Usage examples](#usage-examples) -- [Hayabusa output](#hayabusa-output) - - [Progress bar](#progress-bar) + - [Command Line Options](#command-line-options) + - [Usage Examples](#usage-examples) +- [Testing Hayabusa on Sample Evtx Files](#testing-hayabusa-on-sample-evtx-files) +- [Hayabusa Output](#hayabusa-output) + - [Progress Bar](#progress-bar) - [Color Output](#color-output) -- [Hayabusa rules](#hayabusa-rules) - - [Hayabusa v.s. converted Sigma rules](#hayabusa-vs-converted-sigma-rules) - - [Detection rule tuning](#detection-rule-tuning) - - [Event ID filtering](#event-id-filtering) -- [Other Windows event log analyzers and related projects](#other-windows-event-log-analyzers-and-related-projects) - - [Comparison to other similar tools that support sigma](#comparison-to-other-similar-tools-that-support-sigma) +- [Hayabusa Rules](#hayabusa-rules) + - [Hayabusa v.s. Converted Sigma Rules](#hayabusa-vs-converted-sigma-rules) + - [Detection Rule Tuning](#detection-rule-tuning) + - [Event ID Filtering](#event-id-filtering) +- [Other Windows Event Log Analyzers and Related Projects](#other-windows-event-log-analyzers-and-related-projects) + - [Comparison To Other Similar Tools](#comparison-to-other-similar-tools) - [Community Documentation](#community-documentation) - [English](#english) - [Japanese](#japanese) @@ -65,33 +69,29 @@ Hayabusa is a **Windows event log fast forensics timeline generator** and **thre - [Bug Submission](#bug-submission) - [License](#license) -## Main goals +## Main Goals -### Threat hunting +### Threat Hunting -Hayabusa currently has over 1000 sigma rules and around 50 hayabusa rules with more rules being added regularly. The ultimate goal is to be able to push out hayabusa agents to all Windows endpoints after an incident or for periodic threat hunting and have them alert back to a central server. +Hayabusa currently has over 1300 sigma rules and around 70 hayabusa rules with more rules being added regularly. The ultimate goal is to be able to push out hayabusa agents to all Windows endpoints after an incident or for periodic threat hunting and have them alert back to a central server. -### Fast forensics timeline generation +### Fast Forensics Timeline Generation Windows event log analysis has traditionally been a very long and tedious process because Windows event logs are 1) in a data format that is hard to analyze and 2) the majority of data is noise and not useful for investigations. Hayabusa's main goal is to extract out only useful data and present it in an easy-to-read format that is usable not only by professionally trained analysts but any Windows system administrator. Hayabusa is not intended to be a replacement for tools like [Evtx Explorer](https://ericzimmerman.github.io/#!index.md) or [Event Log Explorer](https://eventlogxp.com/) for more deep-dive analysis but is intended for letting analysts get 80% of their work done in 20% of the time. -# About the development - -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 YML, and then added a backend to sigma to support converting sigma rules into our hayabusa rule format. - # Screenshots ## Startup ![Hayabusa Startup](/screenshots/Hayabusa-Startup.png) -## Terminal output +## Terminal Output ![Hayabusa terminal output](/screenshots/Hayabusa-Results.png) -## Results summary +## Results Summary ![Hayabusa results summary](/screenshots/HayabusaResultsSummary.png) @@ -103,11 +103,11 @@ First inspired by the [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCL ![Hayabusa analysis in Timeline Explorer](screenshots/TimelineExplorer-ColoredTimeline.png) -## Critical alert filtering and computer grouping in Timeline Explorer +## Critical Alert Filtering and Computer Grouping in Timeline Explorer ![Critical alert filtering and computer grouping in Timeline Explorer](screenshots/TimelineExplorer-CriticalAlerts-ComputerGrouping.png) -# Sample timeline results +# Sample Timeline Results You can check out sample CSV timelines [here](https://github.com/Yamato-Security/hayabusa/tree/main/sample-results). @@ -115,31 +115,31 @@ You can learn how to analyze CSV timelines in Excel and Timeline Explorer [here] # Features -* Cross-platform support: Windows, Linux, macOS +* Cross-platform support: Windows, Linux, macOS. * Developed in Rust to be memory safe and faster than a hayabusa falcon! -* Multi-thread support delivering up to a 5x speed improvement! -* Creates a single easy-to-analyze CSV timeline for forensic investigations and incident response -* Threat hunting based on IoC signatures written in easy to read/create/edit YML based hayabusa rules -* Sigma rule support to convert sigma rules to hayabusa rules -* Currently it supports the most sigma rules compared to other similar tools and even supports count rules -* Event log statistics (Useful for getting a picture of what types of events there are and for tuning your log settings) -* Rule tuning configuration by excluding unneeded or noisy rules -* MITRE ATT&CK mapping +* Multi-thread support delivering up to a 5x speed improvement. +* Creates a single easy-to-analyze CSV timeline for forensic investigations and incident response. +* Threat hunting based on IoC signatures written in easy to read/create/edit YML based hayabusa rules. +* Sigma rule support to convert sigma rules to hayabusa rules. +* Currently it supports the most sigma rules compared to other similar tools and even supports count rules. +* Event log statistics. (Useful for getting a picture of what types of events there are and for tuning your log settings.) +* Rule tuning configuration by excluding unneeded or noisy rules. +* MITRE ATT&CK mapping of tactics (only in saved CSV files). # Planned Features -* Enterprise-wide hunting on all endpoints -* Japanese language support -* MITRE ATT&CK heatmap generation -* User logon and failed logon summary -* Input from JSON logs +* Enterprise-wide hunting on all endpoints. +* Japanese language support. +* MITRE ATT&CK heatmap generation. +* User logon and failed logon summary. +* Input from JSON logs. * JSON support for sending alerts to Elastic Stack/Splunk, etc... # Downloads -You can download the latest Hayabusa version from the [Releases](https://github.com/Yamato-Security/hayabusa/releases) page. +You can download the latest stable version of hayabusa with compiled binaries from the [Releases](https://github.com/Yamato-Security/hayabusa/releases) page. -You can also `git clone` the repository with the following command and compile binary from source code.: +You can also `git clone` the repository with the following command and compile binary from source code: ```bash git clone https://github.com/Yamato-Security/hayabusa.git --recursive @@ -150,12 +150,12 @@ Note: If you forget to use --recursive option, the `rules` folder, which is mana You can sync the `rules` folder and get latest Hayabusa rules with `git pull --recurse-submodules` or use the following command: ```bash -.\hayabusa.exe -u +hayabusa.exe -u ``` If the update fails, you may need to rename the `rules` folder and try again. -# Compiling from source (Optional) +# Compiling From Source (Optional) If you have Rust installed, you can compile from source with the following command: @@ -167,12 +167,12 @@ cargo build --release Be sure to periodically update Rust with: ```bash -rustup update +rustup update stable ``` The compiled binary will be outputted in the `target/release` folder. -## Cross-compiling 32-bit Windows binaries +## Cross-compiling 32-bit Windows Binaries You can create 32-bit binaries on 64-bit Windows systems with the following: ```bash @@ -181,7 +181,7 @@ rustup target add i686-pc-windows-msvc rustup run stable-i686-pc-windows-msvc cargo build --release ``` -## Notes on compiling on macOS +## macOS Compiling Notes If you receive compile errors about openssl, you will need to install [Homebrew](https://brew.sh/) and then install the following packages: ```bash @@ -189,7 +189,7 @@ brew install pkg-config brew install openssl ``` -## Notes on compiling on Linux +## Linux Compiling Notes If you receive compile errors about openssl, you will need to install the following package. @@ -203,7 +203,7 @@ Fedora-based distros: sudo yum install openssl-devel ``` -## Advanced: Updating Rust packages +## Advanced: Updating Rust Packages You can update to the latest Rust crates before compiling to get the latest libraries: @@ -213,29 +213,74 @@ cargo update Please let us know if anything breaks after you update. -## Testing hayabusa out on sample evtx files +# Running Hayabusa -We have provided some sample evtx files for you to test hayabusa and/or create new rules at [https://github.com/Yamato-Security/hayabusa-sample-evtx](https://github.com/Yamato-Security/hayabusa-sample-evtx) +## Caution: Anti-Virus/EDR Warnings -You can download the sample evtx files to a new `hayabusa-sample-evtx` sub-directory with the following command: +You may receive warning from anti-virus or EDR when trying to run hayabusa. These are false positives so you may need to configure your security products to allow running hayabusa. If you are worried about malware, please check the hayabusa source code and compile the binaries yourself. -```bash -git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git -``` +## Windows -> Note: You need to run the binary from the Hayabusa root directory. +In Command Prompt or Windows Terminal, just run 32-bit or 64-bit Windoows binary from the hayabusa root directory. +Example: `hayabusa-1.2.0-windows-x64.exe` -# Usage - -> Note: You need to run the Hayabusa binary from the Hayabusa root directory. Example: `.\hayabusa.exe` - -## Caution: Output printed to screen may stop in Windows Terminal +### Caution: Windows Terminal Bug As of Feb 1, 2022, Windows Terminal will freeze midway when displaying results to the screen when run against the sample evtx files. This is because there is a control code (0x9D) in the output. This is known Windows Terminal bug which will eventually be fixed but for the meantime, you can avoid this bug by adding the `-c` (colored output) option when you run hayabusa. -## Command line options +## Linux + +You first need to make the binary executable. + +```bash +chmod +x ./hayabusa-1.2.0-linux-x64 +``` + +Then run it from the Hayabusa root directory: + +```bash +./hayabusa-1.2.0-linux-x64 +``` + +## macOS + +From Terminal or iTerm2, you first need to make the binary executable. + +```bash +chmod +x ./hayabusa-1.2.0-mac-intel +``` + +Then, try to run it from the Hayabusa root directory: + +```bash +./hayabusa-1.2.0-mac-intel +``` + +On the latest version of macOS, you may receive the following security error when you try to run it: + +![Mac Error 1 EN](/screenshots/MacOS-RunError-1-EN.png) + +Click "Cancel" and then from System Preferences, open "Security & Privacy" and from the General tab, click "Allow Anyway". + +![Mac Error 2 EN](/screenshots/MacOS-RunError-2-EN.png) + +After that, try to run it again. + +```bash +./hayabusa-1.2.0-mac-intel +``` + +The following warning will pop up, so please click "Open". + +![Mac Error 3 EN](/screenshots/MacOS-RunError-3-EN.png) + +You should now be able to run hayabusa. + +# Usage + +## Command Line Options ```bash USAGE: @@ -262,78 +307,78 @@ USAGE: --contributors 'Prints the list of contributors.' ``` -## Usage examples +## Usage Examples * Run hayabusa against one Windows event log file: ```bash -.\hayabusa.exe -f eventlog.evtx +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 +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 +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 +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 +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 +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 +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 `.\rules\config\noisy_rules.txt`): ```bash -.\hayabusa.exe -d .\hayabusa-sample-evtx --enable-noisy-rules --enable-deprecated-rules -o results.csv +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 +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 -l -m low +hayabusa.exe -l -m low ``` * Get event ID statistics: ```bash -.\hayabusa.exe -f Security.evtx -s +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 +hayabusa.exe -d .\hayabusa-sample-evtx -v ``` * Verbose output example: @@ -355,23 +400,35 @@ Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1218.004_ By default, hayabusa will save error messages to error log files. If you do not want to save error messages, please add `-Q`. -# Hayabusa output +# Testing Hayabusa on Sample Evtx Files -When Hayabusa output is being displayed to the screen (the default), it will display the following information: +We have provided some sample evtx files for you to test hayabusa and/or create new rules at [https://github.com/Yamato-Security/hayabusa-sample-evtx](https://github.com/Yamato-Security/hayabusa-sample-evtx) + +You can download the sample evtx files to a new `hayabusa-sample-evtx` sub-directory with the following command: + +```bash +git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git +``` + +> Note: You need to run the binary from the Hayabusa root directory. + +# Hayabusa Output + +When hayabusa output is being displayed to the screen (the default), it will display the following information: * `Timestamp`: Default is `YYYY-MM-DD HH:mm:ss.sss +hh:mm` format. This comes from the `` field in the event log. The default timezone will be the local timezone but you can change the timezone to UTC with the `--utc` option. * `Computer`: This comes from the `` field in the event log. * `Event ID`: This comes from the `` field in the event log. * `Level`: This comes from the `level` field in the YML detection rule. (`informational`, `low`, `medium`, `high`, `critical`) By default, all level alerts will be displayed but you can set the minimum level with `-m`. For example, you can set `-m high`) in order to only scan for and display high and critical alerts. * `Title`: This comes from the `title` field in the YML detection rule. -* `Details`: This comes from the `details` field in the YML detection rule, however, only Hayabusa rules have this field. This field gives extra information about the alert or event and can extract useful data from the `` portion of the log. For example, usernames, command line information, process information, etc... +* `Details`: This comes from the `details` field in the YML detection rule, however, only hayabusa rules have this field. This field gives extra information about the alert or event and can extract useful data from the `` portion of the log. For example, usernames, command line information, process information, etc... When saving to a CSV file an additional two fields will be added: * `Rule Path`: The path to the detection rule that generated the alert or event. * `File Path`: The path to the evtx file that caused the alert or event. -## Progress bar +## Progress Bar The progress bar will only work with multiple evtx files. It will display in real time the number and percent of evtx files that it has finished analyzing. @@ -383,7 +440,7 @@ You can change the default colors in the config file at `./config/level_color.tx 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. -# Hayabusa rules +# Hayabusa Rules 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. @@ -408,7 +465,7 @@ Rules are further seperated into directories by log type (Example: Security, Sys Please check out the current rules to use as a template in creating new ones or for checking the detection logic. -## Hayabusa v.s. converted Sigma rules +## Hayabusa v.s. Converted Sigma Rules Sigma rules need to first be converted to hayabusa rule format explained [here](https://github.com/Yamato-Security/hayabusa-rules/blob/main/tools/sigmac/README.md). Hayabusa rules are designed solely for Windows event log analysis and have the following benefits: @@ -423,7 +480,7 @@ Sigma rules need to first be converted to hayabusa rule format explained [here]( > Note: the limitation is in the sigma rule converter and not in hayabusa itself. -## Detection rule tuning +## 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. @@ -431,7 +488,7 @@ You can add a rule ID (Example: `4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6`) to `rule 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 +## Event ID Filtering 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. @@ -440,7 +497,7 @@ We have provided a sample ID filter list at [`config/target_eventids_sample.txt` Please use this list if you want the best performance but be aware that there is a slight possibility for missing events (false negatives). -# Other Windows event log analyzers and related projects +# 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. @@ -448,6 +505,7 @@ There is no "one tool to rule them all" and we have found that each has its own * [Awesome Event IDs](https://github.com/stuhli/awesome-event-ids) - Collection of Event ID resources useful for Digital Forensics and Incident Response * [Chainsaw](https://github.com/countercept/chainsaw) - A similar sigma-based attack detection tool written in Rust. * [DeepBlueCLI](https://github.com/sans-blue-team/DeepBlueCLI) - Attack detection tool written in Powershell by [Eric Conrad](https://twitter.com/eric_conrad). +* [Epagneul](https://github.com/jurelou/epagneul) - Graph visualization for Windows event logs. * [EventList](https://github.com/miriamxyra/EventList/) - Map security baseline event IDs to MITRE ATT&CK by [Miriam Wiesner](https://github.com/miriamxyra). * [EvtxECmd](https://github.com/EricZimmerman/evtx) - Evtx parser by [Eric Zimmerman](https://twitter.com/ericrzimmerman). * [EVTXtract](https://github.com/williballenthin/EVTXtract) - Recover EVTX log files from unallocated space and memory images. @@ -459,22 +517,23 @@ There is no "one tool to rule them all" and we have found that each has its own * [RustyBlue](https://github.com/Yamato-Security/RustyBlue) - Rust port of DeepBlueCLI by Yamato Security. * [Sigma](https://github.com/SigmaHQ/sigma) - Community based generic SIEM rules. * [so-import-evtx](https://docs.securityonion.net/en/2.3/so-import-evtx.html) - Import evtx files into Security Onion. +* [SysmonTools](https://github.com/nshalabi/SysmonTools) - Configuration and off-line log visualization tool for Sysmon. * [Timeline Explorer](https://ericzimmerman.github.io/#!index.md) - The best CSV timeline analyzer by [Eric Zimmerman](https://twitter.com/ericrzimmerman). * [Windows Event Log Analysis - Analyst Reference](https://www.forwarddefense.com/media/attachments/2021/05/15/windows-event-log-analyst-reference.pdf) - by Forward Defense's Steve Anson. * [WELA (Windows Event Log Analyzer)](https://github.com/Yamato-Security/WELA) - The swiff-army knife for Windows event logs by [Yamato Security](https://github.com/Yamato-Security/) * [Zircolite](https://github.com/wagga40/Zircolite) - Sigma-based attack detection tool written in Python. -## Comparison to other similar tools that support sigma +## Comparison To Other Similar Tools 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. +In our tests, we have found hayabusa to support the largest number of sigma rules compared to other similar 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/23 with Hayabusa version 1.0.0. +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/23 with hayabusa version 1.0.0. | | Elapsed Time | Memory Usage | Unique Sigma Rules With Detections | | :-------: | :----------: | :----------------------------------------------------------: | :--------------------------------: | | Chainsaw | 7.5 seconds | 75 MB | 170 | -| Hayabusa | 7.8 seconds | 340 MB | 267 | +| Hayabusa | 7.8 seconds | 340 MB (memory usage depends on the amount of alerts) | 267 | | Zircolite | 34 seconds | 380 MB (normally requires 3 times the size of the log files) | 237 | * With hayabusa rules enabled, it will detect around 300 unique alerts and events. diff --git a/screenshots/Hayabusa-Startup.png b/screenshots/Hayabusa-Startup.png index db909e61..be69cd54 100644 Binary files a/screenshots/Hayabusa-Startup.png and b/screenshots/Hayabusa-Startup.png differ diff --git a/screenshots/MacOS-RunError-1-EN.png b/screenshots/MacOS-RunError-1-EN.png new file mode 100644 index 00000000..4f4068ca Binary files /dev/null and b/screenshots/MacOS-RunError-1-EN.png differ diff --git a/screenshots/MacOS-RunError-1-JP.png b/screenshots/MacOS-RunError-1-JP.png new file mode 100644 index 00000000..714bb5b0 Binary files /dev/null and b/screenshots/MacOS-RunError-1-JP.png differ diff --git a/screenshots/MacOS-RunError-2-EN.png b/screenshots/MacOS-RunError-2-EN.png new file mode 100644 index 00000000..84cdba09 Binary files /dev/null and b/screenshots/MacOS-RunError-2-EN.png differ diff --git a/screenshots/MacOS-RunError-2-JP.png b/screenshots/MacOS-RunError-2-JP.png new file mode 100644 index 00000000..30dff400 Binary files /dev/null and b/screenshots/MacOS-RunError-2-JP.png differ diff --git a/screenshots/MacOS-RunError-3-EN.png b/screenshots/MacOS-RunError-3-EN.png new file mode 100644 index 00000000..86d03685 Binary files /dev/null and b/screenshots/MacOS-RunError-3-EN.png differ diff --git a/screenshots/MacOS-RunError-3-JP.png b/screenshots/MacOS-RunError-3-JP.png new file mode 100644 index 00000000..c10099a7 Binary files /dev/null and b/screenshots/MacOS-RunError-3-JP.png differ