hayabusa/README-Japanese.md

[English] | [日本語]

---

Hayabusa について

Hayabusaは、日本のYamato Securityグループによって作られたWindowsイベントログのファストフォレンジックタイムライン生成およびスレットハンティングツールです。 Hayabusaは日本語で「ハヤブサ」を意味し、ハヤブサが世界で最も速く、狩猟(hunting)に優れ、とても訓練しやすい動物であることから選ばれました。Rust で開発され、マルチスレッドに対応し、可能な限り高速に動作するよう配慮されています。SigmaルールをHayabusaルール形式に変換するツールも提供しています。Hayabusaの検知ルールもSigmaと同様にYML形式であり、カスタマイズ性や拡張性に優れます。稼働中のシステムで実行してライブ調査することも、複数のシステムからログを収集してオフライン調査することも可能です。(※現時点では、リアルタイムアラートや定期的なスキャンには対応していません。) 出力は一つのCSVタイムラインにまとめられ、ExcelやTimeline Explorerで簡単に分析できるようになります。

目次

• Hayabusa について
  • 目次
  • 主な目的
    • スレット(脅威)ハンティング
    • フォレンジックタイムラインの高速生成
• 開発について
• スクリーンショット
  • 起動画面:
  • ターミナル出力画面:
  • 結果サマリ画面:
  • Excelでの解析:
  • Timeline Explorerでの解析:
  • Criticalアラートのフィルタリングとコンピュータごとのグルーピング:
• タイムラインのサンプル結果
• 特徴
• 予定されている機能
• ダウンロード
• ソースコードからのコンパイル（任意）
  • 32ビットWindowsバイナリのクロスコンパイル
  • macOSでのコンパイルの注意点
  • Linuxでのコンパイルの注意点
  • アドバンス: Rustパッケージの更新
  • サンプルevtxファイルでHayabusaをテストする
• 使用方法
  • Windows Terminalで利用する際の注意事項
  • コマンドラインオプション
  • 使用例
• Hayabusaの出力
  • プログレスバー
  • 標準出力へのカラー設定
• Hayabusa ルール
  • Hayabusa v.s. 変換されたSigmaルール
  • 検知ルールのチューニング
  • イベントIDフィルタリング
• その他のWindowsイベントログ解析ツールおよび関連プロジェクト
  • Sigmaをサポートする他の類似ツールとの比較
• コミュニティによるドキュメンテーション
  • 英語
  • 日本語
• 貢献
• バグの報告
• ライセンス

主な目的

スレット(脅威)ハンティング

Hayabusa には現在、1000以上のSigmaルールと約50のHayabusa検知ルールがあり、定期的にルールが追加されています。 最終的な目標はインシデントレスポンスや定期的なスレットハンティングのために、HayabusaエージェントをすべてのWindows端末にインストールして、中央サーバーにアラートを返す仕組みを作ることです。

フォレンジックタイムラインの高速生成

Windowsのイベントログは、 1）解析が困難なデータ形式であること 2）データの大半がノイズであり調査に有用でないこと から、従来は非常に長い時間と手間がかかる解析作業となっていました。 Hayabusa は、有用なデータのみを抽出し、専門的なトレーニングを受けた分析者だけでなく、Windowsのシステム管理者であれば誰でも利用できる読みやすい形式で提示することを主な目的としています。 Evtx ExplorerやEvent Log Explorerのような深掘り分析を行うツールの代替ではなく、分析者が20%の時間で80%の作業を行えるようにすることを目的としています。

開発について

DeepBlueCLIというWindowsイベントログ解析ツールに触発されて、2020年にRustyBlueプロジェクト用にRustに移植することから始めました。その後、YMLで書かれたSigmaのような柔軟な検知シグネチャを作り、SigmaルールをHayabusaルール形式へ変換するツールも作成しました。

スクリーンショット

起動画面:

ターミナル出力画面:

結果サマリ画面:

Excelでの解析:

Timeline Explorerでの解析:

Criticalアラートのフィルタリングとコンピュータごとのグルーピング:

タイムラインのサンプル結果

