If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Yamato-Security/hayabusa shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 6 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Yamato-Security/hayabusa repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Yamato-Security/hayabusa.

What it runs against: a local clone of Yamato-Security/hayabusa — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Yamato-Security/hayabusa | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Yamato-Security/hayabusa. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Yamato-Security/hayabusa.git
#   cd hayabusa
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Yamato-Security/hayabusa and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Yamato-Security/hayabusa(\\.git)?\\b" \\
  && ok "origin remote is Yamato-Security/hayabusa" \\
  || miss "origin remote is not Yamato-Security/hayabusa (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "src" \\
  && ok "src" \\
  || miss "missing critical file: src"
test -f "config/default_profile.yaml" \\
  && ok "config/default_profile.yaml" \\
  || miss "missing critical file: config/default_profile.yaml"
test -f "config/profiles.yaml" \\
  && ok "config/profiles.yaml" \\
  || miss "missing critical file: config/profiles.yaml"
test -f ".github/workflows/release.yml" \\
  && ok ".github/workflows/release.yml" \\
  || miss "missing critical file: .github/workflows/release.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Yamato-Security/hayabusa"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hayabusa is a Rust-based threat hunting and digital forensics timeline generator that parses Windows Event Logs (.evtx files) against Sigma detection rules to identify security incidents and anomalies. It converts massive event log datasets into correlated, time-ordered timelines for DFIR investigations, with support for multiple output formats (JSON, CSV, HTML) and integration with Elastic Stack. Monolithic Rust binary architecture: main binary in src/ handles CLI parsing (via clap), event log parsing (via custom evtx wrapper at Yamato-Security/hayabusa-evtx), Sigma rule matching (embedded Sigma rules), and timeline generation. Config lives in config/ (default_profile.yaml, profiles.yaml, critical_systems.txt, level_color.txt). Output formatters are compiled into the binary. HTML reports use embedded resources (rust-embed crate) from config/html_report/.

Windows incident responders, DFIR analysts, and threat hunters who need to rapidly triage compromised systems by correlating security-relevant events across thousands of log entries. Also used by security researchers building detection rules and forensic teams building enterprise incident response pipelines.

Actively developed and production-ready. The project has significant community adoption (visible from Black Hat Arsenal and multiple security conference features 2022–2025), uses CI/CD workflows (.github/workflows/), and has a stable release cadence (v3.10.0-dev). However, it's a specialized forensics tool rather than a mass-market project, so adoption is smaller than web frameworks.

Low-to-moderate risk for a specialized forensics tool. Dependency surface is large (40+ direct dependencies in Cargo.toml including tokio, serde_json, regex), but most are stable crates. Single-maintainer risk is present (Yamato Security organization, not a distributed team visible here). The project uses git submodules (.gitmodules) for Sigma rules, which adds supply-chain complexity. No obvious unmaintained dependencies or deprecated APIs visible.

The project is in active v3.x development (version 3.10.0-dev in Cargo.toml, rust-version bumped to 1.95.0). Recent work appears focused on performance (mimalloc memory allocator, libmimalloc-sys), integration testing (integration-test.yml workflow), and timeline diffing (timeline-diff.yml workflow). No specific PR or issue data visible, but the presence of coverage.yml and multiple specialized workflows suggests rigorous CI/CD investment.

git clone https://github.com/Yamato-Security/hayabusa.git
cd hayabusa
cargo build --release
./target/release/hayabusa --help

Requires Rust 1.95.0+ (specified in Cargo.toml). For Windows-specific features (elevation detection via is_elevated crate), run on Windows or use WSL2.

Daily commands: Development build: cargo build (debug assertions disabled per [profile.dev]). Release build: cargo build --release (LTO enabled, symbols stripped). Run: ./target/release/hayabusa timeline -d <evtx-dir> -p default_profile.yaml -o output.json. Accepts event log directories as input, outputs forensic timelines.

• Cargo.toml — Project manifest defining Hayabusa version 3.10.0-dev, Rust 1.95.0 requirement, and all dependencies (evtx, chrono, sigma parsing libraries)—essential for build and dependency management.
• src — Root source directory containing the entire Rust codebase for the sigma-based threat hunting engine and timeline generator.
• config/default_profile.yaml — Default profile configuration for Hayabusa's detection and timeline analysis rules—critical for understanding how detections are processed and filtered.
• config/profiles.yaml — Profile definitions controlling detection sensitivity, rule filtering, and output behavior—essential for configuring threat hunting behavior.
• .github/workflows/release.yml — Release automation workflow defining binary builds for Windows, Linux, and macOS—critical for understanding distribution and cross-platform support.
• README.md — Primary documentation covering Hayabusa's purpose as a sigma-based Windows event log forensics tool, usage patterns, and architecture overview.
• CHANGELOG.md — Version history and breaking changes—mandatory reading for understanding evolution of APIs, detection rules, and timeline generation.

Add a New Detection Rule Profile

