Skip to content

Usage Examples

Jump to bottom
Zach Mathis (田中ザック) edited this page Feb 3, 2024 · 2 revisions

Analysis Commands

computer-metrics command

You can use the computer-metrics command to print out the total number and percentage of Event IDs seperated by Channels.

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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

General Options:
  -C, --clobber                        Overwrite files when saving
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

computer-metrics command examples

  • Print computer name metrics from a directory: hayabusa.exe computer-metrics -d ../logs
  • Save results to a CSV file: hayabusa.exe computer-metrics -d ../logs -o computer-metrics.csv

eid-metrics command

You can use the eid-metrics command to print out the total number and percentage of Event IDs seperated by Channels.

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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

General Options:
  -C, --clobber                        Overwrite files when saving
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

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

  • Print Event ID metrics from a single file: hayabusa.exe eid-metrics -f Security.evtx
  • Print Event ID metrics from a directory: hayabusa.exe eid-metrics -d ../logs
  • Save results to a CSV file: hayabusa.exe eid-metrics -f Security.evtx -o eid-metrics.csv

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.

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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

General Options:
  -C, --clobber                        Overwrite files when saving
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

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

  • Print logon summary: hayabusa.exe logon-summary -f Security.evtx
  • Save logon summary results: hayabusa.exe logon-summary -d ../logs -o logon-summary.csv

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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-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

General Options:
  -C, --clobber                        Overwrite files when saving
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

pivot-keywords-list command examples

  • Output pivot keywords to screen: hayabusa.exe pivot-keywords-list -d ../logs -m critical
  • Create a list of pivot keywords from critical alerts and save the results. (Results will be saved to keywords-Ip Addresses.txt, keywords-Users.txt, etc...):
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

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
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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)

General Options:
  -C, --clobber                        Overwrite files when saving
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

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

  • Search the ../hayabusa-sample-evtx directory for the keyword mimikatz:
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.

  • Search the ../hayabusa-sample-evtx directory for the keywords mimikatz or kali:
hayabusa.exe search -d ../hayabusa-sample-evtx -k "mimikatz" -k "kali"
  • Search the ../hayabusa-sample-evtx directory for the keyword mimikatz and ignore case:
hayabusa.exe search -d ../hayabusa-sample-evtx -k "mimikatz" -i
  • Search the ../hayabusa-sample-evtx directory for IP addresses using regular expressions:
hayabusa.exe search -d ../hayabusa-sample-evtx -r "(?:[0-9]{1,3}\.){3}[0-9]{1,3}"
  • Search the ../hayabusa-sample-evtx directory and show all events where the WorkstationName field is kali:
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

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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-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)

General Options:
  -C, --clobber                        Overwrite files when saving
  -w, --no-wizard                      Do not ask questions. Scan for all events and alerts
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

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

  • Run hayabusa against one Windows event log file with default standard profile:
hayabusa.exe csv-timeline -f eventlog.evtx
  • Run hayabusa against the sample-evtx directory with multiple Windows event log files with the verbose profile:
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -p verbose
  • Export to a single CSV file for further analysis with LibreOffice, Timeline Explorer, Elastic Stack, etc... and include all field information (Warning: your file output size will become much larger with the super-verbose profile!):
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -o results.csv -p super-verbose
  • Enable the EID (Event ID) filter:

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
  • Only run hayabusa rules (the default is to run all the rules in -r .\rules):
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\hayabusa -o results.csv -w
  • Only run hayabusa rules for logs that are enabled by default on Windows:
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\hayabusa\builtin -o results.csv -w
  • Only run hayabusa rules for sysmon logs:
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\hayabusa\sysmon -o results.csv -w
  • Only run sigma rules:
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\sigma -o results.csv -w
  • Enable deprecated rules (those with status marked as deprecated) and noisy rules (those whose rule ID is listed in .\rules\config\noisy_rules.txt):

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
  • Only run rules to analyze logons and output in the UTC timezone:
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -r .\rules\hayabusa\builtin\Security\LogonLogoff\Logon -U -o results.csv -w
  • Run on a live Windows machine (requires Administrator privileges) and only detect alerts (potentially malicious behavior):
hayabusa.exe csv-timeline -l -m low
  • Print verbose information (useful for determining which files take long to process, parsing errors, etc...):
hayabusa.exe csv-timeline -d .\hayabusa-sample-evtx -v
  • Verbose output example:

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.
  • Output to a CSV format compatible to import into Timesketch:
hayabusa.exe csv-timeline -d ../hayabusa-sample-evtx --RFC-3339 -o timesketch-import.csv -p timesketch -U
  • 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.

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.

  • When csv-timeline is used, the following 6 columns will be additionally outputted: SrcASN, SrcCity, SrcCountry, TgtASN, TgtCity, TgtCountry.

  • When json-timeline is used, the same SrcASN, SrcCity, SrcCountry, TgtASN, TgtCity, TgtCountry fields will be added to the Details object, but only if they contain information.

  • When SrcIP or TgtIP is localhost (127.0.0.1, ::1, etc...), SrcASN or TgtASN will be outputted as Local.

  • When SrcIP or TgtIP is a private IP address (10.0.0.0/8, fe80::/10, etc...), SrcASN or TgtASN will be outputted as Private.

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
  -J, --JSON-input       Scan JSON formatted logs instead of .evtx (.json or .jsonl)
  -x, --recover-records  Carve evtx records from slack space (default: disabled)

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-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)

General Options:
  -C, --clobber                        Overwrite files when saving
  -w, --no-wizard                      Do not ask questions. Scan for all events and alerts
  -Q, --quiet-errors                   Quiet errors mode: do not save error logs
  -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)

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

  • Normal usage: hayabusa.exe level-tuning
  • Tune rule alert levels based on your custom config file: hayabusa.exe level-tuning -f my_level_tuning.txt

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

  • Set the default profile to minimal: hayabusa.exe set-default-profile minimal
  • Set the default profile to super-verbose: hayabusa.exe set-default-profile super-verbose

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

Hayabusa

General

Preparation

Usage

Hayabusa Rules

Other


日本語版はこちら(Japanese Translation ver.)

Hayabusaについて

準備

使用方法

Hayabusaルール

その他

Clone this wiki locally