CSVと手動で編集したXLSXのタイムライン結果のサンプルはこちらで確認できます。

CSVのタイムラインをExcelやTimeline Explorerで分析する方法はこちらで紹介しています。

特徴

• クロスプラットフォーム対応: Windows, Linux, macOS
• Rustで開発され、メモリセーフでハヤブサよりも高速です！
• マルチスレッド対応により、最大5倍のスピードアップを実現!
• フォレンジック調査やインシデントレスポンスのために、分析しやすいCSVタイムラインを作成します。
• 読みやすい/作成/編集可能なYMLベースのHayabusaルールで作成されたIoCシグネチャに基づくスレット
• SigmaルールをHayabusaルールに変換するためのSigmaルールのサポートがされています。
• 現在、他の類似ツールに比べ最も多くのSigmaルールをサポートしており、カウントルールにも対応しています。
• イベントログの統計（どのような種類のイベントがあるのかを把握し、ログ設定のチューニングに有効です。）
• 不良ルールやノイズの多いルールを除外するルールチューニング設定が可能です。
• MITRE ATT&CKとのマッピング

予定されている機能

• すべてのエンドポイントでの企業全体のスレットハンティング
• 日本語対応
• MITRE ATT&CKのヒートマップ生成機能
• ユーザーログオンと失敗したログオンのサマリー
• JSONログからの入力
• JSONへの出力→Elastic Stack/Splunkへのインポート

ダウンロード

HayabusaのReleasesから最新版をダウンロードできます。

または、以下のgit cloneコマンドでレポジトリをダウンロードし、ソースコードからコンパイルして使用することも可能です。

git clone https://github.com/Yamato-Security/hayabusa.git --recursive

--recursive をつけ忘れた場合、サブモジュールとして管理されている rules/ 内のファイルが取得できません。 Hayabusaでは検知ルールをrules/フォルダの取得はコンパイル後に以下のコマンドでルールの最新版を取得することができます。 rulesフォルダ配下でファイルを削除や更新をしていた場合は更新されないのでその場合はrulesフォルダを他の名前にリネームしたうえで以下のコマンドを打ってください。

.\hayabusa.exe -u

ソースコードからのコンパイル（任意）

Rustがインストールされている場合、以下のコマンドでソースコードからコンパイルすることができます:

cargo clean
cargo build --release

以下のコマンドで定期的にRustをアップデートしてください：

rustup update

コンパイルされたバイナリはtarget/releaseフォルダ配下で作成されます。

32ビットWindowsバイナリのクロスコンパイル

以下のコマンドで64ビットのWindows端末で32ビットのバイナリをクロスコンパイルできます:

rustup install stable-i686-pc-windows-msvc
rustup target add i686-pc-windows-msvc
rustup run stable-i686-pc-windows-msvc cargo build --release

macOSでのコンパイルの注意点

opensslについてのコンパイルエラーが表示される場合は、Homebrewをインストールしてから、以下のパッケージをインストールする必要があります：

brew install pkg-config
brew install openssl

Linuxでのコンパイルの注意点

opensslについてのコンパイルエラーが表示される場合は、以下のパッケージをインストールする必要があります。

Ubuntu系のディストロ:

sudo apt install libssl-dev

Fedora系のディストロ:

sudo yum install openssl-devel

アドバンス: Rustパッケージの更新

コンパイル前に最新のRust crateにアップデートすることで、最新のライブラリを利用することができます:

cargo update

※ アップデート後、何か不具合がありましたらお知らせください。

サンプルevtxファイルでHayabusaをテストする

Hayabusaをテストしたり、新しいルールを作成したりするためのサンプルevtxファイルをいくつか提供しています: https://github.com/Yamato-Security/Hayabusa-sample-evtx

以下のコマンドで、サンプルのevtxファイルを新しいサブディレクトリ hayabusa-sample-evtx にダウンロードすることができます:

git clone https://github.com/Yamato-Security/hayabusa-sample-evtx.git

※ 以下の例でHayabusaを試したい方は、上記コマンドをhayabusaのルートフォルダから実行してください。

使用方法

