How kunai-project/kunai works
Project Type and Purpose
• Kunai is a Rust-based, Linux system-monitoring tool that uses eBPF (via the Aya library) to capture, reorder, enrich, and correlate kernel events for security monitoring and threat hunting—akin to Sysmon for Windows.
• It is organized as a Cargo workspace with multiple crates: a common utilities library, an eBPF-probe crate, a userland CLI binary, and build/launch helpers.
File Structure Analysis
• Top-level workspace:
• Cargo.toml (workspace definition)
• crates:
– kunai-common: shared Rust library for BPF ↔ userland abstractions
– kunai-ebpf: Rust code compiled to eBPF bytecode (kernel probes)
– kunai: the main userland CLI binary that loads probes and processes events
– xlaunch: a small launcher binary (optional orchestration)
– xtask: custom build-and-release tooling
• scripts/: CI, cross-compile, and helper shell scripts
• assets/, README.md, GitHub workflows: documentation and CI configuration
Insights from README
• eBPF programs are embedded in the final standalone binary via Aya and bpf-linker.
• Runtime architecture:
1) Kernel-space eBPF probes generate raw events
2) Events are pushed via perf buffers to userland
3) The kunai userland binary reorders, enriches, correlates, and outputs events
• Build system uses cargo xtask build for both debug and release, with cross-compilation support.
Main Components
a. Kernel Space (eBPF layer)
• kunai-ebpf crate → compiled into .o BPF programs
• eBPF probes attached to kprobes/tracepoints/LSM hooks
b. Userland (Rust application)
• Aya BPF loader
• kunai-common library modules (buffer, cgroup, config, correlation, container awareness)
• kunai CLI binary (main.rs) that orchestrates event loop
• Optional: xlaunch binary for custom startup flows
c. Build & CI
• xtask crate (build orchestration)
• scripts/ (cross-compile, CI test helpers)
• GitHub Actions workflows
d. External Entities
• sysfs/debugfs interfaces for BPF maps
• Output sinks (stdout, file, network collector)
Component Interactions
• Build Flow (offline): xtask/scripts compile kunai-ebpf → BPF object → embed into kunai binary
• Deployment: single kunai executable is deployed on host
• Runtime Flow:
1) kunai starts → Aya loads embedded eBPF programs into kernel
2) Probes fire on kernel events → write to perf buffer & BPF maps
3) kunai reads perf buffer → kunai-common processes events (ordering, enrichment, correlation)
4) Processed events output to chosen sink or log store
• Container-aware logic tags events with namespace/cgroup metadata
Architectural Patterns & Principles
• Layered architecture: Kernel-space (data collection) vs userland (data processing)
• Library reuse: kunai-common decouples userland logic from CLI
• Single-binary deployment: embed BPF bytecode into Rust executable
• Event-driven pipeline: raw events → normalized → enriched → correlated → output