Home

Awesome

<div align="center"> <p> <img alt="Hayabusa Logo" src="logo.png" width="60%"> </p> [ <b>English</b> ] | [<a href="README-Japanese.md">日本語</a>] </div>
<p align="center"> <a href="https://github.com/Yamato-Security/hayabusa/releases"><img src="https://img.shields.io/github/v/release/Yamato-Security/hayabusa?color=blue&label=Stable%20Version&style=flat""/></a> <a href="https://github.com/Yamato-Security/hayabusa/releases"><img src="https://img.shields.io/github/downloads/Yamato-Security/hayabusa/total?style=flat&label=GitHub%F0%9F%A6%85Downloads&color=blue"/></a> <a href="https://github.com/Yamato-Security/hayabusa/stargazers"><img src="https://img.shields.io/github/stars/Yamato-Security/hayabusa?style=flat&label=GitHub%F0%9F%A6%85Stars"/></a> <a href="https://github.com/Yamato-Security/hayabusa/graphs/contributors"><img src="https://img.shields.io/github/contributors/Yamato-Security/hayabusa?label=Contributors&color=blue&style=flat"/></a> <a href="https://www.blackhat.com/asia-22/arsenal/schedule/#hayabusa-26211"><img src="https://raw.githubusercontent.com/toolswatch/badges/master/arsenal/asia/2022.svg"></a> <a href="https://codeblue.jp/2022/en/talks/?content=talks_24"><img src="https://img.shields.io/badge/CODE%20BLUE%20Bluebox-2022-blue"></a> <a href="https://www.seccon.jp/2022/seccon_workshop/windows.html"><img src="https://img.shields.io/badge/SECCON-2023-blue"></a> <a href="https://www.security-camp.or.jp/minicamp/tokyo2023.html"><img src="https://img.shields.io/badge/Security%20MiniCamp%20Tokyo-2023-blue"></a> <a href="https://www.sans.org/cyber-security-training-events/digital-forensics-summit-2023/"><img src="https://img.shields.io/badge/SANS%20DFIR%20Summit-2023-blue"></a> <a href="https://bsides.tokyo/2024/"><img src="https://img.shields.io/badge/BSides%20Tokyo-2024-blue"></a> <a href="https://www.hacker.or.jp/hack-fes-2024/"><img src="https://img.shields.io/badge/Hack%20Fes.-2024-blue"></a> <a href="https://hitcon.org/2024/CMT/"><img src="https://img.shields.io/badge/HITCON-2024-blue"></a> <a href="https://www.blackhat.com/sector/2024/briefings/schedule/index.html#performing-dfir-and-threat-hunting-with-yamato-security-oss-tools-and-community-driven-knowledge-41347"><img src="https://img.shields.io/badge/SecTor-2024-blue"></a> <a href="Maintenance Level"><img src="https://img.shields.io/badge/Maintenance%20Level-Actively%20Developed-brightgreen.svg" /></a> <a href="Total Commits"><img src="https://img.shields.io/github/commit-activity/t/Yamato-Security/hayabusa/main" /></a> <a href="https://rust-reportcard.xuri.me/report/github.com/Yamato-Security/hayabusa"><img src="https://rust-reportcard.xuri.me/badge/github.com/Yamato-Security/hayabusa" /></a> <a href="https://codecov.io/gh/Yamato-Security/hayabusa" ><img src="https://codecov.io/gh/Yamato-Security/hayabusa/branch/main/graph/badge.svg?token=WFN5XO9W8C"/></a> <a href="https://twitter.com/SecurityYamato"><img src="https://img.shields.io/twitter/follow/SecurityYamato?style=social"/></a> </p>

About Hayabusa

Hayabusa is a Windows event log fast forensics timeline generator and threat hunting tool created by the Yamato Security group in Japan. Hayabusa means "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 and supports multi-threading in order to be as fast as possible. We have provided a tool to convert Sigma rules into Hayabusa rule format. The Sigma-compatible Hayabusa detection rules are written in YML in order to be as easily customizable and extensible as possible. Hayabusa can be run either on single running systems for live analysis, by gathering logs from single or multiple systems for offline analysis, or by running the Hayabusa artifact with Velociraptor for enterprise-wide threat hunting and incident response. The output will be consolidated into a single CSV timeline for easy analysis in LibreOffice, Timeline Explorer, Elastic Stack, Timesketch, etc...

Companion Projects

Third-Party Projects That Use Hayabusa

Table of Contents

Main Goals

Threat Hunting and Enterprise-wide DFIR

Hayabusa currently has over 4000 Sigma rules and over 170 Hayabusa built-in detection rules with more rules being added regularly. It can be used for enterprise-wide proactive threat hunting as well as DFIR (Digital Forensics and Incident Response) for free with Velociraptor's Hayabusa artifact. By combining these two open-source tools, you can essentially retroactively reproduce a SIEM when there is no SIEM setup in the environment. You can learn about how to do this by watching Eric Capuano's Velociraptor walkthrough here.

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 goal is to extract out only useful data and present it in a concise as possible easy-to-read format that is usable not only by professionally trained analysts but any Windows system administrator. Hayabusa hopes to let analysts get 80% of their work done in 20% of the time when compared to traditional Windows event log analysis.

DFIR Timeline

Screenshots

Startup

Hayabusa Startup

DFIR Timeline Terminal Output

Hayabusa DFIR terminal output

Keyword Search Results

Hayabusa search results

Detection Fequency Timeline (-T option)

Hayabusa Detection Frequency Timeline

Results Summary

Hayabusa results summary

HTML Results Summary (-H option)

Hayabusa results summary

Hayabusa results summary

Hayabusa results summary

DFIR Timeline Analysis in LibreOffice (-M Multiline Output)

Hayabusa analysis in LibreOffice

DFIR Timeline Analysis in Timeline Explorer

Hayabusa analysis in Timeline Explorer

Critical Alert Filtering and Computer Grouping in Timeline Explorer

Critical alert filtering and computer grouping in Timeline Explorer

Analysis with the Elastic Stack Dashboard

Elastic Stack Dashboard 1

Elastic Stack Dashboard 2

Analysis in Timesketch

Timesketch

Importing and Analyzing Timeline Results

You can learn how to analyze CSV timelines in Excel and Timeline Explorer here.

You can learn how to import CSV files into Elastic Stack here.

You can learn how to import CSV files into Timesketch here.

Analyzing JSON-formatted results with JQ

You can learn how to analyze JSON-formatted results with jq here.

Features

Downloads

Please download the latest stable version of Hayabusa with compiled binaries or compile the source code from the Releases page.

