Komainu is a Linux endpoint telemetry and detection prototype built with eBPF, Go, gRPC, and ClickHouse.
The current MVP focuses on one working vertical slice:
Linux syscall telemetry
-> eBPF probes
-> Go endpoint agent
-> gRPC backend
-> ClickHouse storage
-> YAML detection rules
-> Browser dashboard
This is a school project prototype. It is designed to be understandable, reproducible, and honest about its limits.
| Path | Purpose |
|---|---|
agent/ |
Go eBPF endpoint agent. Captures execve, openat, and IPv4 connect events. |
backend/ |
Go gRPC/HTTP backend. Stores events in ClickHouse, evaluates detection rules, and serves the dashboard. |
dashboard/ |
React/TypeScript browser dashboard for events, rules, alerts, and telemetry summaries. |
docs/ |
Architecture, demo runbook, research notes, and project material. |
progress/ |
Project reports, drafts, and rendered academic outputs. |
tests/ |
Local lab notes and VM experiment setup. |
tools/ |
Helper scripts for research and project maintenance. |
Backend and agent are separate Go modules managed by the root go.work file.
Run the Go testable workspace:
go test ./backend/... ./agent/...Start local ClickHouse:
docker compose up -d clickhouseRun the backend:
cd backend
go run .Build the dashboard assets served by the backend:
cd dashboard
npm install
npm run buildOpen the local dashboard at:
http://127.0.0.1:8080
Build and run the agent on a Linux/Kali VM:
cd agent
./scripts/setup-linux.sh
./scripts/build.sh
sudo BACKEND_GRPC_ADDR=127.0.0.1:50051 ENDPOINT_ID=demo-linux-vm ./scripts/run.shGenerate demo events:
cd agent
./scripts/test-events.sh- Linux only.
- eBPF agent requires root or equivalent capabilities.
- IPv4 only for network connect events.
- No authentication or TLS on local gRPC transport.
- Dashboard HTTP is unauthenticated for the local MVP; bind it to localhost for demos.
- Detection rules are intentionally simple YAML selections, not a complete Sigma implementation.