注意: Hayabusaのルートディレクトリから、バイナリを実行する必要があります。例：.\hayabusa.exe

Windows Terminalで利用する際の注意事項

2021/02/01現在、Windows Terminalから標準出力でhayabusaを使ったときに、コントロールコード(0x9D等)が検知結果に入っていると出力が止まることが確認されています。 Windows Terminalからhayabusaを標準出力で解析させたい場合は、 -c (カラー出力)のオプションをつければ出力が止まることを回避できます。

コマンドラインオプション

USAGE:
    -d --directory=[DIRECTORY] '.evtxファイルを持つディレクトリのパス。'
    -f --filepath=[FILEPATH] '1つの.evtxファイルのパス。'
    -r --rules=[RULEFILE/RULEDIRECTORY] 'ルールファイルまたはルールファイルを持つディレクトリ。(デフォルト: ./rules)'
    -c --color 'カラーで出力する。 (ターミナルはTrue Colorに対応する必要がある。)'
    -o --output=[CSV_TIMELINE] 'タイムラインをCSV形式で保存する。(例: results.csv)'
    -v --verbose '詳細な情報を出力する。'
    -D --enable-deprecated-rules 'Deprecatedルールを有効にする。'
    -n --enable-noisy-rules 'Noisyルールを有効にする。'
    -u --update-rules 'rulesフォルダをhayabusa-rulesのgithubリポジトリの最新版に更新する。'
    -m --min-level=[LEVEL] '結果出力をするルールの最低レベル。(デフォルト: informational)'
    -l --live-analysis 'ローカル端末のC:\Windows\System32\winevt\Logsフォルダを解析する。(Windowsのみ。管理者権限が必要。)'
    --start-timeline=[STARTTIMELINE] '解析対象とするイベントログの開始時刻。(例: '2018/11/28 12:00:00 +09:00')'
    --end-timeline=[ENDTIMELINE] '解析対象とするイベントログの終了時刻。(例: '2018/11/28 12:00:00 +09:00')'
    --rfc-2822 'RFC 2822形式で日付と時刻を出力する。(例: Mon, 07 Aug 2006 12:34:56 -0600)'
    --rfc-3339 'RFC 3339形式で日付と時刻を出力する。 (例: 2006-08-07T12:34:56.485214 -06:00)'
    -U --utc 'UTC形式で日付と時刻を出力する。(デフォルト: 現地時間)'
    -t --thread-number=[NUMBER] 'スレッド数。(デフォルト: パフォーマンスに最適な数値)'
    -s --statistics 'イベント ID の統計情報を表示する。'
    -q --quiet 'Quietモード。起動バナーを表示しない。'
    -Q --quiet-errors 'Quiet errorsモード。エラーログを保存しない。'
    --contributors 'コントリビュータの一覧表示。'

使用例

• １つのWindowsイベントログファイルに対してHayabusaを実行します:

.\hayabusa.exe -f eventlog.evtx

• 複数のWindowsイベントログファイルのあるsample-evtxディレクトリに対して、Hayabusaを実行します:

.\hayabusa.exe -d .\hayabusa-sample-evtx

• １つのCSVファイルにエクスポートして、EXCELやTimeline Explorerでさらに分析することができます:

.\hayabusa.exe -d .\hayabusa-sample-evtx -o results.csv

• Hayabusaルールのみを実行します（デフォルトでは -r .\rules にあるすべてのルールが利用されます）:

.\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv

• Windowsでデフォルトで有効になっているログに対してのみ、Hayabusaルールを実行します:

.\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\default -o results.csv

• Sysmonログに対してのみHayabusaルールを実行します:

.\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv

• Sigmaルールのみを実行します:

.\hayabusa.exe -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv

• 廃棄(deprecated)されたルール(statusがdeprecatedになっているルール)とノイジールール(.\rules\config\noisy_rules.txtにルールIDが書かれているルール)を有効にします:

.\hayabusa.exe -d .\hayabusa-sample-evtx --enable-deprecated-rules --enable-noisy-rules -o results.csv

• ログオン情報を分析するルールのみを実行し、UTCタイムゾーンで出力します:

