# kunai-project/kunai architecture

> Architecture diagram of the GitHub repository kunai-project/kunai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunai-project/kunai
- Repository: https://github.com/kunai-project/kunai

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & CI Layer
    subgraph "Build & CI"
        direction TB
        XTASK["xtask (build orchestration)"]:::build
        SCRIPTS["scripts/"]:::build
        GH["GitHub Actions"]:::build
    end

    XTASK -->|"compile eBPF & userland"| EMBED["Embedded BPF in Executable"]:::user
    SCRIPTS --> EMBED
    GH --> XTASK

    %% Kernel Space Layer
    subgraph "Kernel Space"
        direction TB
        PROBES["eBPF Probes\n(kunai-ebpf)"]:::kernel
        PERF["Perf Buffers & BPF Maps"]:::kernel
    end

    EMBED -->|"load via Aya"| PROBES
    PROBES -->|"write events to"| PERF

    %% Userland Layer
    subgraph "Userland Application"
        direction TB
        LOADER["Aya Loader & CLI\n(kunai binary)"]:::user
        COMMON["kunai-common Library\n(shared utils)"]:::user
    end

    PERF -->|"read events"| LOADER
    LOADER -->|"process & enrich"| COMMON

    %% Output Consumers
    subgraph "External Sinks"
        direction TB
        STD["stdout / file"]:::external
        NET["network collector"]:::external
    end

    COMMON -->|"output events"| STD
    COMMON -->|"send events"| NET

    %% Click Events
    click XTASK "https://github.com/kunai-project/kunai/blob/main/xtask/src/main.rs"
    click SCRIPTS "https://github.com/kunai-project/kunai/tree/main/scripts/"
    click GH "https://github.com/kunai-project/kunai/tree/main/.github/workflows/"
    click PROBES "https://github.com/kunai-project/kunai/blob/main/kunai-ebpf/src/main.rs"
    click LOADER "https://github.com/kunai-project/kunai/blob/main/kunai/src/bin/main.rs"
    click COMMON "https://github.com/kunai-project/kunai/blob/main/kunai-common/src/lib.rs"

    %% Styles
    classDef build fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px;
    classDef kernel fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef user fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef external fill:#eceff1,stroke:#546e7a,stroke-width:2px;
```