We provide binaries for the following architectures:

For some reason the Linux ARM MUSL binary does not run properly so we do not provide that binary. It is out of our control, so we plan on providing it in the future when it gets fixed.

Windows live response packages

As of v2.18.0, we are provide special Windows packages that use XOR-encoded rules provided in a single file as well as all of the config files combined into a single file (hosted at the hayabusa-encoded-rules repository). Just download the zip packages with live-response in the name. The zip files just include three files: the Hayabusa binary, XOR-encoded rules file and the config file. The purpose of these live response packages are for when running Hayabusa on client endpoints, we want to make sure that anti-virus scanners like Windows Defender do not give false positives on .yml rule files. Also, we want to minimize the amount of files being written to the system so that forensics artifacts like the USN Journal do not get overwritten.

Git Cloning

You can git clone the repository with the following command and compile binary from source code:

Warning: The main branch of the repository is for development purposes so you may be able to access new features not yet officially released, however, there may be bugs so consider it unstable.

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

Note: If you forget to use --recursive option, the rules folder, which is managed as a git submodule, will not be cloned.

You can sync the rules folder and get latest Hayabusa rules with git pull --recurse-submodules or use the following command:

hayabusa.exe update-rules

If the update fails, you may need to rename the rules folder and try again.

Caution: When updating, rules and config files in the rules folder are replaced with the latest rules and config files in the hayabusa-rules repository. Any changes you make to existing files will be overwritten, so we recommend that you make backups of any files that you edit before updating. If you are performing level tuning with level-tuning, please re-tune your rule files after each update. If you add new rules inside of the rules folder, they will not be overwritten or deleted when updating.

Advanced: Compiling From Source (Optional)

If you have Rust installed, you can compile from source with the following command:

Note: To compile, you usually need the latest version of Rust.

cargo build --release

You can download the latest unstable version from the main branch or the latest stable version from the Releases page.

Be sure to periodically update Rust with:

rustup update stable

The compiled binary will be outputted in the ./target/release folder.

Updating Rust Packages

You can update to the latest Rust crates before compiling:

cargo update

Please let us know if anything breaks after you update.

Cross-compiling 32-bit Windows Binaries

You can create 32-bit binaries on 64-bit Windows systems with the following:

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

Warning: Be sure to run rustup install stable-i686-pc-windows-msvc whenever there is a new stable version of Rust as rustup update stable will not update the compiler for cross compiling and you may receive build errors.

macOS Compiling Notes

If you receive compile errors about openssl, you will need to install Homebrew and then install the following packages:

brew install pkg-config
brew install openssl

Linux Compiling Notes

If you receive compile errors about openssl, you will need to install the following package.

Ubuntu-based distros:

sudo apt install libssl-dev

Fedora-based distros:

sudo yum install openssl-devel

Cross-compiling Linux MUSL Binaries

On a Linux OS, first install the target.

rustup install stable-x86_64-unknown-linux-musl
rustup target add x86_64-unknown-linux-musl

Compile with:

cargo build --release --target=x86_64-unknown-linux-musl

Warning: Be sure to run rustup install stable-x86_64-unknown-linux-musl whenever there is a new stable version of Rust as rustup update stable will not update the compiler for cross compiling and you may receive build errors.

The MUSL binary will be created in the ./target/x86_64-unknown-linux-musl/release/ directory. MUSL binaries are are about 15% slower than the GNU binaries, however, they are more portable accross different versions and distributions of linux.

Running Hayabusa

Caution: Anti-Virus/EDR Warnings and Slow Runtimes

You may receive an alert from anti-virus or EDR products when trying to run hayabusa or even just when downloading the .yml rules as there will be keywords like mimikatz and suspicious PowerShell commands in the detection signature. These are false positives so will need to configure exclusions in your security products to allow hayabusa to run. If you are worried about malware or supply chain attacks, please check the hayabusa source code and compile the binaries yourself.

You may experience slow runtime especially on the first run after a reboot due to the real-time protection of Windows Defender. You can avoid this by temporarily turning real-time protection off or adding an exclusion to the hayabusa runtime directory. (Please take into consideration the security risks before doing these.)

Windows

In a Command/PowerShell Prompt or Windows Terminal, just run the appropriate 32-bit or 64-bit Windows binary.

Error when trying to scan a file or directory with a space in the path

When using the built-in Command or PowerShell prompt in Windows, you may receive an error that Hayabusa was not able to load any .evtx files if there is a space in your file or directory path. In order to load the .evtx files properly, be sure to do the following:

  1. Enclose the file or directory path with double quotes.
  2. If it is a directory path, make sure that you do not include a backslash for the last character.

Linux

You first need to make the binary executable.

chmod +x ./hayabusa

Then run it from the Hayabusa root directory:

./hayabusa

macOS

From Terminal or iTerm2, you first need to make the binary executable.

chmod +x ./hayabusa

Then, try to run it from the Hayabusa root directory:

./hayabusa

On the latest version of macOS, you may receive the following security error when you try to run it:

Mac Error 1 EN

Click "Cancel" and then from System Preferences, open "Security & Privacy" and from the General tab, click "Allow Anyway".

Mac Error 2 EN

After that, try to run it again.

./hayabusa

The following warning will pop up, so please click "Open".

Mac Error 3 EN

You should now be able to run hayabusa.

Command List

Analysis Commands:

DFIR Timeline Commands:

General Commands:

Command Usage

Analysis Commands

computer-metrics command

You can use the computer-metrics command to check how many events there are according to each computer defined in the <System><Computer> field. Be aware that you cannot completely rely on the Computer field for separating events by their original computer. Windows 11 will sometimes use completely different Computer names when saving to event logs. Also, Windows 10 will sometimes record the Computer name in all lowercase. This command does not use any detection rules so will analyze all events. This is a good command to run to quickly see which computers have the most logs. With this information, you can then use the --include-computer or --exclude-computer options when creating your timelines to make your timeline generation more efficient by creating multiple timelines according to computer or exclude events from certain computers.

Usage: computer-metrics <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
      --timeline-offset <OFFSET>  Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)

Output:
  -o, --output <FILE>  Save the results in CSV format (ex: computer-metrics.csv)

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner
  -v, --verbose   Output verbose information

computer-metrics command examples

computer-metrics screenshot

computer-metrics screenshot

eid-metrics command

You can use the eid-metrics command to print out the total number and percentage of event IDs (<System><EventID> field) seperated by channels. This command does not use any detection rules so will scan all events.