.\hayabusa.exe -d .\hayabusa-sample-evtx -r ./rules/Hayabusa/default/events/Security/Logons -U -o results.csv

• 起動中のWindows端末上で実行し（Administrator権限が必要）、アラート（悪意のある可能性のある動作）のみを検知します:

.\hayabusa.exe -l -m low

• イベントIDの統計情報を取得します:

.\hayabusa.exe -f Security.evtx -s

• 詳細なメッセージを出力します(処理に時間がかかるファイル、パースエラー等を特定するのに便利):

.\hayabusa.exe -d .\hayabusa-sample-evtx -v

• Verbose出力の例:

Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1027.004_Obfuscated Files or Information\u{a0}Compile After Delivery/sysmon.evtx"
1 / 509 [>-------------------------------------------------------------------------------------------------------------------------------------------] 0.20 % 1s 
Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1558.004_Steal or Forge Kerberos Tickets AS-REP Roasting/Security.evtx"
2 / 509 [>-------------------------------------------------------------------------------------------------------------------------------------------] 0.39 % 1s 
Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1558.003_Steal or Forge Kerberos Tickets\u{a0}Kerberoasting/Security.evtx"
3 / 509 [>-------------------------------------------------------------------------------------------------------------------------------------------] 0.59 % 1s 
Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1197_BITS Jobs/Windows-BitsClient.evtx"
4 / 509 [=>------------------------------------------------------------------------------------------------------------------------------------------] 0.79 % 1s 
Checking target evtx FilePath: "./hayabusa-sample-evtx/YamatoSecurity/T1218.004_Signed Binary Proxy Execution\u{a0}InstallUtil/sysmon.evtx"
5 / 509 [=>------------------------------------------------------------------------------------------------------------------------------------------] 0.98 % 1s

• Quiet error mode: デフォルトでは、Hayabusaはエラーメッセージをエラーログに保存します。 エラーメッセージを保存したくない場合は、-Qを追加してください。

Hayabusaの出力

Hayabusaの結果を標準出力に表示しているとき（デフォルト）は、以下の情報を表示します:

• Timestamp: デフォルトではYYYY-MM-DD HH:mm:ss.sss +hh:mm形式になっています。イベントログの<Event><System><TimeCreated SystemTime>フィールドから来ています。デフォルトのタイムゾーンはローカルのタイムゾーンになりますが、--utc オプションで UTC に変更することができます。
• Computer: イベントログの<Event><System><Computer>フィールドから来ています。
• Event ID: イベントログの<Event><System><EventID>フィールドから来ています。
• Level: YML検知ルールのlevelフィールドから来ています。(例：informational, low, medium, high, critical) デフォルトでは、すべてのレベルのアラートとイベントが出力されますが、-mオプションで最低のレベルを指定することができます。例えば-m highオプションを付けると、highとcriticalアラートしか出力されません。
• Title: YML検知ルールのtitleフィールドから来ています。
• Details: YML検知ルールのdetailsフィールドから来ていますが、このフィールドはHayabusaルールにしかありません。このフィールドはアラートとイベントに関する追加情報を提供し、ログの<Event><System><EventData>部分から有用なデータを抽出することができます。

CSVファイルとして保存する場合、以下の2つのフィールドが追加されます:

• Rule Path: アラートまたはイベントを生成した検知ルールへのパス。
• File Path: アラートまたはイベントを起こしたevtxファイルへのパス。

プログレスバー

プログレス・バーは、複数のevtxファイルに対してのみ機能します。 解析したevtxファイルの数と割合をリアルタイムで表示します。

標準出力へのカラー設定

-cまたは--colorを指定することで、Hayabusaの結果はlevel毎に文字色を変えることができます。 ./config/level_color.txtの値を変更することで文字色を変えることができます。 形式はlevel名,(6桁のRGBのカラーhex)です。 注意: True Colorに対応しているターミナルが必要です。 例: Windows Terminal またはmacOSのiTerm2。

Hayabusa ルール

Hayabusa検知ルールはSigmaのようなYML形式で記述されています。rulesディレクトリに入っていますが、将来的にはhttps://github.com/Yamato-Security/hayabusa-rulesのレポジトリで管理する予定なので、ルールのissueとpull requestはhayabusaのレポジトリではなく、ルールレポジトリへお願いします。