1. Create a new YAML profile in config/profiles.yaml following the structure in config/default_profile.yaml with custom rule filters, threshold settings, and severity levels (config/profiles.yaml)
2. Define MITRE ATT&CK mapping by adding tactic identifiers that correspond to rules in your profile (config/mitre_tactics.txt)
3. If adding new severity colors or levels, update config/level_color.txt with the new level identifiers and RGB hex codes (config/level_color.txt)

Add Custom Event Log Expansion Rules

1. Place expansion rule YAML files in config/expand/ directory following Hayabusa sigma rule syntax with field expansion mappings (config/expand/.gitignore)
2. Define field transformations and value mappings in the expansion rule to enrich event fields during parsing (Cargo.toml)

Generate HTML Timeline Reports

1. Configure HTML report styling and layout by customizing CSS in config/html_report/hayabusa_report.css (config/html_report/hayabusa_report.css)
2. Replace background_image.jpg and logo.png in config/html_report/ to customize branding (config/html_report/background_image.jpg)
3. Run hayabusa with --output html flag to generate styled forensic timeline reports from detection results (config/html_report/favicon.png)

Integrate Timeline Export with External Tools

1. Export detection timeline in JSON format (--output json) for programmatic parsing by Timesketch or Elastic Stack (doc/TimesketchImport/TimesketchImport-English.md)
2. Use the Logstash configuration template in doc/ElasticStackImport/6650-hayabusa-jsonl.conf to ingest JSONL output into Elastic (doc/ElasticStackImport/6650-hayabusa-jsonl.conf)
3. Follow integration guides in doc/ElasticStackImport/ and doc/TimesketchImport/ for environment-specific deployment steps (doc/ElasticStackImport/ElasticStackImport-English.md)

• Rust + Cargo — Compiled, memory-safe language with zero-cost abstractions enables fast bulk processing of millions of Windows event logs with minimal memory overhead; cargo provides cross-platform binary distribution (Windows/Linux/macOS).
• evtx-rs (custom fork) — Custom maintained fork of Rust evtx parser with fast-alloc feature provides optimized Windows event log deserialization critical for parsing gigabyte-scale EVTX files efficiently.
• Sigma rule engine — Industry-standard YAML-based detection rule format (sigma) allows portable rule sharing across tools (Splunk, ELK, Timesketch) and decouples rule logic from timeline engine.
• clap CLI framework — undefined
• dashmap + aho-corasick — Lock-free concurrent hashmap (dashmap) enables parallel rule evaluation across CPU cores; aho-corasick provides efficient multi-pattern string matching for IOC detection.
• serde/serde_json + csv crates — Standard Rust serialization framework for JSON and CSV output enables seamless integration with Elastic Stack, Timesketch, and Timeline Explorer forensic tools.

• Sigma YAML over proprietary rule format

  • Why: Portability and community standardization outweigh custom DSL optimization; users can reuse rules across detection platforms.
  • Consequence: Additional YAML parsing overhead at startup; slightly slower than hand-optimized rule matching but acceptable for forensics (batch processing, not real-time).

• Single-pass event log parsing (no index/cache)

  • Why: Simplifies implementation for forensic use case where logs are processed once; avoids complexity of incremental parsing.
  • Consequence: Requires re-parsing entire EVTX for each analysis; not suitable for continuous monitoring; trade throughput for code simplicity.

• In-memory timeline accumulation vs. streaming output

  • Why: Allows sorting and deduplication of detections; enables statistical aggregation for reporting.
  • Consequence: Memory usage scales with event count; large investigations (10M+ events) may require external streaming or partitioning.

• Configuration-driven profiles over code plugins

  • Why: Non-technical users can customize detection sensitivity via YAML without recompilation; lowers barrier to deployment.
  • Consequence: Profile complexity grows with feature set; harder to implement complex conditional logic than in code.

• Real-time event log monitoring—designed for post-incident forensics (batch EVTX processing), not live endpoint streaming
• Linux/macOS event log analysis—Windows-only (Security, System, Application, PowerShell logs), no native Unix/Linux syslog support
• Standalone SIEM—requires external storage (Elastic, Timesketch, Timeline Explorer) for timeline analysis; Hayabusa is a generator, not a database
• Rootkit/kernel-level threat detection—analyzes Windows event logs only; cannot detect attacks that bypass Event Log API

Rust version: Requires Rust 1.95.0 minimum (bumped to a very recent version); older toolchains will fail. Git submodules: The .gitmodules file implies rules or critical code lives in submodules; shallow clones will break (git clone --recurse-submodules required). Platform-specific deps: is_elevated crate for Windows only; conditional compilation for Unix (openssl vendoring required). Memory: mimalloc is the global allocator; disabling it may severely impact performance on large event log sets (100GB+ .evtx files). Config paths: The tool likely expects config/ directory relative to CWD or binary location; running from wrong directory causes silent failures. .env file: .env.example exists but purpose unclear; check if secrets/API keys are needed (GeoIP MaxMind DB license, etc.).