Usage: eid-metrics <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
      --exclude-computer <COMPUTER...>  Do not scan specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --include-computer <COMPUTER...>  Scan only specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --timeline-offset <OFFSET>        Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)

Output:
  -o, --output <FILE>  Save the Metrics in CSV format (ex: metrics.csv)

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner
  -v, --verbose   Output verbose information

Time Format:
      --European-time     Output timestamp in European time format (ex: 22-02-2022 22:00:00.123 +02:00)
      --ISO-8601          Output timestamp in ISO-8601 format (ex: 2022-02-22T10:10:10.1234567Z) (Always UTC)
      --RFC-2822          Output timestamp in RFC 2822 format (ex: Fri, 22 Feb 2022 22:00:00 -0600)
      --RFC-3339          Output timestamp in RFC 3339 format (ex: 2022-02-22 22:00:00.123456-06:00)
      --US-military-time  Output timestamp in US military time format (ex: 02-22-2022 22:00:00.123 -06:00)
      --US-time           Output timestamp in US time format (ex: 02-22-2022 10:00:00.123 PM -06:00)
  -U, --UTC               Output time in UTC format (default: local time)

eid-metrics command examples

eid-metrics command config file

The channel, event IDs and titles of the events are defined in rules/config/channel_eid_info.txt.

Example:

Channel,EventID,EventTitle
Microsoft-Windows-Sysmon/Operational,1,Process Creation.
Microsoft-Windows-Sysmon/Operational,2,File Creation Timestamp Changed. (Possible Timestomping)
Microsoft-Windows-Sysmon/Operational,3,Network Connection.
Microsoft-Windows-Sysmon/Operational,4,Sysmon Service State Changed.

eid-metrics screenshot

eid-metrics screenshot

logon-summary command

You can use the logon-summary command to output logon information summary (logon usernames and successful and failed logon count). You can display the logon information for one evtx file with -f or multiple evtx files with the -d option.

Usage: logon-summary <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
      --exclude-computer <COMPUTER...>  Do not scan specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --include-computer <COMPUTER...>  Scan only specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --timeline-end <DATE>             End time of the event logs to load (ex: "2022-02-22 23:59:59 +09:00")
      --timeline-offset <OFFSET>        Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)
      --timeline-start <DATE>           Start time of the event logs to load (ex: "2020-02-22 00:00:00 +09:00")

Output:
  -o, --output <FILENAME-PREFIX>  Save the logon summary to two CSV files (ex: -o logon-summary)

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner
  -v, --verbose   Output verbose information

Time Format:
      --European-time     Output timestamp in European time format (ex: 22-02-2022 22:00:00.123 +02:00)
      --ISO-8601          Output timestamp in ISO-8601 format (ex: 2022-02-22T10:10:10.1234567Z) (Always UTC)
      --RFC-2822          Output timestamp in RFC 2822 format (ex: Fri, 22 Feb 2022 22:00:00 -0600)
      --RFC-3339          Output timestamp in RFC 3339 format (ex: 2022-02-22 22:00:00.123456-06:00)
      --US-military-time  Output timestamp in US military time format (ex: 02-22-2022 22:00:00.123 -06:00)
      --US-time           Output timestamp in US time format (ex: 02-22-2022 10:00:00.123 PM -06:00)
  -U, --UTC               Output time in UTC format (default: local time)

logon-summary command examples

logon-summary screenshots

logon-summary successful logons screenshot

logon-summary failed logons screenshot

pivot-keywords-list command

You can use the pivot-keywords-list command to create a list of unique pivot keywords to quickly identify abnormal users, hostnames, processes, etc... as well as correlate events.

Important: by default, hayabusa will return results from all events (informational and higher) so we highly recommend combining the pivot-keywords-list command with the -m, --min-level option. For example, start off with only creating keywords from critical alerts with -m critical and then continue with -m high, -m medium, etc... There will most likely be common keywords in your results that will match on many normal events, so after manually checking the results and creating a list of unique keywords in a single file, you can then create a narrowed down timeline of suspicious activity with a command like grep -f keywords.txt timeline.csv.

Usage: pivot-keywords-list <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -w, --no-wizard                      Do not ask questions. Scan for all events and alerts
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
  -E, --EID-filter                      Scan only common EIDs for faster speed (./rules/config/target_event_IDs.txt)
  -D, --enable-deprecated-rules         Enable rules with a status of deprecated
  -n, --enable-noisy-rules              Enable rules set to noisy (./rules/config/noisy_rules.txt)
  -u, --enable-unsupported-rules        Enable rules with a status of unsupported
  -e, --exact-level <LEVEL>             Only load rules with a specific level (informational, low, medium, high, critical)
      --exclude-computer <COMPUTER...>  Do not scan specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --exclude-eid <EID...>            Do not scan specific EIDs for faster speed (ex: 1) (ex: 1,4688)
      --exclude-status <STATUS...>      Do not load rules according to status (ex: experimental) (ex: stable,test)
      --exclude-tag <TAG...>            Do not load rules with specific tags (ex: sysmon)
      --include-computer <COMPUTER...>  Scan only specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --include-eid <EID...>            Scan only specified EIDs for faster speed (ex: 1) (ex: 1,4688)
      --include-status <STATUS...>      Only load rules with specific status (ex: experimental) (ex: stable,test)
      --include-tag <TAG...>            Only load rules with specific tags (ex: attack.execution,attack.discovery)
  -m, --min-level <LEVEL>               Minimum level for rules to load (default: informational)
      --timeline-end <DATE>             End time of the event logs to load (ex: "2022-02-22 23:59:59 +09:00")
      --timeline-offset <OFFSET>        Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)
      --timeline-start <DATE>           Start time of the event logs to load (ex: "2020-02-22 00:00:00 +09:00")

Output:
  -o, --output <FILENAME-PREFIX>  Save pivot words to separate files (ex: PivotKeywords)

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner
  -v, --verbose   Output verbose information

pivot-keywords-list command examples