ルールの作成方法については、hayabusa-rulesレポジトリのREADME をお読みください。

hayabusa-rulesレポジトリにあるすべてのルールは、rulesフォルダに配置する必要があります。

levelがinformationのルールは events とみなされ、low 以上は alerts とみなされます。

Hayabusaルールのディレクトリ構造は、3つのディレクトリに分かれています。

• default: Windows OSでデフォルトで記録されるログ
• non-default: グループポリシーやセキュリティベースラインの適用でオンにする必要があるログ
• sysmon: sysmonによって生成されるログ。
• testing: 現在テストしているルールを配置するための一時ディレクトリ

ルールはさらにログタイプ（例：Security、Systemなど）によってディレクトリに分けられ、次の形式で名前が付けられます。

• アラート形式: <イベントID>_<MITRE ATT&CKの攻撃手法名>_<詳細>.yml
• アラート例: 1102_IndicatorRemovalOnHost-ClearWindowsEventLogs_SecurityLogCleared.yml
• イベント形式: <イベントID>_<詳細>.yml
• イベント例: 4776_NTLM-LogonToLocalAccount.yml

現在のルールをご確認いただき、新規作成時のテンプレートとして、また検知ロジックの確認用としてご利用ください。

Hayabusa v.s. 変換されたSigmaルール

Sigmaルールは、最初にHayabusaルール形式に変換する必要があります。変換のやり方はここで説明されています。Hayabusaルールは、Windowsのイベントログ解析専用に設計されており、以下のような利点があります:

1. ログの有用なフィールドのみから抽出された追加情報を表示するための detailsフィールドを追加しています。
2. Hayabusaルールはすべてサンプルログに対してテストされ、検知することが確認されています。

   変換処理のバグ、サポートされていない機能、実装の違い(正規表現など)により、一部のSigmaルールは意図したとおりに動作しない可能性があります。

制限事項: 私たちの知る限り、Hayabusa はオープンソースの Windows イベントログ解析ツールの中でSigmaルールを最も多くサポートしていますが、まだサポートされていないルールもあります。

1. Rust正規表現クレートでは機能しない正規表現を使用するルール。
2. Sigmaルール仕様のcount以外の集計式。

注意：この制限はSigmaルールの変換ツールにあり、Hayabusa自身にあるわけではありません。

検知ルールのチューニング

ファイアウォールやIDSと同様に、シグネチャベースのツールは、環境に合わせて調整が必要になるため、特定のルールを永続的または一時的に除外する必要がある場合があります。

ルールID(例: 4fe151c2-ecf9-4fae-95ae-b88ec9c2fca6) を rules/config/exclude_rules.txtに追加すると、不要なルールや利用できないルールを無視することができます。

ルールIDを rules/config/noisy_rules.txtに追加して、デフォルトでルールを無視することもできますが、 -nまたは --enable-noisy-rulesオプションを指定してルールを使用することもできます。

イベントIDフィルタリング

config/target_eventids.txtにイベントID番号を追加することで、イベントIDでフィルタリングすることができます。 これはパフォーマンスを向上させるので、特定のIDだけを検索したい場合に推奨されます。

すべてのルールのEventIDフィールドと実際のスキャン結果で見られるIDから作成したIDフィルタリストのサンプルをconfig/target_eventids_sample.txtで提供しています。

最高のパフォーマンスを得たい場合はこのリストを使用してください。ただし、検出漏れの可能性が若干あることにご注意ください。

その他のWindowsイベントログ解析ツールおよび関連プロジェクト

「すべてを統治する1つのツール」というものはなく、それぞれにメリットがあるため、これらの他の優れたツールやプロジェクトをチェックして、どれが気に入ったかを確認することをお勧めします。

