-
- 
-
+ 
+
-[English](README-English.md)
+---
-[Japanese](README-Japanese.md)
\ No newline at end of file
+[tag-1]: https://img.shields.io/github/downloads/Yamato-Security/hayabusa/total?style=plastic&label=GitHub%F0%9F%A6%85DownLoads
+[tag-2]: https://img.shields.io/github/stars/Yamato-Security/hayabusa?style=plastic&label=GitHub%F0%9F%A6%85Stars
+[tag-3]: https://img.shields.io/github/v/release/Yamato-Security/hayabusa?display_name=tag&label=latest-version&style=plastic
+
+![tag-1] ![tag-2] ![tag-3]
+
+# 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](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 YML 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).
+
+## Table of Contents
+
+- [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)
+- [Screenshots](#screenshots)
+ - [Startup](#startup)
+ - [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)
+- [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)
+- [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)
+ - [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)
+- [Community Documentation](#community-documentation)
+ - [English](#english)
+ - [Japanese](#japanese)
+- [Contribution](#contribution)
+- [Bug Submission](#bug-submission)
+- [License](#license)
+
+## Main goals
+
+### 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.
+
+### 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
+
+
+
+## Terminal output
+
+
+
+
+## Results summary
+
+
+
+## Analysis in Excel
+
+
+
+## Analysis in Timeline Explorer
+
+
+
+## Critical alert filtering and computer grouping in Timeline Explorer
+
+
+
+# Sample timeline results
+
+You can check out sample CSV and manually edited XLSX timeline results [here](https://github.com/Yamato-Security/hayabusa/tree/main/sample-results).
+
+You can learn how to analyze CSV timelines in Excel and Timeline Explorer [here](doc/CSV-AnalysisWithExcelAndTimelineExplorer-English.pdf).
+
+# Features
+
+* 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
+
+# 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
+* 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 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
+```
+
+If you forget to use --recursive option, rules/ files which managed in submodule did not cloned.
+You can get latest Hayabusa rules with the execute following command.
+
+When you modified or erased in rules/ , update is failed.
+In this case, you can get latest Hayabusa if you renamed rules folder and execute following command.
+
+```bash
+.\hayabusa.exe -u
+```
+
+# Compiling from source (Optional)
+
+If you have Rust installed, you can compile from source with the following command:
+
+```bash
+cargo clean
+cargo build --release
+```
+
+Be sure to periodically update Rust with:
+
+```bash
+rustup update
+```
+
+The compiled binary will be outputted in the `target/release` folder.
+
+## Cross-compiling 32-bit Windows binaries
+
+You can create 32-bit binaries on 64-bit Windows systems with the following:
+```bash
+rustup install stable-i686-pc-windows-msvc
+rustup target add i686-pc-windows-msvc
+rustup run stable-i686-pc-windows-msvc cargo build --release
+```
+
+## Notes on compiling on macOS
+
+If you receive compile errors about openssl, you will need to install [Homebrew](https://brew.sh/) and then install the following packages:
+```bash
+brew install pkg-config
+brew install openssl
+```
+
+## Notes on compiling on Linux
+
+If you receive compile errors about openssl, you will need to install the following package.
+
+Ubuntu-based distros:
+```bash
+sudo apt install libssl-dev
+```
+
+Fedora-based distros:
+```bash
+sudo yum install openssl-devel
+```
+
+## Advanced: Updating Rust packages
+
+You can update to the latest Rust crates before compiling to get the latest libraries:
+
+```bash
+cargo update
+```
+
+Please let us know if anything breaks after you update.
+
+## Testing hayabusa out on sample evtx files
+
+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.
+
+# 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
+
+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
+
+```bash
+USAGE:
+ -d --directory=[DIRECTORY] 'Directory of multiple .evtx files.'
+ -f --filepath=[FILEPATH] 'File path to one .evtx file.'
+ -r --rules=[RULEFILE/RULEDIRECTORY] 'Rule file or directory. (Default: ./rules)'
+ -c --color 'Output with color. (Terminal needs to support True Color.)'
+ -o --output=[CSV_TIMELINE] 'Save the timeline in CSV format. (Example: results.csv)'
+ -v --verbose 'Output verbose information.'
+ -D --enable-deprecated-rules 'Enable rules marked as deprecated.'
+ -n --enable-noisy-rules 'Enable rules marked as noisy.'
+ -u --update-rules 'Update to the latest rules in the hayabusa-rules github repository.'
+ -m --min-level=[LEVEL] 'Minimum level for rules. (Default: informational)'
+ -l --live-analysis 'Analyze the local C:\Windows\System32\winevt\Logs folder (Windows Only. Administrator privileges required.)'
+ --start-timeline=[STARTTIMELINE] 'Start time of the event logs to load. (Example: '2018/11/28 12:00:00 +09:00')'
+ --end-timeline=[ENDTIMELINE] 'End time of the event logs to load. (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.'
+ -Q --quiet-errors 'Quiet errors mode. Do not save error logs.'
+ --contributors 'Prints the list of contributors.'
+```
+
+## Usage examples
+
+* Run hayabusa against one Windows event log file:
+
+```bash
+.\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
+```
+
+* Export to a single CSV file for further analysis with excel or timeline explorer:
+
+```bash
+.\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
+```
+
+* 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
+```
+
+* Only run hayabusa rules for sysmon logs:
+
+```bash
+.\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
+```
+
+* 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
+```
+
+* 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
+```
+
+* Run on a live Windows machine (requires Administrator privileges) and only detect alerts (potentially malicious behavior):
+
+```bash
+.\hayabusa.exe -l -m low
+```
+
+* Get event ID statistics:
+
+```bash
+.\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
+```
+
+* Verbose output example:
+
+```bash
+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:
+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
+
+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 `
+
+