hayabusa.exe pivot-keywords-list -d ../logs -m critical -o keywords`

pivot-keywords-list config file

You can customize what keywords you want to search for by editing ./rules/config/pivot_keywords.txt. This page is the default setting.

The format is KeywordName.FieldName. For example, when creating the list of Users, hayabusa will list up all the values in the SubjectUserName, TargetUserName and User fields.

search command

The search command will let you keyword search on all events. (Not just Hayabusa detection results.) This is useful to determine if there is any evidence in events that are not detected by Hayabusa.

Usage: hayabusa.exe search <INPUT> <--keywords "<KEYWORDS>" OR --regex "<REGEX>"> [OPTIONS]

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner
  -v, --verbose   Output verbose information

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

Filtering:
  -a, --and-logic                 Search keywords with AND logic (default: OR)
  -F, --filter <FILTER...>        Filter by specific field(s)
  -i, --ignore-case               Case-insensitive keyword search
  -k, --keyword <KEYWORD...>      Search by keyword(s)
  -r, --regex <REGEX>             Search by regular expression
      --timeline-offset <OFFSET>  Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)

Output:
  -J, --JSON-output    Save the search results in JSON format (ex: -J -o results.json)
  -L, --JSONL-output   Save the search results in JSONL format (ex: -L -o results.jsonl)
  -M, --multiline      Output event field information in multiple rows for CSV output
  -o, --output <FILE>  Save the search results in CSV format (ex: search.csv)

Time Format:
      --European-time     Output timestamp in European time format (ex: 22-02-2022 22:00:00.123 +02:00)
      --ISO-8601          Output timestamp in ISO-8601 format (ex: 2022-02-22T10:10:10.1234567Z) (Always UTC)
      --RFC-2822          Output timestamp in RFC 2822 format (ex: Fri, 22 Feb 2022 22:00:00 -0600)
      --RFC-3339          Output timestamp in RFC 3339 format (ex: 2022-02-22 22:00:00.123456-06:00)
      --US-military-time  Output timestamp in US military time format (ex: 02-22-2022 22:00:00.123 -06:00)
      --US-time           Output timestamp in US time format (ex: 02-22-2022 10:00:00.123 PM -06:00)
  -U, --UTC               Output time in UTC format (default: local time)

search command examples

hayabusa.exe search -d ../hayabusa-sample-evtx -k "mimikatz"

Note: The keyword will match if mimikatz is found anywhere in the data. It is not an exact match.

hayabusa.exe search -d ../hayabusa-sample-evtx -k "mimikatz" -k "kali"

hayabusa.exe search -d ../hayabusa-sample-evtx -k "mimikatz" -i

hayabusa.exe search -d ../hayabusa-sample-evtx -r "(?:[0-9]{1,3}\.){3}[0-9]{1,3}"

hayabusa.exe search -d ../hayabusa-sample-evtx -r ".*" -F WorkstationName:"kali"

Note: .* is the regular expression to match on every event.

search command config files

./rules/config/channel_abbreviations.txt: Mappings of channel names and their abbreviations.

DFIR Timeline Commands

Scan Wizard

The csv-timeline and json-timeline commands now have a scan wizard enabled by default. This is intended to help users easily choose which detection rules they want to enable according to their needs and preferences. The sets of detections rules to load are based off of the official lists in the Sigma project. Details are explained in this blog post. You can easily turn off the wizard and use Hayabusa in its traditional way by adding the -w, --no-wizard option.

Core Rules

The core rule set enables rules that have a status of test or stable and a level of high or critical. These are high quality rules of high confidence and relevance and should not produce many false positives. The rule status is test or stable which means no false positives were reported for over 6 months. Rules will match on attacker techniques, generic suspicious activity, or malicious behavior. It is the same as using the --exclude-status deprecated,unsupported,experimental --min-level high options.

Core+ Rules

The core+ rule set enables rules that have a status of test or stable and a level of medium or higher. medium rules most often need additional tuning as certain applications, legitimate user behavior or scripts of an organization might be matched. It is the same as using the --exclude-status deprecated,unsupported,experimental --min-level medium options.

Core++ Rules

The core++ rule set enables rules that have a status of experimental, test or stable and a level of medium or higher. These rules are bleeding edge. They are validated against the baseline evtx files available at the SigmaHQ project and reviewed by multiple detection engineers. Other than that they are pretty much untested at first. Use these if you want to be able to detect threats as early as possible at the cost of managing a higher threshold of false positives. It is the same as using the --exclude-status deprecated,unsupported --min-level medium options.

Emerging Threats (ET) Add-On Rules

The Emerging Threats (ET) rule set enables rules that have a tag of detection.emerging_threats. These rules target specific threats and are especially useful for current threats where not much information is available yet. These rules should not have many false positives but will decrease in relevance over time. When these rules are not enabled, it is the same as using the --exclude-tag detection.emerging_threats option. When running Hayabusa traditionally without the wizard, these rules will be included by default.

Threat Hunting (TH) Add-On Rules

The Threat Hunting (TH) rule set enables rules that have a tag of detection.threat_hunting. These rules may detect unknown malicious activity, however, will typicially have more false positives. When these rules are not enabled, it is the same as using the --exclude-tag detection.threat_hunting option. When running Hayabusa traditionally without the wizard, these rules will be included by default.

Channel-based event log and rules filtering

As of Hayabusa v2.16.0, we enable a Channel-based filter when loading .evtx files and .yml rules. The purpose is to make scanning as efficient as possible by only loading what is necessary. While it possible for there to be multiple providers in a single event log, it is not common to have multiple channels inside a single evtx file. (The only time we have seen this is when someone has artifically merged two different evtx files together for the sample-evtx project.) We can use this to our advantage by first checking the Channel field in the first record of every .evtx file specified to be scanned. We also check which .yml rules use what channels specified in the Channel field of the rule. With these two lists, we only load rules that use channels that are actually present inside the .evtx files.

So for example, if a user wants to scan Security.evtx, only rules that specify Channel: Security will be used. There is no point in loading other detection rules, for example rules that only look for events in the Application log, etc... Note that channel fields (Ex: Channel: Security) are not explicitly defined inside original Sigma rules. For Sigma rules, channel and event IDs fields are implicitly defined with service and category fields under logsource. (Ex: service: security) When curating Sigma rules in the hayabusa-rules repository, we de-abstract the logsource field and explicitly define the channel and event ID fields. We explain how and why we do this in-depth here.

Currently, there are only two detection rules that do not have Channel defined and are intended to scan all .evtx files are the following:

If you want to use these two rules and scan all rules against loaded .evtx files then you will need to add the -A, --enable-all-rules option in the csv-timeline and json-timeline commands. In our benchmarks, the rules filtering usually gives a 20% to 10x speed improvement depending on what files are being scanned and of course uses less memory.

Channel filtering is also used when loading .evtx files. For example, if you specify a rule that looks for events with a channel of Security, then there is no point in loading .evtx files that are not from the Security log. In our benchmarks, this gives a speed benefit of around 10% with normal scans and up to 60%+ performance increase when scanning with a single rule. If you are sure that multiple channels are being used inside a single .evtx file, for example someone used a tool to merge multiple .evtx files together, then you disable this filtering with the -a, --scan-all-evtx-files option in csv-timeline and json-timeline commands.

Note: Channel filtering only works with .evtx files and you will receive an error if you try to load event logs from a JSON file with -J, --json-input and also specify -A or -a.

csv-timeline command

The csv-timeline command will create a forensics timeline of events in CSV format.

Usage: csv-timeline <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -s, --sort-events                    Sort events before saving the file. (warning: this uses much more memory!)
  -w, --no-wizard                      Do not ask questions. Scan for all events and alerts
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -r, --rules <DIR/FILE>               Specify a custom rule directory or file (default: ./rules)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
  -E, --EID-filter                      Scan only common EIDs for faster speed (./rules/config/target_event_IDs.txt)
  -D, --enable-deprecated-rules         Enable rules with a status of deprecated
  -n, --enable-noisy-rules              Enable rules set to noisy (./rules/config/noisy_rules.txt)
  -u, --enable-unsupported-rules        Enable rules with a status of unsupported
  -e, --exact-level <LEVEL>             Only load rules with a specific level (informational, low, medium, high, critical)
      --exclude-category <CATEGORY...>  Do not load rules with specified logsource categories (ex: process_creation,pipe_created)
      --exclude-computer <COMPUTER...>  Do not scan specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --exclude-eid <EID...>            Do not scan specific EIDs for faster speed (ex: 1) (ex: 1,4688)
      --exclude-status <STATUS...>      Do not load rules according to status (ex: experimental) (ex: stable,test)
      --exclude-tag <TAG...>            Do not load rules with specific tags (ex: sysmon)
      --include-category <CATEGORY...>  Only load rules with specified logsource categories (ex: process_creation,pipe_created)
      --include-computer <COMPUTER...>  Scan only specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --include-eid <EID...>            Scan only specified EIDs for faster speed (ex: 1) (ex: 1,4688)
      --include-status <STATUS...>      Only load rules with specific status (ex: experimental) (ex: stable,test)
      --include-tag <TAG...>            Only load rules with specific tags (ex: attack.execution,attack.discovery)
  -m, --min-level <LEVEL>               Minimum level for rules to load (default: informational)
  -P, --proven-rules                    Scan with only proven rules for faster speed (./rules/config/proven_rules.txt)
      --timeline-end <DATE>             End time of the event logs to load (ex: "2022-02-22 23:59:59 +09:00")
      --timeline-offset <OFFSET>        Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)
      --timeline-start <DATE>           Start time of the event logs to load (ex: "2020-02-22 00:00:00 +09:00")

Output:
  -G, --GeoIP <MAXMIND-DB-DIR>       Add GeoIP (ASN, city, country) info to IP addresses
  -H, --HTML-report <FILE>           Save Results Summary details to an HTML report (ex: results.html)
  -M, --multiline                    Output event field information in multiple rows
  -F, --no-field-data-mapping        Disable field data mapping
      --no-pwsh-field-extraction     Disable field extraction of PowerShell classic logs
  -o, --output <FILE>                Save the timeline in CSV format (ex: results.csv)
  -p, --profile <PROFILE>            Specify output profile
  -R, --remove-duplicate-data        Duplicate field data will be replaced with "DUP"
  -X, --remove-duplicate-detections  Remove duplicate detections (default: disabled)

Display Settings:
      --no-color            Disable color output
  -N, --no-summary          Do not display Results Summary for faster speed
  -q, --quiet               Quiet mode: do not display the launch banner
  -v, --verbose             Output verbose information
  -T, --visualize-timeline  Output event frequency timeline (terminal needs to support unicode)

Time Format:
      --European-time     Output timestamp in European time format (ex: 22-02-2022 22:00:00.123 +02:00)
      --ISO-8601          Output timestamp in ISO-8601 format (ex: 2022-02-22T10:10:10.1234567Z) (Always UTC)
      --RFC-2822          Output timestamp in RFC 2822 format (ex: Fri, 22 Feb 2022 22:00:00 -0600)
      --RFC-3339          Output timestamp in RFC 3339 format (ex: 2022-02-22 22:00:00.123456-06:00)
      --US-military-time  Output timestamp in US military time format (ex: 02-22-2022 22:00:00.123 -06:00)
      --US-time           Output timestamp in US time format (ex: 02-22-2022 10:00:00.123 PM -06:00)
  -U, --UTC               Output time in UTC format (default: local time)

csv-timeline command examples

hayabusa.exe csv-timeline -f eventlog.evtx

hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -p verbose

hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -o results.csv -p super-verbose

Note: Enabling the EID filter will speed up the analysis by about 10-15% in our tests but there is a possibility of missing alerts.

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

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

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

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

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

Note: Recently, deprecated rules are now located in a separate directory in the sigma repository so are not included by default anymore in Hayabusa. Therefore, you probably have no need to enable deprecated rules.

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

hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\hayabusa\builtin\Security\LogonLogoff\Logon -U -o results.csv -w

hayabusa.exe csv-timeline -l -m low

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

Loading rules:

Loaded rule: rules/sigma/builtin/deprecated/proc_creation_win_susp_run_folder.yml
Loaded rule: rules/sigma/builtin/deprecated/proc_creation_win_execution_mssql_xp_cmdshell_stored_procedure.yml
Loaded rule: rules/sigma/builtin/deprecated/proc_creation_win_susp_squirrel_lolbin.yml
Loaded rule: rules/sigma/builtin/win_alert_mimikatz_keywords.yml

Errors during the scan:

[ERROR] Failed to parse event file.
EventFile: ../logs/Microsoft-Rdms-UI%4Operational.evtx
Error: Failed to parse record number 58471

[ERROR] Failed to parse event file.
EventFile: ../logs/Microsoft-Rdms-UI%4Operational.evtx
Error: Failed to parse record number 58470

[ERROR] Failed to parse event file.
EventFile: ../logs/Microsoft-Windows-AppxPackaging%4Operational.evtx
Error: An error occurred while trying to serialize binary xml to output.

hayabusa.exe csv-timeline -d ../hayabusa-sample-evtx --RFC-3339 -o timesketch-import.csv -p timesketch -U

Advanced - GeoIP Log Enrichment

You can add GeoIP (ASN organization, city and country) information to SrcIP (source IP) fields and TgtIP (target IP) fields with the free GeoLite2 geolocation data.

Steps:

  1. First sign up for a MaxMind account here.
  2. Download the three .mmdb files from the download page and save them to a directory. The filenames should be called GeoLite2-ASN.mmdb, GeoLite2-City.mmdb and GeoLite2-Country.mmdb.
  3. When running the csv-timeline or json-timeline commands, add the -G option followed by the directory with the MaxMind databases.
GeoIP config file

The field names that contain source and target IP addresses that get looked up in the GeoIP databases are defined in rules/config/geoip_field_mapping.yaml. You can add to this list if necessary. There is also a filter section in this file that determines what events to extract IP address information from.

Automatic updates of GeoIP databases

MaxMind GeoIP databases are updated every 2 weeks. You can install the MaxMind geoipupdate tool here in order to automatically update these databases.

Steps on macOS:

  1. brew install geoipupdate
  2. Edit /usr/local/etc/GeoIP.conf: Put in your AccountID and LicenseKey you create after logging into the MaxMind website. Make sure the EditionIDs line says EditionIDs GeoLite2-ASN GeoLite2-City GeoLite2-Country.
  3. Run geoipupdate.
  4. Add -G /usr/local/var/GeoIP when you want to add GeoIP information.

Steps on Windows:

  1. Download the latest Windows binary (Ex: geoipupdate_4.10.0_windows_amd64.zip) from the Releases page.
  2. Edit \ProgramData\MaxMind/GeoIPUpdate\GeoIP.conf: Put in your AccountID and LicenseKey you create after logging into the MaxMind website. Make sure the EditionIDs line says EditionIDs GeoLite2-ASN GeoLite2-City GeoLite2-Country.
  3. Run the geoipupdate executable.

csv-timeline command config files

./rules/config/channel_abbreviations.txt: Mappings of channel names and their abbreviations.

./rules/config/default_details.txt: The configuration file for what default field information (%Details% field) should be outputted if no details: line is specified in a rule. This is based on provider name and event IDs.

./rules/config/eventkey_alias.txt: This file has the mappings of short name aliases for fields and their original longer field names.

Example:

InstanceID,Event.UserData.UMDFHostDeviceArrivalBegin.InstanceId
IntegrityLevel,Event.EventData.IntegrityLevel
IpAddress,Event.EventData.IpAddress

If a field is not defined here, Hayabusa will automatically check under Event.EventData for the field.

./rules/config/exclude_rules.txt: This file has a list of rule IDs that will be excluded from use. Usually this is because one rule has replaced another or the rule cannot be used in the first place. 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 ./rules/config/exclude_rules.txt in order to ignore any rule that you do not need or cannot be used.

./rules/config/noisy_rules.txt: This file a list of rule IDs that are disabled by default but can be enabled by enabling noisy rules with the -n, --enable-noisy-rules option. These rules are usually noisy by nature or due to false positives.

./rules/config/target_event_IDs.txt: Only the event IDs specified in this file will be scanned if the EID filter is enabled. By default, Hayabusa will scan all events, but if you want to improve performance, please use the -E, --EID-filter option. This usually results in a 10~25% speed improvement.

json-timeline command

The json-timeline command will create a forensics timeline of events in JSON or JSONL format. Outputting to JSONL will be faster and smaller file size than JSON so is good if you are going to just import the results into another tool like Elastic Stack. JSON is better if you are going to manually analyze the results with a text editor. CSV output is good for importing smaller timelines (usually less than 2GB) into tools like LibreOffice or Timeline Explorer. JSON is best for more detailed analysis of data (including large results files) with tools like jq as the Details fields are separated for easier analysis. (In the CSV output, all of the event log fields are in one big Details column making sorting of data, etc... more difficult.)

Usage: json-timeline <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple .evtx files
  -f, --file <FILE>      File path to one .evtx file
  -l, --live-analysis    Analyze the local C:\Windows\System32\winevt\Logs folder

General Options:
  -C, --clobber                        Overwrite files when saving
  -h, --help                           Show the help menu
  -J, --JSON-input                     Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -s, --sort-events                    Sort events before saving the file. (warning: this uses much more memory!)
  -w, --no-wizard                      Do not ask questions. Scan for all events and alerts
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -x, --recover-records                Carve evtx records from slack space (default: disabled)
  -r, --rules <DIR/FILE>               Specify a custom rule directory or file (default: ./rules)
  -c, --rules-config <DIR>             Specify custom rule config directory (default: ./rules/config)
      --target-file-ext <FILE-EXT...>  Specify additional evtx file extensions (ex: evtx_data)
  -t, --threads <NUMBER>               Number of threads (default: optimal number for performance)

Filtering:
  -E, --EID-filter                      Scan only common EIDs for faster speed (./rules/config/target_event_IDs.txt)
  -D, --enable-deprecated-rules         Enable rules with a status of deprecated
  -n, --enable-noisy-rules              Enable rules set to noisy (./rules/config/noisy_rules.txt)
  -u, --enable-unsupported-rules        Enable rules with a status of unsupported
  -e, --exact-level <LEVEL>             Only load rules with a specific level (informational, low, medium, high, critical)
      --exclude-category <CATEGORY...>  Do not load rules with specified logsource categories (ex: process_creation,pipe_created)
      --exclude-computer <COMPUTER...>  Do not scan specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --exclude-eid <EID...>            Do not scan specific EIDs for faster speed (ex: 1) (ex: 1,4688)
      --exclude-status <STATUS...>      Do not load rules according to status (ex: experimental) (ex: stable,test)
      --exclude-tag <TAG...>            Do not load rules with specific tags (ex: sysmon)
      --include-category <CATEGORY...>  Only load rules with specified logsource categories (ex: process_creation,pipe_created)
      --include-computer <COMPUTER...>  Scan only specified computer names (ex: ComputerA) (ex: ComputerA,ComputerB)
      --include-eid <EID...>            Scan only specified EIDs for faster speed (ex: 1) (ex: 1,4688)
      --include-status <STATUS...>      Only load rules with specific status (ex: experimental) (ex: stable,test)
      --include-tag <TAG...>            Only load rules with specific tags (ex: attack.execution,attack.discovery)
  -m, --min-level <LEVEL>               Minimum level for rules to load (default: informational)
  -P, --proven-rules                    Scan with only proven rules for faster speed (./rules/config/proven_rules.txt)
      --timeline-end <DATE>             End time of the event logs to load (ex: "2022-02-22 23:59:59 +09:00")
      --timeline-offset <OFFSET>        Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)
      --timeline-start <DATE>           Start time of the event logs to load (ex: "2020-02-22 00:00:00 +09:00")

Output:
  -G, --GeoIP <MAXMIND-DB-DIR>       Add GeoIP (ASN, city, country) info to IP addresses
  -H, --HTML-report <FILE>           Save Results Summary details to an HTML report (ex: results.html)
  -L, --JSONL-output                 Save the timeline in JSONL format (ex: -L -o results.jsonl)
  -F, --no-field-data-mapping        Disable field data mapping
      --no-pwsh-field-extraction     Disable field extraction of PowerShell classic logs
  -o, --output <FILE>                Save the timeline in JSON format (ex: results.json)
  -p, --profile <PROFILE>            Specify output profile
  -R, --remove-duplicate-data        Duplicate field data will be replaced with "DUP"
  -X, --remove-duplicate-detections  Remove duplicate detections (default: disabled)

Display Settings:
      --no-color            Disable color output
  -N, --no-summary          Do not display Results Summary for faster speed
  -q, --quiet               Quiet mode: do not display the launch banner
  -v, --verbose             Output verbose information
  -T, --visualize-timeline  Output event frequency timeline (terminal needs to support unicode)

Time Format:
      --European-time     Output timestamp in European time format (ex: 22-02-2022 22:00:00.123 +02:00)
      --ISO-8601          Output timestamp in ISO-8601 format (ex: 2022-02-22T10:10:10.1234567Z) (Always UTC)
      --RFC-2822          Output timestamp in RFC 2822 format (ex: Fri, 22 Feb 2022 22:00:00 -0600)
      --RFC-3339          Output timestamp in RFC 3339 format (ex: 2022-02-22 22:00:00.123456-06:00)
      --US-military-time  Output timestamp in US military time format (ex: 02-22-2022 22:00:00.123 -06:00)
      --US-time           Output timestamp in US time format (ex: 02-22-2022 10:00:00.123 PM -06:00)
  -U, --UTC               Output time in UTC format (default: local time)

json-timeline command examples and config files

The options and config files for json-timeline are the same as csv-timeline but one extra option -L, --JSONL-output for outputting to JSONL format.

level-tuning command

The level-tuning command will let you tune the alert levels for rules, either raising or decreasing the risk level according to your environment.

Usage: level-tuning [OPTIONS]

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

General Options:
  -f, --file <FILE>  Tune alert levels (default: ./rules/config/level_tuning.txt)

level-tuning command examples

level-tuning config file

Hayabusa and Sigma rule authors will determine the risk level of the alert when writing their rules. However, the actual risk level may differ according to the environment. You can tune the risk level of the rules by adding them to ./rules/config/level_tuning.txt and executing hayabusa.exe level-tuning which will update the level line in the rule file. Please note that the rule file will be updated directly.

Warning: Anytime you run update-rules, the original alert level will overwrite any settings you have changed, so you will need to run the level-tuning command after every time you run update-rules if you want to change the levels.

./rules/config/level_tuning.txt sample line:

id,new_level
00000000-0000-0000-0000-000000000000,informational # sample level tuning line

In this case, the risk level of the rule with an id of 00000000-0000-0000-0000-000000000000 in the rules directory will have its level rewritten to informational. The possible levels to set are critical, high, medium, low and informational.

list-profiles command

Usage: list-profiles [OPTIONS]

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

set-default-profile command

Usage: set-default-profile [OPTIONS]

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

General Options:
  -p, --profile <PROFILE>  Specify output profile

set-default-profile command examples

update-rules command

The update-rules command will sync the rules folder with the Hayabusa rules github repository, updating the rules and config files.

Usage: update-rules [OPTIONS]

Display Settings:
      --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

General Options:
  -r, --rules <DIR/FILE>  Specify a custom rule directory or file (default: ./rules)

update-rules command example

You will normally just execute this: hayabusa.exe update-rules

Timeline Output

Output Profiles

Hayabusa has 5 pre-defined output profiles to use in config/profiles.yaml:

  1. minimal
  2. standard (default)
  3. verbose
  4. all-field-info
  5. all-field-info-verbose
  6. super-verbose
  7. timesketch-minimal
  8. timesketch-verbose

You can easily customize or add your own profiles by editing this file. You can also easily change the default profile with set-default-profile --profile <profile>. Use the list-profiles command to show the available profiles and their field information.

1. minimal profile output

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %RecordID%, %RuleTitle%, %Details%

2. standard profile output

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %RecordID%, %RuleTitle%, %Details%, %ExtraFieldInfo%

3. verbose profile output

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %MitreTactics%, %MitreTags%, %OtherTags%, %RecordID%, %RuleTitle%, %Details%, %ExtraFieldInfo%, %RuleFile%, %EvtxFile%

4. all-field-info profile output

Instead of outputting the minimal details information, all field information in the EventData and UserData sections will be outputted along with their original field names.

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %RecordID%, %RuleTitle%, %AllFieldInfo%, %RuleFile%, %EvtxFile%

5. all-field-info-verbose profile output

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %MitreTactics%, %MitreTags%, %OtherTags%, %RecordID%, %RuleTitle%, %AllFieldInfo%, %RuleFile%, %EvtxFile%

6. super-verbose profile output

%Timestamp%, %Computer%, %Channel%, %EventID%, %Level%, %RuleTitle%, %RuleAuthor%, %RuleModifiedDate%, %Status%, %RecordID%, %Details%, %ExtraFieldInfo%, %MitreTactics%, %MitreTags%, %OtherTags%, %Provider%, %RuleCreationDate%, %RuleFile%, %EvtxFile%

7. timesketch-minimal profile output

Output to a format compatible with importing into Timesketch.

%Timestamp%, hayabusa, %RuleTitle%, %Computer%, %Channel%, %EventID%, %Level%, %MitreTactics%, %MitreTags%, %OtherTags%, %RecordID%, %Details%, %RuleFile%, %EvtxFile%

8. timesketch-verbose profile output

%Timestamp%, hayabusa, %RuleTitle%, %Computer%, %Channel%, %EventID%, %Level%, %MitreTactics%, %MitreTags%, %OtherTags%, %RecordID%, %Details%, %ExtraFieldInfo%, %RuleFile%, %EvtxFile%

Profile Comparison

The following benchmarks were conducted on a 2018 Lenovo P51 (Xeon 4 Core CPU / 64GB RAM) with 3GB of evtx data and 3891 rules enabled. (2023/06/01)

ProfileProcessing TimeOutput FilesizeFilesize Increase
minimal8 minutes 50 seconds770 MB-30%
standard (default)9 minutes 00 seconds1.1 GBNone
verbose9 minutes 10 seconds1.3 GB+20%
all-field-info9 minutes 3 seconds1.2 GB+10%
all-field-info-verbose9 minutes 10 seconds1.3 GB+20%
super-verbose9 minutes 12 seconds1.5 GB+35%

Profile Field Aliases

The following information can be outputted with built-in output profiles:

Alias nameHayabusa output information
%AllFieldInfo%All field information.
%Channel%The name of log. <Event><System><Channel> field.
%Computer%The <Event><System><Computer> field.
%Details%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 fields in event logs. For example, usernames, command line information, process information, etc... When a placeholder points to a field that does not exist or there is an incorrect alias mapping, it will be outputted as n/a (not available). If the details field is not specified (i.e. sigma rules), default details messages to extract fields defined in ./rules/config/default_details.txt will be outputted. You can add more default details messages by adding the Provider Name, EventID and details message you want to output in default_details.txt. When no details field is defined in a rule nor in default_details.txt, all fields will be outputted to the details column.
%ExtraFieldInfo%Print the field information that was not outputted in %Details%.
%EventID%The <Event><System><EventID> field.
%EvtxFile%The evtx filename that caused the alert or event.
%Level%The level field in the YML detection rule. (informational, low, medium, high, critical)
%MitreTactics%MITRE ATT&CK tactics (Ex: Initial Access, Lateral Movement, etc...).
%MitreTags%MITRE ATT&CK Group ID, Technique ID and Software ID.
%OtherTags%Any keyword in the tags field in a YML detection rule which is not included in MitreTactics or MitreTags.
%Provider%The Name attribute in <Event><System><Provider> field.
%RecordID%The Event Record ID from <Event><System><EventRecordID> field.
%RuleAuthor%The author field in the YML detection rule.
%RuleCreationDate%The date field in the YML detection rule.
%RuleFile%The filename of the detection rule that generated the alert or event.
%RuleModifiedDate%The modified field in the YML detection rule.
%RuleTitle%The title field in the YML detection rule.
%Status%The status field in the YML detection rule.
%Timestamp%Default is YYYY-MM-DD HH:mm:ss.sss +hh:mm format. <Event><System><TimeCreated SystemTime> 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.

Extra Profile Field Aliases

You can also add these extra aliases to your output profile if you need them:

Alias nameHayabusa output information
%RenderedMessage%The <Event><RenderingInfo><Message> field in WEC forwarded logs.
%RuleID%The id field in the YML detection rule.

Note: these are not included in any built in profiles so you will need to manually edit the config/default_profile.yaml file and add the following lines:

Message: "%RenderedMessage%"
RuleID: "%RuleID%"

You can also define event key aliases to output other fields.

Level Abbrevations

In order to save space, we use the following abbrevations when displaying the alert level.

MITRE ATT&CK Tactics Abbreviations

In order to save space, we use the following abbreviations when displaying MITRE ATT&CK tactic tags. You can freely edit these abbreviations in the ./config/mitre_tactics.txt configuration file.

Channel Abbreviations

In order to save space, we use the following abbreviations when displaying Channel. You can freely edit these abbreviations in the ./rules/config/channel_abbreviations.txt configuration file.

Other Abbreviations

The following abbreviations are used in rules in order to make the output as concise as possible:

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.

Color Output

The alerts will be outputted in color based on the alert level. You can change the default colors in the config file at ./config/level_color.txt in the format of level,(RGB 6-digit ColorHex). If you want to disable color output, you can use --no-color option.

Results Summary

Total events, the number of events with hits, data reduction metrics, total and unique detections, dates with the most detections, top computers with detections and top alerts are displayed after every scan.

Detection Fequency Timeline

If you add the -T, --visualize-timeline option, the Event Frequency Timeline feature displays a sparkline frequency timeline of detected events. Note: There needs to be more than 5 events. Also, the characters will not render correctly on the default Command Prompt or PowerShell Prompt, so please use a terminal like Windows Terminal, iTerm2, etc...

Hayabusa Rules

Hayabusa detection rules are written in a sigma-like YML format and are located in the rules folder. The rules are hosted at https://github.com/Yamato-Security/hayabusa-rules so please send any issues and pull requests for rules there instead of the main Hayabusa repository.

Please read the hayabusa-rules repository README to understand about the rule format and how to create rules.

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 2 directories:

Rules are further seperated into directories by log type (Example: Security, System, etc...) and are named in the following format:

Please check out the current rules to use as a template in creating new ones or for checking the detection logic.

Sigma v.s. Hayabusa (Built-in Sigma Compatible) Rules

Hayabusa supports Sigma rules natively with a single exception of handling the logsource fields internally. In order to reduce false positives, , Sigma rules should be run through our convertor explained here. This will add the proper Channel and EventID, and perform field mapping for certain categories like process_creation.

Almost all Hayabusa rules are compatible with the Sigma format so you can use them just like Sigma rules to convert to other SIEM formats. Hayabusa rules are designed solely for Windows event log analysis and have the following benefits:

  1. An extra details field to display additional information taken from only the useful fields in the log.
  2. They are all tested against sample logs and are known to work.
  3. Extra aggregators not found in sigma, such as |equalsfield and |endswithfield.

To our knowledge, hayabusa provides the greatest native support for sigma rules out of any open source Windows event log analysis tool.

Other Windows Event Log Analyzers and Related Resources

Windows Logging Recommendations

In order to properly detect malicious activity on Windows machines, you will need to improve the default log settings. We have created a seperate project to document what log settings need to be enabled as well as scripts to automatically enable the proper settings at https://github.com/Yamato-Security/EnableWindowsLogSettings.

We also recommend the following sites for guidance:

Sysmon Related Projects

To create the most forensic evidence and detect with the highest accuracy, you need to install sysmon. We recommend the following sites and config files:

Community Documentation

English

Japanese

Contribution

We would love any form of contribution. Pull requests, rule creation and sample evtx logs are the best but feature requests, notifying us of bugs, etc... are also very welcome.

At the least, if you like our tool then please give us a star on GitHub and show your support!

Bug Submission

Please submit any bugs you find here. This project is currently actively maintained and we are happy to fix any bugs reported.

If you find any issues (false positives, bugs, etc...) with Hayabusa rules, please report them to the hayabusa-rules GitHub issues page here.

If you find any issues (false positives, bugs, etc...) with Sigma rules, please report them to the upstream SigmaHQ GitHub issues page here.

License

Hayabusa is released under AGPLv3 and all rules are released under the Detection Rule License (DRL) 1.1.

Hayabusa uses GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

Twitter

You can recieve the latest news about Hayabusa, rule updates, other Yamato Security tools, etc... by following us on Twitter at @SecurityYamato.