• APT-Hunter - Pythonで開発された攻撃検知ツール。
• Awesome Event IDs - フォレンジック調査とインシデント対応に役立つイベントIDのリソース。
• Chainsaw - Rustで開発された同様のSigmaベースの攻撃検知ツール。
• DeepBlueCLI - Eric Conrad によってPowershellで開発された攻撃検知ツール。
• EventList - Miriam Wiesnerによるセキュリティベースラインの有効なイベントIDをMITRE ATT&CKにマッピングするPowerShellツール。
• EvtxECmd - Eric ZimmermanによるEvtxパーサー。
• EVTXtract - 未使用領域やメモリダンプからEVTXファイルを復元するツール。
• EvtxToElk - Elastic StackにEvtxデータを送信するPythonツール。
• EVTX ATTACK Samples - SBousseaden によるEVTX攻撃サンプルイベントログファイル。
• EVTX-to-MITRE-Attack - ATT&CKにマッピングされたEVTX攻撃サンプルログのもう一つの素晴らしいレポジトリ。
• EVTX parser - @OBenamram によって書かれた、私たちが使用したRustライブラリ。
• LogonTracer - JPCERTCC による、横方向の動きを検知するためにログオンを視覚化するグラフィカルなインターフェース。
• RustyBlue - 大和セキュリティによるDeepBlueCLIのRust版。
• Sigma - コミュニティベースの汎用SIEMルール。
• so-import-evtx - evtxファイルをSecurityOnionにインポートするツール。
• Timeline Explorer - Eric Zimmerman による最高のCSVタイムラインアナライザ。
• Windows Event Log Analysis - Analyst Reference - Forward DefenseのSteve AnsonによるWindowsイベントログ解析の参考資料。
• WELA (Windows Event Log Analyzer) - Yamato SecurityによるWindowsイベントログ解析のマルチツール。
• Zircolite - Pythonで書かれたSigmaベースの攻撃検知ツール。

Sigmaをサポートする他の類似ツールとの比較

対象となるサンプルデータ、コマンドラインオプション、ルールのチューニング等によって結果が異なるため、完全な比較はできませんが、ご了承ください。 我々のテストでは、Hayabusaはすべてのツールの中で最も多くのSigmaルールをサポートしながらも、非常に高速な速度を維持し、大量のメモリを必要としないことが分かっています。

以下のベンチマークは、2021/12/23に sample-evtx repository から約500個のevtxファイル（130MB）を基に、Lenovo P51で計測したものです。Hayabusa 1.0.0を使いました。

	経過時間	メモリ使用量	利用可能のSigmaルール数
Chainsaw	7.5 seconds	70 MB	170
Hayabusa	7.8 seconds	340 MB	267
Zircolite	34 seconds	380 MB (通常、ログファイルの3倍のサイズが必要)	237

• Hayabusaルールも有効にすると、約300のユニークなアラートとイベントを検知します。
• 合計7.5GBの多数のイベントログファイルでテストしたところ、7分以内に終了し、1GB以上のメモリを使用しませんでした。消費されるメモリ量は、ターゲットのevtxファイルのサイズではなく、結果のサイズによって増えます。
• Timeline Explorerなどのツールで解析するために、結果を1つのCSVタイムラインにまとめる唯一のツールです。

コミュニティによるドキュメンテーション

英語

• 2022/01/24 Hayabusa結果をneo4jで可視化する方法 by Matthew Seyer (@forensic_matt)

日本語

• 2022/01/22 Hayabusa結果をElastic Stackで可視化する方法 by @kzzzzo2
• 2021/12/31 Windowsイベントログ解析ツール「Hayabusa」を使ってみる by itiB (@itiB_S144)
• 2021/12/27 Hayabusaの中身 by Kazuminn (@k47_um1n)

貢献

どのような形でも構いませんので、ご協力をお願いします。プルリクエスト、ルール作成、evtxログのサンプルなどがベストですが、機能リクエスト、バグの通知なども大歓迎です。

少なくとも、私たちのツールを気に入っていただけたなら、Githubで星を付けて、あなたのサポートを表明してください。

バグの報告

見つけたバグをこちらでご連絡ください。報告されたバグを喜んで修正します！

ライセンス

HayabusaはGPLv3で公開され、すべてのルールはDetection Rule License (DRL) 1.1で公開されています。