• Sigma Detection Rules — Hayabusa's entire detection logic is built on Sigma rules (a standardized, vendor-agnostic threat detection language); understanding Sigma syntax is essential to writing and debugging custom detections.
• Windows Event Log (.evtx) Binary Format — Hayabusa parses the proprietary Microsoft .evtx binary format (via the hayabusa-evtx crate); knowledge of this format is needed to debug parsing failures or add new field extractors.
• Timeline Correlation & Forensic Reconstruction — The core mission is converting raw events into correlated timelines for incident reconstruction; understanding event sequence, time zones, and causality is critical to effective DFIR.
• Memory Allocator Optimization (mimalloc) — Hayabusa uses mimalloc instead of the default Rust allocator for forensics-scale datasets; memory allocation can become a bottleneck on multi-GB event log sets.
• Aho-Corasick String Matching — Used for fast multi-pattern detection (e.g., matching multiple IOCs or keywords simultaneously); critical for scaling Sigma rule evaluation across millions of events.
• MITRE ATT&CK Framework Mapping — Hayabusa maps Sigma rules to MITRE ATT&CK tactics/techniques (config/mitre_tactics.txt); understanding this taxonomy is essential for threat classification and reporting.
• Tokio Async Runtime & Thread Pooling — Event log parsing and rule matching use tokio for parallelism; understanding async Rust and thread coordination is necessary for performance optimization or adding new parallel processing stages.

• SigmaHQ/sigma — Upstream Sigma detection rule specification and community rules; Hayabusa is a Sigma-native rule engine and depends on this rule format.
• Yamato-Security/hayabusa-evtx — Custom Windows .evtx binary parser used by Hayabusa (declared as git dependency in Cargo.toml); handles low-level event log deserialization.
• elastic/beats — Elastic Stack integration partner; Hayabusa timelines can be piped into Elastic for centralized DFIR dashboarding (mentioned in doc/ElasticStackImport/).
• JPCERT/LogonTracer — Complementary Japanese DFIR tool for Windows logon event visualization; similar threat hunting focus and community overlap with Yamato Security.
• Yamato-Security/takajo — Companion Yamato Security tool for aggregating Hayabusa output across multiple systems into a centralized timeline (implied by cross-tool compatibility).

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Sigma rule parsing and timeline generation

The repo has a .github/workflows/integration-test.yml workflow file but no visible integration test suite in the file structure. Given that Hayabusa's core function is sigma-based threat hunting and timeline generation, there should be comprehensive integration tests validating rule parsing, event log processing, and timeline output formats (JSON, CSV, HTML). This would catch regressions in the sigma engine and ensure output consistency across releases.

• [ ] Create tests/integration/ directory for integration test suite
• [ ] Add test cases validating sigma rule parsing against config/ profiles (especially config/default_profile.yaml and config/profiles.yaml)
• [ ] Create sample Windows event logs in tests/data/ and test timeline generation in multiple output formats (JSONL, CSV, HTML)
• [ ] Add assertions validating timeline field consistency with doc/DFIR-TimelineCreation-EN.png output structure
• [ ] Update .github/workflows/integration-test.yml to run the new test suite with sample evtx files

Add macOS/Linux-specific unit tests for OpenSSL vendored dependency

The Cargo.toml conditionally includes openssl with vendored feature for Unix systems (Mac/Linux) but there are no visible unit tests validating this static linking works correctly or that platform-specific code paths are tested. Given the repo supports multiple platforms and uses custom evtx parsing, adding platform-specific tests would improve release quality.

• [ ] Create tests/platform/ directory with unix.rs and windows.rs test modules
• [ ] Add tests in tests/platform/unix.rs validating OpenSSL initialization and vendored compilation
• [ ] Test Windows-specific code in tests/platform/windows.rs using the winapi crate's wow64apiset feature
• [ ] Verify mimalloc allocator behavior differs between platforms in memory-intensive operations
• [ ] Add platform-specific CI steps to .github/workflows/rust.yml to compile and test on macOS and Linux runners

Create documentation for HTML report generation and configuration

The repo has HTML report assets in config/html_report/ (CSS, images, favicon) and workflow for diff generation in .github/workflows/timeline-diff.yml, but no dedicated documentation exists explaining how to customize HTML reports, what CSS classes are available, or how the hayabusa_report.css and other assets are used. This is a gap given the sophistication of the output format.

• [ ] Create doc/HTMLReportCustomization-English.md documenting the structure of generated HTML reports
• [ ] Document CSS customization points in config/html_report/hayabusa_report.css with examples for modifying colors, fonts, and layout
• [ ] Add a section explaining the role of background_image.jpg, logo.png, and favicon.png in report branding
• [ ] Create examples showing how to use jq (already documented in doc/AnalysisWithJQ-English.md) to filter results before HTML report generation
• [ ] Link to this documentation from the main README.md in the HTML output section

• Add integration tests for each output format (JSON, CSV, HTML) in .github/workflows/integration-test.yml; currently no visible test fixtures or assertions for timeline diff results.
• Document the Sigma rule schema and custom field extensions in README.md or a new docs/SIGMA_RULES.md, as the embedded Sigma engine likely has Hayabusa-specific syntax not in upstream Sigma specification.
• Add profile templates for common scenarios (e.g., config/profiles/persistence_hunting.yaml, lateral_movement.yaml) with documented use cases, since only default_profile.yaml is visible.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.